openapi: 3.1.0
info:
title: API Overview | Sinch
version: "v1"
description: Sinch SMS API is one of the easiest APIs we offer and enables you to add fast and reliable global SMS to your applications. Send single messages, scheduled batch messages, use available message templates and more.
contact:
name: Support
url: www.sinch.com
email: Support@sinch.com
license:
name: MIT
url: "https://www.sinch.com/toc"
servers:
- url: "https://{region}.sms.api.sinch.com"
description: Global API
variables:
region:
default: us
enum:
- us
- eu
- au
- br
- ca
x-enumDescriptions:
us: United States
eu: Europe
au: Australia
br: Brazil
ca: Canada
security:
- BearerAuth: []
webhooks:
incomingSMS:
summary: Incoming SMS
post:
tags:
- Webhooks
- Inbounds
summary: Incoming SMS
description: |-
An inbound message is a message sent to one of your short codes or long numbers from a mobile phone.
To receive inbound message callbacks, a URL needs to be added to your REST API. This URL can be specified in your [Dashboard](https://dashboard.sinch.com/sms/api).
operationId: incomingSMS
requestBody:
description: The incoming message to your sinch number
content:
application/json:
schema:
oneOf:
- type: object
$ref: '#/components/schemas/MOText'
- type: object
$ref: '#/components/schemas/MOBinary'
- type: object
$ref: '#/components/schemas/MOMedia'
examples:
Text MO:
value:
body: This is a test message.
from: "16051234567"
id: 01XXXXX21XXXXX119Z8P1XXXXX
operator_id: string
received_at: 2022-08-24T14:15:22Z
sent_at: 2022-08-24T14:15:22Z
to: "13185551234"
type: mo_text
Binary MO:
value:
body: VGV4dCBtZXNzYWdl
from: "16051234567"
id: 01XXXXX21XXXXX119Z8P1XXXXX
operator_id: operator
received_at: 2022-08-24T14:15:22Z
sent_at: 2022-08-24T14:15:22Z
to: "13185551234"
type: mo_binary
udh: 10010203040506070809000a0b0c0d0e0f
Media MO:
value:
body:
subject: "Test subject"
message: "Test message"
media:
- url: "https://some.s3.example.com/inbounds"
contentType: "image/png"
status: "UPLOADED"
code: 0
from: "+11203494390"
id: 01XXXXX21XXXXX119Z8P1XXXXX
received_at: 2019-08-24T14:15:22Z
sent_at: 2019-08-24T14:15:22Z
to: "11203453453"
type: mo_media
responses:
"200":
description: A `2xx` status code indicates that the data was received successfully.
"400":
description: A `4xx` status counts as a permanent failure and will not trigger any retries, except for `429`.
"429":
description: The callback will be retried and the callback throughput will be lowered.
"500":
description: A `5xx` status code will trigger a retry.
security: []
deliveryReport:
summary: Delivery Report
post:
tags:
- Webhooks
- Delivery reports
summary: Delivery Report
description: |-
A delivery report contains the status and status code for each recipient of a batch. To get a delivery report callback for a message or batch of messages, set the `delivery_report` field accordingly when [creating a batch](/docs/sms/api-reference/sms/tag/Batches/#tag/Batches/operation/SendSMS).
The following is provided so you can better understand our webhooks/callbacks. Configuration of both webhooks and the type of delivery report requested happens when sending a batch.
#### Callback URL
The callback URL can either be provided for each batch or provisioned globally for your account in your [Sinch Customer Dashboard](https://dashboard.sinch.com/sms/api/rest). Learn how to configure a webhook/callback here.
#### Type
The `type` is the type of delivery report webhook. The response will vary depending on the webhook delivery report you selected when the batch was sent, so choose the appropriate selection under "One of".
- The `delivery_report_sms` and `delivery_report_mms` types are documented under Delivery report. These are reports containing either [a full report or summary report](/docs/sms/api-reference/sms/tag/Batches/#tag/Batches/operation/SendSMS!path=0/delivery_report&t=request), depending on your selection at the time the batch was sent.
- The `recipient_delivery_report_sms` and `recipient_delivery_report_mms` delivery report types are documented under Recipient delivery report. These are delivery reports for recipient phone numbers. If you set `per_recipient` for the `delivery_report` parameter when sending the batch, a recipient report gets sent to you for each status change for each recipient in your batch. If you set `per_recipient_final`, a recipient report gets sent to you for the final status of each recipient in your batch.
operationId: deliveryReport
requestBody:
description: ""
content:
application/json:
schema:
oneOf:
- $ref: "#/components/schemas/DeliveryReport"
- $ref: "#/components/schemas/RecipientDeliveryReport"
examples:
Delivery report:
$ref: "#/components/examples/SmsDeliveryReport"
Recipient delivery report:
$ref: "#/components/examples/SmsRecipientDeliveryReport"
MMS delivery report:
$ref: "#/components/examples/MmsDeliveryReport"
MMS recipient delivery report:
$ref: "#/components/examples/MmsRecipientDeliveryReport"
responses:
"200":
description: A `2xx` status code indicates that the data was received successfully.
"400":
description: A `4xx` status counts as a permanent failure and will not trigger any retries, except for `429`.
"429":
description: The callback will be retried and the callback throughput will be lowered.
"500":
description: A `5xx` status code will trigger a retry.
security: []
paths:
"/xms/v1/{service_plan_id}/batches":
parameters:
- $ref: "#/components/parameters/service_plan_id"
post:
tags:
- Batches
summary: Send
operationId: SendSMS
description: |-
Send a message or a batch of messages.
Depending on the length of the body, one message might be split into multiple parts and charged accordingly.
Any groups targeted in a scheduled batch will be evaluated at the time of sending. If a group is deleted between batch creation and scheduled date, it will be considered empty.
Be sure to use the correct region in the server URL.
requestBody:
content:
application/json:
schema:
oneOf:
- $ref: "#/components/schemas/TextRequest"
- $ref: "#/components/schemas/BinaryRequest"
- $ref: "#/components/schemas/MediaRequest"
examples:
BatchSendFillInText:
$ref: "#/components/examples/BatchSendFillInText"
BatchSendFillInBinary:
$ref: "#/components/examples/BatchSendFillInBinary"
BatchSendFillInMedia:
$ref: "#/components/examples/BatchSendFillInMedia"
BatchSendBasicSMSText:
$ref: "#/components/examples/BatchSendBasicSMSText"
BatchSendBasicSMSBinary:
$ref: "#/components/examples/BatchSendBasicSMSBinary"
BatchSendBasicCardMMS:
$ref: "#/components/examples/BatchSendBasicCardMMS"
BatchSendBasicMediaMMS:
$ref: "#/components/examples/BatchSendBasicMediaMessage"
BatchMessageWExpiryText:
$ref: "#/components/examples/BatchMessageWExpiryText"
BatchMessageWExpiryBinary:
$ref: "#/components/examples/BatchMessageWExpiryBinary"
BatchMessageCustomDeliveryReportURLText:
$ref: "#/components/examples/BatchMessageCustomDeliveryReportURLText"
BatchMessageCustomDeliveryReportURLBinary:
$ref: "#/components/examples/BatchMessageCustomDeliveryReportURLBinary"
BatchParameterizedMessageText:
$ref: "#/components/examples/BatchParameterizedMessageText"
BatchParameterizedMediaMessageText:
$ref: "#/components/examples/BatchParameterizedMediaMessageText"
description: "Default schema is Text if type is not specified."
responses:
"201":
description: Created. A successful response, or an [Error](/docs/sms/api-reference/status-codes/).
content:
application/json:
schema:
oneOf:
- $ref: "#/components/schemas/TextResponse"
- $ref: "#/components/schemas/BinaryResponse"
- $ref: "#/components/schemas/MediaResponse"
examples:
TextResponseExample:
$ref: "#/components/examples/TextResponse"
get:
summary: List Batches
operationId: ListBatches
description: With the list operation you can list batch messages created in the last 14 days that you have created. This operation supports pagination.
tags:
- Batches
security:
- BearerAuth: []
parameters:
- name: page
description: The page number starting from 0.
schema:
type: integer
in: query
example: 4
- name: page_size
schema:
type: integer
default: 30
maximum: 100
example: 50
in: query
description: |-
Determines the size of a page.
- name: from
in: query
schema:
type: string
example: 44345,45607
description: "Only list messages sent from this sender number. Multiple originating numbers can be comma separated. Must be phone numbers or short code."
- name: start_date
in: query
schema:
type: string
description: |-
Only list messages received at or after this date/time. Formatted as [ISO-8601](https://en.wikipedia.org/wiki/ISO_8601): `YYYY-MM-DDThh:mm:ss.SSSZ`.
Default:
Now-24
- name: end_date
in: query
schema:
type: string
description: "Only list messages received before this date/time. Formatted as [ISO-8601](https://en.wikipedia.org/wiki/ISO_8601): `YYYY-MM-DDThh:mm:ss.SSSZ`."
- name: client_reference
in: query
description: Client reference to include
required: false
schema:
maxLength: 2048
minLength: 0
type: string
example: myReference
responses:
"200":
description: OK. A successful response, or an [Error](/docs/sms/api-reference/status-codes/).
headers: {}
content:
application/json:
schema:
$ref: '#/components/schemas/ApiBatchList'
examples:
ApiBatchListExample:
$ref: "#/components/examples/ApiBatchList"
"/xms/v1/{service_plan_id}/inbounds":
parameters:
- $ref: "#/components/parameters/service_plan_id"
get:
summary: List incoming messages
tags:
- Inbounds
security:
- BearerAuth: []
operationId: ListInboundMessages
description: With the list operation, you can list all inbound messages that you have received. This operation supports pagination. Inbounds are returned in reverse chronological order.
parameters:
- $ref: "#/components/parameters/page"
- name: page_size
schema:
type: integer
maximum: 100
default: 30
in: query
description: |-
Determines the size of a page
- name: to
schema:
type: string
example: +14155553421, +13435552671, +14325552677
in: query
description: |-
Only list messages sent to this destination. Multiple phone numbers formatted as either E.164 or short codes can be comma separated.
- name: start_date
schema:
type: string
default: Now-24
format: ISO-8601
in: query
description: |-
Only list messages received at or after this date/time. Formatted as [ISO-8601](https://en.wikipedia.org/wiki/ISO_8601): `YYYY-MM-DDThh:mm:ss.SSSZ`.
Default:
Now-24
- name: end_date
schema:
type: string
format: ISO-8601
example: "2016-10-02T09:34:18.542Z"
in: query
description: "Only list messages received before this date/time. Formatted as [ISO-8601](https://en.wikipedia.org/wiki/ISO_8601): `YYYY-MM-DDThh:mm:ss.SSSZ`."
- name: client_reference
in: query
description: |-
Using a client reference in inbound messages requires additional setup on your account. Contact your account manager to enable this feature.
Only list inbound messages that are in response to messages with a previously provided client reference.
required: false
schema:
maxLength: 2048
minLength: 0
type: string
example: myReference
responses:
"200":
description: OK. A successful response , or an [Error](/docs/sms/api-reference/status-codes/).
headers: {}
content:
application/json:
schema:
$ref: "#/components/schemas/ApiInboundList"
"/xms/v1/{service_plan_id}/inbounds/{inbound_id}":
parameters:
- $ref: "#/components/parameters/service_plan_id"
- $ref: "#/components/parameters/inbound_id"
get:
summary: Retrieve inbound message
description: This operation retrieves a specific inbound message with the provided inbound ID.
operationId: RetrieveInboundMessage
tags:
- Inbounds
security:
- BearerAuth: []
responses:
"200":
description: OK. A successful response , or an [Error](/docs/sms/api-reference/status-codes/).
content:
application/json:
schema:
oneOf:
- type: object
$ref: '#/components/schemas/MOText'
- type: object
$ref: '#/components/schemas/MOBinary'
- type: object
$ref: '#/components/schemas/MOMedia'
examples:
MOTextExample:
$ref: "#/components/examples/MOText"
"/xms/v1/{service_plan_id}/batches/dry_run":
parameters:
- $ref: "#/components/parameters/service_plan_id"
post:
security:
- BearerAuth: []
summary: Dry run
description: This operation will perform a dry run of a batch which calculates the bodies and number of parts for all messages in the batch without actually sending any messages.
operationId: Dry_Run
tags:
- Batches
requestBody:
content:
application/json:
schema:
oneOf:
- $ref: "#/components/schemas/TextRequest"
- $ref: "#/components/schemas/BinaryRequest"
- $ref: "#/components/schemas/MediaRequest"
examples:
DryRunFillIn:
$ref: "#/components/examples/DryRunFillIn"
DryRunParameters:
$ref: "#/components/examples/DryRunParameters"
parameters:
- schema:
type: boolean
example: true
in: query
name: per_recipient
description: Whether to include per recipient details in the response
- schema:
type: integer
maximum: 1000
default: 100
example: 500
in: query
name: number_of_recipients
description: Max number of recipients to include per recipient details for in the response
responses:
"200":
description: OK. A successful response , or an [Error](/docs/sms/api-reference/status-codes/).
content:
application/json:
schema:
$ref: "#/components/schemas/DryRunResponse"
examples:
DryRunResponseExample:
$ref: "#/components/examples/DryRunResponse"
"/xms/v1/{service_plan_id}/batches/{batch_id}":
parameters:
- $ref: "#/components/parameters/service_plan_id"
- $ref: "#/components/parameters/batch_id"
get:
summary: Get a batch message
operationId: GetBatchMessage
description: This operation returns a specific batch that matches the provided batch ID.
tags:
- Batches
security:
- BearerAuth: []
responses:
"200":
description: OK. A successful response , or an [Error](/docs/sms/api-reference/status-codes/).
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/TextResponse'
- $ref: '#/components/schemas/BinaryResponse'
- $ref: '#/components/schemas/MediaResponse'
examples:
RetrieveMessageResponseExample:
$ref: "#/components/examples/TextResponse"
post:
summary: Update a Batch message
operationId: UpdateBatchMessage
description: This operation updates all specified parameters of a batch that matches the provided batch ID.
tags:
- Batches
security:
- BearerAuth: []
requestBody:
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/ApiUpdateTextMtMessage'
- $ref: '#/components/schemas/ApiUpdateBinaryMtMessage'
- $ref: '#/components/schemas/ApiUpdateMmsMtMessage'
examples:
BatchUpdateFillIn:
$ref: "#/components/examples/BatchUpdateFillIn"
BatchRemovePhoneNumbers:
$ref: "#/components/examples/BatchRemovePhoneNumbers"
BatchAddPhoneNumbers:
$ref: "#/components/examples/BatchAddPhoneNumbers"
responses:
"200":
description: A successful response , or an [Error](/docs/sms/api-reference/status-codes/).
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/TextResponse'
- $ref: '#/components/schemas/BinaryResponse'
- $ref: '#/components/schemas/MediaResponse'
examples:
UpdatedMessageResponseExample:
$ref: "#/components/examples/TextResponse"
BinaryResponseExample:
$ref: "#/components/examples/BinaryResponse"
MediaResponseExample:
$ref: "#/components/examples/MediaResponse"
put:
summary: Replace a batch
operationId: ReplaceBatch
description: This operation will replace all the parameters of a batch with the provided values. It is the same as cancelling a batch and sending a new one instead.
tags:
- Batches
security:
- BearerAuth: []
requestBody:
content:
application/json:
schema:
oneOf:
- $ref: "#/components/schemas/TextRequest"
- $ref: "#/components/schemas/BinaryRequest"
- $ref: "#/components/schemas/MediaRequest"
examples:
TextRequestExample:
$ref: "#/components/examples/TextRequest"
BinaryRequestExample:
$ref: "#/components/examples/BinaryRequest"
MediaRequestExample:
$ref: "#/components/examples/MediaRequest"
responses:
"200":
description: A successful response , or an [Error](/docs/sms/api-reference/status-codes/).
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/TextResponse'
- $ref: '#/components/schemas/BinaryResponse'
- $ref: '#/components/schemas/MediaResponse'
delete:
summary: Cancel a batch message
operationId: CancelBatchMessage
description: |-
A batch can be canceled at any point. If a batch is canceled while it's currently being delivered some messages currently being processed might still be delivered. The delivery report will indicate which messages were canceled and which weren't.
Canceling a batch scheduled in the future will result in an empty delivery report while canceling an already sent batch would result in no change to the completed delivery report.
tags:
- Batches
security:
- BearerAuth: []
responses:
"200":
description: Batch deleted or an [Error](/docs/sms/api-reference/status-codes/).
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/TextResponse'
- $ref: '#/components/schemas/BinaryResponse'
- $ref: '#/components/schemas/MediaResponse'
examples:
CancelBatchResponseExample:
$ref: '#/components/examples/CancelBatchResponse'
"/xms/v1/{service_plan_id}/batches/{batch_id}/delivery_report":
parameters:
- $ref: "#/components/parameters/service_plan_id"
- $ref: "#/components/parameters/batch_id"
get:
summary: Retrieve a delivery report
description: |-
Delivery reports can be retrieved even if no callback was requested. The difference between a summary and a full report is only that the full report contains the phone numbers in E.164 format for each status code.
security:
- BearerAuth: []
tags:
- Delivery reports
operationId: GetDeliveryReportByBatchId
parameters:
- schema:
type: string
enum: [summary, full]
default: summary
in: query
name: type
description: |-
The type of delivery report.
- A `summary` will count the number of messages sent per status.
- A `full` report give that of a `summary` report but in addition, lists phone numbers.
- schema:
type: string
example: "Queued,Dispatched,Delivered"
in: query
name: status
description: Comma separated list of delivery_report_statuses to include
- schema:
type: string
example: "400,405"
in: query
name: code
description: Comma separated list of delivery_receipt_error_codes to include
responses:
"202":
description: Accepted, or an [Error](/docs/sms/api-reference/status-codes/).
content:
application/json:
schema:
$ref: "#/components/schemas/DeliveryReport"
examples:
Delivery Report:
$ref: "#/components/examples/SmsDeliveryReport"
Mms Delivery Report:
$ref: "#/components/examples/MmsDeliveryReport"
"/xms/v1/{service_plan_id}/batches/{batch_id}/delivery_report/{recipient_msisdn}":
parameters:
- $ref: "#/components/parameters/service_plan_id"
- $ref: "#/components/parameters/batch_id"
- $ref: "#/components/parameters/recipient_msisdn"
get:
summary: Retrieve a recipient delivery report
security:
- BearerAuth: []
tags:
- Delivery reports
operationId: GetDeliveryReportByPhoneNumber
description: A recipient delivery report contains the message status for a single recipient phone number.
responses:
"200":
description: A successful response, or an [Error](/docs/sms/api-reference/status-codes/).
content:
application/json:
schema:
$ref: '#/components/schemas/RecipientDeliveryReport'
examples:
Delivery Report:
$ref: "#/components/examples/SmsRecipientDeliveryReport"
Mms Delivery Report:
$ref: "#/components/examples/MmsRecipientDeliveryReport"
"/xms/v1/{service_plan_id}/delivery_reports":
get:
tags:
- Delivery reports
summary: Retrieve a list of delivery reports
description: |-
Get a list of finished delivery reports.
This operation supports pagination.
operationId: getDeliveryReports
parameters:
- $ref: "#/components/parameters/service_plan_id"
- name: page
in: query
description: The page number starting from 0.
required: false
schema:
minimum: 0
type: integer
default: 0
example: 4
- name: page_size
in: query
description: |-
Determines the size of a page.
required: false
schema:
maximum: 100
minimum: 1
type: integer
default: 30
example: 50
- name: start_date
in: query
description: |-
Only list messages received at or after this date/time.
Default: 24h ago
required: false
schema:
type: string
format: YYYY-MM-DDThh:mm:ss.SSSZ
- name: end_date
in: query
description: Only list messages received before this date/time.
required: false
schema:
type: string
format: YYYY-MM-DDThh:mm:ss.SSSZ
example: 2022-10-02T09:34:18.542Z
- name: status
in: query
description: Comma separated list of delivery report statuses to include.
required: false
schema:
type: string
example: "Queued,Dispatched,Delivered"
- name: code
in: query
description: Comma separated list of delivery receipt error codes to include.
required: false
schema:
type: string
example: "400,405"
- name: client_reference
in: query
description: Client reference to include
required: false
schema:
maxLength: 2048
minLength: 0
type: string
example: myReference
responses:
"200":
description: A successful response , or an [Error](/docs/sms/api-reference/status-codes/).
content:
application/json:
schema:
$ref: '#/components/schemas/DeliveryReportList'
examples:
SmsListDeliveryReports:
$ref: "#/components/examples/SmsListDeliveryReports"
security:
- BearerAuth: []
"/xms/v1/{service_plan_id}/batches/{batch_id}/delivery_feedback":
parameters:
- $ref: "#/components/parameters/service_plan_id"
- $ref: "#/components/parameters/batch_id"
post:
tags:
- Batches
summary: Send delivery feedback for a message
description: |-
Send feedback if your system can confirm successful message delivery.
Feedback can only be provided if `feedback_enabled` was set when batch was submitted.
**Batches**: It is possible to submit feedback multiple times for the same batch for different recipients. Feedback without specified recipients is treated as successful message delivery to all recipients referenced in the batch. Note that the `recipients` key is still required even if the value is empty.
**Groups**: If the batch message was creating using a group ID, at least one recipient is required. Excluding recipients (an empty recipient list) does not work and will result in a failed request.
operationId: deliveryFeedback
requestBody:
description: A list of phone numbers (MSISDNs) that successfully received the message.
content:
application/json:
schema:
$ref: '#/components/schemas/ApiDeliveryFeedback'
required: true
responses:
"202":
description: Accepted, or an [Error](/docs/sms/api-reference/status-codes/). A successful response will return an empty 202 HTTP response, indicating that the request has been received and is processing.
security:
- BearerAuth: []
"/xms/v1/{service_plan_id}/groups":
parameters:
- $ref: "#/components/parameters/service_plan_id"
get:
summary: List Groups
operationId: ListGroups
description: |-
With the list operation you can list all groups that you have created. This operation supports pagination.
Groups are returned in reverse chronological order.
security:
- BearerAuth: []
tags:
- Groups
parameters:
- schema:
type: integer
minimum: 0
default: 0
in: query
name: page
description: |-
The page number starting from 0.
example: 50
- schema:
type: integer
maximum: 100
minimum: 0
default: 30
in: query
name: page_size
description: |-
Determines the size of a page.
example: 50
responses:
"200":
description: A successful response, or an [Error](/docs/sms/api-reference/status-codes/).
content:
application/json:
schema:
$ref: "#/components/schemas/GroupList"
examples:
GroupListExample:
$ref: "#/components/examples/GroupList"
post:
summary: Create a group
operationId: CreateGroup
description: |-
This endpoint allows you to create a group of recipients. A new group must be created with a group name. This is represented by the `name` field which can be up to 20 charecters. In addition, there are a number of optional fields:
- `members` field enables groups to be created with an initial list of contacts
- `auto_update` allows customers to auto subscribe to a new group. This contains three fields. The `to` field contains the group creator's number. (This number **must be provisioned by contacting your account manager**.) The `add` and `remove` fields are objects containing the keywords that customers need to text to join or leave a group.
security:
- BearerAuth: []
tags:
- Groups
requestBody:
content:
application/json:
schema:
$ref: "#/components/schemas/groupObject"
examples:
GroupCreateFillIn:
$ref: "#/components/examples/GroupCreateFillIn"
CreateGroup:
$ref: "#/components/examples/CreateGroup"
GroupCreateParent:
$ref: "#/components/examples/GroupCreateParent"
responses:
"201":
description: Created, or an [Error](/docs/sms/api-reference/status-codes/).
content:
application/json:
schema:
$ref: "#/components/schemas/createGroupResponse"
examples:
createGroupResponseExample:
$ref: "#/components/examples/createGroupResponse"
"/xms/v1/{service_plan_id}/groups/{group_id}":
parameters:
- $ref: "#/components/parameters/service_plan_id"
- $ref: "#/components/parameters/group_id"
get:
summary: Retrieve a group
description: This operation retrieves a specific group with the provided group ID.
operationId: RetrieveGroup
tags:
- Groups
responses:
"200":
description: A successful response, or an [Error](/docs/sms/api-reference/status-codes/).
content:
application/json:
schema:
$ref: "#/components/schemas/createGroupResponse"
post:
summary: Update a group
description: |-
With the update group operation, you can add and remove members in an existing group as well as rename the group.
This method encompasses a few ways to update a group:
1. By using `add` and `remove` arrays containing phone numbers, you control the group movements. Any list of valid numbers in E.164 format can be added.
2. By using the `auto_update` object, your customer can add or remove themselves from groups.
3. You can also add or remove other groups into this group with `add_from_group` and `remove_from_group`.
#### Other group update info
- The request will not be rejected for duplicate adds or unknown removes.
- The additions will be done before the deletions. If an phone number is on both lists, it will not be apart of the resulting group.
- Updating a group targeted by a batch message scheduled in the future is allowed. Changes will be reflected when the batch is sent.
operationId: UpdateGroup
security:
- BearerAuth: []
tags:
- Groups
requestBody:
content:
application/json:
schema:
$ref: "#/components/schemas/UpdateGroup"
examples:
GroupAddRemoveList:
$ref: "#/components/examples/GroupAddRemoveList"
GroupAutoUpdate:
$ref: "#/components/examples/GroupAutoUpdate"
GroupAutoUpdateSharedShortCode:
$ref: "#/components/examples/GroupAutoUpdateSharedShortCode"
GroupUpdateAdd:
$ref: "#/components/examples/GroupUpdateAdd"
GroupUpdateRemove:
$ref: "#/components/examples/GroupUpdateRemove"
GroupUpdateNameKeepMembers:
$ref: "#/components/examples/GroupUpdateNameKeepMembers"
responses:
"200":
description: A successful response, or an [Error](/docs/sms/api-reference/status-codes/).
content:
application/json:
schema:
$ref: "#/components/schemas/createGroupResponse"
put:
security:
- BearerAuth: []
summary: Replace a group
operationId: ReplaceGroup
description: |-
The replace operation will replace all parameters, including members, of an existing group with new values.
Replacing a group targeted by a batch message scheduled in the future is allowed and changes will be reflected when the batch is sent.
tags:
- Groups
requestBody:
content:
application/json:
schema:
$ref: "#/components/schemas/ReplacedGroup"
examples:
GroupReplaceGroup:
$ref: "#/components/examples/GroupReplaceGroup"
responses:
"200":
description: A successful response, or an [Error](/docs/sms/api-reference/status-codes/).
content:
application/json:
schema:
$ref: "#/components/schemas/createGroupResponse"
delete:
tags:
- Groups
summary: Delete a group
description: This operation deletes the group with the provided group ID.
operationId: deleteGroup
parameters:
- name: service_plan_id
in: path
required: true
$ref: '#/components/parameters/service_plan_id'
schema:
type: string
- name: group_id
in: path
required: true
$ref: '#/components/parameters/group_id'
schema:
type: string
responses:
"200":
description: A successful response , or an [Error](/docs/sms/api-reference/status-codes/).
security:
- BearerAuth: []
"/xms/v1/{service_plan_id}/groups/{group_id}/members":
parameters:
- $ref: "#/components/parameters/service_plan_id"
- $ref: "#/components/parameters/group_id"
get:
summary: Get phone numbers for a group
description: |-
This operation retrieves the members of the group with the provided group ID.
security:
- BearerAuth: []
operationId: GetMembers
tags:
- Groups
responses:
"200":
description: A successful response, or an [Error](/docs/sms/api-reference/status-codes/).
content:
application/json:
schema:
type: array
items:
$ref: "#/components/schemas/msisdn"
components:
examples:
MediaRequest:
summary: media request example
value:
to:
- 15551231234
- 15551256344
body:
url: https://en.wikipedia.org/wiki/Sinch_(company)#/media/File:Sinch_LockUp_RGB.png
BinaryRequest:
summary: binary request example
value:
to:
- 15551231234
- 15551256344
body: Hi ${name}! How are you?
udh: abcxaf123
TextRequest:
summary: example text request
value:
to:
- 15551231234
- 15551256344
body: Hi ${name}! How are you?
DryRunResponse:
summary: example dry run response
value:
number_of_recipients: 1
number_of_messages: 1
per_recipient:
- recipient: 15551231234
number_of_parts: 1
body: Test Message
encoding: GSM
ApiUpdateTextMtMessage:
summary: example message response
value:
id: 01FC66621XXXXX119Z8PMV1QPQ
to:
- 15551231234
- 15551256344
from: 15551231234
canceled: false
parameters:
"{parameter_key}":
"{msisdn}": string
default: string
body: Hi ${name}! How are you?
type: mt_text
created_at: '2019-08-24T14:15:22Z'
modified_at: '2019-08-24T14:15:22Z'
delivery_report: none
send_at: '2019-08-24T14:15:22Z'
expire_at: '2019-08-24T14:15:22Z'
callback_url: string
client_reference: myReference
feedback_enabled: false
flash_message: false
truncate_concat: true
max_number_of_message_parts: 1
from_ton: 6
from_npi: 18
createGroupResponse:
summary: example group response
value:
id: 01FC66621XXXXX119Z8PMV1QPU
name: My new customers
size: 2
created_at: '2019-08-24T14:15:22Z'
modified_at: '2019-08-24T14:15:22Z'
child_groups:
- 01FC66621XXXXX119Z8PMV1AHY
auto_update:
to: 15551231234
add: join
remove: leave
msisdn:
summary: phone number response
value:
- "+453234457784"
ApiInboundList:
summary: List of incoming messages
value:
count: 1
page: 0
inbounds:
- body: Test Message
client_reference: ABC123
from: "+11203494390"
id: 01FC66621XXXXX119Z8PMV1QPA
operator_id: '35000'
received_at: '2019-08-24T14:15:22Z'
sent_at: '2019-08-24T14:15:22Z'
to: '11203453453'
type: mo_text
page_size: 50
MOText:
summary: Mobile originating message
value:
body: Test message
client_reference: ABC123
from: "+11203494390"
id: 01FC66621XXXXX119Z8PMV1QPA
operator_id: '35000'
received_at: '2019-08-24T14:15:22Z'
sent_at: '2019-08-24T14:15:22Z'
to: '11203453453'
type: mo_text
MOMedia:
summary: Mobile originating message
value:
body:
subject: Test subject
message: Test message
media:
- url: "https://some.s3.example.com/inbounds"
contentType: 'image/jpeg'
status: UPLOADED
code: 0
from: "+11203494390"
id: 01FC66621XXXXX119Z8PMV1QPA
received_at: '2019-08-24T14:15:22Z'
sent_at: '2019-08-24T14:15:22Z'
to: '11203453453'
type: mo_media
CancelBatchResponse:
summary: batch message example
value:
id: 01FC66621XXXXX119Z8PMV1QPQ
to:
- 15551231234
- 15551256344
from: 15551231234
canceled: true
parameters:
"{parameter_key}":
"{msisdn}": 15551231234
default: string
body: Hi ${name}! How are you?
type: mt_text
created_at: '2019-08-24T14:15:22Z'
modified_at: '2019-08-24T14:15:22Z'
delivery_report: none
send_at: '2019-08-24T14:15:22Z'
expire_at: '2019-08-24T14:15:22Z'
callback_url: myCallbackUrl
client_reference: myReference
feedback_enabled: false
flash_message: false
truncate_concat: true
max_number_of_message_parts: 1
from_ton: 6
from_npi: 18
TextResponse:
summary: batch message example
value:
id: 01FC66621XXXXX119Z8PMV1QPQ
to:
- 15551231234
- 15551256344
from: 15551231234
canceled: false
parameters:
"{parameter_key}":
"{msisdn}": 15551231234
default: string
body: Hi ${name}! How are you?
type: mt_text
created_at: '2019-08-24T14:15:22Z'
modified_at: '2019-08-24T14:15:22Z'
delivery_report: none
send_at: '2019-08-24T14:15:22Z'
expire_at: '2019-08-24T14:15:22Z'
callback_url: myCallbackUrl
client_reference: myReference
feedback_enabled: false
flash_message: false
truncate_concat: true
max_number_of_message_parts: 1
from_ton: 6
from_npi: 18
BinaryResponse:
summary: binary response example
value:
id: 01FC66621XXXXX119Z8PMV1QPQ
to:
- 15551231234
- 15551256344
from: 15551231234
canceled: false
parameters:
"{parameter_key}":
"{msisdn}": 15551231234
default: string
body: "YOUR_base64_message_body"
udh: "abcxaf123"
type: mt_binary
created_at: '2019-08-24T14:15:22Z'
modified_at: '2019-08-24T14:15:22Z'
delivery_report: none
send_at: '2019-08-24T14:15:22Z'
expire_at: '2019-08-24T14:15:22Z'
callback_url: myCallbackUrl
client_reference: myReference
feedback_enabled: false
from_ton: 6
from_npi: 18
MediaResponse:
summary: media response example
value:
id: 01FC66621XXXXX119Z8PMV1QPQ
to:
- 15551231234
- 15551256344
from: 15551231234
canceled: false
parameters:
"{parameter_key}":
"{msisdn}": 15551231234
default: string
body:
url: example.source.jpg
message: your image
type: mt_media
created_at: '2019-08-24T14:15:22Z'
modified_at: '2019-08-24T14:15:22Z'
delivery_report: none
send_at: '2019-08-24T14:15:22Z'
expire_at: '2019-08-24T14:15:22Z'
callback_url: myCallbackUrl
client_reference: myReference
feedback_enabled: false
strict_validation: false
ApiBatchList:
summary: API batch list example
value:
count: "2"
page: "1"
batches:
- id: "abc123"
to:
- "01234567"
from: "01234567"
canceled: false
body: "Test message"
udh: "abcxaf123"
type: "mt_text"
created_at: "2023-11-11T09:00:20.0"
modified_at: "2023-11-11T09:00:20.0"
delivery_report: none
send_at: "2023-11-11T09:00:20.0"
expire_at: ""
callback_url: ""
client_reference: "xyz"
feedback_enabled: false
flash_message: false
truncate_concat: "false"
max_number_of_message_parts: "1"
from_ton: "0"
from_npi: "0"
- id: "def345"
to:
- "07654321"
from: "012346790"
canceled: false
body: "Test Message 2"
udh: "abcxaf123"
type: "mt_text"
created_at: "2023-11-11T09:00:20.0"
modified_at: "2023-11-11T09:00:20.0"
delivery_report: none
send_at: "2023-11-11T09:00:20.0"
expire_at: "2023-11-11T09:00:20.0"
callback_url: ""
client_reference: "abc"
feedback_enabled: false
flash_message: false
truncate_concat: "false"
max_number_of_message_parts: "1"
from_ton: "0"
from_npi: "0"
page_size: "10"
BatchSendFillInBinary:
summary: Binary - fill-in
value:
from: "YOUR_Sinch_virtual_number"
to: ["YOUR_recipient_number"]
body: "YOUR_base64_message_body"
delivery_report: "summary"
type: "mt_binary"
udh: "YOUR_user_data_header"
BatchSendFillInMedia:
summary: Media - fill-in
value:
from: "YOUR_Sinch_virtual_number"
to: ["YOUR_recipient_number"]
body: {
"url": "YOUR_media_link",
"message": "Optional Text Message"
}
delivery_report: "summary"
type: "mt_media"
BatchSendFillInText:
summary: Text - fill-in
value:
from: "YOUR_Sinch_virtual_number"
to: ["YOUR_recipient_number"]
body: "YOUR_message_body"
delivery_report: "summary"
type: "mt_text"
BatchSendBasicSMSBinary:
summary: Binary - Basic SMS example
value:
from: "12345"
to: ["+15551231212"]
body: "U2FtcGxlIG1lc3NhZ2Uu"
delivery_report: "full"
type: "mt_binary"
udh: "YOUR_user_data_header"
BatchSendBasicSMSText:
summary: Text - Basic SMS example
value:
from: "12345"
to: ["+15551231212"]
body: "Programmers are tools for converting caffeine into code. We just got a new shipment of mugs! Check them out: https://tinyurl.com/4a6fxce7!"
delivery_report: "full"
type: "mt_text"
BatchSendBasicMediaMessage:
summary: Media - Media only MMS
value:
from: "12345"
to: ["15551231212"]
body: {
"url": "https://en.wikipedia.org/wiki/Sinch_(company)#/media/File:Sinch_LockUp_RGB.png",
}
type: "mt_media"
BatchSendBasicCardMMS:
summary: Media - Card MMS
value:
from: "12345"
to: ["15551231212"]
body: {
"url": "https://en.wikipedia.org/wiki/Sinch_(company)#/media/File:Sinch_LockUp_RGB.png",
"message": "Text message from Sinch!"
}
type: "mt_media"
BatchMessageWExpiryBinary:
summary: Binary - Batch message with expiry
value:
from: "12345"
to: ["+12345678901", "+19876543210"]
body: "U2FtcGxlIG1lc3NhZ2Uu"
delivery_report: "summary"
type: "mt_binary"
udh: "YOUR_user_data_header"
BatchMessageWExpiryText:
summary: Text - Batch message with expiry
value:
from: "12345"
to: ["+12345678901", "+19876543210"]
body: "This is a message that will stop attempting to send after three hours."
delivery_report: "summary"
type: "mt_text"
BatchParameterizedMessageText:
summary: Text - Parameterized message
value:
from: "12345"
to: ["+12345678910", "+449876543210"]
body: "Hi ${name}! Are you in for next week?"
delivery_report: "summary"
type: "mt_text"
parameters:
name:
+12345678910: "Joe"
default: "there"
BatchParameterizedMediaMessageText:
summary: Media - Parameterized message
value:
from: "12345"
to: ["+12345678910", "+449876543210"]
body: {
"url": "https://en.wikipedia.org/wiki/Sinch_(company)#/media/File:Sinch_LockUp_RGB.png",
"message": "Hi ${name}! Are you in for next week?"
}
delivery_report: "summary"
type: "mt_media"
parameters:
name:
+12345678910: "Joe"
default: "there"
BatchMessageCustomDeliveryReportURLBinary:
summary: Binary - Batch message with custom delivery report URL
value:
from: "12345"
to: ["+12345678910", "+449876543210"]
body: "U2FtcGxlIG1lc3NhZ2Uu"
delivery_report: "summary"
callback_url: "http://www.example.com"
type: "mt_binary"
udh: "YOUR_user_data_header"
BatchMessageCustomDeliveryReportURLText:
summary: Text - Batch message with custom delivery report URL
value:
from: "12345"
to: ["+12345678910", "+449876543210"]
body: "There's a fine line between a numerator and a denominator that only a fraction of people understand."
delivery_report: "summary"
callback_url: "http://www.example.com"
type: "mt_text"
DryRunFillIn:
summary: Dry Run
value:
from: "YOUR_virtual_number"
to: ["YOUR_numbers_sending_to", "another_number"]
body: "YOUR body text here"
parameters:
name:
"Phone_number_of_recipient" : "recipient_name"
default: "default_in_place_of_name"
DryRunParameters:
summary: Dry run batch with parameters
# description: Test out a batch with a name parameter without actually sending it.
value:
from: "12345"
to: ["+12345678910", "+449876543210"]
body: "Hi ${name}! Our latest survey shows that 3 out of 4 people make up 75% of the world's population."
parameters:
name:
+12345678910: "Joe"
default: "there"
BatchGetSpecificNumberBatchesInTimeFrame:
summary: Get a specific number of batches within a certain time frame
# description: Retrieve the first 30 batches from the last 24 hours.
value:
page: 1
page_size: 30
start_date: Now-24
BatchGetSpecificPage:
summary: Get a specific page from a batch with multiple pages
# description: Get the third page of a batch with 50 pages from the last 48 hours.
value:
page: 3
page_size: 50
start_date: Now-48
BatchGetSpecificDate:
summary: Get a batch from a specific date
# description: Retrieve batches created on June 23rd, 2021 UTC.
value:
start_date: "2022-06-23T0000"
end_date: "2022-06-23T2400"
BatchGetSpecificBatches:
summary: Get multiple, specific batches
# description: Retrieve batches 44345 and 45607.
value:
from: 44345,45607
BatchUpdateFillIn:
summary: Update
value:
to_remove: ["YOUR_numbers", "to_remove", "as_strings_in_array", "with_country_code", "16267890123"]
to_add: ["YOUR_numbers", "to_add"]
BatchRemovePhoneNumbers:
summary: Remove a group of phone numbers from a batch
# description: Remove five phone numbers from batch 12345.
value:
to_remove: ["11111111111", "29999999999", "15551234567", "1123456789", "15559876543"]
BatchAddPhoneNumbers:
summary: Add phone numbers to a batch
# description: Add two phone numbers to batch 12345
value:
to_add: ["123456789", "987654321"]
DeliveryReportSummary:
summary: Summary report response
# description: Gives a summary report of how many messages were sent, the status code and the status description.
value:
type: "delivery_report_sms"
batch_id: "{batch_id}"
total_message_count: 3
statuses:
- code: 400
status: "Queued"
count: 1
- code: 0
status: "Delivered"
count: 2
DeliveryReportFull:
summary: Full report
# description: Gives a full report of the number of messages sent, status codes, status descriptions and an array of the numbers sent to/failed messages.
value:
type: "delivery_report_sms"
batch_id: "{batch_id}"
total_message_count: 3
statuses:
- code: 400
status: "Queued"
count: 1
recipients: ["123456789"]
- code: 0
status: "Delivered"
count: 2
recipients: ["987654321", "123459876"]
DeliveryReportSpecificNumber:
summary: For a specific number
# description: Pulls up a report for a specific phone number or short code
value:
type: "recipient_delivery_report_sms"
batch_id: "{batch_id}"
total_message_count: 1
statuses:
- code: 400
status: "Queued"
count: 1
recipients: ["123456789"]
SmsDeliveryReport:
summary: SMS delivery report
value:
batch_id: 01FC66621XXXXX119Z8PMV1QPQ
statuses:
- code: 0
count: 1
recipients:
- "44231235674"
status: Delivered
total_message_count: 1
type: delivery_report_sms
MmsDeliveryReport:
summary: MMS delivery report
value:
batch_id: 01FC66621XXXXX119Z8PMV1QPQ
statuses:
- code: 0
count: 1
recipients:
- "44231235674"
status: Delivered
total_message_count: 1
type: delivery_report_mms
MmsRecipientDeliveryReport:
summary: MMS recipient delivery report
value:
at: 2022-08-30T08:16:08.930Z
batch_id: 01FC66621XXXXX119Z8PMV1QPQ
code: 0
recipient: "44231235674"
status: Delivered
type: recipient_delivery_report_mms
SmsRecipientDeliveryReport:
summary: SMS recipient delivery report
value:
type: "recipient_delivery_report_sms"
batch_id: "01FC66621XXXXX119Z8PMV1QPQ"
recipient: "+44231235674"
code: 401
status: "Dispatched"
at: "2022-08-30T08:16:08.930Z"
SmsListDeliveryReports:
summary: List delivery reports
value:
count: 1
page: 0
page_size: 2
delivery_reports:
- applied_originator: "My Originator"
at: "2019-08-24T14:15:22Z"
batch_id: "01FC66621XXXXX119Z8PMV1QPQ"
client_reference: "my_client_reference"
code: 0
encoding: "GSM"
number_of_message_parts: 1
operator: "35000"
operator_status_at: "2019-08-24T14:15:22Z"
recipient: "15551231234"
status: "Delivered"
type: "recipient_delivery_report_sms"
GroupCreateFillIn:
summary: Create a group - fill in
value:
members: ["member_MSISDNs", "as_strings_in_array", "16051234567"]
name: "YOUR_group_name"
CreateGroup:
summary: Create a group
value:
members: ["123456789", "987654321"]
name: "Atlanta Pythonistas"
GroupAutoUpdate:
summary: Update a group based on customer keyword response
# description: Create auto update group for members sending MOs to `443456789012`. Keyword JOIN will add them to the group, keyword STOP will remove them from the group.
value:
name: "Homeowners"
auto_update:
to: "443456789012"
add:
first_word: "Join"
remove:
first_word: "Stop"
GroupAutoUpdateSharedShortCode:
summary: Create auto an update group for a shared short code
value:
name: "Patients at Clinic 2"
auto_update:
to: "54321"
add:
first_word: "West2"
second_word: "Join"
remove:
first_word: "West2"
second_word: "Stop"
GroupAddRemoveList:
summary: Add or remove a list of phone numbers
value:
add: ["+14058961234", "+447911123456", "+55987654321"]
remove: ["+4612345678", "+15551235555"]
GroupCreateParent:
summary: Create a parent group
description: Create a parent group that includes all members of groups with a certain ID.
value:
name: "New Munster"
child_groups: ["01FC66621XXXXX119Z8PMV1QPQ", "01AB61221XXXXX119X8PMV1ABA"]
GroupUpdateAdd:
summary: Add or remove members from another group
value:
add_from_group: "01FC66621XXXXX119Z8PMV1QPQ"
remove_from_group: "01AB61221XXXXX119X8PMV1ABA"
GroupUpdateRemove:
summary: Rename a group without changing its members
value:
name: "New group name"
GroupUpdateNameKeepMembers:
summary: Remove the name of a group without changing its members
value:
name: "string"
GroupReplaceGroup:
summary: Replace a group
value:
members: ["123456789", "987654321"]
name: "New Name of the Group"
ListGroupQuantity:
summary: Retrieve the first 30 groups
value:
page: 0
count: 30
ListGroupPage:
summary: Retrieve a certain page with a defined page size
# description: Retrieve the third page of groups with a page size of 50.
value:
page: 3
page_size: 50
GroupList:
summary: Retrieve a list of groups
value:
page: 50
page_size: 50
count: 1
groups:
- name: My First Group
members: ["+14155553421", "+13435552671", "+14325552677"]
child_groups: []
auto_update:
to: "+453234457784"
add:
first_word: join
second_word: add
remove:
first_word: leave
second_word: remove
schemas:
GroupList:
type: object
properties:
page:
type: integer
description: "The requested page."
example: 50
page_size:
type: integer
description: "The number of groups returned in this request"
example: 50
count:
type: integer
description: "The total number of groups."
example: 1
groups:
type: array
items:
$ref: "#/components/schemas/groupObject"
DryRunResponse:
type: object
properties:
number_of_recipients:
type: integer
description: The number of recipients in the batch
number_of_messages:
type: integer
description: The total number of SMS message parts to be sent in the batch
per_recipient:
type: array
description: "The recipient, the number of message parts to this recipient, the body of the message, and the encoding type of each message"
items:
type: object
properties:
recipient:
type: string
number_of_parts:
type: integer
body:
type: string
encoding:
type: string
ReplacedGroup:
type: object
required:
- members
properties:
name:
type: string
maxItems: 20
description: |-
Name of group.
members:
type: array
maxItems: 10000
description: |-
The initial members of the group.
Constraints:
Elements must be phone numbers in E.164 format MSISDNs.
items:
$ref: "#/components/schemas/msisdn"
UpdateGroup:
type: object
properties:
name:
type: [string, "null"]
maxLength: 20
description: The name of the group. Omitting `name` from the JSON body will leave the name unchanged. To remove an existing name set, name explicitly to the JSON value `null`.
add:
type: array
description: Add a list of phone numbers (MSISDNs) to this group. The phone numbers are a strings within an array and must be in E.164 format.
remove:
type: array
description: Remove a list of phone numbers (MSISDNs) to this group.The phone numbers are a strings within an array and must be in E.164 format.
add_from_group:
type: string
description: |-
Copy the members from the another group into this group.
Constraints:
Must be valid group ID
remove_from_group:
type: string
description: |-
Remove the members in a specified group from this group.
Constraints:
Must be valid group ID
auto_update:
type: object
properties:
to:
type: string
description: |-
Short code or long number addressed in MO.
Constraints:
Must be valid phone number or short code which has been **provisioned by your account manager**.
add:
type: object
properties:
first_word:
type: string
pattern: '^\w+$'
description: |-
Keyword to be sent in MO to add phone number to a group opt-in keyword like "JOIN". If `auto_update.to` is dedicated long/short number or unique brand keyword like "Sinch" if it is a shared short code.
Constraints:
Must be one word.
maxLength: 15
second_word:
type: string
pattern: '^\w+$'
description: |-
Opt-in keyword like "JOIN" if auto_update.to is shared short code.
Constraints:
Must be one word.
maxLength: 15
remove:
type: object
description: Keyword to be sent in MO to remove from a group.
properties:
first_word:
type: string
pattern: '^\w+$'
description: |-
Opt-out keyword. For example, "LEAVE" if `auto_update.to` is a dedicated long/short number or a unique brand keyword like "Sinch" (if it is a shared short code).
Constraints:
Must be one word.
maxLength: 15
second_word:
type: string
pattern: '^\w+$'
description: |-
Opt-out keyword. For example, "LEAVE" if `auto_update.to` is a shared short code.
Constraints:
Must be one word.
maxLength: 15
recipients:
type: array
items:
$ref: '#/components/schemas/msisdn'
errorResponseObj:
type: object
properties:
code:
type: string
description: The error code. See [error codes](/docs/sms/api-reference/#error-codes).
text:
type: string
description: The human readable description of the error.
GroupAutoUpdate:
required:
- to
type: object
properties:
to:
type: string
description: |-
Short code or long number addressed in MO.
Constraints:
Must be valid phone number or short code which has been **provisioned by your account manager**.
format: E.164
example: +15551231234
add:
$ref: '#/components/schemas/addKeyword'
remove:
$ref: '#/components/schemas/removeKeyword'
addKeyword:
type: string
removeKeyword:
type: string
createGroupResponse:
type: object
properties:
id:
type: string
description: The ID used to reference this group.
example: 01FC66621XXXXX119Z8PMV1QPU
name:
maxLength: 20
minLength: 1
type: string
description: Name of group, if set.
example: My new customers
size:
type: integer
description: The number of members currently in the group.
format: int32
readOnly: true
example: 2
created_at:
type: string
description: |-
Timestamp for group creation. Format: YYYY-MM-DDThh:mm:ss.SSSZ
format: date-time
readOnly: true
modified_at:
type: string
description: |-
Timestamp for when the group was last updated. Format: YYYY-MM-DDThh:mm:ss.SSSZ
format: date-time
readOnly: true
child_groups:
maxItems: 10
minItems: 0
uniqueItems: true
type: array
description: |-
Phone numbers (MSISDNs) of child group will be included in this group. If present, this group will be auto populated.
Constraints: Elements must be group IDs.
example:
- 01FC66621XXXXX119Z8PMV1AHY
items:
$ref: '#/components/schemas/MtGroupId'
auto_update:
$ref: '#/components/schemas/GroupAutoUpdate'
MtGroupId:
type: object
description: |-
Phone numbers (MSISDNs) of a child group will be included in this group. If present, this group will be auto populated.
Constraints: Elements must be group IDs.
example:
- 01FC66621XXXXX119Z8PMV1AHY
ApiGroup:
type: object
properties:
id:
type: string
description: Unique identifier for the group
readOnly: true
example: 01FC66621XXXXX119Z8PMV1QPQ
DeliveryReportList:
type: object
properties:
count:
type: integer
description: The total number of entries matching the given filters.
format: int64
example: 1
page:
type: integer
description: The requested page.
format: int32
example: 0
page_size:
type: integer
description: The number of entries returned in this request.
format: int32
example: 2
delivery_reports:
type: array
description: The page of delivery reports matching the given filters.
items:
$ref: '#/components/schemas/RecipientDeliveryReport'
RecipientDeliveryReport:
properties:
applied_originator:
type: string
description: "The default originator used for the recipient this delivery\
\ report belongs to, if default originator pool configured and no originator\
\ set when submitting batch."
at:
type: string
format: date-time
description: "A timestamp of when the Delivery Report was created in the Sinch service. Formatted as [ISO-8601](https://en.wikipedia.org/wiki/ISO_8601): `YYYY-MM-DDThh:mm:ss.SSSZ`."
batch_id:
type: string
description: The ID of the batch this delivery report belongs to
example: 01FC66621XXXXX119Z8PMV1QPQ
readOnly: true
client_reference:
type: string
description: "The client identifier of the batch this delivery report belongs to, if set when submitting batch."
code:
type: integer
format: int32
description: The detailed [status code](/docs/sms/api-reference/sms/tag/Delivery-reports/#tag/Delivery-reports/section/Delivery-report-error-codes).
encoding:
type: string
description: Applied encoding for message. Present only if smart encoding
is enabled.
enum:
- GSM
- UNICODE
example: GSM
number_of_message_parts:
type: integer
format: int32
description: The number of parts the message was split into. Present only if `max_number_of_message_parts` parameter was set.
example: 1
operator:
type: string
description: "The operator that was used for delivering the message to this recipient, if enabled on the account by Sinch."
example: "35000"
operator_status_at:
type: string
format: date-time
description: "A timestamp extracted from the Delivery Receipt from the originating SMSC. Formatted as [ISO-8601](https://en.wikipedia.org/wiki/ISO_8601): `YYYY-MM-DDThh:mm:ss.SSSZ`."
recipient:
type: string
description: Phone number that was queried.
example: "15551231234"
status:
type: string
description: The simplified status as described in _Delivery Report Statuses_.
example: Delivered
x-enumDescriptions:
Queued: Intermediate type. Message is queued within REST API system and will be dispatched according to the rate of the account.
Dispatched: Intermediate type. Message has been dispatched and accepted for delivery by the SMSC.
Aborted: Final type. Message was aborted before reaching the SMSC.
Cancelled: Final type. Message was cancelled by user before reaching SMSC.
Failed: Final type. Message failed to be delivered.
Delivered: Final type. Message has been delivered.
Expired: Final type. Message expired before delivery to the SMSC. This may happen if the expiry time for the message was very short.
Rejected: Final type. Message was rejected by the SMSC.
Deleted: Final type. Message was deleted by the SMSC.
Unknown: Final type. Message was delivered to the SMSC but no Delivery Receipt has been received or a Delivery Receipt that couldn't be interpreted was received.
type:
type: string
description: The recipient delivery report type.
enum:
- recipient_delivery_report_sms
- recipient_delivery_report_mms
required:
- at
- batch_id
- code
- recipient
- status
- type
title: Recipient delivery report
DeliveryReport:
properties:
batch_id:
type: string
description: The ID of the batch this delivery report belongs to.
example: 01FC66621XXXXX119Z8PMV1QPQ
readOnly: true
client_reference:
type: string
description: The client identifier of the batch this delivery report belongs to, if set when submitting batch.
statuses:
type: array
description: Array with status objects. Only status codes with at least
one recipient will be listed.
items:
$ref: '#/components/schemas/MessageDeliveryStatus'
total_message_count:
type: integer
format: int32
description: The total number of messages in the batch.
example: 2
minimum: 0
type:
type: string
description: The delivery report type.
enum:
- delivery_report_sms
- delivery_report_mms
required:
- batch_id
- statuses
- total_message_count
- type
title: Delivery report
MessageDeliveryStatus:
description: Array with status objects. Only status codes with at least one
recipient will be listed.
properties:
code:
type: integer
format: int32
description: The detailed [status code](/docs/sms/api-reference/sms/tag/Delivery-reports/#tag/Delivery-reports/section/Delivery-report-error-codes).
count:
type: integer
format: int32
description: The number of messages that currently has this code.
example: 2
minimum: 1
recipients:
type: array
description: Only for `full` report. A list of the phone number recipients
which messages has this status code.
example:
- "15551231234"
- "15551256344"
items:
type: string
description: Only for `full` report. A list of the phone number recipients
which messages has this status code.
example: "[\"15551231234\",\"15551256344\"]"
uniqueItems: true
status:
type: string
description: The simplified status as described in _Delivery Report Statuses_.
example: Delivered
x-enumDescriptions:
Queued: Intermediate type. Message is queued within REST API system and will be dispatched according to the rate of the account.
Dispatched: Intermediate type. Message has been dispatched and accepted for delivery by the SMSC.
Aborted: Final type. Message was aborted before reaching the SMSC.
Cancelled: Final type. Message was cancelled by user before reaching SMSC.
Failed: Final type. Message failed to be delivered.
Delivered: Final type. Message has been delivered.
Expired: Final type. Message expired before delivery to the SMSC. This may happen if the expiry time for the message was very short.
Rejected: Final type. Message was rejected by the SMSC.
Deleted: Final type. Message was deleted by the SMSC.
Unknown: Final type. Message was delivered to the SMSC but no Delivery Receipt has been received or a Delivery Receipt that couldn't be interpreted was received.
required:
- code
- count
- recipients
- status
ApiBatchList:
properties:
count:
type: integer
format: int64
description: The total number of entries matching the given filters.
example: 1
page:
type: integer
format: int32
description: The requested page.
example: 0
batches:
type: array
description: The page of batches matching the given filters.
items:
oneOf:
- $ref: '#/components/schemas/BinaryResponse'
- $ref: '#/components/schemas/MediaResponse'
- $ref: '#/components/schemas/TextResponse'
page_size:
type: integer
format: int32
description: The number of entries returned in this request.
example: 30
ApiUpdateBinaryMtMessage:
allOf:
- $ref: '#/components/schemas/ApiUpdateMtMessage'
- type: object
properties:
body:
type: string
description: "The message content Base64 encoded. \n \n Max 140 bytes\
\ together with udh."
udh:
type: string
description: The UDH header of a binary message HEX encoded. Max 140 bytes
together with body.
type:
type: string
description: SMS in binary format
enum:
- mt_binary
from_ton:
maximum: 6
minimum: 0
type: integer
description: The type of number for the sender number. Use to override
the automatic detection.
format: int32
from_npi:
maximum: 18
minimum: 0
type: integer
description: Number Plan Indicator for the sender number. Use to override
the automatic detection.
format: int32
title: Update binary message
ApiUpdateMmsMtMessage:
allOf:
- $ref: '#/components/schemas/ApiUpdateMtMessage'
- type: object
properties:
body:
$ref: '#/components/schemas/MediaBody'
parameters:
$ref: '#/components/schemas/parameterObj'
type:
type: string
description: MMS
enum:
- mt_media
strict_validation:
default: false
type: boolean
description: |
Whether or not you want the media included in your message to be checked against [Sinch MMS channel best practices](/docs/mms/bestpractices/).
If set to true, your message will be rejected if it doesn't conform to the listed recommendations, otherwise no validation will be performed.
title: Update media message
ApiUpdateMtMessage:
type: object
properties:
from:
type: string
description: Sender number. Must be valid phone number, short code or alphanumeric.
example: +15551231234
type:
type: string
to_add:
type: array
description: List of phone numbers and group IDs to add to the batch.
items:
$ref: '#/components/schemas/MtDestination'
maxItems: 1000
minItems: 1
to_remove:
type: array
description: List of phone numbers and group IDs to remove from the batch.
items:
$ref: '#/components/schemas/MtDestination'
maxItems: 1000
minItems: 1
delivery_report:
type: string
description: "Request delivery report callback. \n \n Note that delivery\
\ reports can be fetched from the API regardless of this setting. "
x-enumDescriptions:
none: No delivery report callback will be sent.
summary: A single delivery report callback will be sent.
full: A single delivery report callback will be sent which includes a list of recipients per delivery status.
per_recipient: A delivery report callback will be sent for each status change of a message. This could result in a lot of callbacks and should be **used with caution for larger batches**. These delivery reports also include a timestamp of when the Delivery Report originated from the SMSC.
per_recipient_final: A delivery report callback representing the final status of a message will be sent for each recipient. This will send only one callback per recipient, compared to the multiple callbacks sent when using `per_recipient`. The delivery report will also include a timestamp of when it originated from the SMSC.
send_at:
type: string
format: date-time
description: |
If set, in the future the message will be delayed until `send_at` occurs. Formatted as ISO-8601: `YYYY-MM-DDThh:mm:ss.SSSZ`.
Constraints: Must be before expire_at. If set in the past, messages will be sent immediately.
expire_at:
type: string
format: date-time
description: |
If set, the system will stop trying to deliver the message at this point.
Constraints: Must be after `send_at`
Default: 3 days after `send_at`
callback_url:
type: string
description: |
Override the default callback URL for this batch.
Constraints: Must be valid URL.
maxLength: 2048
minLength: 0
ApiUpdateTextMtMessage:
allOf:
- $ref: '#/components/schemas/ApiUpdateMtMessage'
- type: object
properties:
parameters:
$ref: '#/components/schemas/parameterObj'
body:
type: string
description: The message content
example: "Hi ${name}! How are you?"
maxLength: 2000
minLength: 0
type:
type: string
description: Regular SMS
enum:
- mt_text
from_ton:
maximum: 6
minimum: 0
type: integer
description: The type of number for the sender number. Use to override
the automatic detection.
format: int32
from_npi:
maximum: 18
minimum: 0
type: integer
description: Number Plan Indicator for the sender number. Use to override
the automatic detection.
format: int32
max_number_of_message_parts:
minimum: 1
type: integer
description: Message will be dispatched only if it is not split to more
parts than Max Number of Message Parts
format: int32
truncate_concat:
type: boolean
description: If set to true the message will be shortened when exceeding
one part.
flash_message:
type: boolean
description: Shows message on screen without user interaction while not
saving the message to the inbox.
default: false
title: Update text message
ApiInboundList:
properties:
count:
type: integer
format: int64
description: The total number of inbounds matching the given filters
example: 1
page:
type: integer
format: int32
description: The requested page.
example: 0
inbounds:
type: array
description: The page of inbounds matching the given filters.
items:
oneOf:
- $ref: '#/components/schemas/MOText'
- $ref: '#/components/schemas/MOBinary'
- $ref: '#/components/schemas/MOMedia'
page_size:
type: integer
format: int32
description: The number of inbounds returned in this request.
example: 50
ApiMoMessage:
type: object
description: The page of inbounds matching the given filters.
properties:
client_reference:
type: string
description: |-
If this inbound message is in response to a previously sent message that contained a client reference, then this field contains *that* client reference.
Utilizing this feature requires additional setup on your account. Contact your account manager to enable this feature.
from:
type: string
description: The phone number that sent the message. More info
example: "+11203494390"
id:
type: string
description: The ID of this inbound message.
example: 01FC66621XXXXX119Z8PMV1QPA
operator_id:
type: string
description: The MCC/MNC of the sender's operator if known.
example: "35000"
received_at:
type: string
format: date-time
description: |-
When the system received the message.
Formatted as ISO-8601: `YYYY-MM-DDThh:mm:ss.SSSZ`.
sent_at:
type: string
format: date-time
description: |-
When the message left the originating device. Only available if provided by operator.
Formatted as ISO-8601: `YYYY-MM-DDThh:mm:ss.SSSZ`.
to:
type: string
description: The Sinch phone number or short code to which the message was sent.
example: "11203453453"
type:
type: string
readOnly: true
required:
- from
- id
- received_at
- to
- type
MOBinary:
allOf:
- $ref: '#/components/schemas/ApiMoMessage'
- type: object
properties:
body:
type: string
description: |
The message content Base64 encoded.
Max 140 bytes together with udh.
type:
type: string
description: SMS in binary format
enum:
- mo_binary
readOnly: true
udh:
type: string
description: The UDH header of a binary message HEX encoded. Max 140 bytes
together with body.
required:
- body
- from
- id
- received_at
- to
- udh
title: Binary MO
MOText:
allOf:
- $ref: '#/components/schemas/ApiMoMessage'
- type: object
properties:
body:
type: string
maxLength: 2000
minLength: 0
type:
type: string
description: Regular SMS
enum:
- mo_text
readOnly: true
required:
- body
- from
- id
- received_at
- to
title: Text MO
MOMedia:
allOf:
- $ref: '#/components/schemas/ApiMoMessage'
- type: object
properties:
body:
type: object
$ref: '#/components/schemas/MOMediaBody'
type:
type: string
description: MMS
enum:
- mo_media
readOnly: true
required:
- body
- from
- id
- received_at
- to
title: Media MO
ApiDeliveryFeedback:
type: object
required:
- recipients
properties:
recipients:
type: array
description: A list of phone numbers (MSISDNs) that have successfully received the message. The key is required, however, the value can be an empty array (`[]`) for *a batch*. If the feedback was enabled for *a group*, at least one phone number is required.
items:
type: string
description: List of recipients confirmed to have received their message.
example:
recipients:
- "+15551231234"
- "+15551256344"
parameterObj:
type: object
additionalProperties: true
properties:
'{parameter_key}':
maxLength: 16
minLength: 1
pattern: "^[A-Za-z0-9_\\-.]+$"
type: object
properties:
'{msisdn}':
maxLength: 1600
type: string
description: The key is the recipient that should have the `parameter_key`
replaced with the value
default:
maxLength: 1600
type: string
description: |-
The fall-back value for omitted recipient phone numbers MSISDNs.
description: |-
The name of the parameter that will be replaced in the message body.
Letters A-Z and a-z, digits 0-9 and .-_ allowed.
description: |-
Contains the parameters that will be used for customizing the message for each recipient.
[Click here to learn more about parameterization](/docs/sms/resources/message-info/message-parameterization).
MtDestination:
type: string
description: |-
List of phone numbers and group IDs that will receive the batch.
More info.
format: E.164
example:
- +15551231234
- +15551256344
TextRequest:
required:
- body
- to
type: object
properties:
to:
maxItems: 1000
minItems: 1
type: array
description: List of Phone numbers and group IDs that will receive the batch. More info
format: E.164
example:
- +15551231234
- +15551256344
items:
$ref: '#/components/schemas/MtDestination'
from:
type: string
description: "Sender number. Must be valid phone number, short code or alphanumeric. Required if Automatic Default Originator not configured."
example: +15551231234
parameters:
$ref: '#/components/schemas/parameterObj'
body:
maxLength: 2000
minLength: 0
type: string
description: The message content
example: "Hi ${name}! How are you?"
type:
type: string
description: Regular SMS
enum:
- mt_text
delivery_report:
type: string
description: Request delivery report callback. Note that delivery reports can be fetched from the API regardless of this setting.
default: none
x-enumDescriptions:
none: No delivery report callback will be sent.
summary: A single delivery report callback will be sent.
full: A single delivery report callback will be sent which includes a list of recipients per delivery status.
per_recipient: A delivery report callback will be sent for each status change of a message. This could result in a lot of callbacks and should be **used with caution for larger batches**. These delivery reports also include a timestamp of when the Delivery Report originated from the SMSC.
per_recipient_final: A delivery report callback representing the final status of a message will be sent for each recipient. This will send only one callback per recipient, compared to the multiple callbacks sent when using `per_recipient`. The delivery report will also include a timestamp of when it originated from the SMSC.
send_at:
type: string
description: |-
If set in the future, the message will be delayed until `send_at` occurs. Must be before `expire_at`. If set in the past, messages will be sent immediately. Formatted as [ISO-8601](https://en.wikipedia.org/wiki/ISO_8601): `YYYY-MM-DDThh:mm:ss.SSSZ`.
format: date-time
example: "2024-08-07T12:34:56.789Z"
expire_at:
type: string
description: |-
If set, the system will stop trying to deliver the message at this point. Must be after `send_at`. Default and max is 3 days after `send_at`. Formatted as [ISO-8601](https://en.wikipedia.org/wiki/ISO_8601): `YYYY-MM-DDThh:mm:ss.SSSZ`.
format: date-time
callback_url:
maxLength: 2048
minLength: 0
type: string
description: Override the *default* callback URL for this batch. Must be a valid URL. Learn how to set a default callback URL here.
client_reference:
maxLength: 2048
minLength: 0
type: string
description: The client identifier of a batch message. If set, the identifier will be added in the delivery report/callback of this batch
feedback_enabled:
type: boolean
description: "If set to `true`, then [feedback](/docs/sms/api-reference/sms/tag/Batches/#tag/Batches/operation/deliveryFeedback) is expected after successful delivery."
default: false
flash_message:
type: boolean
description: Shows message on screen without user interaction while not saving the message to the inbox.
default: false
truncate_concat:
type: boolean
description: If set to `true` the message will be shortened when exceeding one part.
max_number_of_message_parts:
minimum: 1
type: integer
description: Message will be dispatched only if it is not split to more
parts than Max Number of Message Parts
format: int32
from_ton:
maximum: 6
minimum: 0
type: integer
description: The type of number for the sender number. Use to override the
automatic detection.
format: int32
from_npi:
maximum: 18
minimum: 0
type: integer
description: Number Plan Indicator for the sender number. Use to override the automatic detection.
format: int32
TextResponse:
type: object
properties:
id:
type: string
description: Unique identifier for batch
readOnly: true
example: 01FC66621XXXXX119Z8PMV1QPQ
to:
maxItems: 1000
minItems: 1
type: array
description: "List of Phone numbers and group IDs that will receive the batch. [More info](https://community.sinch.com/t5/Glossary/MSISDN/ta-p/7628)"
format: E.164
example:
- +15551231234
- +15551256344
items:
$ref: '#/components/schemas/MtDestination'
from:
type: string
description: "Sender number. Must be valid phone number, short code or alphanumeric. Required if Automatic Default Originator not configured."
example: +15551231234
canceled:
type: boolean
description: Indicates if the batch has been canceled or not.
readOnly: true
default: false
parameters:
$ref: '#/components/schemas/parameterObj'
body:
maxLength: 2000
minLength: 0
type: string
description: The message content
example: "Hi ${name}! How are you?"
type:
type: string
description: Regular SMS
enum:
- mt_text
readOnly: true
# campaign_id:
# type: string
# description: "The [campaign and service IDs](https://dashboard.sinch.com/sms/us-campaigns) this message belongs to. You generate your own campaign and service IDs. US only."
created_at:
type: string
description: "Timestamp for when batch was created. Formatted as [ISO-8601](https://en.wikipedia.org/wiki/ISO_8601):`YYYY-MM-DDThh:mm:ss.SSSZ`."
format: date-time
readOnly: true
modified_at:
type: string
description: "Timestamp for when batch was last updated. Formatted as [ISO-8601](https://en.wikipedia.org/wiki/ISO_8601):`YYYY-MM-DDThh:mm:ss.SSSZ`."
format: date-time
readOnly: true
delivery_report:
type: string
description: "Request delivery report callback. Note that delivery reports can be fetched from the API regardless of this setting. "
default: none
x-enumDescriptions:
none: No delivery report callback will be sent.
summary: A single delivery report callback will be sent.
full: A single delivery report callback will be sent which includes a list of recipients per delivery status.
per_recipient: A delivery report callback will be sent for each status change of a message. This could result in a lot of callbacks and should be **used with caution for larger batches**. These delivery reports also include a timestamp of when the Delivery Report originated from the SMSC.
per_recipient_final: A delivery report callback representing the final status of a message will be sent for each recipient. This will send only one callback per recipient, compared to the multiple callbacks sent when using `per_recipient`. The delivery report will also include a timestamp of when it originated from the SMSC.
send_at:
type: string
description: "If set in the future, the message will be delayed until `send_at` occurs. Must be before `expire_at`. If set in the past, messages will be sent immediately. Formatted as [ISO-8601](https://en.wikipedia.org/wiki/ISO_8601): `YYYY-MM-DDThh:mm:ss.SSSZ`."
format: date-time
expire_at:
type: string
description: "If set, the system will stop trying to deliver the message at this point. Must be after `send_at`. Default and max is 3 days after `send_at`. Formatted as [ISO-8601](https://en.wikipedia.org/wiki/ISO_8601): `YYYY-MM-DDThh:mm:ss.SSSZ`."
format: date-time
callback_url:
maxLength: 2048
minLength: 0
type: string
description: "Override the default callback URL for this batch. Must be valid URL."
client_reference:
maxLength: 2048
minLength: 0
type: string
description: The client identifier of a batch message. If set, the identifier will be added in the delivery report/callback of this batch
example: "myReference"
feedback_enabled:
type: boolean
description: If set to `true`, then [feedback](/docs/sms/api-reference/sms/tag/Batches/#tag/Batches/operation/deliveryFeedback) is expected after successful delivery.
default: false
flash_message:
type: boolean
description: Shows message on screen without user interaction while not saving the message to the inbox.
default: false
truncate_concat:
type: boolean
description: If set to `true` the message will be shortened when exceeding one part.
max_number_of_message_parts:
minimum: 1
type: integer
description: Message will be dispatched only if it is not split to more
parts than Max Number of Message Parts
format: int32
from_ton:
maximum: 6
minimum: 0
type: integer
description: The type of number for the sender number. Use to override the
automatic detection.
format: int32
from_npi:
maximum: 18
minimum: 0
type: integer
description: Number Plan Indicator for the sender number. Use to override the automatic detection.
format: int32
groupObject:
type: object
properties:
name:
type: string
maxLength: 20
description: "Name of the group"
members:
type: array
maxItems: 10000
items:
$ref: "#/components/schemas/msisdn"
description: |-
"Initial list of phone numbers in E.164 format MSISDNs for the group."
child_groups:
type: array
description: |-
Phone numbers (MSISDNs) of child group will be included in this group. If present then this group will be auto populated.
Constraints:
Elements must be group IDs.
maxItems: 10
items:
type: string
description: Group ID
auto_update:
type: object
properties:
to:
type: string
description: |-
Short code or long number addressed in MO.
Constraints:
Must be valid phone number or short code which has been **provisioned by your account manager**.
add:
type: object
properties:
first_word:
type: string
pattern: '^\w+$'
description: |-
Keyword to be sent in MO to add phone number to a group opt-in keyword like "JOIN". If `auto_update.to` is dedicated long/short number or unique brand keyword like "Sinch" if it is a shared short code.
Constraints:
Must be one word.
maxLength: 15
second_word:
type: string
pattern: '^\w+$'
description: |-
Opt-in keyword like "JOIN" if auto_update.to is shared short code.
Constraints:
Must be one word.
maxLength: 15
remove:
type: object
description: Keyword to be sent in MO to remove from a group.
properties:
first_word:
type: string
pattern: '^\w+$'
description: |-
Opt-out keyword like "LEAVE" If auto_update.to is dedicated long/short number or unique brand keyword like "Sinch" if it is a shared short code.
Constraints:
Must be one word.
maxLength: 15
minLength: 1
second_word:
type: string
pattern: '^\w+$'
description: |-
Opt-out keyword like "LEAVE" if auto_update.to is shared short code.
Constraints:
Must be one word.
maxLength: 15
minLength: 1
msisdn:
type: string
format: E.164
description: |-
A phone number in E.164 format.
example: "+453234457784"
BinaryRequest:
required:
- body
- to
- udh
type: object
properties:
to:
maxItems: 1000
minItems: 1
type: array
description: "A list of phone numbers and group IDs that will receive the batch. [More info](https://community.sinch.com/t5/Glossary/MSISDN/ta-p/7628)."
format: E.164
example:
- +15551231234
- +15551256344
items:
$ref: '#/components/schemas/MtDestination'
from:
type: string
description: "Sender number. Must be valid phone number, short code or alphanumeric. Required if Automatic Default Originator not configured."
example: +15551231234
body:
type: string
description: |-
The message content Base64 encoded.
Max 140 bytes including `udh`.
udh:
type: string
description: The UDH header of a binary message HEX encoded. Max 140 bytes including the `body`.
type:
type: string
description: SMS in binary format.
enum:
- mt_binary
delivery_report:
type: string
description: "Request delivery report callback. Note that delivery reports can be fetched from the API regardless of this setting. "
default: none
x-enumDescriptions:
none: No delivery report callback will be sent.
summary: A single delivery report callback will be sent.
full: A single delivery report callback will be sent which includes a list of recipients per delivery status.
per_recipient: A delivery report callback will be sent for each status change of a message. This could result in a lot of callbacks and should be **used with caution for larger batches**. These delivery reports also include a timestamp of when the Delivery Report originated from the SMSC.
per_recipient_final: A delivery report callback representing the final status of a message will be sent for each recipient. This will send only one callback per recipient, compared to the multiple callbacks sent when using `per_recipient`. The delivery report will also include a timestamp of when it originated from the SMSC.
send_at:
type: string
description: |-
If set in the future the message will be delayed until `send_at` occurs.
Must be before `expire_at`.
If set in the past, messages will be sent immediately.
Formatted as [ISO-8601](https://en.wikipedia.org/wiki/ISO_8601). For example: `YYYY-MM-DDThh:mm:ss.SSSZ`.
format: date-time
example: "2024-08-07T12:34:56.789Z"
expire_at:
type: string
description: |-
If set, the system will stop trying to deliver the message at this point. Must be after `send_at`. Default and max is 3 days after `send_at`.
Formatted as [ISO-8601](https://en.wikipedia.org/wiki/ISO_8601). For example: `YYYY-MM-DDThh:mm:ss.SSSZ`.
format: date-time
callback_url:
maxLength: 2048
minLength: 0
type: string
description: Override the *default* callback URL for this batch. Must be a valid URL. Learn how to set a default callback URL here.
client_reference:
maxLength: 2048
minLength: 0
type: string
description: The client identifier of a batch message. If set, the identifier will be added in the delivery report/callback of this batch.
feedback_enabled:
type: boolean
description: |-
If set to true then [feedback](/docs/sms/api-reference/sms/tag/Batches/#tag/Batches/operation/deliveryFeedback) is expected after successful delivery.
default: false
from_ton:
maximum: 6
minimum: 0
type: integer
description: The type of number for the sender number. Use to override the automatic detection.
format: int32
from_npi:
maximum: 18
minimum: 0
type: integer
description: Number Plan Indicator for the sender number. Use to override the automatic detection.
format: int32
BinaryResponse:
type: object
properties:
id:
type: string
description: Unique identifier for batch.
readOnly: true
example: 01FC66621XXXXX119Z8PMV1QPQ
to:
maxItems: 1000
minItems: 1
type: array
description: "A list of phone numbers and group IDs that have received the batch. [More info](https://community.sinch.com/t5/Glossary/MSISDN/ta-p/7628)."
format: E.164
example:
- +15551231234
- +15551256344
items:
$ref: '#/components/schemas/MtDestination'
from:
type: string
description: |-
The sender number provided.
Required if the Automatic Default Originator is not configured.
example: +15551231234
canceled:
type: boolean
description: Indicates whether or not the batch has been canceled.
readOnly: true
default: false
body:
type: string
description: |-
The message content provided. Base64 encoded.
udh:
type: string
description: The UDH header of a binary message HEX encoded. Max 140 bytes including the `body`.
type:
type: string
description: SMS in binary format.
enum:
- mt_binary
created_at:
type: string
description: |-
Timestamp for when batch was created.
Formatted as [ISO-8601](https://en.wikipedia.org/wiki/ISO_8601). For example: `YYYY-MM-DDThh:mm:ss.SSSZ`.
format: date-time
readOnly: true
modified_at:
type: string
description: |-
Timestamp for when batch was last updated.
Formatted as [ISO-8601](https://en.wikipedia.org/wiki/ISO_8601). For example: `YYYY-MM-DDThh:mm:ss.SSSZ`.
format: date-time
readOnly: true
delivery_report:
type: string
description: The delivery report callback option selected. Will be either `none`, `summary`, `full`, `per_recipient`, or `per_recipient_final`.
default: none
send_at:
type: string
description: |-
If set, the date and time the message should be delivered. Formatted as [ISO-8601](https://en.wikipedia.org/wiki/ISO_8601). For example: `YYYY-MM-DDThh:mm:ss.SSSZ`.
format: date-time
expire_at:
type: string
description: |-
If set, the date and time the message will expire. Formatted as [ISO-8601](https://en.wikipedia.org/wiki/ISO_8601). For example: `YYYY-MM-DDThh:mm:ss.SSSZ`.
format: date-time
callback_url:
maxLength: 2048
minLength: 0
type: string
description: The callback URL provided in the request.
client_reference:
maxLength: 2048
minLength: 0
type: string
description: The string input to identify this batch message. If set, the identifier will be added in the delivery report/callback of this batch.
feedback_enabled:
type: boolean
description: |-
If set to true, then [feedback](/docs/sms/api-reference/sms/tag/Batches/#tag/Batches/operation/deliveryFeedback) is expected after successful delivery.
default: false
from_ton:
maximum: 6
minimum: 0
type: integer
description: The type of number for the sender number.
format: int32
from_npi:
maximum: 18
minimum: 0
type: integer
description: Number Plan Indicator for the sender number.
format: int32
MediaRequest:
description: "Only available in the US. Contact your account manager if you wish to send MMS."
properties:
to:
type: array
format: E.164
description: List of Phone numbers and group IDs that will receive the batch. More info
example:
- +15551231234
- +15551256344
items:
$ref: '#/components/schemas/MtDestination'
maxItems: 1000
minItems: 1
from:
type: string
description: "Sender number. Must be valid phone number, short code or alphanumeric. Required if Automatic Default Originator not configured."
example: +15551231234
body:
$ref: '#/components/schemas/MediaBody'
parameters:
$ref: '#/components/schemas/parameterObj'
type:
type: string
description: MMS
enum:
- mt_media
delivery_report:
type: string
default: none
description: Request delivery report callback. Note that delivery reports can be fetched from the API regardless of this setting.
x-enumDescriptions:
none: No delivery report callback will be sent.
summary: A single delivery report callback will be sent.
full: A single delivery report callback will be sent which includes a list of recipients per delivery status.
per_recipient: A delivery report callback will be sent for each status change of a message. This could result in a lot of callbacks and should be **used with caution for larger batches**. These delivery reports also include a timestamp of when the Delivery Report originated from the SMSC.
per_recipient_final: A delivery report callback representing the final status of a message will be sent for each recipient. This will send only one callback per recipient, compared to the multiple callbacks sent when using `per_recipient`. The delivery report will also include a timestamp of when it originated from the SMSC.
send_at:
type: string
format: date-time
description: |
If set in the future, the message will be delayed until `send_at` occurs. Must be before `expire_at`. If set in the past, messages will be sent immediately. Formatted as ISO-8601: `YYYY-MM-DDThh:mm:ss.SSSZ`.
expire_at:
type: string
format: date-time
description: |
If set, the system will stop trying to deliver the message at this point. Must be after `send_at`. Default and max is 3 days after `send_at`. Formatted as ISO-8601: `YYYY-MM-DDThh:mm:ss.SSSZ`.
callback_url:
type: string
description: Override the default callback URL for this batch. Must be valid
URL.
maxLength: 2048
minLength: 0
client_reference:
type: string
description: The client identifier of a batch message. If set, the identifier will be added in the delivery report/callback of this batch
maxLength: 2048
minLength: 0
feedback_enabled:
type: boolean
default: false
description: "If set to `true`, then [feedback](/docs/sms/api-reference/sms/tag/Batches/#tag/Batches/operation/deliveryFeedback) is expected after successful delivery."
strict_validation:
default: false
type: boolean
description: |
Whether or not you want the media included in your message to be checked against [Sinch MMS channel best practices](/docs/mms/bestpractices/).
If set to true, your message will be rejected if it doesn't conform to the listed recommendations, otherwise no validation will be performed.
required:
- body
- to
MediaResponse:
properties:
id:
type: string
description: Unique identifier for batch
example: 01FC66621XXXXX119Z8PMV1QPQ
readOnly: true
to:
type: array
format: E.164
description: "List of Phone numbers and group IDs that will receive the batch. [More info](https://community.sinch.com/t5/Glossary/MSISDN/ta-p/7628)"
example:
- +15551231234
- +15551256344
items:
$ref: '#/components/schemas/MtDestination'
maxItems: 1000
minItems: 1
from:
type: string
description: "Sender number.\n \n Required if Automatic Default Originator\
\ not configured."
example: +15551231234
canceled:
type: boolean
default: false
description: Indicates if the batch has been canceled or not.
readOnly: true
body:
$ref: '#/components/schemas/MediaBody'
parameters:
$ref: '#/components/schemas/parameterObj'
type:
type: string
description: Media message
enum:
- mt_media
readOnly: true
created_at:
type: string
format: date-time
description: "Timestamp for when batch was created. \n \n YYYY-MM-DDThh:mm:ss.SSSZ\
\ format"
readOnly: true
modified_at:
type: string
format: date-time
description: "Timestamp for when batch was last updated. \n \n YYYY-MM-DDThh:mm:ss.SSSZ\
\ format"
readOnly: true
delivery_report:
type: string
default: none
description: "Request delivery report callback. \n \n Note that delivery\
\ reports can be fetched from the API regardless of this setting. "
x-enumDescriptions:
none: No delivery report callback will be sent.
summary: A single delivery report callback will be sent.
full: A single delivery report callback will be sent which includes a list of recipients per delivery status.
per_recipient: A delivery report callback will be sent for each status change of a message. This could result in a lot of callbacks and should be **used with caution for larger batches**. These delivery reports also include a timestamp of when the Delivery Report originated from the SMSC.
per_recipient_final: A delivery report callback representing the final status of a message will be sent for each recipient. This will send only one callback per recipient, compared to the multiple callbacks sent when using `per_recipient`. The delivery report will also include a timestamp of when it originated from the SMSC.
send_at:
type: string
format: date-time
description: "If set in the future the message will be delayed until send_at\
\ occurs. \n \n Must be before `expire_at`. \n \n If set in the past messages\
\ will be sent immediately. \n \n YYYY-MM-DDThh:mm:ss.SSSZ format"
example: "2024-08-07T12:34:56.789Z"
expire_at:
type: string
format: date-time
description: "If set the system will stop trying to deliver the message\
\ at this point. \n \n Must be after `send_at`. Default and max is 3 days\
\ after send_at. \n \n YYYY-MM-DDThh:mm:ss.SSSZ format"
callback_url:
type: string
description: Override the default callback URL for this batch. Must be valid
URL.
maxLength: 2048
minLength: 0
client_reference:
type: string
description: "The client identifier of a batch message. If set, the identifier\
\ will be added in the delivery report/callback of this batch"
maxLength: 2048
minLength: 0
feedback_enabled:
type: boolean
default: false
description: "If set to true then [feedback](/docs/sms/api-reference/sms/tag/Batches/#tag/Batches/operation/deliveryFeedback)\
\ is expected after successful delivery."
strict_validation:
type: boolean
description: |
Whether or not you want the media included in your message to be checked against [Sinch MMS channel best practices](/docs/mms/bestpractices/).
If set to true, your message will be rejected if it doesn't conform to the listed recommendations, otherwise no validation will be performed.
MediaBody:
description: The message content, including a URL to the media file
properties:
subject:
maxLength: 80
minLength: 0
type: string
description: The subject text
example: Media message from Sinch!
message:
type: string
description: The message text. Text only media messages will be rejected, please use SMS instead.
example: Your text message.
maxLength: 2000
minLength: 0
url:
type: string
description: URL to the media file
example: https://en.wikipedia.org/wiki/Sinch_(company)#/media/File:Sinch_LockUp_RGB.png
maxLength: 2048
minLength: 0
required:
- url
MOMediaBody:
type: object
description: The message content, including a URL to the media filters.
properties:
subject:
type: string
description: The subject of the MMS media message.
message:
type: string
description: The text message content of the MMS media message.
media:
type: array
items:
type: object
properties:
url:
type: string
description: URL to the media file
contentType:
type: string
description: The type of media file included in the message
status:
type: string
description: The status of the media upload
code:
type: integer
securitySchemes:
BearerAuth:
type: http
scheme: bearer
description: |
Your API token is sent in the `Authorization` header preceded by `Bearer`. You'll have an API token per `service_plan_id`. Both can be found in the [Sinch Customer Dashboard](https://dashboard.sinch.com/sms/api/rest). Double check that you're using the correct region in your base URL.
parameters:
# path parameters
service_plan_id:
name: service_plan_id
in: path
required: true
description: Your service plan ID. You can find this on your [Dashboard](https://dashboard.sinch.com/sms/api/rest).
schema:
type: string
example: jd63jf88477ll123ab4567cd89012ef3
batch_id:
name: batch_id
in: path
required: true
description: The batch ID you received from sending a message.
schema:
type: string
example: 01FC66621XXXXX119Z8PMV1QPQ
inbound_id:
name: inbound_id
in: path
required: true
description: The inbound ID found when listing inbound messages.
schema:
type: string
example: 01FC66621XXXXX119Z8PMV1QPA
group_id:
name: group_id
in: path
required: true
description: ID of a group that you are interested in getting.
schema:
type: string
recipient_msisdn:
name: recipient_msisdn
in: path
required: true
description: Phone number for which you to want to search.
schema:
type: string
example: "+134848393506"
# query parameters
page:
name: page
in: query
description: The page number starting from 0.
schema:
type: integer
minimum: 0
default: 0
example: 2
tags:
- name: Batches
description: |-
Batches are sets of SMS messages. You can send a single message or many. Batches are queued and sent at the rate limit in first-in-first-out order.
- name: Delivery reports
description: |-
The REST API uses message statuses and error codes in delivery reports, which refer to the state of the batch and can be present in either [Retrieve a delivery report](/docs/sms/api-reference/sms/tag/Delivery-reports/#tag/Delivery-reports/operation/GetDeliveryReportByBatchId) or sent as a callback.
## Delivery report statuses
The status field describes which state a particular message is in. Note that statuses of type Intermediate will only be reported if you request a status `per_recipient` or `per_recipient_final` ([Retrieve a recipient delivery report](/docs/sms/api-reference/sms/tag/Delivery-reports/#tag/Delivery-reports/operation/GetDeliveryReportByPhoneNumber)).
The following statuses are available when using the SMS REST API:
| Status | Type | Description |
| ------------ | ------------ | --------------------------------------------- |
| `Queued` | Intermediate | Message is queued within REST API system and will be dispatched according to the rate of the account. |
| `Dispatched` | Intermediate | Message has been dispatched and accepted for delivery by the SMSC. |
| `Aborted` | Final | Message was aborted before reaching the SMSC. |
| `Cancelled` | Final | Message was cancelled by user before reaching SMSC. |
| `Rejected` | Final | Message was rejected by the SMSC. |
| `Deleted` | Final | Message has been deleted. Message was deleted by a remote SMSC. This may happen if the destination is an invalid MSISDN or opted out subscriber. |
| `Delivered` | Final | Message has been delivered. |
| `Failed` | Final | Message failed to be delivered. |
| `Expired` | Final | Message expired before delivery to the SMSC. This may happen if the expiry time for the message was very short. |
| `Unknown` | Final | Message was delivered to the SMSC but no Delivery Receipt has been received or a Delivery Receipt that couldn't be interpreted was received. |
## Delivery report error codes
The delivery report status code provides a more detailed view of what happened with a message. The REST API error codes are a combination of [SMPP error codes](/docs/sms/smpp/error-codes/#status-reports-error-codes), [MMS error codes](/docs/mms/7-service/mms-status-codes/) and custom codes.
The REST API custom error codes are all within the 4xx range. These are listed below:
| Status Code | Name | Status | Description |
| ----------------- | ---------------------------- | ------------ | --------------------------------------------------------- |
| 400 | Queued | `Queued` | Message is queued within REST API system and will be dispatched according to the rate of the account. |
| 401 | Dispatched | `Dispatched` | Message has been dispatched to SMSC. |
| 402 | Message unroutable | `Aborted` | SMSC rejected message. Retrying is likely to cause the same error. |
| 403 | Internal error | `Aborted` | An unexpected error caused the message to fail. |
| 404 | Temporary delivery failure | `Aborted` | Message failed because of temporary delivery failure. Message can be retried. |
| 405 | Unmatched Parameter | `Aborted` | One or more parameters in the message body has no mapping for this recipient. See [Message Parameterization](../../../../resources/message-info/message-parameterization/) |
| 406 | Internal Expiry | `Aborted` | Message was expired before reaching SMSC. This may happen if the expiry time for the message was very short. |
| 407 | Cancelled | `Cancelled` | Message was cancelled by user before reaching SMSC. |
| 408 | Internal Reject | `Aborted` | SMSC rejected the message. Retrying is likely to cause the same error. |
| 410 | Unmatched default originator | `Aborted` | No default originator exists/configured for this recipient when sending message without originator. |
| 411 | Exceeded parts limit | `Aborted` | Message failed as the number of message parts exceeds the defined max number of message parts. |
| 412 | Unprovisioned region | `Aborted` | SMSC rejected the message. The account hasn't been provisioned for this region. |
| 413 | Blocked | `Aborted` | The account is blocked. Reach out to support for help. Potentially out of credits. |
| 414 | Bad Media | `Aborted` | MMS only, the request failed due to a bad media URL. It is possible that the URL was unreachable, or sent a bad response. |
| 415 | Delivery report Rejected | `Failed` | MMS only, message reached MMSC but was rejected by MMS gateway or mobile network. |
| 416 | Delivery report Not Supported| `Failed` | MMS only, message reached MMSC but it is not supported. |
| 417 | Delivery report Unreachable | `Failed` | MMS only, message reached MMSC but the destination network or the mobile subscriber cannot be reached. |
| 418 | Delivery report Unrecognized | `Failed` | MMS only, message reached MMSC but the handset of the mobile subscriber does not recognize the message content. |
- name: Inbounds
description: |-
Inbounds, or Mobile Originated (MO) messages, are incoming messages. Inbound messages can be listed and retrieved like batch messages and they can also be delivered by callback requests like delivery reports.
## MMS Media error codes
The REST API handles MO media messages by uploading them to specified s3 storage location and providing the URL to download the attachment.
On a successful upload, the code will be `0`. If the upload fails, the code will be a value other than `0`.
| Status Code | Name | Status | Description |
| --------------- | ---------------------------- | ------------ | --------------------------------------------------------- |
| 0 | Uploaded | `Uploaded` | Attachment successfully uploaded to storage. |
| 1 | Internal failure | `Failed` | Internal exception happened during upload. |
| 2 | Bucket not found | `Failed` | Provisioned bucket doesn't exist. |
- name: Groups
description: A group is a set of phone numbers (or [MSISDNs](https://community.sinch.com/t5/Glossary/MSISDN/ta-p/7628)) that can be used as a target when sending an SMS. An phone number (MSISDN) can only occur once in a group and any attempts to add a duplicate are ignored but not rejected.
- name: Webhooks
description: |-
## Callbacks
A callback is an HTTP POST request with a notification made by the Sinch SMS REST API to a URI of your choosing.
The REST API expects the receiving server to respond with a response code within the `2xx` success range. For `5xx` the callback will be retried. For `429` the callback will be retried and the throughput will be lowered. For other status codes in the `4xx` range the callback will not be retried. The first initial retry will happen 5 seconds after the first try. The next attempt is after 10 seconds, then after 20 seconds, after 40 seconds, after 80 seconds, doubling on every attempt. The last retry will be at 81920 seconds (or 22 hours 45 minutes) after the initial failed attempt.
Note that, with these callbacks, the Sinch SMS REST API will make a request to the URI of your choosing. This means that Sinch will be authenticating against **your system**. By making a request to your account manager, SMS REST API callbacks may be configured with the following options:
- **Basic authentication** is the simplest form of authentication. It enables access to the SMS API via a username and password. Basic Auth can be utilised in a callback by provisioning the callback URL with the appropriate username and password. Note that, because callbacks are made by Sinch to a URI of your choosing (rather than a call made by your system to Sinch's endpoints), the username and password must be accepted by **your system**.
- **OAuth 2.0** is a standard form of authentication that provides enhanced security when compared to Basic Authentication. It uses access tokens to reduce the risk of credentials being intercepted. OAuth 2.0 can be utilised in a callback by provisioning the callback URL with username, password and the URL to fetch OAuth access token. Note that, because callbacks are made by Sinch to a URI of your choosing (rather than a call made by your system to Sinch's endpoints), the username, password, and and access token URL must be accepted by **your system**.
- **HMAC** Hash-based message authentication code. It is a cryptographic authentication technique that uses a hash function and a secret key. HMAC can also be configured alongside Basic Auth and OAuth.
- **AWS SNS** is a managed service that provides message delivery from publishers to subscribers by routing messages through SNS topics. Users can utilise AWS SNS in a callback by provisioning the callback URL with an Access Key ID, Secret Key and Region.