Enable or Disable SMS/MMS Messaging for DID

This request enables or disables SMS/MMS messaging for a rented DID.

post	/phonenumber/dids/{did_sid}/messaging

Sample

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

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

Response

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

{
    "campaign_external_id": "CVN1LXI",
    "campaign_sid": "fef13cdd-2f65-4ed8-8272-de2a940d0cb5",
    "did_sid": "f3125c23-29dd-41b7-5dbc-89edba59230d",
    "enabled": true,
    "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
        }
    ]
}

note

Note that for external DIDs SMS/MMS messaging cannot be updated. A POST request for an external DID will return a 422 object validation error. For external DIDs capabilities are activated automatically, i.e. active_capabilities and capabilities match by default.

Required Scopes

To enable SMS/MMS messaging for a rented DID, the partner must have the following scopes enabled:

• phonenumber.create
• phonenumber.manage

Path Arguments

Parameter	Data Type	Description
did_sid required	string	The 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

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 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.

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