{"openapi":"3.1.0","info":{"title":"TSG Global REST APIs","version":"2026-09-11","description":"The REST surface of the TSG Global platform: Programmable SMS, Programmable MMS (including MMS templates)\nand phone-number configuration. Number ordering, CDR reports and compliance forms are GraphQL and are not\npart of this specification; see https://docs.tsgglobal.com/graphql-api-and-authentication.\n\nAuthentication for every operation is an API key sent as `Authorization: Bearer <api_key>`. The SMS and MMS\nservers use the messaging API key; the number-configuration server uses the account API key. Both are shown\nin the Customer Portal at https://customer-portal.tsgglobal.com/account.\n","contact":{"name":"TSG Global support","email":"support@tsgglobal.com","url":"https://docs.tsgglobal.com"}},"servers":[{"url":"https://sms.tsgglobal.world","description":"Programmable SMS (production)"},{"url":"https://mmsc.tsgglobal.world","description":"Programmable MMS and MMS templates (production)"},{"url":"https://api-service.tsgglobal.world","description":"Phone-number configuration (production)"},{"url":"https://sms-api.staging.tsgglobal.com","description":"Programmable SMS (staging)"},{"url":"https://mms-api.staging.tsgglobal.com","description":"Programmable MMS (staging)"}],"security":[{"bearerAuth":[]}],"tags":[{"name":"SMS","description":"Send SMS and fetch messages. Host sms.tsgglobal.world."},{"name":"MMS","description":"Send MMS. Host mmsc.tsgglobal.world."},{"name":"MMS templates","description":"Reusable MMS templates with {placeholder} substitution. Host mmsc.tsgglobal.world."},{"name":"Number configuration","description":"Per-number SMS, MMS and voice settings. Host api-service.tsgglobal.world."}],"paths":{"/messages":{"post":{"tags":["SMS"],"operationId":"sendSms","summary":"Send an SMS message","description":"Sends an SMS to one or more recipients. Recipients are de-duplicated. Long messages are split into\nGSM-standard segments (max 6 for GSM-7 and UCS-2, 5 for Latin-1). Scheduling with `deliver_at` is\nsupported up to 2 years ahead. The response is keyed by recipient number.\n","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SendSmsRequest"},"example":{"from":"12003004000","to":["12003004001"],"body":"This is a sample test SMS message","registered_delivery":1}}}},"responses":{"200":{"description":"Message accepted. One Message object per recipient.","content":{"application/json":{"schema":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/SmsMessage"}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"422":{"$ref":"#/components/responses/InvalidParams"}}}},"/messages/{uuid}":{"get":{"tags":["SMS"],"operationId":"getSms","summary":"Fetch a message or message part","description":"Returns a single message by message id or part id. Intended for testing; register a webhook for production\ntraffic (see https://docs.tsgglobal.com/api-reference/programmable-sms/receive-an-sms-message).\n","parameters":[{"name":"uuid","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"The message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SmsMessage"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/mms":{"post":{"tags":["MMS"],"operationId":"sendMms","summary":"Send an MMS message","description":"Sends an MMS. The body mirrors an MM4 forward request. Parts may be `plain` text, a public `uri`\n(3 MB max, server must answer HEAD and GET with Content-Length), an RFC 2397 `data-uri` (65,535 chars max)\nor an `embedded` body (1 MB max). A 200 means the message was accepted for processing, not delivered.\nSet `request_delivery_reports` to receive DLRs on your inbound webhook.\n","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MmsForwardRequest"},"example":{"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"}]}}}}}},"responses":{"200":{"description":"Accepted. `data.attributes.messages` carries one `message_id` per recipient, used in DLRs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MmsForwardResponse"}}}},"400":{"description":"Malformed JSON (for example unescaped new lines inside strings)."},"401":{"$ref":"#/components/responses/Unauthenticated"}}}},"/mms/templates":{"post":{"tags":["MMS templates"],"operationId":"createMmsTemplate","summary":"Create an MMS template","description":"Placeholders use `{key}` where key matches `[a-zA-Z_][a-zA-Z0-9_]*`. The response lists the extracted placeholders.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MmsTemplateRequest"}}}},"responses":{"200":{"description":"The created template.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MmsTemplateResponse"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"}}},"get":{"tags":["MMS templates"],"operationId":"listMmsTemplates","summary":"List MMS templates","responses":{"200":{"description":"All templates on the account.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/MmsTemplate"}}}}}}},"401":{"$ref":"#/components/responses/Unauthenticated"}}}},"/mms/templates/{id}":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"get":{"tags":["MMS templates"],"operationId":"getMmsTemplate","summary":"Get one MMS template","responses":{"200":{"description":"The template.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MmsTemplateResponse"}}}},"404":{"$ref":"#/components/responses/NotFound"}}},"delete":{"tags":["MMS templates"],"operationId":"deleteMmsTemplate","summary":"Delete an MMS template","responses":{"204":{"description":"Deleted."},"404":{"$ref":"#/components/responses/NotFound"}}}},"/mms/templates/{id}/preview":{"post":{"tags":["MMS templates"],"operationId":"previewMmsTemplate","summary":"Preview a template with real values, without sending","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MmsTemplatePreviewRequest"}}}},"responses":{"200":{"description":"The rendered `mms-forward-req` that a send would produce.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MmsForwardRequest"}}}},"404":{"$ref":"#/components/responses/NotFound"}}}},"/mms/templates/{id}/send":{"post":{"tags":["MMS templates"],"operationId":"sendMmsFromTemplate","summary":"Send an MMS from a template","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MmsTemplateSendRequest"}}}},"responses":{"200":{"description":"Accepted. Same shape as sending an MMS directly.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MmsForwardResponse"}}}},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v5/dids/{number}":{"get":{"tags":["Number configuration"],"operationId":"getNumberConfiguration","summary":"Get a number's SMS and MMS configuration","description":"Clients must ignore unknown properties; new ones may be added without notice.","parameters":[{"name":"number","in":"path","required":true,"schema":{"type":"string"},"example":"13603556404"}],"responses":{"200":{"description":"Configuration.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NumberConfiguration"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/did/lookup":{"get":{"tags":["Number configuration"],"operationId":"lookupNumber","summary":"Look up rate center, routing and activation data (CSV)","description":"Omit `did` to list every number on the account, one per line.","parameters":[{"name":"did","in":"query","required":false,"schema":{"type":"string"},"example":"12022011234"}],"responses":{"200":{"description":"CSV with header row.","content":{"text/csv":{"schema":{"type":"string"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"}}}},"/v2/sms-enablement":{"post":{"tags":["Number configuration"],"operationId":"smsEnablement","summary":"Enable, update or disable SMS (and 10DLC assignment) on a number","description":"Strict parameter parsing: unknown fields reject the request. Use `action: add` to enable, `update` to change\nsettings or attach a campaign, `delete` to disable SMS.\n","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SmsEnablementRequest"}}}},"responses":{"200":{"description":"`Success`","content":{"text/plain":{"schema":{"type":"string","example":"Success"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"},"422":{"$ref":"#/components/responses/InvalidParams"}}}},"/v1/sms/webhook":{"post":{"tags":["Number configuration"],"operationId":"setSmsWebhook","summary":"Set the inbound SMS webhook for a number","description":"Omitting `webhook_url` switches the number to SMPP delivery. Have SMPP credentials tested first.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["did"],"properties":{"did":{"type":"string","example":"12003004000"},"webhook_url":{"type":"string","format":"uri","example":"https://example.com/webhook"},"webhook_type":{"type":"string","enum":["postv2","postv1","post3jam","smpp"],"default":"postv2"},"x_api_key_header":{"type":"string","description":"Sent back to you as the x-api-key header on every webhook call."}}}}}},"responses":{"200":{"description":"`Success`","content":{"text/plain":{"schema":{"type":"string","example":"Success"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"}}}},"/v2/dids/{number}/mms/enable":{"post":{"tags":["Number configuration"],"operationId":"enableMms","summary":"Enable MMS on a number or change its inbound MMS URI","description":"The number must already be SMS-enabled and the account MMS-enabled.","parameters":[{"name":"number","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["uri"],"properties":{"uri":{"type":"string","description":"HTTP(S) URL or `mm4://user:pass@host:port` that receives inbound MMS.","example":"https://example.com/inbound-mms"}}}}}},"responses":{"200":{"description":"Updated configuration.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MmsConfiguration"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"}}}},"/v2/dids/{number}/mms/disable":{"post":{"tags":["Number configuration"],"operationId":"disableMms","summary":"Disable MMS on a number","parameters":[{"name":"number","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Updated configuration with `mms_enabled` false.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MmsConfiguration"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"}}}},"/v1/did/priority/lookup":{"get":{"tags":["Number configuration"],"operationId":"listDestinationPriorities","summary":"List voice destination priorities (CSV)","responses":{"200":{"description":"CSV with columns DID, ROUTING INFO, PRIORITY, CALL TYPE.","content":{"text/csv":{"schema":{"type":"string"}}}},"401":{"$ref":"#/components/responses/Unauthenticated"}}}},"/v1/did/priority":{"post":{"tags":["Number configuration"],"operationId":"addDestinationPriority","summary":"Add a voice destination priority","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DestinationPriority"}}}},"responses":{"200":{"description":"Result code. `-1008-V` or `-1008-P` means added; negative codes below -1000 are errors (see docs).","content":{"text/plain":{"schema":{"type":"string"}}}}}},"patch":{"tags":["Number configuration"],"operationId":"updateDestinationPriority","summary":"Update a voice destination priority","requestBody":{"required":true,"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/DestinationPriority"},{"type":"object","properties":{"dnis":{"type":"string","description":"Dialed number to send to your switch instead of the DID."}}}]}}}},"responses":{"200":{"description":"Result code (see docs).","content":{"text/plain":{"schema":{"type":"string"}}}}}},"delete":{"tags":["Number configuration"],"operationId":"deleteDestinationPriority","summary":"Remove a voice destination priority (priority 1 cannot be deleted)","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["did","priority"],"properties":{"did":{"type":"string","example":"12003004000"},"priority":{"type":"integer","minimum":2,"maximum":3}}}}}},"responses":{"200":{"description":"Result code (see docs).","content":{"text/plain":{"schema":{"type":"string"}}}}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"API key from the Customer Portal, sent as `Authorization: Bearer <api_key>`."}},"responses":{"Unauthenticated":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"NotFound":{"description":"Resource not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"InvalidParams":{"description":"Request understood but parameters invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"schemas":{"Error":{"type":"object","properties":{"id":{"type":"string","enum":["unauthenticated","unauthorized","not_found","server_error","invalid_params"]},"message":{"type":"string"}}},"SendSmsRequest":{"type":"object","required":["from","to","body"],"properties":{"from":{"type":"string","description":"E.164 number or alphanumeric sender ID."},"to":{"type":"array","items":{"type":"string"},"description":"E.164 recipients; de-duplicated."},"body":{"type":"string","description":"UTF-8 text, or base64 when a custom encoding is set."},"encoding":{"type":"integer","enum":[0,3,8],"description":"0 GSM-7, 3 Latin-1, 8 UCS-2."},"force_encoding":{"type":"integer","enum":[0,3,8]},"registered_delivery":{"type":"integer","enum":[1,2,3],"description":"1 always, 2 on success, 3 on error."},"deliver_at":{"type":"string","format":"date-time","description":"UTC, up to 2 years ahead."},"expires_at":{"type":"string","format":"date-time"}}},"SmsMessage":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"object":{"type":"string","enum":["sms"]},"type":{"type":"string","enum":["inbound","outbound"]},"from":{"type":"string"},"to":{"type":"string"},"body":{"type":"string"},"encoding":{"type":"integer"},"status":{"type":"string"},"delivery_receipt":{},"udh":{"type":["object","null"],"properties":{"ref_num":{"type":["integer","null"]},"count":{"type":["integer","null"]},"seq_num":{"type":["integer","null"]}}},"parts":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"}}}},"location":{"type":["string","null"]},"inserted_at":{"type":"string"},"updated_at":{"type":"string"},"scheduled_at":{"type":["string","null"]},"processed_at":{"type":["string","null"]},"delivered_at":{"type":["string","null"]},"expires_at":{"type":["string","null"]}}},"MmsPart":{"type":"object","properties":{"kind":{"type":"string","enum":["plain","uri","data-uri","embedded"],"default":"plain"},"content_type":{"type":"string"},"content_location":{"type":"string"},"content_encoding":{"type":"string"},"transfer_encoding":{"type":"string"},"body":{"type":"string"},"uri":{"type":"string"},"headers":{"type":"object","additionalProperties":{"type":"string"}},"metadata":{"type":"object"}}},"MmsForwardRequest":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["type","attributes"],"properties":{"id":{"type":"string"},"type":{"type":"string","enum":["mms-forward-req"]},"attributes":{"type":"object","required":["from","to","parts"],"properties":{"from":{"type":"string"},"to":{"type":"array","items":{"type":"string"}},"subject":{"type":"string"},"expires_at":{"type":"string","format":"date-time"},"expires_in":{"type":"integer","description":"Seconds after receipt."},"transaction_id":{"type":"string"},"headers":{"type":"object"},"metadata":{"type":"object"},"request_delivery_reports":{"type":"boolean","default":false},"parts":{"type":"array","items":{"$ref":"#/components/schemas/MmsPart"}}}}}}}},"MmsForwardResponse":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"type":{"type":"string","enum":["mms-forward-res"]},"attributes":{"type":"object","properties":{"inserted_at":{"type":"string"},"transaction_id":{"type":"string"},"from":{"type":"string"},"to":{"type":"array","items":{"type":"string"}},"subject":{"type":"string"},"headers":{"type":"object"},"messages":{"type":"array","items":{"type":"object","properties":{"message_id":{"type":"string","format":"uuid"},"to":{"type":"string"}}}},"parts":{"type":"array","items":{"$ref":"#/components/schemas/MmsPart"}}}}}}}},"MmsTemplateRequest":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["type","attributes"],"properties":{"type":{"type":"string","enum":["mms-template"]},"attributes":{"type":"object","required":["name","body_template"],"properties":{"name":{"type":"string"},"body_template":{"type":"string"},"subject_template":{"type":"string"},"parts":{"type":"array","items":{"$ref":"#/components/schemas/MmsPart"}}}}}}}},"MmsTemplate":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"type":{"type":"string","enum":["mms-template"]},"attributes":{"type":"object","properties":{"name":{"type":"string"},"body_template":{"type":"string"},"subject_template":{"type":"string"},"placeholders":{"type":"array","items":{"type":"string"}},"parts":{"type":"array","items":{"$ref":"#/components/schemas/MmsPart"}},"inserted_at":{"type":"string"},"updated_at":{"type":"string"}}}}},"MmsTemplateResponse":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/MmsTemplate"}}},"MmsTemplatePreviewRequest":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["type","attributes"],"properties":{"type":{"type":"string","enum":["mms-template-preview-req"]},"attributes":{"type":"object","required":["from","to","params"],"properties":{"from":{"type":"string"},"to":{"type":"array","items":{"type":"string"}},"params":{"type":"object","additionalProperties":{"type":"string"},"description":"Must cover every placeholder in the template."}}}}}}},"MmsTemplateSendRequest":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["type","attributes"],"properties":{"type":{"type":"string","enum":["mms-template-send-req"]},"attributes":{"type":"object","required":["from","to","params"],"properties":{"from":{"type":"string"},"to":{"type":"array","items":{"type":"string"}},"params":{"type":"object","additionalProperties":{"type":"string"}},"transaction_id":{"type":"string"},"request_delivery_reports":{"type":"boolean","default":false},"metadata":{"type":"object"}}}}}}},"NumberConfiguration":{"type":"object","properties":{"number":{"type":"string"},"number_type":{"type":"string","enum":["long-code","short-code","toll-free"]},"mms_enabled":{"type":"boolean"},"mms_uri":{"type":["string","null"]},"sms_enabled":{"type":"boolean"},"campaign_id":{"type":["string","null"]},"compliance_status":{"type":"string","enum":["non_compliant","pending","compliant"]},"sms_status":{"type":"string","enum":["NONE","PENDING","ACTIVE","ERROR","DSBL-PND"]},"use_case_type":{"type":"string","enum":["","p2p","a2p"]},"nnid":{"type":["string","null"]},"sms_post_ver":{"type":"string","enum":["smpp","postv1","postv2","post3jam"]},"sms_uri":{"type":["string","null"],"description":"null means SMPP delivery."},"x_api_key_header":{"type":["string","null"]},"ten_dlc_registered":{"type":"boolean"},"tmobile_ten_dlc_registered":{"type":"boolean"}}},"MmsConfiguration":{"type":"object","properties":{"number":{"type":"string"},"mms_enabled":{"type":"boolean"},"mms_uri":{"type":["string","null"]},"sms_enabled":{"type":"boolean"},"sms_uri":{"type":["string","null"]}}},"SmsEnablementRequest":{"type":"object","required":["did","action"],"properties":{"did":{"type":"string","example":"12003004000"},"action":{"type":"string","enum":["add","update","delete"]},"use_case_type":{"type":"string","enum":["a2p","p2p","account_default"]},"p2p_nnid":{"type":"string"},"mms_enable":{"type":"string","enum":["true","false"]},"mms_routing":{"type":"string","description":"http, https, mm4 or mm4s URL for inbound MMS."},"webhook_url":{"type":"string","format":"uri"},"webhook_type":{"type":"string","enum":["smpp","postv1","postv2","post3jam"]},"x_api_key_header":{"type":"string"},"campaign_id":{"type":"string","description":"10DLC campaign to assign. Sole-proprietor campaigns allow one number."},"campaign_sub_id":{"type":"string"},"skip_number_validation":{"type":"string","enum":["true"],"description":"Only after TSG has accepted your LOA for the number."}}},"DestinationPriority":{"type":"object","required":["did","priority","destination","call_type"],"properties":{"did":{"type":"string","example":"12003004000"},"priority":{"type":"integer","minimum":1,"maximum":3},"destination":{"type":"string","description":"Gateway IP for VOIP, E.164 for PSTN."},"call_type":{"type":"string","enum":["VOIP","PSTN"],"description":"Case sensitive."},"call_option":{"type":"string","enum":["WP","NP"],"description":"WP sends the DID with a plus, NP without. Case sensitive."}}}}}}