Messaging Switch
A record representing a Switch configuration, supporting SMS and MMS protocols.
Note: The API key provided in the Authorization header must have the apik_ prefix, and requires the API key to have a user with sufficient permissions assigned to it.
Schema
Section titled “Schema”Wrap all create/update fields in a top-level data object; "type": "switch" is optional alongside it. Requirements and defaults below apply to creation; on update, omitted fields retain their current values.
| Name | Type | Description |
|---|---|---|
id |
ULID | Generated. Unique identifier; response only |
name |
String | Required. Display name or canonical name of the Switch; nonblank, 1–64 characters, unique within the account |
inserted_at |
String (format: datetime) | Generated. Creation timestamp; response only |
updated_at |
String (format: datetime) | Generated. Last update timestamp; response only |
sms_auth_method |
Enum:String | Optional. Auth method for SMS. NONE - no auth; BASIC - uses identity + secret; BEARER - uses secret/token only Default: NONE. |
sms_enabled |
Boolean | Optional. Whether the switch can process SMS messages Default: false. |
sms_protocol |
Enum:String | Optional. Protocol for delivering inbound SMS. NONE - discard; HTTP - deliver over HTTP; MAILBOX - write to internal mailbox for manual retrieval via API; EMAIL - deliver via email; SMTP - deliver over SMTP Default: NONE. |
sms_endpoints |
Array:String | Optional. Delivery targets. When enabled: HTTP requires 1–5 HTTP(S) URLs; EMAIL requires 1–128 recipients; SMTP requires 1–5 SMTP(S) URLs. NONE and MAILBOX clear the list. Default: []. |
sms_identity |
String | Optional. Username; required for BASIC when enabled. Cleared for BEARER when enabled. Default: null. |
sms_message_format |
Enum:String | Optional. Payload format for SMS (primarily HTTP). MERCURY_SMS_1_0 or LEGACY_SMS_2_0 Default: MERCURY_SMS_1_0. |
sms_secret |
String | Optional. Password or token; required for BASIC or BEARER when enabled. Default: null. |
mms_auth_method |
Enum:String | Optional. Auth method for MMS. NONE - no auth; BASIC - uses identity + secret; BEARER - uses secret/token only Default: NONE. |
mms_enabled |
Boolean | Optional. Whether the switch can process MMS messages Default: false. |
mms_protocol |
Enum:String | Optional. Transport protocol for MMS delivery. NONE - discard; HTTP - deliver over HTTP; EMAIL - deliver via email; SMTP - deliver raw over SMTP Default: NONE. |
mms_endpoints |
Array:String | Optional. Delivery targets. When enabled: HTTP requires 1–5 HTTP(S) URLs; EMAIL requires 1–128 recipients; SMTP requires 1–5 SMTP(S) URLs. NONE clears the list. Default: []. |
mms_identity |
String | Optional. Username; required for BASIC when enabled. Cleared for BEARER when enabled. Default: null. |
mms_message_format |
Enum:String | Optional. Payload format for MMS (primarily HTTP). MERCURY_MMS_1_0 or LEGACY_MMS_2_0 Default: MERCURY_MMS_1_0. |
mms_secret |
String | Optional. Password or token; required for BASIC or BEARER when enabled. Default: null. |
Examples
Section titled “Examples”Create new switch
Section titled “Create new switch”Minimum HTTP POST configuration for SMS and MMS in the default Mercury 1.0 JSON formats, without authentication. Replace the URL and attach the created Switch to the receiving DID(s).
Request:
POST https://api.swift-api.com/api/v1/switches HTTP/1.1Accept: application/json, text/plainContent-Type: application/jsonAuthorization: Bearer apik_ABC123
{ "data": { "name": "Pager Switch", "sms_enabled": true, "sms_protocol": "HTTP", "sms_endpoints": [ "https://example.com/path/for/inbound" ], "mms_enabled": true, "mms_protocol": "HTTP", "mms_endpoints": [ "https://example.com/path/for/inbound" ] }}Success response:
HTTP/1.1 201Content-Type: application/jsonContent-Length: 402
{ "data": { "id": "01J0CRVTXX9KBD9NWS02R5R8RT", "inserted_at": "2024-06-14T00:00:00.000000Z", "mms_auth_method": "NONE", "mms_enabled": true, "mms_endpoints": [ "https://example.com/path/for/inbound" ], "mms_identity": null, "mms_message_format": "MERCURY_MMS_1_0", "mms_protocol": "HTTP", "mms_secret": null, "name": "Pager Switch", "sms_auth_method": "NONE", "sms_enabled": true, "sms_endpoints": [ "https://example.com/path/for/inbound" ], "sms_identity": null, "sms_message_format": "MERCURY_SMS_1_0", "sms_protocol": "HTTP", "sms_secret": null, "updated_at": "2024-06-14T00:00:00.000000Z" }, "type": "switch"}Invalid parameter response (can apply to any parameter):
HTTP/1.1 422Content-Type: application/jsonContent-Length: 402
{ "errors": [ { "code": "invalid_parameter", "source": { "in": "body", "pointer": "/data/name" }, "detail": "has already been taken", "sub_code": "constraint.unique" } ]}Create switch for sub-account
Section titled “Create switch for sub-account”Request:
POST https://api.swift-api.com/api/v1/accounts/{account_id}/switchesAccept: application/json, text/plainContent-Type: application/jsonAuthorization: Bearer apik_ABC123
{ "data": { "name": "Pager Switch", "sms_enabled": true, "sms_protocol": "HTTP", "sms_endpoints": [ "https://example.com/path/for/inbound" ], "mms_enabled": true, "mms_protocol": "HTTP", "mms_endpoints": [ "https://example.com/path/for/inbound" ] }}Success response:
HTTP/1.1 201Content-Type: application/jsonContent-Length: 402
{ "data": { "id": "01J0CRVTXX9KBD9NWS02R5R8RT", "inserted_at": "2024-06-14T00:00:00.000000Z", "mms_auth_method": "NONE", "mms_enabled": true, "mms_endpoints": [ "https://example.com/path/for/inbound" ], "mms_identity": null, "mms_message_format": "MERCURY_MMS_1_0", "mms_protocol": "HTTP", "mms_secret": null, "name": "Pager Switch", "sms_auth_method": "NONE", "sms_enabled": true, "sms_endpoints": [ "https://example.com/path/for/inbound" ], "sms_identity": null, "sms_message_format": "MERCURY_SMS_1_0", "sms_protocol": "HTTP", "sms_secret": null, "updated_at": "2024-06-14T00:00:00.000000Z" }, "type": "switch"}Update Switch
Section titled “Update Switch”Request:
PATCH https://api.swift-api.com/api/v1/switches/{id} HTTP/1.1Accept: application/json, text/plainContent-Type: application/jsonAuthorization: Bearer apik_ABC123
{ "data": { "mms_auth_method": "NONE", "mms_enabled": false, "mms_endpoints": [ "https://example.com/path/for/inbound" ], "mms_identity": "string", "mms_message_format": "MERCURY_MMS_1_0", "mms_protocol": "HTTP", "mms_secret": "string", "name": "Pager Switch", "sms_auth_method": "NONE", "sms_enabled": false, "sms_endpoints": [ "https://example.com/path/for/inbound" ], "sms_identity": "string", "sms_message_format": "MERCURY_SMS_1_0", "sms_protocol": "HTTP", "sms_secret": "string" }, "type": "switch"}Success response:
HTTP/1.1 200Content-Type: application/jsonContent-Length: 402
{ "data": { "id": "01J0CRVTXX9KBD9NWS02R5R8RT", "inserted_at": "2024-06-14T00:00:00.000000Z", "mms_auth_method": "NONE", "mms_enabled": false, "mms_endpoints": [ "https://example.com/path/for/inbound" ], "mms_identity": "string", "mms_message_format": "MERCURY_MMS_1_0", "mms_protocol": "HTTP", "mms_secret": "string", "name": "Pager Switch", "sms_auth_method": "NONE", "sms_enabled": false, "sms_endpoints": [ "https://example.com/path/for/inbound" ], "sms_identity": "string", "sms_message_format": "MERCURY_SMS_1_0", "sms_protocol": "HTTP", "sms_secret": "string", "updated_at": "2024-06-14T00:00:00.000000Z" }, "type": "switch"}Invalid parameter response (can apply to any parameter):
HTTP/1.1 422Content-Type: application/jsonContent-Length: 402
{ "errors": [ { "code": "invalid_parameter", "source": { "in": "body", "pointer": "/data/name" }, "detail": "has already been taken", "sub_code": "constraint.unique" } ]}Not found response:
HTTP/1.1 404Content-Type: application/jsonContent-Length: 402
{ "errors": [ { "code": "not_found", "title": "Not Found", "params": { "resource": { "id": "01J0CRVTXX9KBD9NWS02R5R8RT", "type": "switch" } }, "sub_code": "none" } ]}Delete switch
Section titled “Delete switch”Request:
DELETE https://api.swift-api.com/api/v1/switches/{id} HTTP/1.1Authorization: Bearer apik_ABC123Success response (returns the deleted switch object):
HTTP/1.1 200Content-Type: application/jsonContent-Length: 402
{ "data": { "id": "01J0CRVTXX9KBD9NWS02R5R8RT", "inserted_at": "2024-06-14T00:00:00.000000Z", "mms_auth_method": "NONE", "mms_enabled": false, "mms_endpoints": [ "https://example.com/path/for/inbound" ], "mms_identity": "string", "mms_message_format": "MERCURY_MMS_1_0", "mms_protocol": "HTTP", "mms_secret": "string", "name": "Pager Switch", "sms_auth_method": "NONE", "sms_enabled": false, "sms_endpoints": [ "https://example.com/path/for/inbound" ], "sms_identity": "string", "sms_message_format": "MERCURY_SMS_1_0", "sms_protocol": "HTTP", "sms_secret": "string", "updated_at": "2024-06-14T00:00:00.000000Z" }, "type": "switch"}Not found response:
HTTP/1.1 404Content-Type: application/jsonContent-Length: 402
{ "errors": [ { "code": "not_found", "title": "Not Found", "params": { "resource": { "id": "01J0CRVTXX9KBD9NWS02R5R8RT", "type": "switch" } }, "sub_code": "none" } ]}List switches
Section titled “List switches”Lists all the switches associated with the parent account, and all sub-accounts.
Request:
GET https://api.swift-api.com/api/v1/switchesAuthorization: Bearer apik_ABC123Success response (paginated list of switches):
HTTP/1.1 200Content-Type: application/jsonContent-Length: 402
{ "data": { "items": [ { "data": { /* Switch object */ }, "type": "switch" } ], "page_info": { "after": "string", "before": "string", "limit": 0, "total": 0 } }, "type": "list"}Get switch
Section titled “Get switch”GET https://api.swift-api.com/api/v1/switches/{id}Authorization: Bearer apik_ABC123Success response:
HTTP/1.1 200Content-Type: application/jsonContent-Length: 402
{ "data": { "id": "01J0CRVTXX9KBD9NWS02R5R8RT", "inserted_at": "2024-06-14T00:00:00.000000Z", "mms_auth_method": "NONE", "mms_enabled": false, "mms_endpoints": [ "https://example.com/path/for/inbound" ], "mms_identity": "string", "mms_message_format": "MERCURY_MMS_1_0", "mms_protocol": "HTTP", "mms_secret": "string", "name": "Pager Switch", "sms_auth_method": "NONE", "sms_enabled": false, "sms_endpoints": [ "https://example.com/path/for/inbound" ], "sms_identity": "string", "sms_message_format": "MERCURY_SMS_1_0", "sms_protocol": "HTTP", "sms_secret": "string", "updated_at": "2024-06-14T00:00:00.000000Z" }, "type": "switch"}Not found response:
HTTP/1.1 404Content-Type: application/jsonContent-Length: 402
{ "errors": [ { "code": "not_found", "title": "Not Found", "params": { "resource": { "id": "01J0CRVTXX9KBD9NWS02R5R8RT", "type": "switch" } }, "sub_code": "none" } ]}