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://us.sms.api.sinch.com"
# description: Default Global API (US)
# - url: "https://eu.sms.api.sinch.com"
# description: Europe
# - url: "https://au.sms.api.sinch.com"
# description: Australia
# - url: "https://br.sms.api.sinch.com"
# description: Brazil
# - url: "https://ca.sms.api.sinch.com"
# description: Canada
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:
operationId: incomingSMS
security: []
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).
requestBody:
description: The incoming Message to your sinch number
content:
application/json:
schema:
$ref: "#/components/schemas/inboundsObject"
example:
type: mo_text
id: 01XXXXX21XXXXX119Z8P1XXXXX
from: "16051234567"
to: "13185551234"
body: This is a test message.
operator_id: "string"
send_at: "2022-08-24T14:15:22Z"
received_at: "2022-08-24T14:15:22Z"
responses:
"200":
description: A 200 status indicates that the data was received successfully.
deliveryReport:
summary: Delivery Report
post:
security: []
operationId: deliveryReport
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 you need to set the `delivery_report` field accordingly when creating a batch.
The callback URL can either be provided for each batch or provisioned globally for your account in your [Dashboard](https://dashboard.sinch.com/sms/api/rest).
requestBody:
description: ""
content:
application/json:
schema:
$ref: "#/components/schemas/retrieveDeliveryResponseObj"
responses:
"200":
description: Return a 200 status to indicate that the data was received successfully
paths:
"/xms/v1/{service_plan_id}/batches":
parameters:
- $ref: "#/components/parameters/service_plan_id"
post:
tags:
- Batches
summary: Send
operationId: SendSMS
description: |-
Sends 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.
requestBody:
content:
application/json:
schema:
oneOf:
- $ref: "#/components/schemas/Text"
- $ref: "#/components/schemas/Binary"
examples:
BatchSendFillIn:
$ref: "#/components/examples/BatchSendFillIn"
BatchSendBasicSMS:
$ref: "#/components/examples/BatchSendBasicSMS"
BatchMessageWExpiry:
$ref: "#/components/examples/BatchMessageWExpiry"
BatchParameterizedMessage:
$ref: "#/components/examples/BatchParameterizedMessage"
BatchMessageCustomDeliveryReportURL:
$ref: "#/components/examples/BatchMessageCustomDeliveryReportURL"
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/Text"
- $ref: "#/components/schemas/Binary"
# "400":
# description: "Bad request."
# content:
# application/json:
# schema:
# $ref: "#/components/schemas/errorResponseObj"
# example:
# code: syntax_invalid_parameter_format
# text: "The format of parameter 'to[0]' is invalid; value '+1' is not a valid MSISDN or group ID."
# "403":
# description: "Forbidden."
# content:
# application/json:
# schema:
# $ref: "#/components/schemas/errorResponseObj"
# example:
# code: missing_callback_url
# text: "Requesting delivery report without any callback URL."
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:
type: object
properties:
page:
type: integer
description: The requested page.
example: 1
count:
type: integer
description: The total number of batches matching the given filters.
example: 2000
page_size:
type: integer
description: The number of batches returned in this request
example: 50
batches:
type: array
items:
$ref: "#/components/schemas/sendBatchObject"
description: "The page of batches matching the given filters"
# '400':
# description: >-
# INVALID_ARGUMENT
# content:
# application/json:
# schema: {}
# example:
# error:
# code: 400
# message: 'parsing field "type": "XXX" is not a valid value'
# status: INVALID_ARGUMENT
# details: []
"/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/inboundResponseObject"
# '400':
# description: >-
# INVALID_ARGUMENT
# content:
# application/json:
# schema: {}
# example:
# error:
# code: 400
# message: 'parsing field "type": "XXX" is not a valid value'
# status: INVALID_ARGUMENT
# details: []
"/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:
$ref: "#/components/schemas/inboundsObject"
# "404":
# description: Not found. The inbound ID is unknown to the system.
"/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:
$ref: "#/components/schemas/sendBatchObject"
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:
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
message_part:
type: string
body:
type: string
encoding:
type: string
# "400":
# description: Bad request.
# content:
# application/json:
# schema:
# $ref: "#/components/schemas/errorResponseObj"
# example:
# code: syntax_invalid_parameter_format
# description: "'tru' is not a valid boolean"
"/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:
$ref: "#/components/schemas/sendBatchCreated"
examples:
response:
value:
id: "9dfn32n423kljklj234"
from: "12345"
to: ["+15551231212"]
body: "Hello! How are you?"
created_at: "2022-02-25T23:01:01Z"
modified_at: "2022-02-25T23:01:01Z"
canceled: false
# "404":
# description: Not found. The batch ID is unknown to the system.
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:
$ref: "#/components/schemas/updateBatchReq"
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:
$ref: "#/components/schemas/sendBatchCreated"
# "400":
# description: Bad request.
# content:
# application/json:
# schema:
# $ref: "#/components/schemas/errorResponseObj"
# example:
# code: syntax_invalid_parameter_format
# text: "The format of parameter 'to[0]' is invalid; value '+1' is not a valid MSISDN or group ID."
# "403":
# description: Forbidden.
# content:
# application/json:
# schema:
# $ref: "#/components/schemas/errorResponseObj"
# example:
# code: missing_callback_url
# text: Requesting delivery report without any callback URL.
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:
$ref: "#/components/schemas/sendBatchObject"
responses:
"200":
description: A successful response , or an [Error](/docs/sms/api-reference/status-codes/).
content:
application/json:
schema:
$ref: "#/components/schemas/sendBatchCreated"
# "400":
# description: Bad request.
# content:
# application/json:
# schema:
# $ref: "#/components/schemas/errorResponseObj"
# example:
# code: syntax_invalid_parameter_format
# text: "The format of parameter 'to[0]' is invalid; value '+1' is not a valid MSISDN or group ID."
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:
$ref: "#/components/schemas/sendBatchObject"
# '400':
# description: >-
# INVALID_ARGUMENT
# content:
# application/json:
# schema: {}
# example:
# error:
# code: 400
# message: 'parsing field "type": "XXX" is not a valid value'
# status: INVALID_ARGUMENT
# details: []
"/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.
Constraints:
Must be summary or full
#### Summary and full
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: "\tComma 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/retrieveDeliveryResponseObj"
# "400":
# description: Bad request
# content:
# application/json:
# schema:
# $ref: "#/components/schemas/errorResponseObj"
# example:
# code: syntax_invalid_parameter_format
# description: "'report' is not a valid report type"
# "404":
# description: Not found. The batch ID is not known to the system.
"/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/retrieveRecipientDeliveryResponseObj'
example:
type: "recipient_delivery_report_sms"
batch_id: "01FC66621VHDBN119Z8PMV1QPQ"
recipient: "+44231235674"
code: 401
status: "Dispatched"
at: "2022-08-30T08:16:08.930Z"
# "404":
# description: Not found. The batch ID is not known to the system or the recipient is not a target of this batch.
"/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'
# "400":
# description: Bad request
# content:
# application/json:
# schema:
# $ref: '#/components/schemas/errorResponseObj'
# example:
# code: syntax_invalid_parameter_format
# text: Parameter 'page_size' is not a valid integer; value 'zero'.
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.
# "400":
# description: >-
# Bad request
# content:
# application/json:
# schema:
# $ref: '#/components/schemas/errorResponseObj'
# example:
# code: syntax_constraint_violation
# text: At least one recipient required for delivery feedback if the
# batch was created with group ID.
# "404":
# description: Not found. The batch ID is unknown to the system.
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:
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."
groups:
type: array
items:
$ref: "#/components/schemas/groupObject"
# '400':
# description: >-
# INVALID_ARGUMENT
# content:
# application/json:
# schema: {}
# example:
# error:
# code: 400
# message: 'parsing field "type": "XXX" is not a valid value'
# status: INVALID_ARGUMENT
# details: []
post:
summary: Create a group
operationId: CreateGroup
description: A group is a set of phone numbers (MSISDNs) that can be used as a target in the `send_batch_msg` operation. An MSISDN can only occur once in a group and any attempts to add a duplicate would be ignored but not rejected.
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"
# "400":
# description: Bad request.
# content:
# application/json:
# schema:
# $ref: "#/components/schemas/errorResponseObj"
# example:
# code: syntax_invalid_parameter_format
# text: "The format of parameter 'members[0]' is invalid; value '+1' is not a valid MSISDN or group ID."
# "403":
# description: Forbidden.
# content:
# application/json:
# schema:
# $ref: "#/components/schemas/errorResponseObj"
# example:
# code: unknown_group
# description: "Group '01FC66621VHDBN119Z8PMV1QPU' is unknown or deleted"
"/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"
# "404":
# description: Not Found. The group ID is unknown to the system.
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.
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 in both lists, then it will not be apart of the resulting group.
To remove an existing name set, name explicitly to the JSON value null. Omitting name from the JSON body will leave the name unchanged.
Updating a group targeted by a batch message scheduled in the future is allowed and changes will be reflected until the batch is sent.
operationId: UpdateGroup
security:
- BearerAuth: []
tags:
- Groups
requestBody:
content:
application/json:
schema:
type: object
properties:
name:
type: string
maxLength: 20
description: "Name of group."
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.
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
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
add_from_group:
type: string
description: |-
Copy the members from the given group into this group.
Constraints:
Must be valid group ID
remove_from_group:
type: string
description: |-
Remove members in the given group from group.
Constraints:
Must be valid group ID
examples:
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"
# "400":
# description: Bad request.
# content:
# application/json:
# schema:
# $ref: "#/components/schemas/errorResponseObj"
# example:
# code: syntax_invalid_parameter_format
# text: "The format of parameter 'members[0]' is invalid; value '+1' is not a valid MSISDN or group ID."
# "403":
# description: Forbidden. One or more groups referenced in your request could not be found.
# content:
# application/json:
# schema:
# $ref: "#/components/schemas/errorResponseObj"
# example:
# code: unknown_group
# description: "Group '01FC66621VHDBN119Z8PMV1QPU' is unknown or deleted"
# "404":
# description: Not found. If the group ID is unknown to the system.
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:
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"
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"
# "400":
# description: Bad request.
# content:
# application/json:
# schema:
# $ref: "#/components/schemas/errorResponseObj"
# example:
# code: syntax_invalid_parameter_format
# text: "The format of parameter 'members[0]' is invalid; value '+1' is not a valid MSISDN or group ID."
# "403":
# description: Forbidden. One or more groups referenced in your request could not be found.
# content:
# application/json:
# schema:
# $ref: "#/components/schemas/errorResponseObj"
# example:
# code: unknown_group
# description: "Group 'my_group' is unknown or deleted"
# "404":
# description: Not found. If the group ID is unknown to the system.
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/).
# "404":
# description: Not found. The group ID is unknown to the system.
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"
# "404":
# description: Not found. Appears if the group ID is unknown to the system.
components:
examples:
BatchSendFillIn:
summary: SMS - fill in
value:
from: "YOUR_Sinch_virtual_number"
to: "YOUR_to_number"
body: "YOUR_message_body"
BatchSendBasicSMS:
summary: 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!"
BatchMessageWExpiry:
summary: Batch message with expiry
value:
from: "12345"
to: ["123456789", "987654321"]
body: "This is a message that will stop attempting to send after three hours."
send_at: "2022-10-02T09:30Z"
expire_at: "2022-10-02T12:30Z"
BatchParameterizedMessage:
summary: Parameterized message
# description: Personalize an SMS message with parameters in the text body.
value:
from: "12345"
to: ["123456789", "987654321"]
body: "Hi ${name}! You miss 100% of the shots you don't take. Are you in for next week?"
# Steve Carrell, The Office, "Michael Scott Paper Company", Season 5, Episode 23, April 9, 2009
parameters:
name:
123456789: "Joe"
default: "there"
BatchMessageCustomDeliveryReportURL:
summary: Batch message with custom delivery report URL
value:
from: "12345"
to: ["123456789", "987654321"]
body: "I'll be right back."
# 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"
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: ["123456789", "987654321"]
body: "Hi ${name}! Our latest survey shows that 3 out of 4 people make up 75% of the world's population."
parameters:
name:
123456789: "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:
toRemove: ["11111111111", "29999999999", "15551234567", "1123456789", "15559876543"]
BatchAddPhoneNumbers:
summary: Add phone numbers to a batch
# description: Add two phone numbers to batch 12345
value:
toAdd: ["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: 3
statuses:
- code: 400
status: "Queued"
count: 1
recipients: ["123456789"]
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 update group for shared short code
value:
name: "Patients at Westside Clinic 2"
auto_update:
to: "54321"
add:
first_word: "West2"
second word: "Join"
remove:
first_word: "West2"
second_word: "Stop"
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: ["dxCJTlfb1UsF", "yiinTKVNAEAu"]
GroupUpdateAdd:
summary: Add or remove members to existing group
value:
add: ["123456789", "987654321"]
remove: ["432156789"]
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: null
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
schemas:
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 MSISDN or short code.
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: 01FC66621VHDBN119Z8PMV1QPU
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:
- 01FC66621VHDBN119Z8PMV1AHY
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:
- 01FC66621VHDBN119Z8PMV1AHY
ApiGroup:
type: object
properties:
id:
type: string
description: Unique identifier for the group
readOnly: true
example: 01FC66621VHDBN119Z8PMV1QPQ
DeliveryReportList:
type: object
properties:
count:
type: integer
description: The total number of entries matching the given filters.
format: int64
example: 2
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/DeliveryReportRecipient'
DeliveryReportRecipient:
description: A page of delivery reports matching the given filters.
required:
- at
- batch_id
- code
- recipient
- status
type: object
properties:
applied_originator:
type: string
description: |-
If no default originator pool was set when the batch was submitted, this is the default originator for the recipients on this delivery report.
at:
type: string
description: A timestamp of when the delivery report was created.
format: date-time
batch_id:
type: string
description: The ID of the batch for this delivery report.
readOnly: true
example: 01FC66621VHDBN119Z8PMV1QPQ
client_reference:
type: string
description: |-
The client provided identifier of the batch this delivery report belongs to, if set when submitting the batch.
code:
type: integer
description: The detailed status code.
format: int32
encoding:
type: string
description: Applied encoding for message. Present only if smart encoding is enabled.
example: GSM
enum:
- GSM
- UNICODE
number_of_message_parts:
type: integer
description: The number of parts the message was split into. Present only if the `max_number_of_message_parts` parameter was set.
format: int32
example: 1
operator:
type: string
description: |-
If configured to the account, the operator used for delivering the message to this recipient. In MCC/MNC format.
example: "35000"
operator_status_at:
type: string
description: |-
A timestamp extracted from the delivery receipt from the originating SMSC.
format: date-time
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
enum:
- Queued
- Dispatched
- Aborted
- Failed
- Delivered
- Expired
- Rejected
- Deleted
- Unknown
type:
type: string
description: The object type. Will always be `recipient_delivery_report_sms`.
enum:
- recipient_delivery_report_sms
retrieveRecipientDeliveryResponseObj:
required:
- at
- batch_id
- code
- recipient
- status
type: object
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
description: A timestamp of when the Delivery Report was created in the Sinch service.
format: date-time
batch_id:
type: string
description: The ID of the batch this delivery report belongs to
readOnly: true
example: 01FC66621VHDBN119Z8PMV1QPQ
client_reference:
type: string
description: "The client identifier of the batch this delivery report belongs to, if set when submitting batch."
code:
type: integer
description: The detailed status code.
format: int32
number_of_message_parts:
type: integer
description: The number of parts the message was split into. Present only if `max_number_of_message_parts` parameter was set.
format: int32
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
description: A timestamp extracted from the Delivery Receipt from the originating SMSC.
format: date-time
recipient:
type: string
description: Phone number that was queried for.
example: "15551231234"
status:
type: string
description: 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 no callback will be made to report them.
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.
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 object type. Will always be `recipient_delivery_report_sms`.
enum:
- recipient_delivery_report_sms
retrieveDeliveryResponseObj:
type: object
properties:
type:
type: string
default: delivery_report_sms
description: The object type. Will always be `delivery_report_sms`.
batch_id:
type: string
description: The ID of the batch this delivery report belongs to
total_message_count:
type: string
description: The total number of messages for the batch
statuses:
type: array
description: Array with status objects. Only status codes with at least one recipient will be listed.
items:
type: object
properties:
code:
description: The detailed status code.
type: integer
status:
type: string
enum:
- Queued
- Dispatched
- Aborted
- Failed
- Delivered
- Expired
- Rejected
- Deleted
- Unknown
description: The simplified status as described in _Delivery Report Statuses_
count:
description: The number of messages that currently has this code. Will always be at least 1
type: integer
recipients:
type: array
description: Only for _full_ report. A list of the phone number recipients which messages has this status code.
items:
type: string
client_reference:
type: string
description: The client identifier of the batch this delivery report belongs to, if set when submitting batch.
example:
type: delivery_report_sms
batch_id: 01FC66621VHDBN119Z8PMV1QPQ
total_message_count: "20000"
statuses:
[
{ code: 0, status: "Delivered", count: 19999 },
{ code: 401, status: "Dispatched", count: 1 },
]
updateBatchReq:
type: object
properties:
from:
type: string
description: Sender number. Must be valid phone number, short code or alphanumeric.
example: "+46342324894"
body:
type: string
maxLength: 1600
description: |-
The message content. Normal text string for `mt_text` and Base64 encoded for `mt_binary`.
Constraints:
- Max 1600 chars for `mt_text`
- Max 140 bytes together with udh for `mt_binary`.
example: "A text message!"
to_add:
type: array
description: List of phone numbers and group IDs to add to the batch.
items:
type: string
minItems: 1
maxItems: 100
example: ["+44531234233", "34234445434"]
to_remove:
description: "List of phone numbers and group IDs to remove from the batch."
type: array
items:
type: string
example: ["+4453868734", "3423423432"]
delivery_report:
type: string
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.
description: Request delivery report callback. Note that delivery reports can be fetched from the API regardless of this setting.
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](https://en.wikipedia.org/wiki/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
maxLength: 2048
description: |-
Override the default callback URL for this batch.
Constraints:
Must be valid URL.
example: "example.callback.com"
inboundResponseObject:
type: object
properties:
page:
type: integer
description: The requested page.
example: 1
page_size:
type: integer
description: The number of inbounds returned in this request.
example: 50
count:
type: integer
description: The total number of inbounds matching the given filters
example: 100
inbounds:
type: array
description: The page of inbounds matching the given filters
items:
$ref: "#/components/schemas/inboundsObject"
inboundsObject:
type: object
description: "The response object of an inbound message. They can be retrieved and listed or sent via a callback."
properties:
type:
type: string
description: The object type. Either mo_text or mo_binary.
example: mo_text
id:
type: string
description: The ID of this inbound message.
example: 01FC66621VHDBN119Z8PMV1QPA
from:
type: string
description: The phone number that sent the message.
example: +11203494390
to:
type: string
description: The Sinch phone number or short code to which the message was sent.
example: +11203453453
body:
type: string
description: The message body. Base64 encoded if type is `mo_binary`.
example: This is a test message
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.
operator_id:
type: string
description: The MCC/MNC of the sender's operator if known.
send_at:
type: string
format: date-time
description: |-
When the message left the originating device. Only available if provided by operator.
Formatted as [ISO-8601](https://en.wikipedia.org/wiki/ISO_8601): YYYY-MM-DDThh:mm:ss.SSSZ
received_at:
type: string
format: date-time
description: |-
When the system received the message.
Formatted as [ISO-8601](https://en.wikipedia.org/wiki/ISO_8601): YYYY-MM-DDThh:mm:ss.SSSZ
sendBatchCreated:
type: object
properties:
to:
type: array
minItems: 1
maxItems: 1000
items:
$ref: "#/components/schemas/msisdn"
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"]
from:
type: string
description: |
Sender number.
Required if Automatic Default Originator not configured.
example: "+15551231234"
type:
type: string
default: mt_text
enum:
- mt_text
- mt_binary
description: |-
Identifies the type of batch message.
Default:
`mt_text` is regular SMS, `mt_binary` is a binary format.
example: mt_text
body:
type: string
description: |-
The message content. Normal text string for `mt_text` and Base64 encoded for `mt_binary`.
Max 1600 chars for `mt_text` and max 140 bytes together with udh for `mt_binary`.
example: "This is a message to be sent!"
udh:
type: string
description: |-
The UDH header of a binary message. Max 140 bytes together with body.
Required if type is `mt_binary`.
delivery_report:
type: string
enum:
- none
- summary
- full
- per_recipient
description: "Request delivery report callback. \n\nNote that delivery reports can be fetched from the API regardless of this setting. \n\nValid types are none, summary, full and per_recipient\t"
send_at:
type: string
format: date-time
description: "If set in the future, the message will be delayed until `send_at` occurs.\n\nMust be before `expire_at`. \n \nIf set in the past, messages will be sent immediately.\t"
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 is 3 days after `send_at`.
callback_url:
type: string
maxLength: 2048
description: |-
Override the default callback URL for this batch.
Must be valid URL.
Max 2048 characters long.
flash_message:
type: boolean
default: false
description: |-
Shows message on screen without user interaction while not saving the message to the inbox.
true or false.
parameters:
type: object
description: |-
Contains the parameters that will be used for customizing the message for each recipient.
Not applicable to if type is `mt_binary`.
[Click here to learn more about parameterization.](/docs/sms/resources/message-info/message-parameterization)
properties:
"{parameter_key}":
type: string
maxLength: 16
pattern: '^[A-Za-z0-9_\-.]+$'
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. Max 16 characters long
"{parameter_key}.{msisdn}":
type: string
maxLength: 160
description: |-
The recipient that should get this value
Max 160 characters long
"{parameter_key}.default":
type: string
maxLength: 160
description: |-
The fall-back value for omitted recipient phone numbers ([MSISDNs](https://community.sinch.com/t5/Glossary/MSISDN/ta-p/7628))
Max 160 characters long
client_reference:
type: string
maxLength: 128
description: |-
The client identifier of a batch message. If set, the identifier will be added in the delivery report/callback of this batch
Max 128 characters long
max_number_of_message_parts:
type: integer
minimum: 1
description: |-
Message will be dispatched only if it is not split to more parts than Max Number of Message Parts
Must be higher or equal 1
id:
type: string
description: Unique identifier for batch
created_at:
type: string
format: date-time
description: |-
Timestamp for when batch was created.
Formatted as [ISO-8601](https://en.wikipedia.org/wiki/ISO_8601): YYYY-MM-DDThh:mm:ss.SSSZ.
modified_at:
type: string
format: date-time
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.
canceled:
type: boolean
description: Indicates if the batch has been canceled or not.
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
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](https://community.sinch.com/t5/Glossary/MSISDN/ta-p/7628))"
description: "The name of the parameter that will be replaced in the message\
\ body. \n \n 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. \n \n [Click here to learn more about parameterization.](/docs/sms/resources/message-info/message-parameterization)"
MtDestination:
type: object
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
Text:
required:
- body
- delivery_report
- to
type: object
properties:
id:
type: string
description: Unique identifier for batch
readOnly: true
example: 01FC66621VHDBN119Z8PMV1QPQ
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
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.
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`. \n \n 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. \n \n 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
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
sendBatchObject:
type: object
required:
- to
- body
properties:
to:
type: array
minItems: 1
maxItems: 1000
items:
$ref: "#/components/schemas/msisdn"
description: |-
List of Phone numbers and group IDs that will receive the batch.
Constraints: 1 to 1000 elements [More info](https://community.sinch.com/t5/Glossary/MSISDN/ta-p/7628)
example: ["+15551231234", "+15551256344"]
from:
type: string
description: |
Sender ID. This can be a phone number or an alphanumeric sender.
Required if Automatic Default Originator not configured.
example: "+15551231234"
type:
type: string
default: mt_text
enum:
- mt_text
- mt_binary
description: |-
Identifies the type of batch message.
example: mt_text
body:
type: string
description: |-
The message content. Normal text string for `mt_text` and Base64 encoded for `mt_binary`.
Max 1600 chars for `mt_text` and max 140 bytes together with udh for `mt_binary`.
example: "This is a message to be sent!"
udh:
type: string
description: |-
The UDH header of a binary message. Max 140 bytes together with body.
Required if type is `mt_binary`.
delivery_report:
type: string
enum:
- none
- summary
- full
- per_recipient
description: "Request delivery report callback. \n\nNote that delivery reports can be fetched from the API regardless of this setting. \n\nValid types are none, summary, full and per_recipient\t"
example: summary
send_at:
type: string
format: date-time
description: "If set in the future, the message will be delayed until `send_at` occurs.\n\nMust be before `expire_at`. \n \nIf set in the past, messages will be sent immediately.\t"
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 is 3 days after `send_at`.
callback_url:
type: string
format: uri
example: https://yourdomain.com/sms/deliveryreports
maxLength: 2048
description: |-
Override the default callback URL for this batch.
Must be valid URL.
Max 2048 characters long.
flash_message:
type: boolean
default: false
description: |-
Shows message on screen without user interaction while not saving the message to the inbox.
true or false.
parameters:
type: object
description: |-
Contains the parameters that will be used for customizing the message for each recipient.
Not applicable to if type is `mt_binary`.
'example : "parameters: [{"name": {
"123456789": "Joe",
"default": "there"}]'
[Click here to learn more about parameterization.](/docs/sms/resources/message-info/message-parameterization)
properties:
"{parameter_key}":
type: object
maxLength: 16
pattern: '^[A-Za-z0-9_\-.]+$'
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. Max 16 characters long.
properties:
"{msisdn}":
type: string
maxLength: 160
example: '{"15551231212":"Joe"}'
description: |-
The recipient that should get this value
Max 160 characters long
"default":
type: string
maxLength: 160
example: '{"default":"Customer"}'
description: |-
The fall-back value for omitted recipient MSISDNs
Max 160 characters long.
client_reference:
type: string
maxLength: 128
description: |-
The client identifier of a batch message. If set, the identifier will be added in the delivery report/callback of this batch
Max 128 characters long
max_number_of_message_parts:
type: integer
minimum: 1
description: |-
Message will be dispatched only if it is not split to more parts than Max Number of Message Parts
Must be higher or equal 1
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.
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
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
msisdn:
type: string
format: e.164
description: |-
A phone number in E.164 format.
example: "+453234457784"
Binary:
required:
- body
- delivery_report
- to
- udh
type: object
properties:
id:
type: string
description: Unique identifier for batch
readOnly: true
example: 01FC66621VHDBN119Z8PMV1QPQ
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.\n \n 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
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
created_at:
type: string
description: "Timestamp for when batch was created. \n \n Formatted as [ISO-8601](https://en.wikipedia.org/wiki/ISO_8601): YYYY-MM-DDThh:mm:ss.SSSZ\
\ format"
format: date-time
readOnly: true
modified_at:
type: string
description: "Timestamp for when batch was last updated. \n \n Formatted as [ISO-8601](https://en.wikipedia.org/wiki/ISO_8601): YYYY-MM-DDThh:mm:ss.SSSZ\
\ format"
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.
send_at:
type: string
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 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. \n \n Must be after `send_at`. Default and max is 3 days\
\ after `send_at`. \n \n 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. \n \n 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
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
securitySchemes:
BearerAuth:
type: http
scheme: bearer
description: |
The token is sent in the `Authorization` header preceded by `Bearer`. It's required for all requests made to the REST API.
You can find your `service_plan_id` and token in the [Dashboard](https://dashboard.sinch.com/sms/api/rest)
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: 01FC66621VHDBN119Z8PMV1QPQ
inbound_id:
name: inbound_id
in: path
required: true
description: The inbound ID found when listing inbound messages.
schema:
type: string
example: 01FC66621VHDBN119Z8PMV1QPA
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: 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.
- 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: Delivery reports
description: |-
The REST API uses message statuses and error codes in delivery reports, which refer to the state of the SMS 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 to 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 ([Retrieve a recipient delivery report](/docs/sms/api-reference/sms/tag/Delivery-reports/#tag/Delivery-reports/operation/GetDeliveryReportByPhoneNumber)), no callback will be made to report them.
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. |
| `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 shares most of its error codes with other SMS services.
In addition to these standard error codes, the REST API provides an additional set of error codes, all within the 4xx range (vendor specific errors in the range of 0x400 to 0x4FF as referenced in the SMPP specification). These are listed below:
| Status Code (Hex) | 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 | Canceled | `Aborted` | Message was canceled 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 credits. |
- 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. If no successful response is received, the REST API will either schedule a retry, if the error is expected to be temporary, or discard the callback, if the error seems permanent. 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.
The SMS REST API offers the following callback options which can be configured for your account upon request to your account manager.
- Callback with mutual authentication over TLS (HTTPS) connection by provisioning the callback URL with client keystore and password.
- Callback with basic authentication by provisioning the callback URL with username and password.
- Callback with OAuth 2.0 by provisioning the callback URL with username, password and the URL to fetch OAuth access token.
- Callback using AWS SNS by provisioning the callback URL with an Access Key ID, Secret Key and Region.