DID

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

DIDs represent any E164 number or address associated with the account.

See Ordering to add new numbers to your account.

Schema

Name	Type	Description
id	ULID	Unique identifier for the DID
inserted_at	String(format:datetime)	Timestamp when the DID was created
mms_enabled	Boolean	Whether or not MMS is enabled on the DID
mms_status	Enum:String	The enablement status of the MMS capabilities on the DID. Possible values are UNAVAILABLE, PENDING, and AVAILABLE.
number	String(format:e164)	The number or address of the DID (unique)
sms_enabled	Boolean	Whether or not SMS is enabled on the DID
sms_status	Enum:String	The enablement status of the SMS capabilities on the DID. Possible values are UNAVAILABLE, PENDING, and AVAILABLE.
updated_at	String(format:datetime)	Timestamp when the DID was last updated

Examples

List DIDs

Lists DIDs for immediate and all sub accounts.

Request:

GET https://api.swift-api.com/api/v1/dids HTTP/1.1
Accept: application/json, text/plain
Authorization: Bearer apik_ABC123

Response:

HTTP/1.1 200
Content-Type: application/json
Content-Length: 567

{
  "data": {
    "items": [
      {
        "data": {
          "id": "01J0CRVTXX9KBD9NWS02R5R8RT",
          "inserted_at": "2024-06-14T00:00:00.000000Z",
          "mms_enabled": true,
          "mms_status": "AVAILABLE",
          "number": "17055551234",
          "sms_enabled": true,
          "sms_status": "AVAILABLE",
          "updated_at": "2024-06-14T00:00:00.000000Z"
        },
        "type": "did"
      }
    ],
    "page_info": {
      "after": "string",
      "before": "string",
      "limit": 0.0,
      "total": 0.0
    }
  },
  "type": "list"
}

List DIDs for account

Lists all the DIDs under the specified account.

Request:

GET https://api.swift-api.com/api/v1/accounts/{account_id}/dids HTTP/1.1
Accept: application/json, text/plain
Authorization: Bearer apik_ABC123

Response:

HTTP/1.1 200
Content-Type: application/json
Content-Length: 314

{
  "data": {
    "items": [
      {
        "associations": {
          "account": {
            "data": {
              "id": "01J0CRVTXX9KBD9NWS02R5R8RT"
            },
            "type": "account"
          },
          "auto_response": {
            "data": {
              "id": null
            },
            "type": "messaging_auto_response"
          },
          "csp_campaign": {
            "data": {
              "id": null
            },
            "type": "csp_campaign"
          },
          "group": {
            "data": {
              "id": null
            },
            "type": "did_group"
          },
          "switch": {
            "data": {
              "id": "01J0CRVTXX9KBD9NWS02R5R8RT"
            },
            "type": "switch"
          }
        },
        "data": {
          "id": "01J0CRVTXX9KBD9NWS02R5R8RT",
          "inserted_at": "2026-01-13T14:31:21.273062Z",
          "mms_enabled": true,
          "mms_rate_ms": null,
          "mms_status": "AVAILABLE",
          "number": "17055551234",
          "sms_enabled": true,
          "sms_rate_ms": null,
          "sms_status": "AVAILABLE",
          "updated_at": "2026-02-16T18:05:16.017701Z"
        },
        "type": "did"
      },
      {
        "associations": {
          "account": {
            "data": {
              "id": "01J0CRVTXX9KBD9NWS02R5R8RT"
            },
            "type": "account"
          },
          "auto_response": {
            "data": {
              "id": null
            },
            "type": "messaging_auto_response"
          },
          "csp_campaign": {
            "data": {
              "id": null
            },
            "type": "csp_campaign"
          },
          "group": {
            "data": {
              "id": null
            },
            "type": "did_group"
          },
          "switch": {
            "data": {
              "id": "01J0CRVTXX9KBD9NWS02R5R8RT"
            },
            "type": "switch"
          }
        },
        "data": {
          "id": "01J0CRVTXX9KBD9NWS02R5R8RT",
          "inserted_at": "2026-01-13T14:31:21.273062Z",
          "mms_enabled": true,
          "mms_rate_ms": null,
          "mms_status": "AVAILABLE",
          "number": "17055551235",
          "sms_enabled": true,
          "sms_rate_ms": null,
          "sms_status": "AVAILABLE",
          "updated_at": "2026-02-16T18:05:16.017701Z"
        },
        "type": "did"
      }
    ],
    "page_info": {
      "after": "string",
      "before": "string",
      "limit": 0.0,
      "total": 0.0
    }
  },
  "type": "list"
}

Get DID

Retrieve a DID by its ID.

Request:

GET https://api.swift-api.com/api/v1/dids/{id} HTTP/1.1
Accept: application/json, text/plain
Authorization: Bearer apik_ABC123

Response:

HTTP/1.1 200
Content-Type: application/json
Content-Length: 314

{
  "associations": {
    "account": {
      "data": {
        "id": "01J0CRVTXX9KBD9NWS02R5R8RT"
      },
      "type": "account"
    },
    "auto_response": {
      "data": {
        "id": null
      },
      "type": "messaging_auto_response"
    },
    "csp_campaign": {
      "data": {
        "id": null
      },
      "type": "csp_campaign"
    },
    "group": {
      "data": {
        "id": null
      },
      "type": "did_group"
    },
    "switch": {
      "data": {
        "id": null
      },
      "type": "switch"
    }
  },
  "data": {
    "id": "01J0CRVTXX9KBD9BWS02R5R8RT",
    "inserted_at": "2026-01-13T14:31:21.273062Z",
    "mms_enabled": true,
    "mms_rate_ms": null,
    "mms_status": "AVAILABLE",
    "number": "17055551235",
    "sms_enabled": true,
    "sms_rate_ms": null,
    "sms_status": "AVAILABLE",
    "updated_at": "2026-02-16T18:05:16.017701Z"
  },
  "type": "did"
}

Bind DID to API key

Required for outbound sending. A DID can be bound to multiple API keys.

Returns the API key that the DID was bound to.

Request:

PUT https://api.swift-api.com/api/v1/dids/{did_id}/api_keys{api_key_id} HTTP/1.1
Authorization: Bearer apik_ABC123

Response:

HTTP/1.1 200
Content-Type: application/json
Content-Length: 402

{
    "associations": {
        "account": {
            "data": {
                "id": "01J0CRVTXX9KBD9NWS02R5R8RT"
            },
            "type": "account"
        }
    },
    "data": {
    "id": "01J0CRVTXX9KBD9NWS02R5R8RT",
    "inserted_at": "2024-06-14T00:00:00.000000Z",
    "name": "string",
    "notes": "This API Key will be used for the Westcoast SMS Application.\n",
    "smpp_secret": "PASSWORD",
    "smpp_system_id": "ABCDEF123456789",
    "token": "string",
    "updated_at": "2024-06-14T00:00:00.000000Z"
  },
  "type": "api_key"
}

Unbind DID from API key

Returns the API key that was removed from the DID.

Request:

DELETE https://api.swift-api.com/api/v1/dids/{did_id}/api_keys/{api_key_id} HTTP/1.1
Authorization: Bearer apik_ABC123

Response:

HTTP/1.1 200
Content-Type: application/json
Content-Length: 402

{
    "associations": {
        "account": {
            "data": {
                "id": "01J0CRVTXX9KBD9NWS02R5R8RT"
            },
            "type": "account"
        }
    },
    "data": {
    "id": "01J0CRVTXX9KBD9NWS02R5R8RT",
    "inserted_at": "2024-06-14T00:00:00.000000Z",
    "name": "string",
    "notes": "This API Key will be used for the Westcoast SMS Application.\n",
    "smpp_secret": "PASSWORD",
    "smpp_system_id": "ABCDEF123456789",
    "token": "string",
    "updated_at": "2024-06-14T00:00:00.000000Z"
  },
  "type": "api_key"
}

Bind DID to Switch

Required for receiving and processing incoming messages to a DID. A DID can only be associated to one switch at a time.

Returns the switch the DID was bound to.

Request:

PUT https://api.swift-api.com/api/v1/dids/{did_id}/switch/{switch_id} HTTP/1.1
Authorization: Bearer apik_ABC123

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"
}

Unbind DID from Switch

Required for receiving and processing incoming messages to a DID. A DID can only be associated to one switch at a time.

Returns the switch that the DID was unbound from.

Request:

DELETE https://api.swift-api.com/api/v1/dids/{did_id}/switch HTTP/1.1
Authorization: Bearer apik_ABC123

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"
}