Number Ordering

Note: The API key provided in the Authorization header must have the apik_ prefix, and requires the API key to have a user with sufficient permissions assigned to it..

Numbers can be ordered and added, or removed from your account. This is done by:

(Optional) Search our number inventory with the coverage endpoint to view counts of available numbers according to your filters
Create a cart
Add one or more requests to the cart (using NEW_NUMBERS or REMOVE_NUMBERS requests)
Checkout the cart to order the numbers

See examples below for complete and individual examples.

Schemas

Swift Inventory Coverage

Request

Provided via query string.

Name	Type	Description
number_type	String	The type of number to search for. Always `tendlc`.
group_by[]	String	The fields to group the results by. Valid values are `npa`, `nxx`, `lata`, `state`, `rate_center`, `country_code`.
npa	String	Optional. The NPA (area code) to search for.
nxx	String	Optional. The NXX (exchange code) to search for.
lata	String	Optional. The LATA (local access and transport area) to search for.
state	String	Optional. The state/province to search for.
rate_center	String	Optional. The rate center to search for.
country_code	String	Optional. The country code to search for.

Response

Inventory Coverage Response Object

Name	Type	Description
associations	Object	Associations to other entities in the system related to the account.
data	Object(Inventory Coverage Data Object)	Contains details about the coverage results.
type	String	Object type identifier. Always `"inventory_coverage"`.

Inventory Coverage Data Object

Name	Type	Description
entries	Array(Object(Inventory Coverage Entry Object))	List of grouped inventory entries. Each object is described below.
quantity	Integer	Total number of numbers available that match the request filters.

Inventory Coverage Entry Object

Name	Type	Description
key	Array(String)	List of fields used for grouping the inventory (e.g. `npa`, `nxx`, etc).
quantity	Integer	Number of phone numbers available for the specified group.
value	Object	Key-value map containing field(s) and value(s) for this group (e.g. `{ "npa": "555" }`).

Cart

Name	Type	Description
id	String	The unique identifier of the record.
inserted_at	String(datetime)	When the record was created, in ISO 8601 format.
updated_at	String(datetime)	When the record was last updated, in ISO 8601 format.
name	String	The name of the cart.
notes	String or null	Optional. Notes about the cart.
reference_id	String or null	Optional. An identifier for the cart for your own reference.

Cart Request

Requests are added to carts to alter the numbers on your account.

Cart Request Object

Name	Type	Description
type	String	The type of the object. For cart request objects, this value is always `cart_request`.
data	Object(Cart Request Data Object)	The data payload for the cart request.

Cart Request Data Object

Name	Type	Description
name	String	The name for this request in the cart.
notes	String or null	Optional notes related to this cart request.
type	String	The type of number order request. For new numbers, this value can be `NEW_NUMBERS` or `REMOVE_NUMBERS`.
data	Object(Number Request Data Object)	Additional parameters for the request.

Number Request Data Objects

Note: numbers are considered “tainted” after being ordered, and cannot be removed from the account for 30 minutes.

NEW_NUMBERS:

Name	Type	Description
quantity	Integer	Number of new numbers to request.
number_type	String	The type of number to order. Always `tendlc`.
country_code	String	Optional. Country code for the new numbers (e.g., `"1"` for North America).
npa	String	Optional. The NPA (area code) for the new numbers.
nxx	String	Optional. The NXX (exchange code) for the new numbers.
lata	String	Optional. The LATA (local access and transport area) for the new numbers.
state	String	Optional. The state/province for the new numbers.
rate_center	String	Optional. The rate center for the new numbers.
country_code	String	Optional. The country code for the new numbers.

ADD_MESSAGING_NUMBERS:

Name	Type	Description
numbers	Array(String(format:e164))	The numbers to enable on your account.
mms_enabled	Boolean	Optional. If the number should have MMS enabled. Defaults to false. Requires MMS access on your account.
api_key_ids	Array(String(ID))	Optional. IDs of API Keys to associate to the numbers. Defaults to none.
switch_id	String(ID)	Optional. ID of switch to associate to the numbers. Defaults to none.

REMOVE_NUMBERS:

Name	Type	Description
numbers	Array:String(format:e164)	Array of numbers to remove from the account, in E.164 format excluding the `+` prefix (eg `17055551234`).

Order

Carts are converted to orders when they are checked out, and can no longer be modified outside of the name and notes.

Order Object

Name	Type	Description
id	String	The unique identifier of the order.
name	String	The name of the order (from the cart name).
notes	String or null	Optional notes about the order.
reference_id	String or null	Optional reference identifier for the order.
status	String	The processing status of the order. Possible values include `NEW`, `PROCESSING`, `COMPLETED`, `ERROR`, `COMPLETED_WITH_ERRORS`.
error_code	String	A code indicating if an error occurred. Typically `OK` if successful.
inserted_at	String(datetime)	When the order was created, in ISO 8601 format.
updated_at	String(datetime)	When the order was last updated, in ISO 8601 format.
completed_at	String(datetime) or null	When the order was completed, in ISO 8601 format, or null if not completed yet.
status_history	Array:Object(Status History Object)	The history of status changes for the order.

Status History Object

Name	Type	Description
status	String	The status at this point in time.
detail	String	Additional detail about the status change.
error_code	String	Error code for this status update.
inserted_at	String(datetime)	When this status update was recorded.

Examples

Note: Requests, carts, and orders can be performed for a sub account as well, by adding /accounts/:account_id to the URL:

/api/v1/accounts/{account_id}/carts
/api/v1/accounts/{account_id}/orders
/api/v1/accounts/{account_id}/requests

Complete number order process

A complete example of ordering numbers for an account:

Search coverage of Swift number inventory by filter:

Request:

GET /api/v1/inventory/coverage?number_type=tendlc&group_by[]=npa HTTP/1.1
Accept: application/json, text/plain
Authorization: Bearer apik_ABC123

Response:

HTTP/1.1 200
Content-Type: application/json
Content-Length: 402

{
    "associations": {},
    "data": {
        "entries": [
            {
                "key": [
                    "npa"
                ],
                "quantity": 1,
                "value": {
                    "npa": "555"
                }
            }
        ],
        "quantity": 1
    },
    "type": "inventory_coverage"
}

Create a cart:

Request:

POST /api/v1/carts HTTP/1.1
Accept: application/json, text/plain
Authorization: Bearer apik_ABC123

{
    "data": {
        "name": "cart name",
        "notes": "cart note"
    },
    "type": "cart"
}

Response:

HTTP/1.1 201
Content-Type: application/json
Content-Length: 365

{
    "associations": {
        "account": {
            "data": {
                "id": "01K3S620PA5JPWPR10F0000000"
            },
            "type": "account"
        },
        "author": {
            "data": {
                "id": "01KBB59RM02N21V7K0V0000000"
            },
            "type": "user"
        }
    },
    "data": {
        "id": "01KBC4VZE1CFMG5MAB089000000",
        "inserted_at": "2025-12-01T05:06:21.249813Z",
        "name": "cart name",
        "notes": "cart note",
        "reference_id": null,
        "updated_at": "2025-12-01T05:06:21.249813Z"
    },
    "type": "cart"
}

Add a request to the cart:

Request:

POST /api/v1/carts/{cart_id}/requests HTTP/1.1
Accept: application/json, text/plain
Authorization: Bearer apik_ABC123

{
    "type": "cart_request",
    "data": {
        "name": "request name",
        "notes": "request note",
        "type": "NEW_NUMBERS",
        "data": {
            "quantity": 5,
            "country_code": "1",
            "number_type": "tendlc"
        }
    }
}

Response:

HTTP/1.1 201
Content-Type: application/json
Content-Length: 464

{
    "associations": {
        "account": {
            "data": {
                "id": "01K3S620PA5JPWPR10F0000000"
            },
            "type": "account"
        },
        "author": {
            "data": {
                "id": "01KBB59RM02N21V7K0V0000000"
            },
            "type": "user"
        },
        "cart": {
            "data": {
                "id": "01KBC4VZE1CFMG5MAB089000000"
            },
            "type": "cart"
        }
    },
    "data": {
        "data": {},
        "id": "01KBC4VZE1CFMG5MAB089000000",
        "inserted_at": "2025-12-01T04:27:50.055391Z",
        "name": "request name",
        "notes": null,
        "reference_id": null,
        "type": "NONE",
        "updated_at": "2025-12-01T04:27:50.055391Z"
    },
    "type": "cart_request"
}

Checkout the cart:

Request:

POST /api/v1/carts/{cart_id}/checkout HTTP/1.1
Accept: application/json, text/plain
Authorization: Bearer apik_ABC123

Response:

HTTP/1.1 200
Content-Type: application/json
Content-Length: 540

{
    "associations": {
        "account": {
            "data": {
                "id": "01K3S620PA5JPWPR10F0000000"
            },
            "type": "account"
        },
        "author": {
            "data": {
                "id": "01KBB59RM02N21V7K0V0000000"
            },
            "type": "user"
        }
    },
    "data": {
        "completed_at": null,
        "error_code": "OK",
        "id": "01KBC4VZE1CFMG5MAB089000000",
        "inserted_at": "2025-11-30T20:45:39.807030Z",
        "name": "cart name",
        "notes": null,
        "reference_id": null,
        "status": "NEW",
        "status_history": [
            {
                "detail": "checkout cart",
                "error_code": "OK",
                "inserted_at": "2025-12-01T04:37:39.098864Z",
                "status": "NEW"
            }
        ],
        "updated_at": "2025-12-01T04:37:39.099025Z"
    },
    "type": "order"
}

Search Swift inventory by coverage filter

Request:

GET /api/v1/inventory/coverage?number_type=tendlc&group_by[]=npa HTTP/1.1
Accept: application/json, text/plain
Authorization: Bearer apik_ABC123

Response:

HTTP/1.1 200
Content-Type: application/json
Content-Length: 402

{
    "associations": {},
    "data": {
        "entries": [
            {
                "key": [
                    "npa"
                ],
                "quantity": 1,
                "value": {
                    "npa": "555"
                },
                "value": {
                    "npa": "555"
                }
            }
        ],
        "quantity": 1
    },
    "type": "inventory_coverage"
}

Add `remove_numbers` request to cart

This assumes a cart has already been created. Request:

POST /api/v1/carts/{cart_id}/requests HTTP/1.1
Accept: application/json, text/plain
Authorization: Bearer apik_ABC123

{
    "type": "cart_request",
    "data": {
        "notes": "request note",
        "name": "request name",
        "type": "REMOVE_NUMBERS",
        "data": {
            "numbers": [
              "17055551234",
              "17055551235",
              "17055551236"
            ]
        }
    }
}

Response:

HTTP/1.1 201
Content-Type: application/json
Content-Length: 464

{
    "associations": {
        "account": {
            "data": {
                "id": "01K3S620PA5JPWPR10F0000000"
            },
            "type": "account"
        },
        "author": {
            "data": {
                "id": "01KBB59RM02N21V7K0V0000000"
            },
            "type": "user"
        },
        "cart": {
            "data": {
                "id": "01KBC4VZE1CFMG5MAB089000000"
            },
            "type": "cart"
        }
    },
    "data": {
        "data": {},
        "id": "01KBC4VZE1CFMG5MAB089000000",
        "inserted_at": "2025-12-01T04:27:50.055391Z",
        "name": "request name",
        "notes": null,
        "reference_id": null,
        "type": "REMOVE_NUMBERS",
        "updated_at": "2025-12-01T04:27:50.055391Z"
    },
    "type": "cart_request"
}

Checkout cart

Request:

POST /api/v1/carts/{cart_id}/checkout HTTP/1.1
Accept: application/json, text/plain
Authorization: Bearer apik_ABC123

Response:

HTTP/1.1 200
Content-Type: application/json
Content-Length: 540

{
    "associations": {
        "account": {
            "data": {
                "id": "01K3S620PA5JPWPR10F0000000"
            },
            "type": "account"
        },
        "author": {
            "data": {
                "id": "01KBB59RM02N21V7K0V0000000"
            },
            "type": "user"
        }
    },
    "data": {
        "completed_at": null,
        "error_code": "OK",
        "id": "01KBC4VZE1CFMG5MAB089000000",
        "inserted_at": "2025-12-01T05:06:21.249813Z",
        "name": "cart name",
        "notes": null,
        "reference_id": null,
        "status": "NEW",
        "status_history": [
            {
                "detail": "checkout cart",
                "error_code": "OK",
                "inserted_at": "2025-12-01T14:36:58.137795Z",
                "status": "NEW"
            }
        ],
        "updated_at": "2025-12-01T14:36:58.138004Z"
    },
    "type": "order"
}

Bring your own numbers to your account

This feature requires approval from Swift, and must be explicitly enabled on your account.

Begin by creating a cart like normal, but when adding a request to the cart, use the ADD_MESSAGING_NUMBERS request type.

Request:

POST /api/v1/carts/{cart_id}/requests HTTP/1.1
Accept: application/json, text/plain
Authorization: Bearer apik_ABC123

{
  "type": "cart_request",
  "data": {
    "name": "request name",
    "type": "ADD_MESSAGING_NUMBERS",
    "data": {
      "notes": "request note",
      "mms_enabled": true,
      "api_key_ids: [
        "01KBC4VZE1CFMG5MAB089000001",
        "01KBC4VZE1CFMG5MAB089000002"
      ],
      "switch_id": "01KBC4VZE1CFMG5MAB089000002",
      "numbers": [
        "17055551234",
        "17055551235",
        "17055551236"
      ]
    }
  }
}

Response:

HTTP/1.1 201
Content-Type: application/json
Length: 464

Number Ordering

Schemas

Swift Inventory Coverage

Request

Response

Inventory Coverage Response Object

Inventory Coverage Data Object

Inventory Coverage Entry Object

Cart

Cart Request

Cart Request Object

Cart Request Data Object

Number Request Data Objects

Order

Order Object

Status History Object

Examples

Complete number order process

Search Swift inventory by coverage filter

Add remove_numbers request to cart

Checkout cart

Bring your own numbers to your account

Add `remove_numbers` request to cart