DID Object

The DID (Direct Inward Dialing) object represents a phone number and all of its associated data within the CarrierX platform. Each DID includes identifying information, provisioning details, capabilities, and ownership metadata.

DIDs can be queried, rented, updated, and managed through the API. Their configuration defines how the number behaves for voice and messaging, what partner it belongs to, and what carrier and trunk group handle its routing.

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. If messaging is disabled for a DID, this attribute will be set to 4 if the DID has voice capabilities or to 0 for DIDs without voice capabilities. To activate the SMS/MMS capabilities of your rented DIDs, you need to enable them. See also SMS/MMS enablement.
attributes createupdate	object	Custom DID attributes. Can be used for various additional purposes.
callback_url createupdate	string	The callback URL to receive events for SMS.
campaign_sid read only	string	The secure ID of the 10DLC campaign associated with the DID.
capabilities read only	integer	The phone number supported capabilities. Capabilities represent what this DID is potentially capable of: receiving, sending SMS, MMS, voice calls, etc. This field accepts numerical values. To enable more than one capability, add the corresponding integers together. The following are the numerical values for each capability: 1 for receiving SMS 2 for sending SMS 4 for voice 8 for receiving MMS 16 for sending MMS To enable receiving SMS and voice, add 1 and 4 together to make 5. The maximum value for this field is 31 (1 + 2 + 4 + 8 + 16) for all capabilities: SMS (receiving and sending), voice, and MMS (receiving and sending). Note, that by default, SMS/MMS messaging capabilities are disabled for all rented DIDs. To enable these capabilities, you need to have them activated. With non-activated capabilities an error will be returned when trying to send an SMS/MMS. See also the active_capabilities attribute above. The value of this field can be changed by administrators only. Contact CarrierX support if you need to update this field.
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 code of this DID. This field is assigned automatically.
did_group_sid createupdate	string	The DID group secure ID.
did_sid read only	string	The DID secure ID.
in_country_format read only	string	The DID in a national format.
international_format read only	string	The DID in an international format.
lata read only	string	LATA: Local Access and Transport Area, a geographic code representing the location of the call origination.
locality read only	string	The locality or city of the DID.
lrn_sid read only	string	The secure ID of the Location Routing Number assigned to this DID.
name createupdate	string	The DID name. By default, it is set to the local-format version of the phone number (e.g., (808) 384-2079).
ocn read only	string	The operating company number (OCN) from the LERG associated with the Location Routing Number (LRN) currently assigned to this DID.
ocn_block read only	string	The operating company number (OCN) from the LERG assigned directly to this DID. This value represents the original operating company for the phone number itself and does not take LRN-based changes into account.
partner read only	object	The Partner object associated with the DID. This field is displayed if with_related is set to true when performing the GET queries.
partner_sid read only	string	The secure ID of the partner associated with the DID.
pending_port_in read only	string	A 4-character string representing the expected new OCN (Operating Company Number) for a new phone number that is being ported to a new carrier. The system polls the database every 10 minutes to check if porting has finished. Once the number's OCN matches the expected value, the system automatically clears the pending_port_in field and proceeds with messaging enablement. When this field is not null, it means that messaging enablement request is acknowledged, but completion is blocked until the number has finished porting.
phonenumber create	string	The phone number for the DID in the E.164 format.
porting_pin createupdate	string	A random 6-digit PIN code automatically assigned to a DID when it is rented. The porting PIN is used to verify requests for DID porting. The PIN code can be changed at any time.
price read only	number	The price of the DID.
state read only	string	The state or province of the DID.
status read only	string	The current DID status. Values accepted in this field are: aging for DIDs released but not yet available. assigned for DIDs assigned to the partner. available for DIDs available for renting. deleted for DIDs that have been deleted from the system. pending_assignment for DIDs in the process of being assigned (approved request, but not yet active/attached to partner's account).
string_key_1 createupdate	string	A user-defined string key.
string_key_2 createupdate	string	A user-defined string key.
transformations createupdate	array of objects	The transformations that are applied to the DID. Refer to the transformations section for more information.
trunk_group_sid createupdate	string	The secure ID of the trunk group associated with the DID.
underlying_carrier_sid read only	string	The Carrier ID referencing the underlying carrier that owns this DID while in the inventory.

Capabilities vs. Active Capabilities

There are two DID Object attributes, capabilities and active_capabilities, which describe what a phone number can support and what is currently enabled in the CarrierX network. Although they look similar, they serve different purposes and must not be conflated.

capabilities

• Indicates which services a phone number can technically support (for example: voice, SMS, MMS).
• Defined by the number itself (for example, by number type, provider, and routing) and available immediately after the DID is rented.
• Can be modified only by administrators, not by partners.
• Always read-only from the partner perspective.

active_capabilities

• Indicates which services are currently enabled and operational in the CarrierX network.
• Derived from the current messaging enablement state.
• Always read-only from the partner perspective (status depends on whether messaging is enabled or disabled).
• Partners can enable or disable messaging services (SMS/MMS) for rented DIDs, which indirectly updates active_capabilities.

As a result:

• capabilities defines the upper bound of what the phone number can ever support.
  • Before renting a DID, partners can look up available phone numbers and filter results by capabilities to select numbers that meet their requirements.
• active_capabilities reflects the current operational state of the number inside the CarrierX platform and may change over time as messaging is enabled or disabled.

Sample DID Object

{
    "active_capabilities": 4,
    "attributes": {},
    "callback_url": null,
    "campaign_sid": null,
    "capabilities": 7,
    "classification_sid": "17f4d954-d635-4cda-912b-c2a2fa3a6860",
    "country_code": "USA",
    "did_group_sid": null,
    "did_sid": "f448e2c3-88c1-4cd1-8cf2-3567c16e0794",
    "in_country_format": "(516) 206-5575",
    "international_format": "+1 516-206-5575",
    "lata": null,
    "locality": "NEW YORK",
    "lrn_sid": null,
    "name": "(516) 206-5575",
    "ocn": "251F",
    "ocn_block": "251F",
    "partner_sid": "e00430c3-a7d0-4666-ab5c-f7202448382f",
    "pending_port_in": null,
    "phonenumber": "15162065575",
    "porting_pin": null,
    "price": "0.6",
    "state": "NY",
    "status": "assigned",
    "string_key_1": null,
    "string_key_2": null,
    "transformations": [],
    "trunk_group_sid": null,
    "underlying_carrier_sid": "40a8c9cf-8b08-4c21-a3e3-952c65ee892d"
}

note

When determining the callback URL, the system will use the first non-empty value from:

1. the callback_url field of the DID object;
2. the callback_url field of the DID Group object;
3. the callbacks.sms field of the Partner object.