Create SMS Trunk#

Creates an SMS trunk.

The configuration object is required. Its type decides which configuration attributes the trunk takes and whether the trunk handles inbound messages, outbound messages, or both. The type cannot be changed after the trunk is created.

Request#

HTTP Method: POST

URI Path: /v3/sms_trunks

Request Body Object Attributes#

Name

Type

Nullable

Is Required?

Description

name

string

No

Yes

Friendly name of the SMS trunk. Must be unique among the SMS trunks and SMS trunk groups of the account.

external_reference_id

string

Yes

No

Optional identifier for the SMS trunk in the customer’s external system. Maximum length is 100 characters.

blocked

boolean

No

No

When true, the trunk does not handle messages. Default value is false.

priority

integer

Yes

No

Routing priority of the trunk within its SMS trunk group. The range is 0-32767. On sms_to_email, http_in, smpp_esme, and smpp_smsc trunks, the value 100 is used when priority is omitted or null. On http_out trunks, priority must be omitted or null.

allow_any_did_as_source

boolean

No

No

When true, any DID of the account can be used as the source address of messages sent through the trunk, and outgoing_dids must be empty. Can be enabled only on http_out, smpp_esme, and smpp_smsc trunks. Default value is false.

configuration

object

No

Yes

Trunk configuration object with type and attributes. type is one of sms_to_email, http_in, http_out, smpp_esme, smpp_smsc. See Configuration Attributes by Type.

Request Body Object Relationships#

Name

Type

Description

outgoing_dids

To many

DIDs allowed as the source address of messages sent through the trunk. Applies to http_out, smpp_esme, and smpp_smsc trunks. Must be empty while allow_any_did_as_source is true. Only DIDs of the account that support the p2p feature are accepted; a DID awaiting registration is rejected.

sms_trunk_group

To one

The SMS Trunk Group the trunk joins, or null. Not allowed on http_out trunks.

Inbound routing is not configured on the trunk: to route a DID to the trunk, update the sms_trunk relationship of the DID.

Configuration Attributes by Type#

Send the configuration attributes in configuration.attributes. Read-only attributes (auth_name and auth_password of http_out trunks, system_id and password of smpp_esme trunks) are generated by DIDWW and must not be sent. An attribute that does not belong to the selected type is rejected. For the returned attributes, see Configuration.

Name

Type

Nullable

Is Required?

Description

send_to

string

No

Yes

Recipient email address.

subject

string

No

Yes

Email subject template.

message

string

No

Yes

Email body template.

Examples#

http

 1POST /v3/sms_trunks HTTP/1.1
 2Host: api.didww.com
 3Content-Type: application/vnd.api+json
 4Accept: application/vnd.api+json
 5Authorization: Bearer [access token]
 6
 7{
 8  "data": {
 9    "type": "sms_trunks",
10    "attributes": {
11      "name": "Inbound email",
12      "configuration": {
13        "type": "sms_to_email",
14        "attributes": {
15          "send_to": "sms@example.com",
16          "subject": "New SMS from {SMS_SRC_ADDR}",
17          "message": "{SMS_TIME} {SMS_SRC_ADDR} -> {SMS_DST_ADDR}: {SMS_TEXT}"
18        }
19      }
20    }
21  }
22}

curl

1curl -i -X POST https://api.didww.com/v3/sms_trunks -H "Accept: application/vnd.api+json" -H "Content-Type: application/vnd.api+json" -H "Authorization: Bearer [access token]" --data-raw '{"data": {"attributes": {"configuration": {"attributes": {"message": "{SMS_TIME} {SMS_SRC_ADDR} -> {SMS_DST_ADDR}: {SMS_TEXT}", "send_to": "sms@example.com", "subject": "New SMS from {SMS_SRC_ADDR}"}, "type": "sms_to_email"}, "name": "Inbound email"}, "type": "sms_trunks"}}'

response

 1HTTP/1.1 201 Created
 2Content-Type: application/vnd.api+json
 3
 4{
 5  "data": {
 6    "id": "0b1f6c2e-5d4a-4f8e-9c3b-7a2d1e6f4b90",
 7    "type": "sms_trunks",
 8    "attributes": {
 9      "name": "Inbound email",
10      "external_reference_id": null,
11      "blocked": false,
12      "priority": 100,
13      "allow_any_did_as_source": false,
14      "allow_in": true,
15      "allow_out": false,
16      "created_at": "2026-10-22T09:15:42.118Z",
17      "updated_at": "2026-10-22T09:15:42.118Z",
18      "configuration": {
19        "type": "sms_to_email",
20        "attributes": {
21          "send_to": "sms@example.com",
22          "subject": "New SMS from {SMS_SRC_ADDR}",
23          "message": "{SMS_TIME} {SMS_SRC_ADDR} -> {SMS_DST_ADDR}: {SMS_TEXT}"
24        }
25      }
26    },
27    "relationships": {
28      "outgoing_dids": {
29        "links": {
30          "self": "https://api.didww.com/v3/sms_trunks/0b1f6c2e-5d4a-4f8e-9c3b-7a2d1e6f4b90/relationships/outgoing_dids",
31          "related": "https://api.didww.com/v3/sms_trunks/0b1f6c2e-5d4a-4f8e-9c3b-7a2d1e6f4b90/outgoing_dids"
32        }
33      },
34      "incoming_dids": {
35        "links": {
36          "self": "https://api.didww.com/v3/sms_trunks/0b1f6c2e-5d4a-4f8e-9c3b-7a2d1e6f4b90/relationships/incoming_dids",
37          "related": "https://api.didww.com/v3/sms_trunks/0b1f6c2e-5d4a-4f8e-9c3b-7a2d1e6f4b90/incoming_dids"
38        }
39      },
40      "sms_trunk_group": {
41        "links": {
42          "self": "https://api.didww.com/v3/sms_trunks/0b1f6c2e-5d4a-4f8e-9c3b-7a2d1e6f4b90/relationships/sms_trunk_group",
43          "related": "https://api.didww.com/v3/sms_trunks/0b1f6c2e-5d4a-4f8e-9c3b-7a2d1e6f4b90/sms_trunk_group"
44        }
45      },
46      "sender_id_verifications": {
47        "links": {
48          "self": "https://api.didww.com/v3/sms_trunks/0b1f6c2e-5d4a-4f8e-9c3b-7a2d1e6f4b90/relationships/sender_id_verifications",
49          "related": "https://api.didww.com/v3/sms_trunks/0b1f6c2e-5d4a-4f8e-9c3b-7a2d1e6f4b90/sender_id_verifications"
50        }
51      }
52    }
53  },
54  "meta": {
55    "api_version": "2026-11-19"
56  }
57}

Other Responses#

Code

Success

Description

422

No

Validation Error Object

400

No

Bad Request. Also returned with the title Quota limit reached when the account has reached its limit of SMS trunks and SMS trunk groups.

401

No

Unauthorized

403

No

The access token carries the read scope, which does not cover this method (title Insufficient scope). The response carries WWW-Authenticate: Bearer error="insufficient_scope". See Scopes.

429

No

The request budget of the account for the current window is spent (too_many_requests). Retry-After gives the number of seconds to wait.