External DID Object

The External DID object represents a phone number that is not owned or rented from CarrierX, but is instead registered by a customer for SMS and MMS messaging only. External DIDs allow customers to manage messaging traffic for phone numbers obtained from third party providers while using the CarrierX messaging platform.

Unlike standard DIDs, External DIDs:

Are not rentable through CarrierX inventory, they are customer-owned
Never support voice capabilities
Are managed through a dedicated set of endpoints
Have messaging capabilities that can be configured by the partner at registration time and enabled or disabled independently within the CarrierX platform, subject to the capabilities supported by the underlying carrier

External DIDs are validated against partner system restrictions (such as allowed prefixes or OCNs) at creation time. Once created, messaging can be enabled or disabled independently.

info

To be able to add an external DID to your account, contact CarrierX support.

External DID Object Attributes

The fields listed in the table below will be returned in a JSON object when a successful request has been made.

Attribute	Data Type	Description
active_capabilities read only	integer	The phone number enabled (activated) capabilities. Criteria are similar to the `capabilities` attribute below. Note that this attribute is read-only, fully managed by the system and its status depends on whether SMS/MMS is enabled for a DID. By default, newly registered external DIDs have `active_capabilities` set to the same value as capabilities, but messaging services may still be administratively disabled until explicitly enabled for the number. To activate the SMS/MMS capabilities on your external DIDs, you need to enable them. With non-activated capabilities an error will be returned when trying to send an SMS/MMS. See also SMS/MMS enablement.
attributes create update	object	Custom External DID attributes. Can be used for various additional purposes.
callback_url create update	string	The callback URL to receive SMS-related events for this external DID.
campaign_sid read only	string	The secure ID of the 10DLC campaign associated with the external DID.
capabilities create	integer	Integer representation of a bit mask describing the initial supported capabilities of the external DID. Capabilities represent what this external DID is potentially capable of: receiving, sending SMS, MMS, etc.: `1` — SMS IN `2` — SMS OUT `8` — MMS IN `16` — MMS OUT For example, a value of `3` represents SMS (IN + OUT) capabilities. This attribute can be set on external DID registration depending on your messaging needs. Voice capabilities are not allowed and trying to set them will result in an error. By default `active_capabilities` are set to the same value as `capabilities` when an external DID is registered. However, messaging is still disabled on all newly-registed external DIDs. To enable it, you need to send a `POST` request to the enablement endpoint. Note that while you can set `capabilities` during external DID registration, they cannot be modified afterwards. If you need to change the capabilities of an existing external DID, you would need to delete it and register a new one with the desired capabilities and the same phone number. warning When configuring messaging capabilities for an external DID, you need to make sure that your external phone number can actually support the capabilities you set. For example, if you set MMS capabilities for an external DID but the underlying carrier does not support MMS for that number, you will not be able to send or receive MMS messages through that external DID.
classification_sid read only	string	The phone number classification secure ID, which can be set to one of the DID Classification object secure IDs.
country_code read only	string	The ISO 3166-1 alpha-3 country code of this external DID. This field is assigned automatically.
external_did_sid read only	string	The external DID secure ID.
in_country_format read only	string	The external DID represented in a national format.
international_format read only	string	The external DID represented in an international format.
lata read only	string	Applicable for US numbers only. LATA: Local Access and Transport Area (a geographic code representing the location of the call origination) associated with the external DID.
locality read only	string	The locality or city associated with the external DID.
lrn_sid read only	string	The secure ID of the Location Routing Number to which this external DID belongs.
name create update	string	The human-readable name assigned to the external DID.
ocn read only	string	Applicable for US numbers only. The operating company number (OCN) from the LERG associated with the Location Routing Number (LRN) currently assigned to this external DID.
ocn_block read only	string	Applicable for US numbers only. The operating company number (OCN) from the LERG assigned directly to this external DID. This value represents the original operating company for the phone number itself and does not take LRN-based changes into account.
partner_sid read only	string	The secure ID of the partner associated with the external DID.
phonenumber create	string	The phone number of the external DID in E.164 format.
state read only	string	The state or province associated with the external DID.
status read only	string	The current DID status. Values returned in this field are: `assigned` for external DIDs registered to the partner.
string_key_1 create update	string	A user-defined string key.
string_key_2 create update	string	A user-defined string key.
underlying_carrier_sid create	string	The secure ID of the underlying carrier associated with this External DID.

Capabilities vs. Active Capabilities

As with all DIDs, messaging support on external DIDs is expressed using the capabilities and active_capabilities fields, which have distinct meanings and must not be conflated.

capabilities

Indicates which capabilities a phone number can technically support.
Never includes voice for external DIDs.
Unlike for internal CarrierX DIDs, for external DIDs, partners can configure capabilities themselves. capabilities are set at the time of external DID registration. The only limitation is that voice capabilities cannot be set for external DIDs.

warning

When configuring messaging capabilities for an external DID, you need to make sure that your external phone number can actually support the capabilities you set. For example, if you set MMS capabilities for an external DID but the underlying carrier does not support MMS for that number, you will not be able to send or receive MMS messages through that external DID.

active_capabilities

Indicates which capabilities are currently enabled in the CarrierX network.
Always read-only (status depends on whether messaging is enabled or disabled).
Partners can enable or disable messaging services (SMS/MMS) for external DIDs, which directly affects active_capabilities.

As a result:

capabilities defines the upper bound of what the number can support.
active_capabilities reflects the current operational state within CarrierX.

Sample External DID Object

{
    "active_capabilities": 3,
    "attributes": {},
    "callback_url": "https://example.com/sms-callback",
    "campaign_sid": null,
    "capabilities": 3,
    "classification_sid": null,
    "country_code": "USA",
    "external_did_sid": "8efbf9d0-3872-4f5c-b4b6-e6ba64176f30",
    "in_country_format": null,
    "international_format": null,
    "lata": "476",
    "locality": "BIRMINGHAM",
    "lrn_sid": null,
    "name": "External DID 102505",
    "ocn": "XXXX",
    "ocn_block": "XXXX",
    "partner_sid": "a13c384d-cf78-46fd-ab8b-1056b49291ba",
    "phonenumber": "12059051025",
    "state": "AL",
    "status": "assigned",
    "string_key_1": null,
    "string_key_2": null,
    "underlying_carrier_sid": "61ced070-8dad-43b4-b5e6-f7d61f7aeb65"
}

External DID Object Attributes​

Capabilities vs. Active Capabilities​

Sample External DID Object​

External DID Object Attributes

Capabilities vs. Active Capabilities

Sample External DID Object