logo

API documentation

Introduction

This API is intended to create campaigns automatically. The campaign application is to be customized on the Sinch platform so that it can be duplicated by this API. The statistics for a campaign are available after the date it was sent.

The API requests described below must be done on https://api.us.campaign.sinch.com except the user login whose URL is https://us.campaign.sinch.com/api/login.

The contents of all HTTP responses are in JSON format. A response with an HTTP status of 400 indicates an API usage error. A response whose HTTP status is 401 indicates an authentication error. In case of error, the attribute errors documents errors.

Strings sent to the service must be encoded in UTF-8 unless otherwise specified. Likewise, the strings you receive are encoded in UTF-8.

Except the authentication, all POST requests accept two types of content

  • The header Content-Type: application/x-www-form-urlencoded is used to post "encode url" parameters which is the web form's standard format.
  • The header Content-Type: application/json allows you to post parameters in a JSON object. A different encoding of the UTF-8 can be specified in the charset parameter as follows. 
    Content-Type: application/json; charset=utf-16

Authentication

Authentication with secret key (recommended)

Request a secret key to use the API without the password of the account. If we generated it, it is available on the Sinch Options page. This key must be stored securely on your server and must not be served.

To use the other API points, you must request an access token with the secret key. This request is described below and and must be done from server to server. An access token will be provided in the response and will be used to identify you in all other queries. The access token expires after 2 hours.It will be necessary to obtain another after this period.

Request
URL
https://api.us.campaign.sinch.com/v1/token
Method
POST
HTTP header
Authorization: Basic <secret key>

Replace <secret key> by your secret key.

Example
POST /api/token HTTP/1.1
Host: api.us.campaign.sinch.com
Content-Length: 0
Accept: application/json
Authorization: Basic NWM1MDQyNzAtYzUwYi00MDgxLTk0ZWMtZGFkODQyMWQyOTRmOjc2NWYzMTVlLTIwM2QtNGJjNC05ZmExLTkyNWRkMGJlODUxMQ==
Accept-Encoding: gzip
cURL example
curl 'https://api.us.campaign.sinch.com/v1/token' -X POST -H 'Authorization: Basic NWM1MDQyNzAtYzUwYi00MDgxLTk0ZWMtZGFkODQyMWQyOTRmOjc2NWYzMTVlLTIwM2QtNGJjNC05ZmExLTkyNWRkMGJlODUxMQ==' -H 'Accept-Encoding: gzip' -H 'Accept: application/json' -H 'Content-Length: 0' --compressed
Python example 
import requests
response = requests.post(
    'https://api.us.campaign.sinch.com/v1/token',
    headers={'Authorization': 'Basic NWM1MDQyNzAtYzUwYi00MDgxLTk0ZWMtZGFkODQyMWQyOTRmOjc2NWYzMTVlLTIwM2QtNGJjNC05ZmExLTkyNWRkMGJlODUxMQ=='}
)
Answer on success

The response in JSON contains the access token to add in the header Authorization of the other requests.

Attributes of the JSON object
access_token
Access token needed for other requests.
expires
UTC expiration date of the ISO format access token.
Example
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 119

{"access_token": "vNjIyZTAyNWQtYjRkOC00OWNiLThiY2UtZWRhYTJjYTRkMWQ0", "expires": "2016-08-12T10:45:04", "success": true}
Answer in case of error

In case of error, the HTTP status is 401 and the response in JSON contains the error message in the attribute errors.

Example
HTTP/1.1 401 UNAUTHORIZED
Content-Type: application/json
Content-Length: 50

{"errors": "Invalid secret key", "success": false}
Using the access token

Unless otherwise specified, the access token obtained must be added in the header Authorization of other requests as follow.

Authorization: Bearer vNjIyZTAyNWQtYjRkOC00OWNiLThiY2UtZWRhYTJjYTRkMWQ0

If the access token is invalid or expired, the status of the response will be 401.

Error example
HTTP/1.1 401 UNAUTHORIZED
Content-Type: application/json
Content-Length: 73
Access-Control-Allow-Origin: *

{"errors": {"Authorization": ["Invalid access token"]}, "success": false}

User connexion

The user connexion allows to start a user session without his password. It is necessary to have an access token got from your server thanks to your secret key. The user must make the following request with his browser. Place a link on your site for example.

Be careful, this is the only request that is made on https://us.campaign.sinch.com.

Request
URL
https://us.campaign.sinch.com/api/login
Method
GET
Settings
access_token
An access token got from your server thanks to your secret key.
Example
GET /api/login?access_token=ZWU5YjU2NWUtZjM4NS00OWYyLTg5YmMtZjA3Nzg1YWYwMWE2 HTTP/1.1
Host: us.campaign.sinch.com
User-Agent: Mozilla/5.0 (X11; Ubuntu; Linux x86_64; rv:48.0) Gecko/20100101 Firefox/48.0
Accept: text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8
Accept-Language: en-US,en;q=0.5
Accept-Encoding: gzip, deflate
Referer: http://my.site.com/my-connect-page/
Connection: keep-alive
HTML example with Jinja template generator
<a href="https://us.campaign.sinch.com/api/login?access_token={{ access_token }}">Connexion</a>
HTML and Javascript example
<a id="connectLink" href="https://us.campaign.sinch.com/api/login">Connexion</a>
<script>
    // Get access token from your server
    var accessToken = 'ZWU5YjU2NWUtZjM4NS00OWYyLTg5YmMtZjA3Nzg1YWYwMWE2';
    document.getElementById('connectLink').href += '?access_token=' + accessToken;
</script>
Response if success: redirection

The response is a redirection 302 on the Sinch campaign list page of the account.

Example
HTTP/1.1 302 FOUND
Content-Type: text/html; charset=utf-8
Content-Length: 269
Location: https://us.campaign.sinch.com/campaigns
Set-Cookie: richsms-v2.cookie=0f49d737408384d7559f37d54f2ee6e2b810260f; Expires=Fri, 19-Aug-2016 13:37:38 GMT; Max-Age=86400; Path=/

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
<title>Redirecting...</title>
<h1>Redirecting...</h1>
<p>You should be redirected automatically to target URL: <a href="https://us.campaign.sinch.com/campaigns">https://us.campaign.sinch.com/campaigns</a>.  If not click the link.
Answer in case of error

In case of error, the HTTP status is 401 and the text response contains the error message.

Example
HTTP/1.1 401 UNAUTHORIZED
Content-Type: text/plain; charset=utf-8
Content-Length: 20

Invalid access token

Campaign creation

Campaign creation is made by duplication. You can customise your template on the platform Sinch then program automatic sending of copies of this template.

Request
URL
https://api.us.campaign.sinch.com/v1/campaign/create
Method
POST
HTTP header
Authorization or token
Authentication token (see Authentication)
Content-Type
application/x-www-form-urlencoded or application/json (voir Introduction)
Settings
logic
Template type choice (only duplicate is available). duplicate has to be used to create campaign.
logic_param
Template parameters depending on template type.
name
Campaign's name.
sender
This parameter is only available for SMS channel. Message sender name. Optional if logic type is duplicate and if the copied campaign already have a correct sender. In this case, the new campaign sender will be a copy of the copied campaign sender. (Optional)
message
This parameter is only available for SMS channel. Message text where [[URL]] will be replaced by the application URL and [[X]] will be replaced by value of column X (A to Z available) Optional if logic type is duplicate and the copied campaign already have a correct message. In this case, the new campaign message will be a copy of the copied campaign message. (Optional)
contacts
Recipients list in JSON, see example below: [["0612345678", "Alice"], ["0612345679", "Bob"]]
send_date
Campaign sending date in the future (1h in the past is accepted), format: yyyy-mm-dd HH:MM
timezone
Optional. Timezone Identifier using standard namings (Europe/Paris, UTC), default value: UTC
tag
Any string (Optional)
external_channel
true to use the external channel, otherwise do not use this parameter. The external channel is only available if the option has been unlocked on your account. (Optional)
field_names
List of names of the contact fields provided in the parameter contacts, by default: A, B, C… The names must contains only alphanumeric charaters, underscores, dashes, or white spaces. These field names will be returned in the contact data route. (Optional)

Either the request includes all parameters, or it includes neither sender, nor message.

Example of existing campaign duplication with Python
import requests
import simplejson as json
import datetime
r = requests.post('https://api.us.campaign.sinch.com/v1/campaign/create', {
    'logic': 'duplicate',
    'logic_param': '0cafc06b-13ba-4e1e-b03c-dd7b9a11b5e7', # Campaign UUID to duplicate
    'name': 'Mon app',
    'sender': 'Moi',
    'message': 'Bonjour [[B]] ! Clique ici [[URL]]',
    'contacts': json.dumps([['0612345678', 'Alice'], ['0612345679', 'Bob'], ['0634567812', 'Claire']]),
    'send_date': datetime.datetime.now().strftime('%Y-%m-%d %H:%M'),
}, headers={'Authorization': 'Bearer be3e1c6d-e6bc-46aa-8868-d9e24b051ed8'})

The value of parameter logic_param must be a campaign UUID. You can see UUID on your campaign list clicking "Show the IDs".

Example of existing campaign duplication with Python using JSON
import requests
import simplejson as json
import datetime
r = requests.post('https://api.us.campaign.sinch.com/v1/campaign/create', json.dumps({
    'logic': 'duplicate',
    'logic_param': '0cafc06b-13ba-4e1e-b03c-dd7b9a11b5e7', # Campaign UUID to duplicate
    'name': 'Mon app',
    'sender': 'Moi',
    'message': 'Bonjour [[B]] ! Clique ici [[URL]]',
    'contacts': [['0612345678', 'Alice'], ['0612345679', 'Bob'], ['0634567812', 'Claire']],
    'send_date': datetime.datetime.now().strftime('%Y-%m-%d %H:%M'),
}), headers={'Authorization': 'Bearer be3e1c6d-e6bc-46aa-8868-d9e24b051ed8', 'Content-Type': b'application/json'})

The value of parameter logic_param must be a campaign UUID. You can see UUID on your campaign list clicking "Show the IDs".

Answer on success
HTTP status
200
Content-Type
application/json
Content
{
    "success": true,
    "solde": 430,
    "campaign": {
        "uuid": "5a7b28fd-a216-4d31-90b3-0f62c2e4ee7f",
        "url": "https://rsms.us/bTD",
        "contact_count": 2,
        "duplicated_contacts": [],
        "wrong_contacts": [],
        "tag": null
    }
}
solde
Remaining credits after campaign creation
uuid
New campaign UUID
url
Sinch link
contact_count
Number of recipients found
duplicated_contacts
List of MSISDN found more than once
wrong_contacts
List of MSISDN with a wrong format
tag
Campaign tag
Example of response in case of parameters errors.
HTTP status
400
Content-Type
application/json
Content
{
    "success": false,
    "errors": {
        "logic": ["Logic not found. Try with duplicate"],
        "name": ["This field is required."],
        "sender": ["Invalid input."],
        "message": ["This field is required."],
        "send_date": ["Not a valid datetime value"]
    }
}

Each wrong parameter appears in errors object with a list of error messages.

Send SMS on a campaign

This endpoint allows you to add contacts on an existing campaign and send a message to these contacts.

Request
URL
https://api.us.campaign.sinch.com/v1/campaign/sendsms
Method
POST
HTTP header
Authorization or token
Authentication token (see Authentication)
Content-Type
application/x-www-form-urlencoded or application/json (see Introduction)
Settings
campaign_uuid
Campaign UUID
contact (deprecated)
The recipient in JSON, see example below: ["0612345678", "Alice"]
contacts
Multiple contacts, ie. a JSON formated string. For example: [["0612345678", "Alice"], ["0612345679", "Bob"]]. Maximum list size is 1000.
external_channel
true to use the external channel, otherwise do not use this parameter. The external channel is only available if the option has been unlocked on your account. (Optional)
Example with Python
import requests
import simplejson as json
import datetime
r = requests.post('https://api.us.campaign.sinch.com/v1/campaign/sendsms', {
    'campaign_uuid': '5a7b28fd-a216-4d31-90b3-0f62c2e4ee7f',
    'contacts': json.dumps([["0612345678", "Alice"], ["0612345679", "Bob"]]),
}, headers={'Authorization': 'Bearer be3e1c6d-e6bc-46aa-8868-d9e24b051ed8'})
Example using JSON with Python
import requests
import simplejson as json
import datetime
r = requests.post('https://api.us.campaign.sinch.com/v1/campaign/sendsms', json.dumps({
    'campaign_uuid': '5a7b28fd-a216-4d31-90b3-0f62c2e4ee7f',
    'contacts': [["0612345678", "Alice"], ["0612345679", "Bob"]],
}), headers={'Authorization': 'Bearer be3e1c6d-e6bc-46aa-8868-d9e24b051ed8', 'Content-Type': b'application/json'})
Answer on success
HTTP status
200
Content-Type
application/json
Content
{
    "success": true,
    "contacts": [
        {
            "msisdn": "33612345678",
            "url": "https://rsms.us/bTD0",
        },
        {
            "msisdn": "33612345679",
            "url": "https://rsms.us/bTD1",
        }
    ]
}
Example of response in case of parameters errors.
HTTP status
400
Content-Type
application/json
Content
{
    "success": false,
    "errors": {
        "campaign_uuid": ["Campaign '5a7b28fd-a216-4d31-90b3-0f62c2e4ee7f' not found."],
        "contact": ["No JSON object could be decoded."],
    }
}

Each wrong parameter appears in errors object with a list of error messages.

Generate Landing Page

This endpoint allows you to generate a Landing Page on existing campaign with external channel.

Request
URL
https://api.us.campaign.sinch.com/v1/campaign/generate-landingpages
Method
POST
HTTP header
Authorization or token
Authentication token (see Authentication)
Content-Type
application/x-www-form-urlencoded or application/json (see Introduction)
Settings
campaign_uuid
Campaign UUID
contacts
Multiple contacts, ie. a JSON formated string. For example: [["0612345678", "Alice"], ["0612345679", "Bob"]]. Maximum list size is 1000.
Example with Python
import requests
response  = requests.post(
    f'https://api.us.campaign.sinch.com/v1/campaign/generate-landingpages',
    json={
        'campaign_uuid': '01987a5d-7e5d-465d-b133-fad0fffa680c',
        'contacts': [["id1", "Alice", "SALE30"], ["id2", "Bob", "SALE10"]]},
    headers={'Authorization': f'Bearer be3e1c6d-e6bc-46aa-8868-d9e24b051ed8'})
Answer on success
HTTP status
200
Content-Type
application/json
Content
{
    'success': true,
    'contacts': [
            {'msisdn': 'id1', 'url': 'https://rsms.us/qRfQXD9O'},
            {'msisdn': 'id2', 'url': 'https://rsms.us/qRfJnoDm'}
    ]
}
}
Example of response in case of parameters errors.
HTTP status
400
Content-Type
application/json
Content
{
    "success": false,
    "errors": {
        "contacts": ["This field is required."],
        "campaign_uuid": ["Campaign '5a7b28fd-a216-4d31-90b3-0f62c2e4ee7f' not found."],
    }
}

Each wrong parameter appears in errors object with a list of error messages.

Campain Redirect creation

This endpoint allows you to create a redirect campaign. ⚠️ Only external channel is supported at this time.

Request
URL
https://api.us.campaign.sinch.com/v1/campaign/create-redirect
Method
POST
HTTP header
Authorization or token
Authentication token (see Authentication)
Content-Type
application/x-www-form-urlencoded or application/json (see Introduction)
Settings
name
Campaign name. For example:Redirect for sales
target_url
Final link after redirection, it supports static links or personalized links. For example:https://mysales.com/id=[[A]]&promocode=[[C]]
contacts
Multiple contacts, ie. a JSON formated string. For example: [["33612345678", "Alice", "SALE30"], ["33612345679", "Bob", "SALE10"]]. Maximum list size is 1000.
tag
Any string (Optional)
Example with Python
import requests
requests.post('https://api.us.campaign.sinch.com/v1/campaign/create-redirect', json={
    'name': 'Redirect Sales',
    'target_url': 'https://example.com?id=[[A]]&promocode=[[C]]',
    'contacts': [["id1", "Alice", "SALE30"], ["id2", "Bob", "SALE10"]],
}, headers={'Authorization': 'Bearer be3e1c6d-e6bc-46aa-8868-d9e24b051ed8'})
Answer on success
HTTP status
200
Content-Type
application/json
Content
{
    "success": true,
    "contacts": [
        {
            "key": "id1",
            "target_url": "https://example.com?id=id1&promocode=SALE30",
            "redirection": "https://rsms.us/M1AM98Nb"
        },
        {
            "key": "id2",
            "target_url": "https://example.com?id=id2&promocode=SALE10",
            "redirection": "https://rsms.us/M1AOIq66"
        }
    ],
    "campaign_id": "0197efe0-6158-46a6-a941-7ee2c2f7400c",
    "expiration_date": "2026-07-09T15:49:09.091388+00:00"
}
Example of response in case of parameters errors.
HTTP status
400
Content-Type
application/json
Content
{"success": false, "errors": {"contacts": ["This field is required."]}}

Each wrong parameter appears in errors object with a list of error messages.

List of campaigns

Provides a summary of all campaigns sent by the account. This makes it possible to know the identifier of the campaign, the name of the issuer, the message sent, the date of sending, etc.

The campaigns created more than a year ago might not be returned.

Request
URL
https://api.us.campaign.sinch.com/v1/campaigns
Method
GET
HTTP header
Authorization or token
Authentication token (see Authentication)
Settings
start
Exclude the campaigns sent before this date (included). Date in the format yyyy-mm-dd HH:MM:SS UTC (Optional)
stop
Exclude the campaigns sent at this date or after (excluded). Date in the format yyyy-mm-dd HH:MM:SS UTC (Optional)
status
Status filter, should be one of: ['draft', 'scheduled', 'sending', 'sent'] (Optional)
extended
Show more informations about the campaigns. New fields may appear in future versions without further notice. ['false', 'true'] (Optional) default: false
Example with Python
import requests
r = requests.get('https://api.us.campaign.sinch.com/v1/campaigns', headers={'Authorization': 'Bearer be3e1c6d-e6bc-46aa-8868-d9e24b051ed8'})
Answer on success
HTTP status
200
Content-Type
application/json
Content
{
    "success": true,
    "campaigns": [
        {
            "status": "draft",
            "code": "HcE",
            "send_date": null,
            "name": "Modele pour API",
            "message": "Demo [[A]], voir [[URL]]",
            "contact_count": 4,
            "id": "c2d2f656-09f4-4e26-b9f3-92c14e15116d",
            "sender": "DemoEmett",
            "is_test": true,
            "tag": null,
            "connect_tag": null,
            "is_burst": false,
            "conversation": {
                "module": "module_name",
                "data": {}
            }
        },
        {
            "status": "sent",
            "code": "mpD",
            "send_date": "2016-04-06 10:40:00",
            "name": "Campagne promo",
            "message": "Bonjour [[A]], opération déstockage à [[URL]]",
            "contact_count": 3500,
            "id": "e397637a-f9e2-4838-bcd0-2b87eef1311b",
            "sender": "Prom Emett",
            "is_test": false,
            "tag": "mycampaignid",
            "connect_tag": "mybaseid",
            "is_burst": false,
            "conversation": null
        },
        {
            "status": "scheduled",
            "code": "bTD",
            "send_date": "2016-04-12 15:30:00",
            "name": "Mon app",
            "message": "Bonjour [[B]] ! Clique ici [[URL]]",
            "contact_count": 2,
            "id": "a7b28fd-a216-4d31-90b3-0f62c2e4ee7f",
            "sender": "Moi",
            "is_test": false,
            "tag": null,
            "connect_tag": null,
            "is_burst": false,
            "conversation": {
                "module": "module_name",
                "data": {
                    "type": "order",
                    "foo": "bar"
                }
            }
        }
    ],
}
id
Campaign ID (UUID)
code
3 letter short ID
name
Campaign's name
sender
Name of the sender
message
Message content
send_date
UTC send date of the campaign. The date id formatted as follows yyyy-mm-dd HH:MM:SS.
status
Status of the campaign. The status can be one of the following : draft, scheduled, sending or sent.
contact_count
Number of recipients
is_test
True if campaign is test, else false.
tag
Campaign tag
connect_tag
Connect base tag
is_burst (deprecated)
deprecated parameter, always disabled
conversation
Conversation module configuration information if it is activated: null / Object
conversation.module
Activated module public name
conversation.data
Conversation module configuration filled by Sinch team for a campaign
channel
Channel - only available if extended=true [available since the 03/04/2025]
has_landing_page
Has landing page - only available if extended=true [available since the 03/04/2025]
first_send_date
If campaign has many sending (see APIv2) show the date of the first sending - only available if extended=true [available since the 17/10/2025]

Campaign stats

After campaign sending, stats are available for 6 months. A sum up gives number of sent, delivered and stopped SMS, and number of visits, general and unique, number of previews, and the hard bounced number. For each recipient we have a sending and a reception date, if the response is STOP, the number and dates of his visits, his user agent and if the preview was displayed in the message.

Request
URL
https://api.us.campaign.sinch.com/v1/campaign/stats
Method
GET
HTTP header
Authorization or token
Authentication token (see Authentication)
Settings
campaign_uuid
Campaign UUID
start
First contact index to return, included (pagination, default: 0)
stop
Stop index, excluded (pagination, default: number of contacts)
columns
Adds the columns of the contact file to the response (Optional)
filters
Filter the contact fields of the answer by name (Optional)
stopped_as_date
stopped_as_date=1 returns stopped field as a date formatted as yyyy-mm-dd HH:MM:SS (Optional)
Example with Python
import requests
r = requests.get('https://api.us.campaign.sinch.com/v1/campaign/stats', params={
    'campaign_uuid': '5a7b28fd-a216-4d31-90b3-0f62c2e4ee7f'
}, headers={'Authorization': 'Bearer be3e1c6d-e6bc-46aa-8868-d9e24b051ed8'})
Answer on success
HTTP status
200
Content-Type
application/json
Content
{
    "success": true,
    "summary": {
        "sms_submitted": 3,
        "sms_delivered": 2,
        "sms_stopped": 1,
        "clicks": 3,
        "unique_clicks": 2,
        "previews": 1,
        "npai": 1,
        "credits_used": 3,
    },
    "contacts": [
            {
                "msisdn": "33612345678",
                "url": "https://rsms.us/bTD0",
                "message": "Bonjour Alice ! Clique ici https://rsms.us/bTD0",
                "submitted": u"2014-12-16 13:00:00",
                "delivered": u"2014-12-16 13:30:00",
                "stopped": null,
                "visits": 2,
                "datetimes": "2014-12-16 14:00:00,2014-12-16 14:30:00",
                "preview": null,
                "user_agent": "Firefox OS",
                "npai": false,
            },
            {
                "msisdn": "33612345679",
                "url": "https://rsms.us/bTD1",
                "message": "Bonjour Bob ! Clique ici https://rsms.us/bTD1",
                "submitted": "2014-12-16 13:01:00",
                "delivered": "2014-12-16 13:31:00",
                "stopped": true,
                "visits": 1,
                "datetimes": "2014-12-16 15:00:00",
                "preview": true,
                "user_agent": "Android",
                "npai": false,
            },
            {
                "msisdn": "33634567812",
                "url": "https://rsms.us/bTD2",
                "message": "Bonjour Claire ! Clique ici https://rsms.us/bTD2",
                "submitted": "2014-12-16 13:02:00",
                "delivered": null,
                "stopped": null,
                "visits": 0,
                "datetimes": null,
                "preview": null,
                "user_agent": null,
                "npai": true,
            },
        ],
    }
}
Response on success with the parameter columns
Paramètres
columns=1&columns=3
Statut HTTP
200
Content-Type
application/json
Contenu
{
    "success": true,
    "summary": {
        "sms_submitted": 3,
        "sms_delivered": 2,
        "sms_stopped": 1,
        "clicks": 3,
        "unique_clicks": 2,
        "previews": 1,
        "npai": 1,
        "credits_used": 3,
    },
    "contacts": [
            {
                "msisdn": "33612345678",
                "url": "https://rsms.us/bTD0",
                "message": "Bonjour Alice ! Clique ici https://rsms.us/bTD0",
                "submitted": u"2014-12-16 13:00:00",
                "delivered": u"2014-12-16 13:30:00",
                "stopped": null,
                "visits": 2,
                "datetimes": "2014-12-16 14:00:00,2014-12-16 14:30:00",
                "preview": null,
                "user_agent": "Firefox OS",
                "npai": false,
                "columns": ["CLIENT1234", "Alice"]
            },
            {
                "msisdn": "33612345679",
                "url": "https://rsms.us/bTD1",
                "message": "Bonjour Bob ! Clique ici https://rsms.us/bTD1",
                "submitted": "2014-12-16 13:01:00",
                "delivered": "2014-12-16 13:31:00",
                "stopped": true,
                "visits": 1,
                "datetimes": "2014-12-16 15:00:00",
                "preview": true,
                "user_agent": "Android",
                "npai": false,
                "columns": ["CLIENT5678", "Bob"]
            },
            {
                "msisdn": "33634567812",
                "url": "https://rsms.us/bTD2",
                "message": "Bonjour Claire ! Clique ici https://rsms.us/bTD2",
                "submitted": "2014-12-16 13:02:00",
                "delivered": null,
                "stopped": null,
                "visits": 0,
                "datetimes": null,
                "preview": null,
                "user_agent": null,
                "npai": true,
                "columns": ["CLIENT9123", "Mark"]
            },
        ],
    }
}
Response on success with the filters
Paramètres
filters=msisdn&filters=message
Statut HTTP
200
Content-Type
application/json
Contenu
{
    "success": true,
    "summary": {
        "sms_submitted": 3,
        "sms_delivered": 2,
        "sms_stopped": 1,
        "clicks": 3,
        "unique_clicks": 2,
        "previews": 1,
        "npai": 1,
        "credits_used": 3,
    },
    "contacts": [
            {
                "msisdn": "33612345678",
                "message": "Bonjour Alice ! Clique ici https://rsms.us/bTD0"
            },
            {
                "msisdn": "33612345679",
                "message": "Bonjour Bob ! Clique ici https://rsms.us/bTD1"
            },
            {
                "msisdn": "33634567812",
                "message": "Bonjour Claire ! Clique ici https://rsms.us/bTD2"
            },
        ],
    }
}

All dates are in format yyyy-mm-dd HH:MM:SS.

summary
sms_submitted
Number of messages sent
sms_delivered
Number of delivered messages
sms_stopped
Number of stops
clicks
Total number of visits
unique_clicks
Number of unique visits
previews
Number of previews
napi
Total hard bounced
contacts
msisdn
Recipient phone number in format MSISDN
url
Web link for this recipient
message
Message content
submitted
Message sending date
delivered
Message delivery date
stop
Boolean indicating if the recipient response is STOP
visits
Rich visits number
datetimes
Visits dates list
preview
Boolean indicating if the preview was displayed in the message
user_agent
Web browser user agent
Response in case of not found campaign
HTTP status
400
Content-Type
application/json
Content
{
    "success": false,
    "errors": {
        "campaign_uuid": "La campagne n'existe pas ou n'est pas associée à ce compte."
    }
}

Get campaign events

This API allows to get an existing campaign events list within two dates.

Request
URL
https://api.us.campaign.sinch.com/v1/campaign/log
Method
GET
HTTP header
Authorization or token
Authentication token (see Authentication)
Settings
campaign_uuid
Campaign UUID
start
Date of the first event you want to get yyyy-mm-dd HH:MM:SS
stop
Date of the last event you want to get yyyy-mm-dd HH:MM:SS
columns
Adds the columns of the contact file to the response (Optional)
types
Optional filter on event type. For example: types=SUBMIT&types=DELIVER. See the type list. (Optional)
Example with Python
import requests
r = requests.get('https://api.us.campaign.sinch.com/v1/campaign/log', params={
    'campaign_uuid': '5a7b28fd-a216-4d31-90b3-0f62c2e4ee7f',
    'start': '2015-07-06 17:30:00',
    'stop': '2015-07-06 19:00:00'
}, headers={'Authorization': 'Bearer be3e1c6d-e6bc-46aa-8868-d9e24b051ed8'})
Answer on success
HTTP status
200
Content-Type
application/json
Content
{
    "success": true,
    "log": [
        {
            "datetime" : "2015-07-06 17:30:00",
            "contact": {"msisdn": "33612345678", "code": "0", "channel": "sms"},
            "type": "SUBMIT",
            "data": {"datetime" : "2015-07-06 17:29:54", "success": true, "message": "Bonjour Alice ! Clique ici https://rsms.us/bTD0", "nb_parts": 1}
        },
        {
            "datetime" : "2015-07-06 17:30:01",
            "contact": {"push_id": "clientid", "channel": "push"},
            "type": "SUBMIT",
            "data": {"datetime" : "2015-07-06 17:30:00", "success": true, "message": "Bonjour Alice !", "nb_parts": 1}
        },
        {
            "datetime" : "2015-07-06 17:30:02",
            "contact": {"msisdn": "33612345678", "code": "0", "channel": "sms"},
            "type": "DELIVER",
            "data": {"datetime" : "2015-07-06 17:30:01", "success": true, "code": "2", "reason": "Delivered", "nb_parts": 1}
        },
        {
            "datetime" : "2015-07-06 17:31:42",
            "contact": {"msisdn": "33612345678", "code": "0", "channel": "sms"},
            "type": "RESPONSE",
            "data": {"datetime" : "2015-07-06 17:31:40", "message": "STOP svp", "stop": true}
        },
        {
            "datetime" : "2015-07-06 17:31:00"
            "contact": {"msisdn": "33612345678", "code": "0", "channel": "sms"},
            "type": "VISIT",
            "data": {
                "datetime" : "2015-07-06 16:55:22",
                "user_agent": "Mozilla/5.0 (iPhone; CPU iPhone OS 5_0_1 like Mac OS X) AppleWebKit/534.46 (KHTML, like Gecko) Mobile/9A405",
                "device": {"family": "iPhone"},
                "os": {"family": "iOS", "version", "5.0.1"},
                "browser": {"family": "Mobile Safari", "version": "5.0.1"}
            }
        },
        {
            "datetime" : "2015-07-06 17:31:00"
            "contact": {"msisdn": "33612345678", "code": "0", "channel": "sms"},
            "type": "OG_PREVIEW",
            "data": {
                "datetime" : "2015-07-06 16:55:22",
                "user_agent": "Mozilla/5.0 (iPhone; CPU iPhone OS 5_0_1 like Mac OS X) AppleWebKit/534.46 (KHTML, like Gecko) Mobile/9A405",
            }
        },
        {
            "datetime": "2015-07-06 17:59:19",
            "contact": {"msisdn": "33612345678", "code": "0", "channel": "sms"},
            "type": "TRACKER",
            "data": {
                "datetime": "2015-07-06 17:58:32",
                "name": "button_662a",
                "value": "click"
            }
        },
        {
            "datetime": "2015-07-06 17:35:24",
            "contact": {"msisdn": "33612345678", "code": "0", "channel": "sms"},
            "type": "FORM",
            "data": {
                "datetime": "2015-07-06 17:31:28",
                "name": "newsletter_inscriptions",
                "form": {
                    "email": "customer@example.com"
                }
            }
        }
    ]
}
Response on success with the parameter start, stop and columns
Paramètres
start=2015-07-06%2017%3A29%3A40&stop=2015-07-06%2017%3A30%3A20&columns=1&columns=3
Statut HTTP
200
Content-Type
application/json
Contenu
{
    "success": true,
    "log":[
        {
            "datetime" : "2015-07-06 17:30:00",
            "contact": {"msisdn": "33612345678", "code": "0", "channel": "sms", "columns": ["CLIENT1234", "Alice"]},
            "type": "SUBMIT",
            "data": {"datetime" : "2015-07-06 17:29:54", "success": true, "message": "Bonjour Alice ! Clique ici https://rsms.us/bTD0", "nb_parts": 1}
        },
    ]
}
Response example in case of parameters errors
HTTP status
400
Content-Type
application/json
Content
{
    "success": false,
    "errors": {
        "campaign_uuid": ["Campaign '5a7b28fd-a216-4d31-90b3-0f62c2e4ee7f' not found."],
        "start": ["this field is required"]
        "stop": ["this field is required"]
    }
}

Each wrong parameter appears in errors object with a list of error messages.

Events types are the following:

SUBMIT
Message sending
DELIVER
message received by recipient
RESPONSE
response sent back by recipient
VISIT
recipient visited the webpage (he clicked the message or the link in it)
OG_PREVIEW
preview displayed in the message
TRACKER
tracked event in the html page (for example: click a button)
FORM
data sent by recipients in the html page forms

An event always have those four attributes:

datetime
Event record date in Sinch in format yyyy-mm-dd HH:MM:SS
contact
Recipient object. 'msisdn' is the phone number in format MSISDN. 'code' is a Sinch ID. You may add 'columns' attribute in request with parameter 'columns' to get more data about recipients.
type
Event type. Possible values are mentioned above.
data
Event data depending on type.

Event data description per type (content of field data):

SUBMIT
datetime
Message sending date in format yyyy-mm-dd HH:MM:SS
success
true if message was sent successfully, else false
message
Message text
nb_parts
Number of subparts of the message; in the case of a multiple sms, the number of simple sms sent. May be absent
DELIVER
datetime
Message sending date in format yyyy-mm-dd HH:MM:SS
success
true if the recipient received the message, else false
code
Obsolete, kept for compatibility
reason
Fail reason, may be missing
nb_parts
Number of subparts of the message; in the case of a multiple SMS, the number of simple SMSs received. May be absent
RESPONSE
datetime
Response time in format yyyy-mm-dd HH:MM:SS
message
Text of the message sent back by recipient
stop
true if "stop" is in the message, else false
VISIT
datetime
Visit time in format yyyy-mm-dd HH:MM:SS
user_agent
Recipient user agent
device
Recipient phone model according to user agent
os
Recipient phone OS according to user agent
browser
Web browser according to user agent
OG_PREVIEW
datetime
Preview time in format yyyy-mm-dd HH:MM:SS
user_agent
Messaging app user agent
TRACKER
datetime
Visit time in format yyyy-mm-dd HH:MM:SS
name
Name of the tracked action in the webpage
value
Event value (null if not used).
FORM
datetime
Form entry creation time in format yyyy-mm-dd HH:MM:SS
name
Form name
form
Object containing the fields of a form entry

Get data of a recipient

This API allows to get a campaign recipient data only for internal usage. The contact identifier is required. The response contains the contact field names provided in the campaign creation route. The SFTP Connectors can use the CSV header as field names. The recipient is available up to 6 months after sending the campaign.

Request
URL
https://api.us.campaign.sinch.com/v1/campaign/contacts/{contact_id}
Method
GET
HTTP header
Authorization or token
Authentication token (see Authentication)
Example with Curl
curl https://api.us.campaign.sinch.com/v1/campaign/contacts/018d55fe-dd08-4cb4-bece-e4efa5f0be01_0 \
  -H "Authorization: Bearer $ACCESS_TOKEN"
Answer on success
HTTP status
200
Content-Type
application/json
Content
{
    "success": true,
    "fields": [
        {"name": "phone", "value": "33612345678"},
        {"name": "firstname", "value": "Alice"}
    ]
}

Get campaign recipients

This API allows to get a campaign recipients list. Those recipients are available up to 6 months after sending the campaign.

Request
URL
https://api.us.campaign.sinch.com/v1/campaign/contacts
Method
GET
HTTP header
Authorization or token
Authentication token (see Authentication)
Settings
campaign_uuid
Campaign UUID
Example with Python
import requests
r = requests.get('https://api.us.campaign.sinch.com/v1/campaign/contacts', {
    'campaign_uuid': '5a7b28fd-a216-4d31-90b3-0f62c2e4ee7f',
}, headers={'Authorization': 'Bearer be3e1c6d-e6bc-46aa-8868-d9e24b051ed8'})
Answer on success
HTTP status
200
Content-Type
application/json
Content
{
    "success": true,
    "contacts": [
        ["0612345678", "Alice"],
        ["0612345679", "Bob"],
        ["0634567812", "Claire"]
    ]
}
Response example in case of parameters errors
HTTP status
400
Content-Type
application/json
Content
{
    "success": false,
    "errors": {
        "campaign_uuid": ["Campaign '5a7b28fd-a216-4d31-90b3-0f62c2e4ee7f' not found."],
    }
}

Each wrong parameter appears in errors object with a list of error messages.

Campaign Infos

Provides information on a campaign. This makes it possible to know the identifier of the campaign, the name of the issuer, the message sent, the date of sending, etc.

Request
URL
https://api.us.campaign.sinch.com/v1/campaigns/{id}
Method
GET
HTTP header
Authorization or token
Authentication token (see Authentication)
Example with Python
import requests
r = requests.get('https://api.us.campaign.sinch.com/v1/campaigns/5a7b28fd-a216-4d31-90b3-0f62c2e4ee7f', headers={'Authorization': 'Bearer be3e1c6d-e6bc-46aa-8868-d9e24b051ed8'})
Answer on success
HTTP status
200
Content-Type
application/json
Content
{
    "success": true,
    "campaign":
        {
            "status": "draft",
            "code": "HcE",
            "send_date": null,
            "name": "Modele pour API",
            "message": "Demo [[A]], voir [[URL]]",
            "contact_count": 4,
            "id": "c2d2f656-09f4-4e26-b9f3-92c14e15116d",
            "sender": "DemoEmett",
            "is_test": true,
            "tag": null,
            "connect_tag": null,
            "conversation": {
                "module": "module_name",
                "data": {}
            },
            "format": "rich",
            "validation_errors" : {
                "contacts": [],
                "message": ["Missing sender"],
                "app": ["App is empty"],
                "global": ["Not enough credits"]
            }
        },
}
id
Campaign ID (UUID)
code
3 letter short ID
name
Campaign's name
sender
Name of the sender
message
Message content
send_date
UTC send date of the campaign. The date id formatted as follows yyyy-mm-dd HH:MM:SS.
status
Status of the campaign. The status can be one of the following : draft, scheduled, sending or sent.
contact_count
Number of recipients
is_test
True if campaign is test, else false.
tag
Campaign tag
connect_tag
Connect base tag
conversation
Conversation module configuration information if it is activated: null / Object
conversation.module
Activated module public name
conversation.data
Conversation module configuration filled by Sinch team for a campaign
format
Campaign format. Can be simple or rich
validation_errors
List of all errors before campaign validation

Known Limitations

To prevent the API from being overwhelmed, we recommend our clients to make sequential requests on the different endpoints and to avoid making multiple calls on the same account at the same time.

For more information, please contact us: campaign_manager_api@sinch.com

© us.campaign.sinch.com