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 (for more information, see Atmosphere® API Authentication)
Content-Type STRING application/json

Path

Field Type Description
Email (optional) STRING An e-mail address to notify about changes in the order’s status.
Notes (optional) STRING Notes regarding the fulfilment of the order.
npa STRING

The NPA from which to order numbers.

Mutually exclusive with numbers, reservations, and state.
numbers ARRAY

An array of numbers to order (for more information, see Search and Reserve).

Mutually exclusive with npa, quantity, reservations, and state.

Each item is in 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 (for more information, 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.address1; billingAddress.city; billingAddress.state; billingAddress.zip
billingAddress (optional) OBJECT The billing address. If omitted, serviceAddress is 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.address1; billingAddress.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.address1; billingAddress.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.address1; billingAddress.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.address1; billingAddress.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.address1; billingAddress.city; billingAddress.state; billingAddress.zip

Order by NPA

Copy 
POST /_rest/v3/my/did/orders

{

  "npa": "619",

  "packageID": 1234567,

  "serviceName": "ABC Signs",

  "serviceAddress": {

    "address1": "1234 Main St",

    "city": "Springfield",

    "state": "IL",

    "zip": "62701"

  }

}

Order by Reserved Numbers

Copy 
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"

  }

}

Order by Reservation IDs

Copy 
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.

Allowed values: PENDING, PROVISIONED, QUEUED

  • 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.
  • QUEUED: Our services and systems are aware that work needs to occur, but the work has not been started yet.
number OBJECT The number.

Success Response

Copy 
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

Code 401 Response

Copy 
HTTP/1.1 401 Unauthorized

{

    "code": 401,

    "error": "Unauthorized"

}

 

Copy 
HTTP/1.1 401 Unauthorized

{

    "code": 401,

    "error": "Session Expired"

}

Code 402 Response

Copy 
HTTP/1.1 402 Payment Required

{
    "code": 402,

    "error": "Order blocked; trial limit realized.  Limit: %d seats."
}

Code 406 Response

Copy 
HTTP/1.1 406 Not Acceptable

{
    "code": 406,

    "error": "Not Acceptable"
}

Code 422 Response

Copy 
HTTP/1.1 422 Unprocessable Entity

{
    "code": 422,

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

 

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

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

 

Copy 
HTTP/1.1 422 Unprocessable Entity
{

    "code": 422,

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

 

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

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

 

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

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

 

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

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

 

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

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

 

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

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

 

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

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