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

Name	Type	Description
id	ULID	Unique identifier
name	String	Display name or canonical name of the Switch
inserted_at	String (format: datetime)	Creation timestamp
updated_at	String (format: datetime)	Last update timestamp
sms_auth_method	Enum:String	Auth method for SMS. NONE - no auth; BASIC - uses identity + secret; BEARER - uses secret/token only
sms_enabled	Boolean	Whether the switch can process SMS messages
sms_protocol	Enum:String	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 - transmit as barebones ISO8601 message
sms_endpoints	Array:String	Targets for message delivery depending on chosen protocol. EG URLs for HTTP, or emails addresses for EMAIL.
sms_identity	String	Username component when using BASIC auth
sms_message_format	Enum:String	Payload format for SMS (primarily HTTP). MERCURY_SMS_1_0 - default; LEGACY_SMS_2_0 - backwards compatibility
sms_secret	String	BASIC auth password, or BEARER auth token/secret
mms_auth_method	Enum:String	Auth method for MMS webhook. NONE - no auth; BASIC - uses identity + secret; BEARER - uses secret/token only
mms_enabled	Boolean	Whether the switch can process MMS messages
mms_protocol	Enum:String	Transport protocol for MMS delivery. NONE - discard; HTTP - deliver over HTTP; MM4 - industry-standard MMS transport; EMAIL - deliver via email; SMTP - deliver raw over SMTP
mms_endpoints	Array:String	Endpoint(s) for the switch to act on. Can be URLs for a webhook, or email
mms_identity	String	Username component when using BASIC auth
mms_message_format	Enum:String	Payload format for MMS (primarily HTTP). MERCURY_SMS_1_0 - default; LEGACY_SMS_2_0 - backwards compatibility
mms_secret	String	BASIC auth password, or BEARER auth token/secret

Examples

Create new switch

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": {
        "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 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": false,
        "mms_endpoints": [
            "https://example.com/path/for/inbound"
        ],
        "mms_identity": "string",
        "mms_message_format": "MERCURY_MMS_1_0",
        "mms_options": null,
        "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_options": null,
        "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"
        }
    ]
}

Create switch for sub-account

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": {
        "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 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": false,
        "mms_endpoints": [
            "https://example.com/path/for/inbound"
        ],
        "mms_identity": "string",
        "mms_message_format": "MERCURY_MMS_1_0",
        "mms_options": null,
        "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_options": null,
        "sms_protocol": "HTTP",
        "sms_secret": "string",
        "updated_at": "2024-06-14T00:00:00.000000Z"
    },
    "type": "switch"
}

Update 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_options": null,
        "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_options": null,
        "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"
        }
    ]
}

Delete switch

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_options": null,
        "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_options": null,
        "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"
        }
    ]
}

List switches

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 switch

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_options": null,
        "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_options": null,
        "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"
        }
    ]
}