We use cookies to give you the best possible experience while you browse through our site. By continuing to use our website you implicitly agree to the usage of cookies on this site.

Read More
← Atlas API & Provisioning Reference

DIDs

Schema

A provisioned did

Type Object

Name Type Description
activated Boolean Desc. activated
brand_name String(0..255) Desc. brand_name
description String Desc. description
forward_number String Desc. forward_number
help_message String(0..255) Desc. help_message
id String(format:uuid) Desc. id
inserted_at String(format:date-time) An ISO8601 formatted timestamp
message_class Enum(NONE, A2P, P2P):String
mms_enabled Boolean Desc. mms_enabled
number String Desc. number
rate_center String
segment_overrides Array:SubObject Desc. segment_overrides
segment_threshold Integer Desc. segment_threshold
sms_enabled Boolean Desc. sms_enabled
state String
tier Enum:String Desc. tier
updated_at String(format:date-time) An ISO8601 formatted timestamp
upgrade_asset_handling Enum:String The asset handling flag for SMS Upgrades
voice_enabled Boolean Desc. voice_enabled

Desc. activated

Is the DID active for use?

Desc. brand_name

Custom Brand Name when the number is not actively apart of TCR's Campaign setup, this field will be used in place of the brand name.

Added on 2026-05-04.

Desc. description

Any notes to attach to the number.

Desc. forward_number

When this DID receives an inbound message, the message will be routed to the specified forward_number.

Note. using forward_number or its switch equivalent will charge the account for 2 messages, instead of 1: * Once for the inbound (to the host number) * Again for the outbound (from the host number to the forward number)

If this field is nil, or blank the sms_switch will be used for routing instead

Desc. help_message

Custom HELP Message that should be sent when an inbound message matching "HELP" is received.

For help messages longer than 255 characters, they must handled by the receiver.

Desc. id

A Universally unique identifier, which identifies the resource

Desc. mms_enabled

Whether or not the number is MMS capable, does not affect SMS or SMS to MMS upgrades.

Desc. number

The 3 to 15 digit code of the number.

SubObject

Sub-Schema

Type Object

Name Type Description
encoding Integer Desc. encoding
id String(format:uuid) Desc. id
segment_threshold Integer Desc. segment_threshold
target_reference_id String Desc. target_reference_id

Desc. encoding

The SMS encoding that this override should trigger on.

Desc. id

The UUID of the specific segment override, required when changing an existing override.

Desc. segment_threshold

See number's segment_threshold for more information.

Desc. target_reference_id

Internal reference_id for a carrier, contact support for details or if a required carrier is not available.

Reference ids tend to have the form:

<country_code>_<name>

Example:

us_tmobile
ca_rogers
dm_digicel

Desc. segment_overrides

While the segment_threshold can be used to apply to all outgoing sms messages, sometimes its required to tailor fit an upgrade to a particular carrier.

Note, when updating the segment_overrides, all overrides must be provided for the did, any unspecified overrides will be removed.

Desc. segment_threshold

How many segments should a outgoing message have before it triggers an MMS upgrade.

Contact support to learn more about MMS upgrades.

0 will disable upgrades, any value greater than 1 will trigger an upgrade when that many sms segments would have been sent.

Upgrades only apply to HTTP originated traffic, customers using SMPP will not for outbound are not subject to upgrades.

Desc. sms_enabled

Whether or not a number is messaging capable.

Note that this flag also affects mms availability.

Enum Values tier

Allowed values

  • L0
  • L1
  • T1
  • T2
  • T3
  • AK
  • HI
  • CAN
  • PR
  • TF
  • SHORTCODE
  • M0
  • M1
  • BYON

Desc. tier

The billing tier associated with the number:

  • L0 - Tychron OCN Tier 0
  • L1 - Tychron OCN Tier 1
  • T1 - Partner Tier 0
  • T2 - Partner Tier 1
  • T3 - Partner Tier 3
  • AK - Alaska
  • HI - Hawaii
  • CAN - Canada
  • PR - Puerto Rico
  • TF - Tollfree
  • SHORTCODE - General Shortcode
  • M0 - Mobile Tier 0
  • M1 - Mobile Tier 1
  • BYON - Bring-Your-Own-Number

Enum Values upgrade_asset_handling

Allowed values

  • FALLBACK
  • OFF
  • ALWAYS_UPGRADE
  • SEGMENT_UPGRADE

Desc. voice_enabled

Whether or not the specified number is voice-capable (only affects outgoing)

Example

{
  "activated": true,
  "brand_name": "ACME Corp.",
  "description": "Test number used for XYZ.Corp\n",
  "forward_number": "12003004000",
  "help_message": "Available Keywords are: HELP, SUBSCRIBED, UNSUBSCRIBE.",
  "id": "c6be45e4-b7dd-412c-96c4-777e83fb9c48",
  "inserted_at": "2021-08-13T04:08:44.762841Z",
  "message_class": "A2P",
  "mms_enabled": true,
  "number": "12003004000",
  "rate_center": "KISSIMEE",
  "segment_overrides": [
    {
      "encoding": 0,
      "id": "c6be45e4-b7dd-412c-96c4-777e83fb9c48",
      "segment_threshold": 0,
      "target_reference_id": "us_tmobile"
    }
  ],
  "segment_threshold": 1,
  "sms_enabled": true,
  "state": "FL",
  "tier": "T1",
  "updated_at": "2021-08-13T04:08:44.762841Z",
  "upgrade_asset_handling": "FALLBACK",
  "voice_enabled": true
}

Summary

DIDs, or Numbers represent a Longcode (10DLC, Tollfree, International), Shortcode or Sender ID.

They are the primary resource for messaging and VoIP operations.

API

Update DID

PATCH /api/v1/numbers/{id} HTTP/1.1

Update some features on the specified number.

Path Parameters

Name Type Description
id String(format:uuid)! Number or ID

Request application/json

PATCH /api/v1/numbers/{id} HTTP/1.1
Accept: application/json
Content-Type: application/json
Content-Length: 505

{
  "data": {
    "description": "Test number used for XYZ.Corp\n",
    "forward_number": "12003004000",
    "help_message": "Available Keywords are: HELP, SUBSCRIBED, UNSUBSCRIBE.",
    "mms_enabled": true,
    "segment_overrides": [
      {
        "encoding": 0,
        "id": "c6be45e4-b7dd-412c-96c4-777e83fb9c48",
        "segment_threshold": 0,
        "target_reference_id": "us_tmobile"
      }
    ],
    "segment_threshold": 1,
    "upgrade_asset_handling": "FALLBACK"
  },
  "type": "number"
}

Response 200

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

{
  "associations": {
    "campaign": {
      "id": "01EH2Y28M6KXG14QMPM3HSP1Y0",
      "tcr_brand_id": "B000000",
      "tcr_campaign_id": "C000000"
    },
    "messaging_switch": {
      "id": "c6be45e4-b7dd-412c-96c4-777e83fb9c48"
    },
    "voice_switch": {
      "id": "c6be45e4-b7dd-412c-96c4-777e83fb9c48"
    }
  },
  "data": {
    "activated": true,
    "brand_name": "ACME Corp.",
    "description": "Test number used for XYZ.Corp\n",
    "forward_number": "12003004000",
    "help_message": "Available Keywords are: HELP, SUBSCRIBED, UNSUBSCRIBE.",
    "id": "c6be45e4-b7dd-412c-96c4-777e83fb9c48",
    "inserted_at": "2021-08-13T04:08:44.762841Z",
    "message_class": "A2P",
    "mms_enabled": true,
    "number": "12003004000",
    "rate_center": "KISSIMEE",
    "segment_overrides": [
      {
        "encoding": 0,
        "id": "c6be45e4-b7dd-412c-96c4-777e83fb9c48",
        "segment_threshold": 0,
        "target_reference_id": "us_tmobile"
      }
    ],
    "segment_threshold": 1,
    "sms_enabled": true,
    "state": "FL",
    "tier": "T1",
    "updated_at": "2021-08-13T04:08:44.762841Z",
    "upgrade_asset_handling": "FALLBACK",
    "voice_enabled": true
  },
  "type": "number"
}

Response 403

application/json
HTTP/1.1 403
Content-Type: application/json
Content-Length: 312

{
  "errors": [
    {
      "code": "access_denied.no_scope",
      "detail": "No scope available to user role",
      "params": {
        "action": "index",
        "level": "guest",
        "resource": "resource"
      },
      "sub_code": "none",
      "title": "Access Denied, no scope available"
    }
  ]
}

Response 404

application/json
HTTP/1.1 404
Content-Type: application/json
Content-Length: 314

{
  "errors": [
    {
      "code": "not_found",
      "detail": "The specified resource could not be found",
      "params": {
        "resource": {
          "id": "3fbb573a-6049-44a0-a12c-d3a1ffae0b69",
          "type": "user"
        }
      },
      "sub_code": "none",
      "title": "Not Found"
    }
  ]
}

List DIDs

GET /api/v1/numbers HTTP/1.1

Retrieve a list of numbers provisioned on the account.

Query Parameters

Name Type Description
first Integer Query Desc. first
last Integer Query Desc. last
after String Query Desc. after
before String Query Desc. before

Query Desc. first

The number of items to return starting from the 'after' cursor

Query Desc. last

The number of items to return behind the 'before' cursor

Query Desc. after

The cursor representing the starting point of a 'first' based paging

Query Desc. before

The cursor representing the starting point of a 'last' based paging

Request

GET /api/v1/numbers HTTP/1.1
Accept: application/json

Response 200

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

{
  "count": 1,
  "page_info": {
    "first": "string",
    "has_next_page": true,
    "has_previous_page": true,
    "last": "string"
  },
  "results": [
    {
      "associations": {
        "campaign": {
          "id": "01EH2Y28M6KXG14QMPM3HSP1Y0",
          "tcr_brand_id": "B000000",
          "tcr_campaign_id": "C000000"
        },
        "messaging_switch": {
          "id": "c6be45e4-b7dd-412c-96c4-777e83fb9c48"
        },
        "voice_switch": {
          "id": "c6be45e4-b7dd-412c-96c4-777e83fb9c48"
        }
      },
      "data": {
        "activated": true,
        "brand_name": "ACME Corp.",
        "description": "Test number used for XYZ.Corp\n",
        "forward_number": "12003004000",
        "help_message": "Available Keywords are: HELP, SUBSCRIBED, UNSUBSCRIBE.",
        "id": "c6be45e4-b7dd-412c-96c4-777e83fb9c48",
        "inserted_at": "2021-08-13T04:08:44.762841Z",
        "message_class": "A2P",
        "mms_enabled": true,
        "number": "12003004000",
        "rate_center": "KISSIMEE",
        "segment_overrides": [
          {
            "encoding": 0,
            "id": "c6be45e4-b7dd-412c-96c4-777e83fb9c48",
            "segment_threshold": 0,
            "target_reference_id": "us_tmobile"
          }
        ],
        "segment_threshold": 1,
        "sms_enabled": true,
        "state": "FL",
        "tier": "T1",
        "updated_at": "2021-08-13T04:08:44.762841Z",
        "upgrade_asset_handling": "FALLBACK",
        "voice_enabled": true
      },
      "type": "number"
    }
  ]
}

Response 403

application/json
HTTP/1.1 403
Content-Type: application/json
Content-Length: 312

{
  "errors": [
    {
      "code": "access_denied.no_scope",
      "detail": "No scope available to user role",
      "params": {
        "action": "index",
        "level": "guest",
        "resource": "resource"
      },
      "sub_code": "none",
      "title": "Access Denied, no scope available"
    }
  ]
}

Get DID

GET /api/v1/numbers/{id} HTTP/1.1

Lookup a number by ID or it's number

Path Parameters

Name Type Description
id String(format:uuid)! Number or ID

Request

GET /api/v1/numbers/{id} HTTP/1.1
Accept: application/json

Response 200

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

{
  "associations": {
    "campaign": {
      "id": "01EH2Y28M6KXG14QMPM3HSP1Y0",
      "tcr_brand_id": "B000000",
      "tcr_campaign_id": "C000000"
    },
    "messaging_switch": {
      "id": "c6be45e4-b7dd-412c-96c4-777e83fb9c48"
    },
    "voice_switch": {
      "id": "c6be45e4-b7dd-412c-96c4-777e83fb9c48"
    }
  },
  "data": {
    "activated": true,
    "brand_name": "ACME Corp.",
    "description": "Test number used for XYZ.Corp\n",
    "forward_number": "12003004000",
    "help_message": "Available Keywords are: HELP, SUBSCRIBED, UNSUBSCRIBE.",
    "id": "c6be45e4-b7dd-412c-96c4-777e83fb9c48",
    "inserted_at": "2021-08-13T04:08:44.762841Z",
    "message_class": "A2P",
    "mms_enabled": true,
    "number": "12003004000",
    "rate_center": "KISSIMEE",
    "segment_overrides": [
      {
        "encoding": 0,
        "id": "c6be45e4-b7dd-412c-96c4-777e83fb9c48",
        "segment_threshold": 0,
        "target_reference_id": "us_tmobile"
      }
    ],
    "segment_threshold": 1,
    "sms_enabled": true,
    "state": "FL",
    "tier": "T1",
    "updated_at": "2021-08-13T04:08:44.762841Z",
    "upgrade_asset_handling": "FALLBACK",
    "voice_enabled": true
  },
  "type": "number"
}

Response 403

application/json
HTTP/1.1 403
Content-Type: application/json
Content-Length: 312

{
  "errors": [
    {
      "code": "access_denied.no_scope",
      "detail": "No scope available to user role",
      "params": {
        "action": "index",
        "level": "guest",
        "resource": "resource"
      },
      "sub_code": "none",
      "title": "Access Denied, no scope available"
    }
  ]
}

Response 404

application/json
HTTP/1.1 404
Content-Type: application/json
Content-Length: 314

{
  "errors": [
    {
      "code": "not_found",
      "detail": "The specified resource could not be found",
      "params": {
        "resource": {
          "id": "3fbb573a-6049-44a0-a12c-d3a1ffae0b69",
          "type": "user"
        }
      },
      "sub_code": "none",
      "title": "Not Found"
    }
  ]
}

Updated 2026-08-12 · Generated from the Atlas OpenAPI spec.