Skip to main content

Register External DID

This request registers an External DID for a partner. External DIDs are non-CarrierX phone numbers rented by the partners from 3rd party providers, managed outside of CarrierX voice infrastructure and are intended for SMS/MMS messaging only. Voice capabilities are not supported for External DIDs.

post /phonenumber/external_dids

When registering an External DID, the partner provides the phone number and its capabilities, and CarrierX creates a corresponding External DID object in the system. The External DID becomes available for SMS/MMS messaging immediately after registration.

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.

Sample​

A sample POST request to register an External DID for a partner:

curl -X POST \
'https://api.carrierx.com/core/v2/phonenumber/external_dids' \
-H 'Content-Type: application/json' \
--data-binary '{"phonenumber":"12059051025","capabilities":3,"callback_url":"https://example.com/sms-callback","underlying_carrier_sid": "61ced070-8dad-43b4-b5e6-f7d61f7aeb65"}'
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'

Response​

200 status code with a serialized copy of the 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"
}

After a successful request, the External DID is registered and immediately available for SMS/MMS messaging. But first, make sure that messaging is enabled, and if not, enable it by sending a POST request to the API. However, the general rule is that upon external DID registration, active_capabilities are set to the same value as capabilities, which means that if you set SMS/MMS capabilities during registration, the External DID will be ready for messaging right away without the need for additional enablement steps.

Required Scopes​

To create an External DID object, the partner must have one of the following scopes enabled:

  • phonenumber.manage
  • phonenumber.create

Body Arguments​

JSON representation of the fields and values of the External DID object to be created.

Required fields to register an external DID are:

  • phonenumber - must be provided in E.164 format without the + prefix.
  • capabilities - must include at least one messaging capability (SMS or MMS) and cannot include voice capabilities. For example, if you want to set both SMS and MMS capabilities, the value of this field must be 27 (3 for SMS IN/OUT + 24 for MMS IN/OUT = 27). Note, that once created, the External DID capabilities cannot be modified.
  • underlying_carrier_sid - required only if no default underlying carrier is configured for your partner account. If you are unsure whether a default underlying carrier is set, contact CarrierX technical support. If a default underlying carrier is configured for your account, you can omit this field and the External DID will be automatically associated with the default underlying carrier upon registration. If you don't have a default underlying carrier and you also don't provide underlying_carrier_sid in the request body, the request will fail with an error.

Refer to this table to view all fields that appear in the External DID object.