Definitions, Formats & Errors


Sender Identity

The Application-to-Person (A2P) agent that sends messages to the end user, sometimes referred to as a chat bot, bot or agent.

Sender ID

The unique identifier for the Sender Identity registered on the Sinch platform.

Example: AbCDEfghIJKlMNop

Please contact your Sinch account manager to get your Sender ID.

User Agent

The end users messaging application on device that receives messages from the Agent and sends messages, events and status back to the RCS API.

Data formats


JSON (application/json) is the content type of both requests and responses if not otherwise specified. Requests with invalid JSON will be rejected.

Null values can be omitted in requests and will be omitted in responses. In some cases explicitly setting null will overwrite a previously set value with null.


An MSISDN is the phone number associated with a single SIM card. Only MSISDNs in international E.164 format are accepted by the API.

MSISDNs can be sent in with or without a leading + or 00 (+123456789, 00123456789 and 123456789 are equivalent). Any spaces, dashes or brackets, will be ignored by the API.

All MSISDNs returned by the REST API will be without a + or 00 prefix, even if they were originally sent in with one.


Timestamps are represented using the ISO-8601 standard.

All timestamps returned will be in UTC with millisecond precision.

The time zone can be specified in accordance with ISO-8601. If no time zone offset is specified (local time in ISO-8601) then UTC will be used.


The REST API returns the appropriate HTTP status codes for the request made. Such as 200 OK, 401 Unauthorized or a 400 Bad Request.

When an 4XX HTTP error is returned the response body also contains an Error object with more information.

For example, a 400 Bad Request could be due to Missing Required Property or Invalid Property.

Error Codes

To distinguish these errors, the response body has an API error_code property.

HTTP STATUS API Error Code Description
500 1 Unknown server error
1000 Invalid JSON
1001 Invalid API message
400 1002 Invalid property value
1003 Mismatched input
400 1004 Missing required property
400 1005 Invalid property value
400 1006 Invalid property value
1007 Missing property
1010 Couldn't handle the input
401 1011 Unauthorized
404 1014 Subscriber not found (MISDIN not valid or not registered to with an RCS provider)
404 N/A Some 404 errors have no body
405 N/A Method not allowed (has body but no error_code field)
409 N/A Conflict (Empty body - delete a message that has been deleted)
We'd love to hear from you!
Rate this content:
Still have a question?
Ask the community.