Sinch REST API Reference

The Sinch REST API serves the main purpose of making it possible to perform certain actions that are either not possible, or not recommended, to perform directly from a client application that has the Sinch SDK embedded.

The Sinch REST API is RESTful in the sense that it exposes a way to interact with resources for a certain instance of a Sinch SDK Application over the HTTPS protocol. Resources are identified as URLs, that map to endpoints. HTTP methods (GET, POST, PUT, DELETE) are used to perform different operations on the resources. Request and response bodies should be encoded as JSON.

API Version and Base URL

Current version is V1.

All URLs for API endpoints referenced in the documentation have the following base URL:

Environment Base URL
Live https://clientapi.sinch.com/V1/
Sandbox https://sandbox.sinch.com/V1/

Using the REST API to handle feedback from Apple Push Notification Service or Google Cloud Messaging

If Push Notifications are enabled via either Apple Push Notification Service (APNS) or Google Cloud Messaging (GCM), these services will provide feedback if the application backend service is attempting to send a notification to a device that is no longer registered with APNS or GCM. This section describes how the application backend service should interact with the Sinch REST API upon receiving such feedback.

For background for this section, please refer to the section on Push Notifications in the platform-specific section of the user guide on iOS and Android respectively. Also see Apple Push Notification Programming Guide - The Feedback Service and Google Cloud Messaging - How Unregistration Works.

A typical scenario is that a client A has registered for Apple Push Notifications, another client B is attempting to call A, and client B will then request to send a push notification to A’s device via the application backend service (which in turn interacts with APNS). If A has uninstalled the application at the point in time when B is requesting to send a push notification to A’s device, the APNS will respond to the application backend service that the device token for client A is no longer valid. If this occurs, further actions must be taken to avoid that additional requests that target the invalid device token are made.

A key consideration is that the push notification data, which is used to identify A’s device and thus contains the invalid device token, is still present in the Sinch system. When any client is attempting to call A, that is the information the clients are given. It will in turn be used by the application backend service to target A’s device via either APNS or GCM (see the section on Push Notifications for details on push notification data). The Sinch REST API provides a way to clean out these invalid tokens, so that no following requests are made to target the invalid device identifier.

When receiving feedback from APNS or GCM about an invalid device identifier, after an attempt to reach a user, the application backend service should make a DELETE request to the endpoint V1/Partner/PushData. If the parameter PushData is omitted in the request, all push notification data entries for all the devices of that user will be deleted. The preferred way is to only delete the push notification data entry which corresponds to the invalid device token (APNS) / RegistrationID (GCM) that was reported from the feedback service, by specifying it as a parameter in the request.

REST API Endpoints

DELETE Partner/PushData

Request Parameters

Name Type Required Description
ApplicationKey String Yes Application Key
UserId String Yes User Identify within you application domain
PushData String No When push notification data is registered via the client SDKs, it is typed as an array of bytes. But when specifying to delete a specific entry via the REST API, the parameter in the request must be the Base64-encoded equivalent of the original push notification data that was registered in the client. Must be < 1024 characters if specified. If the parameter is omitted, all push notification data entries for all the devices of the user will be deleted.
Signature String Yes Signature for the request. See Calculating Signature below.

Example Request Body:

{
    "ApplicationKey":"19608731-e815-4bd4-8984-60d8d8a43f1f",
    "UserId":"John",
    "PushData":"QThDNUNBMjZFMzJBQ0I0MzgzNjQzNDBFM0ZDRkFDRUM0Njk5MjI2NzUzQkFGMUM3NjcwOTA0QjVGQUI3M0U1DQo=",
    "Signature":"1jOsVY+atyJmOJQZJP9HxZKfdO8="
}

Response

Example

{
    "Result": 200,
    "Message":"PushDataDeleted"
}

Error codes

0x530003    ApplicationKeyParameterEmpty
0x530004    SignatureParameterEmpty
0x530005    SignatureParameterInvalid
0x530007    ApplicationNotFound
0x530009    RequestEmpty
0x530012    ApplicationKeyParameterInvalid
0x530021    UserIdParameterEmpty
0x530024    UserIdParameterTooLong
0x530027    PushDataParameterInvalid
0x530033    UserNotFound

Calculating Signature

string buffer = userId + pushData + applicationKey + secret;

byte[] signatureData = Encoding.UTF8.GetBytes(buffer);
byte[] signature = SHA1.Create().ComputeHash(signatureData);

string signature = Convert.ToBase64String(signature);