Phone numbers

Find a number, buy it, configure how it behaves, give it back.

Provisioning buys a number from a carrier. It costs money, and deleting the row does not undo it — releasing a number is a separate, deliberate act that puts it back in the carrier's pool where someone else can take it. The two are behind different capabilities for that reason, so a key that configures numbers day to day cannot buy or give one away.

Which carrier a number sits behind is not part of this contract. Numbers get ported, and an integration that branched on the carrier would break the day one moved.

List numbers

Numbers the organization has provisioned, with how each is configured.

GET/api/v1/phone-numbers

Responses

{
  "data": {
    "phoneNumbers": [
      {
        "id": "2f11…",
        "phoneNumber": "+15125550147",
        "friendlyName": "Member services main line",
        "capabilities": {
          "voice": true,
          "sms": true,
          "mms": false
        },
        "config": {
          "voicemail": {
            "enabled": true,
            "maxLength": 180
          }
        },
        "isOrgShared": true
      }
    ]
  },
  "meta": {
    "requestId": "req_…"
  }
}

Request

curl -X GET "https://voice.evryhealth.com/api/v1/phone-numbers" \
  -H "Authorization: Bearer YOUR_API_KEY"

Find numbers to buy

A read against the carrier. Nothing is reserved by looking, so a number here can be gone by the time it is provisioned — handle a conflict on the purchase rather than assuming.

GET/api/v1/phone-numbers/available

Query parameters

Parameter	Type	Description
`areaCode`	`string`	e.g. 512.
`country`	`string`	ISO country code.
`voice`	`string`	`true` for voice-capable only.
`sms`	`string`	`true` for SMS-capable only.
`limit`	`number`	Up to 50. Default: `10`

Responses

{
  "data": {
    "available": [
      {
        "phoneNumber": "+15125550188",
        "locality": "Austin",
        "region": "TX",
        "capabilities": {
          "voice": true,
          "sms": true,
          "mms": true
        }
      }
    ]
  },
  "meta": {
    "requestId": "req_…"
  }
}

Request

curl -X GET "https://voice.evryhealth.com/api/v1/phone-numbers/available" \
  -H "Authorization: Bearer YOUR_API_KEY"

Provision a number

Buys the number and records it. Billable and not undone by deleting the row. Behind `phone_number:provision`, which a key has to be explicitly scoped for.

POST/api/v1/phone-numbers

Responses

{
  "data": {
    "id": "2f11…",
    "phoneNumber": "+15125550188"
  },
  "meta": {
    "requestId": "req_…"
  }
}

Request

curl -X POST "https://voice.evryhealth.com/api/v1/phone-numbers" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phoneNumber": "+15125550188",
    "friendlyName": "Member services main line"
  }'

Get a number

One number and its configuration.

GET/api/v1/phone-numbers/{phoneNumberId}

Path parameters

Parameter	Type	Description
`phoneNumberId`required	`string`	Phone number id.

Responses

{
  "data": {
    "id": "2f11…",
    "phoneNumber": "+15125550147"
  },
  "meta": {
    "requestId": "req_…"
  }
}

Request

curl -X GET "https://voice.evryhealth.com/api/v1/phone-numbers/{phoneNumberId}" \
  -H "Authorization: Bearer YOUR_API_KEY"

Configure a number

Rename it, share it, or change how it behaves — call forwarding, business hours, voicemail. The configuration is validated on write; an invalid forwarding number or schedule is refused rather than stored.

PATCH/api/v1/phone-numbers/{phoneNumberId}

Path parameters

Parameter	Type	Description
`phoneNumberId`required	`string`	Phone number id.

Responses

{
  "data": {
    "id": "2f11…"
  },
  "meta": {
    "requestId": "req_…"
  }
}

Request

curl -X PATCH "https://voice.evryhealth.com/api/v1/phone-numbers/{phoneNumberId}" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "config": {
      "voicemail": {
        "enabled": true,
        "greeting": "Sorry we missed you.",
        "maxLength": 180
      }
    }
  }'

Release a number

Gives the number back to the carrier. Irreversible — someone else can take it. Behind `phone_number:release`, separate from the capability that configures one.

DELETE/api/v1/phone-numbers/{phoneNumberId}

Path parameters

Parameter	Type	Description
`phoneNumberId`required	`string`	Phone number id.

Responses

{
  "data": {
    "released": true
  },
  "meta": {
    "requestId": "req_…"
  }
}

Request

curl -X DELETE "https://voice.evryhealth.com/api/v1/phone-numbers/{phoneNumberId}" \
  -H "Authorization: Bearer YOUR_API_KEY"