Purchase DID Numbers

After finding, or finding and reserving, your unique DID numbers use Purchase DID Numbers to buy them. 

Endpoints and methods
POST /_rest/v3/my/did/orders

 

Parameters

Header

Accept: application/json

Authorization: xxxxxxxxxxxxxxxxx

Content-Type: application/json


Field

Type

Description

Accept

 

String

application/json

Authorization


String

Authorization token (see Authenticate)

Content-Type

String

application/json

 

Path

Field

Type

Description

Email optional


String

An e-mail address to notify about changes in this order’s status.

Notes optional


String

Notes regarding the fulfilment of this order.

npa

String

The NPA from which to order numbers.

 

  • Mutually exclusive with numbers, reservations, and state

 

numbers

Array

An array of reserved numbers to order (see Search and Reserve)

 

  • Mutually exclusive with npa, quantity, reservations, and state
  • Each item is of the following form:
{

    "countryCode": "1",
    "number": "1112223456"
}

 

packageID

 

Integer

The target packageID to order numbers for.

quantity

Integer

The quantity of numbers to order.

 

  • Mutually exclusive with numbers and reservations.

 

referenceID
optional

String

A non-empty string indicating your reference ID or code.

Reservations optional

String[]

An array of reservation IDs (see Search and Reserve)

 

  • Mutually exclusive with npa, numbers, quantity, and state

 

Sequential optional

Boolean

True to require all of this order’s numbers to be in sequence. May incur additional charges.

 

Default value: false

 

state

String

Two-digit state abbreviation from which to order numbers.

 

  • Mutually exclusive with npa and numbers.

 

serviceName

String

The name of the service location.

serviceAddress

 

Object

The service address.

address1


String

The first line of the service address.

address2


String

The second line of the service address.

city

 

String

The city of the service address.

state

String

The state of the service address.

zip


String

The zip code (postal code) of the service address.

billingName
optional

String

The name of the billing location.

 

Note:If any of the billingAddress* parameters are provided the following parameters are also required:

 

billingName billingAddress.address1billingAddress.city billingAddress.state billingAddress.zip

 

billingAddress
optional

Object

The billing address. If omitted, serviceAddress will be used in place of billingAddress.

 

Address1
optional

String

The first line of the billing address.

 

Note:If any of the billingAddress* parameters are provided the following parameters are also required:

 

billingName billingAddress.address1billingAddress.city billingAddress.state billingAddress.zip

 

Address2
optional

String

The second line of the billing address.

 

Note:If any of the billingAddress* parameters are provided the following parameters are also required:

 

billingName billingAddress.address1billingAddress.city billingAddress.state billingAddress.zip

 

City
optional

String

The city of the billing address.

 

Note:If any of the billingAddress* parameters are provided the following parameters are also required:

 

billingName billingAddress.address1billingAddress.city billingAddress.state billingAddress.zip

 

State 
optional

String

The state of the billing address.

 

Note:If any of the billingAddress* parameters are provided the following parameters are also required:

 

billingName billingAddress.address1billingAddress.city billingAddress.state billingAddress.zip

 

Zip
optional

String

The zip code (postal code) of the billing address.

 

Note:If any of the billingAddress* parameters are provided the following parameters are also required:

 

billingName billingAddress.address1billingAddress.city billingAddress.state billingAddress.zip

POST /_rest/v3/my/did/orders

{

  "npa": "619",

  "packageID": 1234567,

  "serviceName": "ABC Signs",

  "serviceAddress": {

    "address1": "1234 Main St",

    "city": "Springfield",

    "state": "IL",

    "zip": "62701"

  }

}
POST /_rest/v3/my/did/orders

{

  "numbers": [

    {

      "countryCode": "1",

      "number": "2125559998"

    },

    {

      "countryCode": "1",

      "number": "2125559999"

    }

  ],

  "packageID": 1234567,

  "billingName": "ABC Signs",

  "billingAddress": {

    "address1": "1234 Main St",

    "city": "Springfield",

    "state": "IL",

    "zip": "62701"

  },

  "serviceName": "Signs 'R' Us",

  "serviceAddress": {

    "address1": "4475 2nd Ave",

    "city": "Aurora",

    "state": "CO",

    "zip": "80013"

  }

}
POST /_rest/v3/my/did/orders

{

  "reservations": [

    "ae62b6bd-cf20-11e7-b207-525400807a6d",

    "baa7fe27-cf20-11e7-b207-525400807a6d",

    "c5c7b9d6-cf20-11e7-b207-525400807a6d"

  ],

  "packageID": 1234567,

  "serviceName": "Diaspora Direct",

  "serviceAddress": {

    "address1": "10715 Beaufort St",

    "city": "Denver",

    "state": "CO",

    "zip": "80244"

  }

}

Response example and schema

Success 200

 

Field

Type

Description

order



Object

A complex object identifying batch-specific and number provisioning details.

orderID


Integer

The overall ID associated with this order.

batches

Array

An array of “batch” objects with associated number provisioning details.

 

batchID

Integer

The ID associated with this portion of the order (batch).

 

numbers




Array

An array of objects specifying the numbers and provisioning attributes associated with this particular batch.

callerID optional

String

The provisioning status of caller ID lookup service, if ordered/applicable (See network for value descriptions.)

 

Allowed values: PENDING, PROVISIONED, QUEUED

 

Cnam optional

String

The provisioning status of Caller ID Registration (CNAM) service, if ordered/applicable. (See network for value descriptions.)

 

Allowed values: PENDING, PROVISIONED, QUEUED

 

countryCode

Numeric

The number’s country code.

 

directoryListing 
optional

String

The provisioning status of Directory Listing service, if ordered/applicable. (See network for value descriptions.)

 

Allowed values: PENDING, PROVISIONED, QUEUED

 

e164


Numeric

The e.164 representation of the number.

E911 optional

String

The provisioning status of 911 service, if ordered/applicable. (See network for value descriptions.)

 

Allowed values: PENDING, PROVISIONED, QUEUED

 

e911Address optional



Object

If the order is adding or changing 911 service, this is the associated address.

name


string

The name/label of the 911 registration address.

address1

 

 

string

The first line of the 911 registration address.

address2


string

The second line of the 911 registration address.

city


string

The city of the 911 registration address.

state


string

The state of the 911 registration address.

network

String

The number’s provisioning status.

 

  • QUEUED: Our services and systems are aware that work needs to occur, but the work has not been started yet.
  • PENDING: Our services and systems have begun the necessary work to provide this service.
  • PROVISIONED: Our services and systems have completed the necessary work and the service is currently active, unless altered by a later order.

 

Allowed values: PENDING, PROVISIONED, QUEUED

 

number

Object

The number.

 

HTTP/1.1 200 OK

{

  "orderID": 12345,

  "batches": [

    {

      "batchID": 23456,

      "numbers": [

        {

          "callerID": "QUEUED",

          "cnam": null,

          "countryCode": "1",

          "directoryListing": null,

          "e164": "+14084744638",

          "e911": "QUEUED",

          "e911Address": null,

          "network": "PENDING",

          "number": "4084744638"

        },

        {

          "callerID": "QUEUED",

          "cnam": null,

          "countryCode": "1",

          "directoryListing": null,

          "e164": "+14084744638",

          "e911": "QUEUED",

          "e911Address": null,

          "network": "PENDING",

          "number": "4084744638"

        }

      ]

    }

  ]

}

Error

 

Name

Type

Description

code

 

Integer

Error code

error
String

Error description

HTTP/1.1 401 Unauthorized

{

    "code": 401,

    "error": "Unauthorized"

}


HTTP/1.1 401 Unauthorized

{

    "code": 401,

    "error": "Session Expired"

}
HTTP/1.1 402 Payment Required

{
    "code": 402,

    "error": "Order blocked; trial limit realized.  Limit: %d seats."
}
HTTP/1.1 406 Not Acceptable

{
    "code": 406,

    "error": "Not Acceptable"
}
HTTP/1.1 422 Unprocessable Entity

{
    "code": 422,

    "error": "The '%s' parameter is required."
}

HTTP/1.1 422 Unprocessable Entity
{
    "code": 422,

    "error": "The '%s' parameter must be scalar."
}

HTTP/1.1 422 Unprocessable Entity
{

    "code": 422,

    "error": "The '%s' parameter must be formatted as a(n) boolean."
}

HTTP/1.1 422 Unprocessable Entity
{
    "code": 422,

    "error": "The '%s' parameter must be formatted as a(n) integer."
}

HTTP/1.1 422 Unprocessable Entity
{
    "code": 422,

    "error": "The '%s' parameter must be formatted as a(n) numeric."
}

HTTP/1.1 422 Unprocessable Entity
{
    "code": 422,

    "error": "The '%s' parameter must be formatted as a(n) string."
}

HTTP/1.1 422 Unprocessable Entity
{
    "code": 422,

    "error": "The '%' parameter is required for each Number object."
}

HTTP/1.1 422 Unprocessable Entity
{
    "code": 422,

    "error": "The 'countryCode' parameter must match one of the following values: 1"
}

HTTP/1.1 422 Unprocessable Entity
{
    "code": 422,

    "error": "The 'number' parameter must be 10 numeric digits."
}