Skip to content

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.

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.

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.1
Accept: application/json, text/plain
Content-Type: application/json
Authorization: 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 201
Content-Type: application/json
Content-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 422
Content-Type: application/json
Content-Length: 402
{
"errors": [
{
"code": "invalid_parameter",
"source": {
"in": "body",
"pointer": "/data/name"
},
"detail": "has already been taken",
"sub_code": "constraint.unique"
}
]
}

Request:

POST https://api.swift-api.com/api/v1/accounts/{account_id}/switches
Accept: application/json, text/plain
Content-Type: application/json
Authorization: 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 201
Content-Type: application/json
Content-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"
}

Request:

PATCH https://api.swift-api.com/api/v1/switches/{id} HTTP/1.1
Accept: application/json, text/plain
Content-Type: application/json
Authorization: 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 200
Content-Type: application/json
Content-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 422
Content-Type: application/json
Content-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 404
Content-Type: application/json
Content-Length: 402
{
"errors": [
{
"code": "not_found",
"title": "Not Found",
"params": {
"resource": {
"id": "01J0CRVTXX9KBD9NWS02R5R8RT",
"type": "switch"
}
},
"sub_code": "none"
}
]
}

Request:

DELETE https://api.swift-api.com/api/v1/switches/{id} HTTP/1.1
Authorization: Bearer apik_ABC123

Success response (returns the deleted switch object):

HTTP/1.1 200
Content-Type: application/json
Content-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 404
Content-Type: application/json
Content-Length: 402
{
"errors": [
{
"code": "not_found",
"title": "Not Found",
"params": {
"resource": {
"id": "01J0CRVTXX9KBD9NWS02R5R8RT",
"type": "switch"
}
},
"sub_code": "none"
}
]
}

Lists all the switches associated with the parent account, and all sub-accounts.

Request:

GET https://api.swift-api.com/api/v1/switches
Authorization: Bearer apik_ABC123

Success response (paginated list of switches):

HTTP/1.1 200
Content-Type: application/json
Content-Length: 402
{
"data": {
"items": [
{
"data": { /* Switch object */ },
"type": "switch"
}
],
"page_info": {
"after": "string",
"before": "string",
"limit": 0,
"total": 0
}
},
"type": "list"
}
GET https://api.swift-api.com/api/v1/switches/{id}
Authorization: Bearer apik_ABC123

Success response:

HTTP/1.1 200
Content-Type: application/json
Content-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 404
Content-Type: application/json
Content-Length: 402
{
"errors": [
{
"code": "not_found",
"title": "Not Found",
"params": {
"resource": {
"id": "01J0CRVTXX9KBD9NWS02R5R8RT",
"type": "switch"
}
},
"sub_code": "none"
}
]
}