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. The platform chooses the carrier for searches and purchases; a provider sent by an older client is ignored.

List numbers#

Numbers in the key's organization that the key may read, with how each is configured.

GET/api/v1/phone-numbers

Responses

The numbers.

Request

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

Response200

{
  "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_…"
  }
}

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, so handle a conflict on the purchase rather than assuming.

GET/api/v1/phone-numbers/available

Query parameters

areaCodestring: e.g. 512.
countrystring: ISO country code.
voicestring: `true` for voice-capable only.
smsstring: `true` for SMS-capable only.
limitnumber: Up to 50.; Default10

Responses

What the carrier has.

Request

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

Response200

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

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

Body

application/json

phoneNumber: string (E.164); required
friendlyName: string
areaCode: string
isOrgShared: boolean

Responses

The provisioned number.

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"
  }'

Response201

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

Get a number#

One number and its configuration.

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

Path parameters

phoneNumberIdstringrequired: Phone number id.

Responses

The number.

Request

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

Response200

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

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

phoneNumberIdstringrequired: Phone number id.

Body

application/json

friendlyName: string
isOrgShared: boolean
config: object

Responses

The updated number.

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
      }
    }
  }'

Response200

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

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

phoneNumberIdstringrequired: Phone number id.

Responses

Released.

Request

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

Response200

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