Enable or Disable SMS/MMS Messaging for External DID

This request enables or disables SMS/MMS messaging for an external DID.

post	/phonenumber/external_dids/{external_did_sid}/messaging

Sample

A sample POST request to enable or disable SMS/MMS for the external DID:

curl -X POST \
'https://api.carrierx.com/core/v2/phonenumber/external-dids/f3125c23-29dd-41b7-5dbc-89edba59230d/messaging' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer 5ebe03d6-8b2b-44ad-bf65-72d4f1491dda' \
--data-binary '{
  "campaign_sid": "fef13cdd-2f65-4ed8-8272-de2a940d0cb5",
  "enabled": true,
  "type": "a2p"
}'

Response

200 status code with information about the status of SMS/MMS enablement for the external DID:

{
  "campaign_external_id": "CVN1LXI",
  "campaign_sid": "fef13cdd-2f65-4ed8-8272-de2a940d0cb5",
  "did_sid": "f3125c23-29dd-41b7-5dbc-89edba59230d",
  "enabled": true,
  "p2p_nnid": null,
  "status": "in_progress",
  "type": "a2p"
}

tip

If no SMS/MMS capabilities are set for this DID, i.e. if this DID has only voice capabilities, the request will return the 404 status code with the no item error message.

{
    "message": "no item error",
    "errors": [
        {
            "field": null,
            "message": "cannot find item by sid",
            "reference_sid": null
        }
    ]
}

Required Scopes

To enable SMS/MMS messaging for an external DID, the partner must have one of the following scopes enabled:

• phonenumber.create
• phonenumber.manage

Path Arguments

Parameter	Data Type	Description
external_did_sid required	string	The external DID secure ID.

Query Arguments

Parameter	Data Type	Description
force	boolean	When set to true, allows direct updates to the DID messaging configuration including type, campaign_sid, or p2p_nnid in a single POST request, bypassing the standard two-step disable-then-re-enable process. Use force=true to: Update type (e.g., a2p ↔ p2p), campaign_sid, or p2p_nnid without first disabling messaging (enabled must remain true). Apply changes immediately in one operation. Default behavior (force=false or omitted) requires the standard two-request workflow: Disable messaging ("enabled": false). Re-enable ("enabled": true) with the updated type, campaign_sid, or p2p_nnid.

Body Arguments

JSON representation of the fields and values of the DID Messaging Enablement object to be created or updated.

Required fields to enable or disable messaging for the phone number:

• campaign_sid if the messaging type is a2p
• enabled
• p2p_nnid if the messaging type is p2p

Fields that can be modified are:

• campaign_sid if the messaging type is a2p
• enabled
• p2p_nnid if the messaging type is p2p
• type (if p2p is enabled for your DIDs, see note below)

note

By default, partners are only enabled for a2p messaging. To be able to change the type from a2p to p2p contact CarrierX Technical Support at support@carrierx.com to enable p2p for your DIDs.

For a complete list of object attributes, see the External DID Messaging Enablement object.

Response

A successful response will be the 200 OK code and the DID status will be one of the following:

• in_progress, meaning that the phone number is being processed for message enablement. Sometimes, this process may take up to several minutes. While the status is in_progress, no further messaging update requests are accepted for this DID. If a POST request is sent to a DID with the in_progress status, a 409 error will be returned.
• enabled, meaning that SMS/MMS messaging is enabled for this phone number.
• disabled, meaning that SMS/MMS messaging is disabled for this phone number.
• failed, meaning that some error has occurred in the process.
• pending_port_in, meaning that voice routing is enabled, messaging enablement request is acknowledged, but completion is blocked until the number has finished porting. The system periodically (every 10 minutes) checks the number's OCN against the expected value. When porting completes, the status automatically advances to in_progress → enabled.

To be notified when the messaging status changes for a particular DID, you can set up the phonenumber_messaging_update callback.