OpenAPI Specification

OpenAPI 3.1 description of the TSG Global REST APIs (SMS, MMS, MMS templates, number configuration) with interactive operation blocks and a downloadable spec.

The REST APIs are described in an OpenAPI 3.1 document. Use it to generate clients, import into Postman or Insomnia, or feed to an AI assistant. The GraphQL APIs (number ordering, CDR reports, compliance forms) are not covered; see GraphQL API & Authentication.

Download: tsg-global-rest.json

The blocks below render straight from the spec, so they stay in step with it.

SMS

Send an SMS message

post

/messages

Sends an SMS to one or more recipients. Recipients are de-duplicated. Long messages are split into GSM-standard segments (max 6 for GSM-7 and UCS-2, 5 for Latin-1). Scheduling with deliver_at is supported up to 2 years ahead. The response is keyed by recipient number.

Authorizations

AuthorizationstringRequired

API key from the Customer Portal, sent as Authorization: Bearer <api_key>.

Body

fromstringRequired

E.164 number or alphanumeric sender ID.

tostring[]Required

E.164 recipients; de-duplicated.

bodystringRequired

UTF-8 text, or base64 when a custom encoding is set.

encodinginteger · enumOptional

0 GSM-7, 3 Latin-1, 8 UCS-2.

Possible values:

force_encodinginteger · enumOptionalPossible values:

registered_deliveryinteger · enumOptional

1 always, 2 on success, 3 on error.

Possible values:

deliver_atstring · date-timeOptional

UTC, up to 2 years ahead.

expires_atstring · date-timeOptional

Responses

200

Message accepted. One Message object per recipient.

application/json

401

Missing or invalid API key.

application/json

422

Request understood but parameters invalid.

application/json

post/messages

POST /messages HTTP/1.1
Host: sms.tsgglobal.world
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 110

{
  "from": "12003004000",
  "to": [
    "12003004001"
  ],
  "body": "This is a sample test SMS message",
  "registered_delivery": 1
}

{
  "ANY_ADDITIONAL_PROPERTY": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "object": "sms",
    "type": "inbound",
    "from": "text",
    "to": "text",
    "body": "text",
    "encoding": 1,
    "status": "text",
    "delivery_receipt": null,
    "udh": {
      "ref_num": null,
      "count": null,
      "seq_num": null
    },
    "parts": [
      {
        "id": "123e4567-e89b-12d3-a456-426614174000"
      }
    ],
    "location": null,
    "inserted_at": "text",
    "updated_at": "text",
    "scheduled_at": null,
    "processed_at": null,
    "delivered_at": null,
    "expires_at": null
  }
}

Fetch a message or message part

get

/messages/{uuid}

Returns a single message by message id or part id. Intended for testing; register a webhook for production traffic (see https://docs.tsgglobal.com/api-reference/programmable-sms/receive-an-sms-message).

Authorizations

AuthorizationstringRequired

API key from the Customer Portal, sent as Authorization: Bearer <api_key>.

Path parameters

uuidstring · uuidRequired

Responses

200

The message.

application/json

idstring · uuidOptional

objectstring · enumOptionalPossible values:

typestring · enumOptionalPossible values:

fromstringOptional

tostringOptional

bodystringOptional

encodingintegerOptional

statusstringOptional

delivery_receiptanyOptional

locationstring · nullableOptional

inserted_atstringOptional

updated_atstringOptional

scheduled_atstring · nullableOptional

processed_atstring · nullableOptional

delivered_atstring · nullableOptional

expires_atstring · nullableOptional

401

Missing or invalid API key.

application/json

404

Resource not found.

application/json

get/messages/{uuid}

GET /messages/{uuid} HTTP/1.1
Host: sms.tsgglobal.world
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "object": "sms",
  "type": "inbound",
  "from": "text",
  "to": "text",
  "body": "text",
  "encoding": 1,
  "status": "text",
  "delivery_receipt": null,
  "udh": {
    "ref_num": null,
    "count": null,
    "seq_num": null
  },
  "parts": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000"
    }
  ],
  "location": null,
  "inserted_at": "text",
  "updated_at": "text",
  "scheduled_at": null,
  "processed_at": null,
  "delivered_at": null,
  "expires_at": null
}

MMS

Send an MMS message

post

/mms

Sends an MMS. The body mirrors an MM4 forward request. Parts may be plain text, a public uri (3 MB max, server must answer HEAD and GET with Content-Length), an RFC 2397 data-uri (65,535 chars max) or an embedded body (1 MB max). A 200 means the message was accepted for processing, not delivered. Set request_delivery_reports to receive DLRs on your inbound webhook.

Authorizations

AuthorizationstringRequired

API key from the Customer Portal, sent as Authorization: Bearer <api_key>.

Body

Responses

200

Accepted. data.attributes.messages carries one message_id per recipient, used in DLRs.

application/json

400

Malformed JSON (for example unescaped new lines inside strings).

401

Missing or invalid API key.

application/json

post/mms

POST /mms HTTP/1.1
Host: sms.tsgglobal.world
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 338

{
  "data": {
    "type": "mms-forward-req",
    "attributes": {
      "from": "+12223334444",
      "to": [
        "+14252437709"
      ],
      "request_delivery_reports": true,
      "parts": [
        {
          "kind": "plain",
          "content_type": "text/plain",
          "content_location": "body.txt",
          "body": "This is a test MMS for the body"
        },
        {
          "kind": "uri",
          "content_location": "aurora.jpg",
          "uri": "https://example.com/aurora.jpg"
        }
      ]
    }
  }
}

{
  "data": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "type": "mms-forward-res",
    "attributes": {
      "inserted_at": "text",
      "transaction_id": "text",
      "from": "text",
      "to": [
        "text"
      ],
      "subject": "text",
      "headers": {},
      "messages": [
        {
          "message_id": "123e4567-e89b-12d3-a456-426614174000",
          "to": "text"
        }
      ],
      "parts": [
        {
          "kind": "plain",
          "content_type": "text",
          "content_location": "text",
          "content_encoding": "text",
          "transfer_encoding": "text",
          "body": "text",
          "uri": "text",
          "headers": {
            "ANY_ADDITIONAL_PROPERTY": "text"
          },
          "metadata": {}
        }
      ]
    }
  }
}

Create an MMS template

post

/mms/templates

Placeholders use {key} where key matches [a-zA-Z_][a-zA-Z0-9_]*. The response lists the extracted placeholders.

Authorizations

AuthorizationstringRequired

API key from the Customer Portal, sent as Authorization: Bearer <api_key>.

Body

Responses

200

The created template.

application/json

401

Missing or invalid API key.

application/json

post/mms/templates

POST /mms/templates HTTP/1.1
Host: sms.tsgglobal.world
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 324

{
  "data": {
    "type": "mms-template",
    "attributes": {
      "name": "text",
      "body_template": "text",
      "subject_template": "text",
      "parts": [
        {
          "kind": "plain",
          "content_type": "text",
          "content_location": "text",
          "content_encoding": "text",
          "transfer_encoding": "text",
          "body": "text",
          "uri": "text",
          "headers": {
            "ANY_ADDITIONAL_PROPERTY": "text"
          },
          "metadata": {}
        }
      ]
    }
  }
}

{
  "data": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "type": "mms-template",
    "attributes": {
      "name": "text",
      "body_template": "text",
      "subject_template": "text",
      "placeholders": [
        "text"
      ],
      "parts": [
        {
          "kind": "plain",
          "content_type": "text",
          "content_location": "text",
          "content_encoding": "text",
          "transfer_encoding": "text",
          "body": "text",
          "uri": "text",
          "headers": {
            "ANY_ADDITIONAL_PROPERTY": "text"
          },
          "metadata": {}
        }
      ],
      "inserted_at": "text",
      "updated_at": "text"
    }
  }
}

Send an MMS from a template

post

/mms/templates/{id}/send

Authorizations

AuthorizationstringRequired

API key from the Customer Portal, sent as Authorization: Bearer <api_key>.

Path parameters

idstring · uuidRequired

Body

Responses

200

Accepted. Same shape as sending an MMS directly.

application/json

404

Resource not found.

application/json

post/mms/templates/{id}/send

POST /mms/templates/{id}/send HTTP/1.1
Host: sms.tsgglobal.world
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 199

{
  "data": {
    "type": "mms-template-send-req",
    "attributes": {
      "from": "text",
      "to": [
        "text"
      ],
      "params": {
        "ANY_ADDITIONAL_PROPERTY": "text"
      },
      "transaction_id": "text",
      "request_delivery_reports": false,
      "metadata": {}
    }
  }
}

{
  "data": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "type": "mms-forward-res",
    "attributes": {
      "inserted_at": "text",
      "transaction_id": "text",
      "from": "text",
      "to": [
        "text"
      ],
      "subject": "text",
      "headers": {},
      "messages": [
        {
          "message_id": "123e4567-e89b-12d3-a456-426614174000",
          "to": "text"
        }
      ],
      "parts": [
        {
          "kind": "plain",
          "content_type": "text",
          "content_location": "text",
          "content_encoding": "text",
          "transfer_encoding": "text",
          "body": "text",
          "uri": "text",
          "headers": {
            "ANY_ADDITIONAL_PROPERTY": "text"
          },
          "metadata": {}
        }
      ]
    }
  }
}

Number configuration

Get a number's SMS and MMS configuration

get

/v5/dids/{number}

Clients must ignore unknown properties; new ones may be added without notice.

Authorizations

AuthorizationstringRequired

API key from the Customer Portal, sent as Authorization: Bearer <api_key>.

Path parameters

numberstringRequiredExample: 13603556404

Responses

200

Configuration.

application/json

numberstringOptional

number_typestring · enumOptionalPossible values:

mms_enabledbooleanOptional

mms_uristring · nullableOptional

sms_enabledbooleanOptional

campaign_idstring · nullableOptional

compliance_statusstring · enumOptionalPossible values:

sms_statusstring · enumOptionalPossible values:

use_case_typestring · enumOptionalPossible values:

nnidstring · nullableOptional

sms_post_verstring · enumOptionalPossible values:

sms_uristring · nullableOptional

null means SMPP delivery.

x_api_key_headerstring · nullableOptional

ten_dlc_registeredbooleanOptional

tmobile_ten_dlc_registeredbooleanOptional

401

Missing or invalid API key.

application/json

404

Resource not found.

application/json

get/v5/dids/{number}

GET /v5/dids/{number} HTTP/1.1
Host: sms.tsgglobal.world
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "number": "text",
  "number_type": "long-code",
  "mms_enabled": true,
  "mms_uri": null,
  "sms_enabled": true,
  "campaign_id": null,
  "compliance_status": "non_compliant",
  "sms_status": "NONE",
  "use_case_type": "",
  "nnid": null,
  "sms_post_ver": "smpp",
  "sms_uri": null,
  "x_api_key_header": null,
  "ten_dlc_registered": true,
  "tmobile_ten_dlc_registered": true
}

Enable, update or disable SMS (and 10DLC assignment) on a number

post

/v2/sms-enablement

Strict parameter parsing: unknown fields reject the request. Use action: add to enable, update to change settings or attach a campaign, delete to disable SMS.

Authorizations

AuthorizationstringRequired

API key from the Customer Portal, sent as Authorization: Bearer <api_key>.

Body

didstringRequiredExample: 12003004000

actionstring · enumRequiredPossible values:

use_case_typestring · enumOptionalPossible values:

p2p_nnidstringOptional

mms_enablestring · enumOptionalPossible values:

mms_routingstringOptional

http, https, mm4 or mm4s URL for inbound MMS.

webhook_urlstring · uriOptional

webhook_typestring · enumOptionalPossible values:

x_api_key_headerstringOptional

campaign_idstringOptional

10DLC campaign to assign. Sole-proprietor campaigns allow one number.

campaign_sub_idstringOptional

skip_number_validationstring · enumOptional

Only after TSG has accepted your LOA for the number.

Possible values:

Responses

200

Success

text/plain

stringOptionalExample: Success

401

Missing or invalid API key.

application/json

422

Request understood but parameters invalid.

application/json

post/v2/sms-enablement

POST /v2/sms-enablement HTTP/1.1
Host: sms.tsgglobal.world
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 279

{
  "did": "12003004000",
  "action": "add",
  "use_case_type": "a2p",
  "p2p_nnid": "text",
  "mms_enable": "true",
  "mms_routing": "text",
  "webhook_url": "https://example.com",
  "webhook_type": "smpp",
  "x_api_key_header": "text",
  "campaign_id": "text",
  "campaign_sub_id": "text",
  "skip_number_validation": "true"
}

Success

Set the inbound SMS webhook for a number

post

/v1/sms/webhook

Omitting webhook_url switches the number to SMPP delivery. Have SMPP credentials tested first.

Authorizations

AuthorizationstringRequired

API key from the Customer Portal, sent as Authorization: Bearer <api_key>.

Body

didstringRequiredExample: 12003004000

webhook_urlstring · uriOptionalExample: https://example.com/webhook

webhook_typestring · enumOptionalDefault: postv2Possible values:

x_api_key_headerstringOptional

Sent back to you as the x-api-key header on every webhook call.

Responses

200

Success

text/plain

stringOptionalExample: Success

401

Missing or invalid API key.

application/json

post/v1/sms/webhook

POST /v1/sms/webhook HTTP/1.1
Host: sms.tsgglobal.world
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 115

{
  "did": "12003004000",
  "webhook_url": "https://example.com/webhook",
  "webhook_type": "postv2",
  "x_api_key_header": "text"
}

Success

Enable MMS on a number or change its inbound MMS URI

post

/v2/dids/{number}/mms/enable

The number must already be SMS-enabled and the account MMS-enabled.

Authorizations

AuthorizationstringRequired

API key from the Customer Portal, sent as Authorization: Bearer <api_key>.

Path parameters

numberstringRequired

Body

uristringRequired

HTTP(S) URL or mm4://user:pass@host:port that receives inbound MMS.

Example: https://example.com/inbound-mms

Responses

200

Updated configuration.

application/json

numberstringOptional

mms_enabledbooleanOptional

mms_uristring · nullableOptional

sms_enabledbooleanOptional

sms_uristring · nullableOptional

401

Missing or invalid API key.

application/json

post/v2/dids/{number}/mms/enable

POST /v2/dids/{number}/mms/enable HTTP/1.1
Host: sms.tsgglobal.world
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 41

{
  "uri": "https://example.com/inbound-mms"
}

{
  "number": "text",
  "mms_enabled": true,
  "mms_uri": null,
  "sms_enabled": true,
  "sms_uri": null
}

Add a voice destination priority

post

/v1/did/priority

Authorizations

AuthorizationstringRequired

API key from the Customer Portal, sent as Authorization: Bearer <api_key>.

Body

didstringRequiredExample: 12003004000

priorityinteger · min: 1 · max: 3Required

destinationstringRequired

Gateway IP for VOIP, E.164 for PSTN.

call_typestring · enumRequired

Case sensitive.

Possible values:

call_optionstring · enumOptional

WP sends the DID with a plus, NP without. Case sensitive.

Possible values:

Responses

200

Result code. -1008-V or -1008-P means added; negative codes below -1000 are errors (see docs).

text/plain

stringOptional

post/v1/did/priority

POST /v1/did/priority HTTP/1.1
Host: sms.tsgglobal.world
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 93

{
  "did": "12003004000",
  "priority": 1,
  "destination": "text",
  "call_type": "VOIP",
  "call_option": "WP"
}

200

Result code. -1008-V or -1008-P means added; negative codes below -1000 are errors (see docs).

text

Every operation in the spec

Method

Path

Operation

POST

/messages

sendSms

GET

/messages/{uuid}

getSms

POST

/mms

sendMms

POST

/mms/templates

createMmsTemplate

GET

/mms/templates

listMmsTemplates

GET

/mms/templates/{id}

getMmsTemplate

DELETE

/mms/templates/{id}

deleteMmsTemplate

POST

/mms/templates/{id}/preview

previewMmsTemplate

POST

/mms/templates/{id}/send

sendMmsFromTemplate

GET

/v5/dids/{number}

getNumberConfiguration

GET

/v1/did/lookup

lookupNumber

POST

/v2/sms-enablement

smsEnablement

POST

/v1/sms/webhook

setSmsWebhook

POST

/v2/dids/{number}/mms/enable

enableMms

POST

/v2/dids/{number}/mms/disable

disableMms

GET

/v1/did/priority/lookup

listDestinationPriorities

POST

/v1/did/priority

addDestinationPriority

PATCH

/v1/did/priority

updateDestinationPriority

DELETE

/v1/did/priority

deleteDestinationPriority

The hand-written pages under API Reference remain the place for narrative, encoding rules, webhook payloads and worked examples; the spec is the machine-readable contract.

PreviousAI Assistants & MCP

NextProgrammable SMS

Was this helpful?