Introduction

Scroll down for code samples, example requests and responses. Select a language for code samples from the tabs above or the mobile navigation menu.

The TxtSync API allows you to programatically perform operations that the web client does.

TxtSync API is built using REST principles which ensures predictable URLs that makes writing applications easy. This API follows HTTP rules, enabling a wide range of HTTP clients can be used to interact with the API.

Every resource is exposed as a URL. The URL of each resource can be obtained by accessing the API Root Endpoint.

Getting Started

TxtSync APIs require two mandatory headers which are.

Authorization - Authentication request header.

x-api-key - The API key that grants access and a usage policy to the API.

API Key

if you are just starting out with TxtSync you can use 7yKeQ3Wecx1e671r88tq814FYEdPkYT89sdl9SRD as an API key. This a shared key which imposes shared throttling limits on to all using the key.

Authentication

Code samples

GET /contacts HTTP/1.1
Host: api.txtsync.com
Content-Type: application/json
Authorization: Basic QjBtVmJFVjBpTWZiSVYzWk9sUHQ6dzk3T0N0dnJ5eG90ancybnpzN29ldnlGMHUybEZEZWU2ZkFva3ZKbg==
x-api-key: 7yKeQ3Wecx1e671r88tq814FYEdPkYT89sdl9SRD

All TxtSync APIs need to be authenticated using Basic Authentication Token within the authorization header.

The token used within the Authorization is a base64 of a ClientKey:ClientSecret prefixed with the keywork "Basic"

You can obtain a Client Key and Secret pair by creating a client application within the TxtSync web UI.

HTTP Methods

TxtSync API uses appropriate HTTP verbs for every action.

Method	Description
GET	Used for retrieving resources.
POST	Used for creating resources and performing resource actions.
PUT	Used for updating resources.
DELETE	Used for deleting resources.

Requests

The base URL, also known as {root}, of all requests made to the TxtSync API is https://api.txtsync.com/

Responses

Responses will be in the JSON format with a status code of 200 if the API was successfully executed. The body of the response will contain the API resource response object.

Errors

TxtSync uses HTTP status codes to indicate success or failure of an API call. In general, status codes in the 2xx range means success, 4xx range means there was an error in the provided information, and those in the 5xx range indicates server side errors. Commonly used HTTP status codes are listed below.

Status Code	Description
2xx	Success.
4xx	Bad request sent to server.
5xx	Server side error.

Status Code	Action	Description
200	Success	The request was successfully completed.
400	Bad request	The request cannot be performed. Usually due to a validation error.
401	Unauthorized	Request was rejected because of invalid Authentication token.
403	Forbidden	The user does not have enough permission to access the resource.
404	Not Found	Unable to locate the requested resource.
429	Forbidden	Too many requests have been made against the API key.
500	Server Error	TxtSync server encountered an error which prevents it from fulfilling the request.
502	Bad Gateway	Occurs when the API Gateway encounters are error such as a timeout.

API Call Limit

API calls are limited on the shared API key to provide better quality of service and availability to all the users. The limits are illustrated below:

Rate: 50 requests per second

Burst: 200 requests

Quota: 100,000 requests per day

Query Engine

Typical REST APIs can be quite limiting in the way that data is retrieved from endpoints. In order to increase the flexibility of the API TxtSync has implemented its own query engine that allows you to pass in clauses to many of the GET requests. This engine allows you to control what data is returned to your integration. Generally the more sepcific your queries the quicker your return values will be.

On a typical get query that is not limited by a path parameter id you will be able to perform the following within the querystring.

Parameter	Type	Description
select	string	The select parameter allows you to specify the specific columns of an area you would like to retrieve. If you want to specify specific columns you must seperate each column name by a comma. For example FirstName,LastName,FullName. If you wish to retrieve all columns you can simply specify * or leave the querystring parameter as empty. Remember the less you ask for the quicker your result will be returned.
limit	number	the limit parameter allows you to specify the number of records that you would like being returned from the API. The API will return data in a paged format of up to 250 records as a time. If you enter a value greater than 250 your query will be defaulted to 250 results. Please see pagination below for details on handling paging
offset	numer	The offset parameter works hand in hand with limit by allowing you to specify where in your result set would you like to start returning results.
orderby	string	The order by allows you to specify the order of the data returned back from the API. You can specify multiple columns and the direction ascending (asc) and descending (desc). Each column and direction pair must be seperated by a comma. For example - LastName asc, CreatedDate desc.
recountcount	boolean	The recordcount parameter can be true or false. If true then your total record count for the query you are performing will be retruned in the headers as a param of 'Pagination-Records'. This is useful if you intend to do paging and display to the user how many records are available.
count	boolean	This value can be true or false and is used to determine whether you would just like to receive a record count for the query you are performing.
where	string	The where clause allows you to be specific with the data you wish to be returned. You can specify a combination of operators and sentinels to make up your query. Please see details below on whats available.

Where Clause

Code samples

GET /?select=MobileNumber,%20ContactID&where=FullName%20like%20%22%Cabaniuk%25%22&limit=1&recordcount=true HTTP/1.1
Host: api.txtsync.com
Content-Type: application/json
Authorization: Basic QjBtVmJFVjBpTWZiSVYzWk9sUHQ6dzk3T0N0dnJ5eG90ancybnpzN29ldnlGMHUybEZEZWU2ZkFva3ZKbg==
x-api-key: 7yKeQ3Wecx1e671r88tq814FYEdPkYT89sdl9SRD

Sentinels

Allow you to combine expressions

• or - allows you to 'or' expressions.
• and - allows you to 'expressions.

Operators

Allow you to create expression between a column and value

• = - The column value equals the value specified. EG FirstName = "Hulk"
• < - The column value is less than the value specified. EG Age < 21
• > - The column value is greater than the value specified. EG Age > 21
• <= - The column value is less than or equal to the value specified. EG Age <= 21
• >= - The column value is greater than or equal the value specified. EG Age >= 21
• != - The column value does not equal the value specified. EG FullName != "Doctor Strange"
• in - The column value is in a specified range which is determined by CSV values inside square brackets. EG ContactID in [1,2,3,4]
• notin - The column value is not in a specified range which is determined by CSV values inside square brackets. EG FirstName notin ["Tony","Thor","Steve","Vision"]
• like - The column value is like the specified value supplied. Wildcard values can be used with this operator. EG FirstName like "%vid%"

Brackets

Brackets () can be used to group expressions by a sentinel. EG FirstName = ("Peter" AND LastName = "Parker") or (FullName = "Clint Barton")

Types

When querying with the where clause string and date values must always be enclosed by double quotes ". Boolean and number values don't need to be enclosed by quotes. Dates in the API are sotred in UTC and need to be queried in the format of "DD-MM-YYYY HH:mm:ss"

Pagination

Response sample

HTTP/1.1 200 OK
Content-Type: application/json
Pagination-Offset: 0
Pagination-Limit: 1
Pagination-Records: 0
Pagination-HasMore: false

Paging information for GET requests are returned within the response headers. The following will be returned.

• Pagination-Limit - The current limit that has been specified.
• Pagination-Offset - The current offset that has been specified.
• Pagination-HasMore - Whether there are more records that can be retrieved.

If recountcount has been specified within the query you will also get

• Pagination-Records - This is the total amount of records available for the query being performed.

Campaigns

A campaign allows you to send out a bulk text messages in which the messages are trackable back to the campaign. When setting up a campaign you will be able to add campaign connections which are tags or contacts that the campaign will send messages out for. While the campaign is in draft you can keep adding additional campaign connections. When you are ready for the messages to be sent out the campaign can be activated. Once activated your text messages will start to be sent out in the bacground.

Once the campaign has been activated the campaign reporting will become available which offers statistics on the outcome of the campaign.

If you wish to send out a bulk SMS quickly then you can use the Bulk SMS API which will allow you to easily send out your messages while creating a campaign around your request in the background.

Add Campaign

Code samples

POST http://api.txtsync.com/campaigns HTTP/1.1
Host: api.txtsync.com
Content-Type: application/json
Authorization: Basic QjBtVmJFVjBpTWZiSVYzWk9sUHQ6dzk3T0N0dnJ5eG90ancybnpzN29ldnlGMHUybEZEZWU2ZkFva3ZKbg==
x-api-key: 7yKeQ3Wecx1e671r88tq814FYEdPkYT89sdl9SRD

Body parameter

{
  "Name": "My First Campaign"
}

Sample Response

{
  "Name": "My First Campaign",
  "CreatedDate": "2018-10-27T20:05:42.513Z",
  "ModifiedDate": "2018-10-27T20:05:42.513Z",
  "CustomerID": 1,
  "ModifiedBy": 1,
  "CreatedBy": 1,
  "ModifiedByApp": null,
  "CreatedByApp": null,
  "Status": 0,
  "CampaignID": 1
}

POST: {root}/campaigns

Create a new campaign

Body Parameters

Parameter	Type	Required	Description
Name	string	true	The name that is given to the campaign to identify it
NumberID	number	false	The number that the messages will be sent from
TextMessage	number	false	The message that is to be sent out

Responses

Status	Description	Schema
200	Success	Campaign
400	Validation Error	ErrorMessage

Get Campaign

Code samples

GET http://api.txtsync.com/campaigns/1 HTTP/1.1
Host: api.txtsync.com
Content-Type: application/json
Authorization: Basic QjBtVmJFVjBpTWZiSVYzWk9sUHQ6dzk3T0N0dnJ5eG90ancybnpzN29ldnlGMHUybEZEZWU2ZkFva3ZKbg==
x-api-key: 7yKeQ3Wecx1e671r88tq814FYEdPkYT89sdl9SRD

Sample Response

{
  "CampaignID": 1,
  "ProcessedContacts": 0,
  "TotalContacts": 0,
  "IsSharedNumber": false,
  "LastSentSMSDate": null,
  "ActivatedDate": null,
  "CostGBP": 0,
  "CostLocal": 0,
  "CurrencyCode": "GBP",
  "Name": "My First Campaign",
  "Type": 0,
  "NumberID": null,
  "CustomerNumber": null,
  "TextMessage": null,
  "Status": 0,
  "CreatedByApp": null,
  "CreatedByAppName": null,
  "CreatedBy": 1,
  "CreatedByName": "David Cabaniuk",
  "CreatedDate": "2018-10-27T20:05:43.000Z",
  "ModifiedByApp": null,
  "ModifiedByAppName": null,
  "ModifiedBy": 1,
  "ModifiedByName": "David Cabaniuk",
  "ModifiedDate": "2018-10-27T20:20:34.000Z"
}

GET: {root}/campaigns/{id}

Retrieves a single campaign record.

Path Parameters

Parameter	Type	Required	Description
id	number	true	Campaign identifier

Responses

Status	Description	Schema
200	Success	Campaign record

Get Campaigns

Code samples

GET http://api.txtsync.com/campaigns HTTP/1.1
Host: api.txtsync.com
Content-Type: application/json
Authorization: Basic QjBtVmJFVjBpTWZiSVYzWk9sUHQ6dzk3T0N0dnJ5eG90ancybnpzN29ldnlGMHUybEZEZWU2ZkFva3ZKbg==
x-api-key: 7yKeQ3Wecx1e671r88tq814FYEdPkYT89sdl9SRD

Querystring parameters

  "select": "*",
  "where": "CampaignID = 1",
  "limit": 1,
  "offset": 0,
  "orderby": "Name ASC",
  "recordcount": true,
  "count": false

Sample Response

[{
  "CampaignID": 1,
  "ProcessedContacts": 0,
  "TotalContacts": 0,
  "IsSharedNumber": false,
  "LastSentSMSDate": null,
  "ActivatedDate": null,
  "CostGBP": 0,
  "CostLocal": 0,
  "CurrencyCode": "GBP",
  "Name": "My First Campaign",
  "Type": 0,
  "NumberID": null,
  "CustomerNumber": null,
  "TextMessage": null,
  "Status": 0,
  "CreatedByApp": null,
  "CreatedByAppName": null,
  "CreatedBy": 1,
  "CreatedByName": "David Cabaniuk",
  "CreatedDate": "2018-10-27T20:05:43.000Z",
  "ModifiedByApp": null,
  "ModifiedByAppName": null,
  "ModifiedBy": 1,
  "ModifiedByName": "David Cabaniuk",
  "ModifiedDate": "2018-10-27T20:20:34.000Z"
}]

GET: {root}/campaigns

Retrieves a list of paginated campaigns

Querystring Parameters

Parameter	Type	Required	Description
select	string	false	CSV of columns for Campaign
where	string	false	A where clause to perform
limit	number	false	The number of records to retrieve. Maximum is 250 at a time
offset	number	false	The position to start the retrieval of records from
orderby	string	false	The Campaign columns to order on
recordcount	boolean	false	whether to return the overall record within the response headers
count	boolean	false	Whether to just return the record count

Responses

Status	Description	Schema
200	Success	Campaign[]

Update Campaign

Code samples

PUT http://api.txtsync.com/campaigns/1 HTTP/1.1
Host: api.txtsync.com
Content-Type: application/json
Authorization: Basic QjBtVmJFVjBpTWZiSVYzWk9sUHQ6dzk3T0N0dnJ5eG90ancybnpzN29ldnlGMHUybEZEZWU2ZkFva3ZKbg==
x-api-key: 7yKeQ3Wecx1e671r88tq814FYEdPkYT89sdl9SRD

Body parameters

{
  "TextMessage": "Hey all this is my first campaign"
}

Sample Response

{
  "CampaignID": 1,
  "ProcessedContacts": 0,
  "TotalContacts": 0,
  "IsSharedNumber": false,
  "LastSentSMSDate": null,
  "ActivatedDate": null,
  "CostGBP": 0,
  "CostLocal": 0,
  "CurrencyCode": "GBP",
  "Name": "My First Campaign",
  "Type": 0,
  "NumberID": null,
  "CustomerNumber": null,
  "TextMessage": "Hey all this is my first campaign",
  "Status": 0,
  "CreatedByApp": null,
  "CreatedByAppName": null,
  "CreatedBy": 1,
  "CreatedByName": "David Cabaniuk",
  "CreatedDate": "2018-10-27T20:05:43.000Z",
  "ModifiedByAppName": null,
  "ModifiedByName": "David Cabaniuk",
  "ModifiedDate": "2018-10-27T20:20:34.396Z",
  "ModifiedBy": 1,
  "ModifiedByApp": null
}

PUT: {root}/campaigns/{id}

Updates a single campaign record.

Path Parameters

Parameter	Type	Required	Description
id	number	true	Campaign identifier

Body Parameters

Parameter	Type	Required	Description
Name	string	false	The name that is given to the campaign to identify it
NumberID	number	false	The number that the messages will be sent from
TextMessage	number	false	The message that is to be sent out

Responses

Status	Description	Schema
200	Success	Campaign record
400	Validation Error	ErrorMessage

Delete Campaign

Code samples

DELETE http://api.txtsync.com/campaigns/1 HTTP/1.1
Host: api.txtsync.com
Content-Type: application/json
Authorization: Basic QjBtVmJFVjBpTWZiSVYzWk9sUHQ6dzk3T0N0dnJ5eG90ancybnpzN29ldnlGMHUybEZEZWU2ZkFva3ZKbg==
x-api-key: 7yKeQ3Wecx1e671r88tq814FYEdPkYT89sdl9SRD

Sample Response

true

DELETE: {root}/campaigns/{id}

Deletes a single campaign record. You can only delete a campaign that is in draft

Path Parameters

Parameter	Type	Required	Description
id	number	true	Campaign identifier

Responses

Status	Description	Schema
200	Success

Activate Campaign

Code samples

POST http://api.txtsync.com/campaigns/1/activate HTTP/1.1
Host: api.txtsync.com
Content-Type: application/json
Authorization: Basic QjBtVmJFVjBpTWZiSVYzWk9sUHQ6dzk3T0N0dnJ5eG90ancybnpzN29ldnlGMHUybEZEZWU2ZkFva3ZKbg==
x-api-key: 7yKeQ3Wecx1e671r88tq814FYEdPkYT89sdl9SRD

Body parameter

{}

Sample Response

true

POST: {root}/campaigns/{id}/activate

Activates a draft campaign and starts the process of sending out text messages

Responses

Status	Description	Schema
200	Success
400	Validation Error	ErrorMessage

Campaign Reporting

Code samples

GET http://api.txtsync.com/campaigns/1/report HTTP/1.1
Host: api.txtsync.com
Content-Type: application/json
Authorization: Basic QjBtVmJFVjBpTWZiSVYzWk9sUHQ6dzk3T0N0dnJ5eG90ancybnpzN29ldnlGMHUybEZEZWU2ZkFva3ZKbg==
x-api-key: 7yKeQ3Wecx1e671r88tq814FYEdPkYT89sdl9SRD

Sample Response

{
  "Links": [
    {
      "Name": "Some Link",
      "URL": "https://someurl/someimage.gif",
      "ImageURL": "https://someurl/someimage.gif",
      "OpenCount": 8
    }
  ],
  "Name": "Bulk SMS 1538492413375",
  "ActivatedDate": "2018-10-02T15:00:13.000Z",
  "LastSentSMSDate": "2018-10-02T15:00:20.000Z",
  "CampaignCost": 0.19347,
  "CurrencyCode": "GBP",
  "PendingCount": 0,
  "QueuedCount": 0,
  "SentCount": 0,
  "DeliveredCount": 3,
  "UndeliveredCount": 0,
  "FailedCount": 0,
  "FrozenCount": 0,
  "RecipientCount": 3
}

GET: {root}/campaigns/{id}/report

Retrieves the campaign report.

Path Parameters

Parameter	Type	Required	Description
id	number	true	Campaign identifier

Responses

Status	Description	Schema
200	Success	CampaignReport record

Campaign Connections

Campaign Connections are tags and contacts that can be assigned to a campaign before the campaign is acivated. When the campaign is activated it sends out text messages to all the camapgin connections

Add Campaign Connection

Code samples

POST http://api.txtsync.com/campaigns/1/connections HTTP/1.1
Host: api.txtsync.com
Content-Type: application/json
Authorization: Basic QjBtVmJFVjBpTWZiSVYzWk9sUHQ6dzk3T0N0dnJ5eG90ancybnpzN29ldnlGMHUybEZEZWU2ZkFva3ZKbg==
x-api-key: 7yKeQ3Wecx1e671r88tq814FYEdPkYT89sdl9SRD

Body parameter

{
  "ContactIDs": [],
  "TagIDs": [],
  "Numbers": ["+447711111111"]
}

Sample Response

[{
  "CampaignID": 1,
  "ToNumber": "+447711111111",
  "CampaignConnectionID": 148
}]

POST: {root}/campaign/1/connections

Create new campaign connections

Body Parameters

Parameter	Type	Required	Description
ContactIDs	number[]	false	The identifiers of the contacts to add
TagIDs	number[]	false	The identifiers of the tags to add
Numbers	string[]	false	The numbers to add

Responses

Status	Description	Schema
200	Success	Campaign Connection
400	Validation Error	ErrorMessage

Get Campaign Connection

Code samples

GET http://api.txtsync.com/campaigns/1/connections/148 HTTP/1.1
Host: api.txtsync.com
Content-Type: application/json
Authorization: Basic QjBtVmJFVjBpTWZiSVYzWk9sUHQ6dzk3T0N0dnJ5eG90ancybnpzN29ldnlGMHUybEZEZWU2ZkFva3ZKbg==
x-api-key: 7yKeQ3Wecx1e671r88tq814FYEdPkYT89sdl9SRD

Sample Response

{
  "CampaignID": 1,
  "ToNumber": "+447711111111",
  "ContactID": 1,
  "TagID": null,
  "ContactName": "David Cabaniuk",
  "TagName": null
}

GET: {root}/campaigns/{id}/connections/{connectionId}

Retrieves a single campaign connection record.

Path Parameters

Parameter	Type	Required	Description
id	number	true	Campaign identifier
iconnectionIdd	number	true	Campaign Connection identifier

Responses

Status	Description	Schema
200	Success	Campaign Connection record

Get Campaign Connections

Code samples

GET http://api.txtsync.com/campaigns/1/connections HTTP/1.1
Host: api.txtsync.com
Content-Type: application/json
Authorization: Basic QjBtVmJFVjBpTWZiSVYzWk9sUHQ6dzk3T0N0dnJ5eG90ancybnpzN29ldnlGMHUybEZEZWU2ZkFva3ZKbg==
x-api-key: 7yKeQ3Wecx1e671r88tq814FYEdPkYT89sdl9SRD

Querystring parameters

  "select": "*",
  "where": "",
  "limit": 50,
  "offset": 0,
  "orderby": "ContactName ASC",
  "recordcount": true,
  "count": false

Sample Response

[{
  "CampaignID": 1,
  "ToNumber": "+447711111111",
  "ContactID": 1,
  "TagID": null,
  "ContactName": "David Cabaniuk",
  "TagName": null
}]

GET: {root}/campaigns/{id}/connections

Retrieves a list of paginated campaign connections

Querystring Parameters

Parameter	Type	Required	Description
select	string	false	CSV of columns for Campaign Connection
where	string	false	A where clause to perform
limit	number	false	The number of records to retrieve. Maximum is 250 at a time
offset	number	false	The position to start the retrieval of records from
orderby	string	false	The Campaign Connection columns to order on
recordcount	boolean	false	whether to return the overall record within the response headers
count	boolean	false	Whether to just return the record count

Responses

Status	Description	Schema
200	Success	Campaign Connection[]

Delete Campaign Connection

Code samples

DELETE http://api.txtsync.com/campaigns/1/connections/148 HTTP/1.1
Host: api.txtsync.com
Content-Type: application/json
Authorization: Basic QjBtVmJFVjBpTWZiSVYzWk9sUHQ6dzk3T0N0dnJ5eG90ancybnpzN29ldnlGMHUybEZEZWU2ZkFva3ZKbg==
x-api-key: 7yKeQ3Wecx1e671r88tq814FYEdPkYT89sdl9SRD

Sample Response

true

DELETE: {root}/campaigns/{id}/connections/{connectionId}

Deletes a single campaign connection record if the campaign has not been activated

Path Parameters

Parameter	Type	Required	Description
id	number	true	Campaign identifier
connectionId	number	true	Campaign Connection identifier

Responses

Status	Description	Schema
200	Success

Campaign Recipients

Campaign Recipients are a collection of contacts who have all had a text message sent to them by the campaign.

Get Campaign Recipient

Code samples

GET http://api.txtsync.com/campaigns/1/recipients/21 HTTP/1.1
Host: api.txtsync.com
Content-Type: application/json
Authorization: Basic QjBtVmJFVjBpTWZiSVYzWk9sUHQ6dzk3T0N0dnJ5eG90ancybnpzN29ldnlGMHUybEZEZWU2ZkFva3ZKbg==
x-api-key: 7yKeQ3Wecx1e671r88tq814FYEdPkYT89sdl9SRD

Sample Response

{
  "CampaignRecipientID": 21,
  "SMSID": 201,
  "ContactID": 1,
  "CampaignID": 1,
  "FullName": "David Cabaniuk",
  "Status": 3,
  "FromNumber": "+447411111111",
  "ToNumber": "+447722222222",
  "OpenSummary": 0
}

GET: {root}/campaigns/{id}recipients/{recipientId}

Retrieves a single campaign recipient record.

Path Parameters

Parameter	Type	Required	Description
id	number	true	Campaign identifier
recipientId	number	true	Campaign Recipient identifier

Responses

Status	Description	Schema
200	Success	Campaign Recipient record

Get Campaign Recipients

Code samples

GET http://api.txtsync.com/campaigns/1/recipients HTTP/1.1
Host: api.txtsync.com
Content-Type: application/json
Authorization: Basic QjBtVmJFVjBpTWZiSVYzWk9sUHQ6dzk3T0N0dnJ5eG90ancybnpzN29ldnlGMHUybEZEZWU2ZkFva3ZKbg==
x-api-key: 7yKeQ3Wecx1e671r88tq814FYEdPkYT89sdl9SRD

Querystring parameters

  "select": "*",
  "where": "CampaignRecipientID = 21",
  "limit": 1,
  "offset": 0,
  "orderby": "Name ASC",
  "recordcount": true,
  "count": false

Sample Response

[{
  "CampaignRecipientID": 21,
  "SMSID": 201,
  "ContactID": 1,
  "CampaignID": 1,
  "FullName": "David Cabaniuk",
  "Status": 3,
  "FromNumber": "+447411111111",
  "ToNumber": "+447722222222",
  "OpenSummary": 0
}]

GET: {root}/campaigns/{id}/recipients

Retrieves a list of paginated campaigns recipients

Querystring Parameters

Parameter	Type	Required	Description
select	string	false	CSV of columns for Campaign Recipient
where	string	false	A where clause to perform
limit	number	false	The number of records to retrieve. Maximum is 250 at a time
offset	number	false	The position to start the retrieval of records from
orderby	string	false	The Campaign Recipient columns to order on
recordcount	boolean	false	whether to return the overall record within the response headers
count	boolean	false	Whether to just return the record count

Responses

Status	Description	Schema
200	Success	Campaign Recipient[]

Get Activity History

Code samples

GET http://api.txtsync.com/campaigns/1/recipients/1/activityhistory HTTP/1.1
Host: api.txtsync.com
Content-Type: application/json
Authorization: Basic QjBtVmJFVjBpTWZiSVYzWk9sUHQ6dzk3T0N0dnJ5eG90ancybnpzN29ldnlGMHUybEZEZWU2ZkFva3ZKbg==
x-api-key: 7yKeQ3Wecx1e671r88tq814FYEdPkYT89sdl9SRD

Querystring parameters

  "select": "*",
  "where": "",
  "limit": 50,
  "offset": 0,
  "orderby": "ActivityHistoryID DESC",
  "recordcount": true,
  "count": false

Sample Response

[{
  "ActivityHistoryID": 139,
  "LinkName": "Some link title",
  "LinkURL": "https://someurl.com",
  "LinkImageURL": "https://someurl.com/someimage.jpg",
  "CampaignRecipientID": 21,
  "ContactID": 3,
  "CreatedDate": "2018-10-02T11:03:46.000Z",
  "Type": 0,
  "CampaignID": 61,
  "LinkID": 8
}]

GET: {root}/campaigns/{id}/recipients/{recipientId}/activityhistory

Retrieves a list of paginated campaign recipient activity

Querystring Parameters

Parameter	Type	Required	Description
select	string	false	CSV of columns for Activity History
where	string	false	A where clause to perform
limit	number	false	The number of records to retrieve. Maximum is 250 at a time
offset	number	false	The position to start the retrieval of records from
orderby	string	false	The Activity History columns to order on
recordcount	boolean	false	whether to return the overall record within the response headers
count	boolean	false	Whether to just return the record count

Responses

Status	Description	Schema
200	Success	Activity History[]

Contacts

Contacts are fundamentally your address book and at the very least a contact must always have a mobile phone number. The more information captured around contact the better as it will allow for better personalisation when sending out text messages. Text message whether they are incoming or outgoing will always be associated to a contact.

Add Contact

Code samples

POST http://api.txtsync.com/contacts HTTP/1.1
Host: api.txtsync.com
Content-Type: application/json
Authorization: Basic QjBtVmJFVjBpTWZiSVYzWk9sUHQ6dzk3T0N0dnJ5eG90ancybnpzN29ldnlGMHUybEZEZWU2ZkFva3ZKbg==
x-api-key: 7yKeQ3Wecx1e671r88tq814FYEdPkYT89sdl9SRD

Body parameter

{
  "FirstName": "Lara",
  "LastName": "Croft",
  "MobileNumber": "+447711212132",
  "EmailAddress": "tomb.raider@hotmail.com",
  "CompanyName": "Croft Limited",
  "AllowSMS": "boolean",
  "ExternalReference": "string",
  "DateOfBirth": "1992-02-14",
  "AddressLine1": "Croft Manor, 142 Abbingdom Road",
  "AddressLine2": null,
  "City": "Guildford",
  "Postcode": null,
  "County": "Surrey",
  "Country": "United Kingdom",
  "CountryCode": "GB",
}

Sample Response

{
  "ContactID": 29,
  "FirstName": "Lara",
  "LastName": "Croft",
  "MobileNumber": "+447711212132",
  "EmailAddress": "tomb.raider@hotmail.com",
  "CompanyName": "Croft Limited",
  "AllowSMS": true,
  "ExternalReference": null,
  "DateOfBirth": "1992-02-14",
  "AddressLine1": "Croft Manor, 142 Abbingdom Road",
  "AddressLine2": null,
  "City": "Guildford",
  "Postcode": null,
  "County": "Surrey",
  "Country": "United Kingdom",
  "CountryCode": "GB",
  "CreatedDate": "2019-10-25T21:08:54.455Z",
  "ModifiedDate": "2019-10-25T21:08:54.455Z",
  "ModifiedByApp": null,
  "CreatedByApp": null,
  "ModifiedBy": 2,
  "CreatedBy": 2,
  "AllowSMS": true,
  "TotalInboundSMS": 0,
  "TotalOutboundSMS": 0,
  "TotalLinksSent": 0,
  "TotalDistinctLinkClicks": 0,
  "OverallRating": 0,
  "LatestSMSID": 2,
  "LatestInboundSMSID": 1,
  "LatestOutboundSMSID": 2,
  "HasTags": true,
  "LastCommunicationDate": "2018-10-25"
}

POST: {root}/contact

Create a new contact

Body Parameters

Parameter	Type	Required	Description
body	Contact	true	Contact object or an array of up to 25 Contact objects

Responses

Status	Description	Schema
200	Success	Contact
400	Validation Error	ErrorMessage

Get Contact

Code samples

GET http://api.txtsync.com/contacts/1 HTTP/1.1
Host: api.txtsync.com
Content-Type: application/json
Authorization: Basic QjBtVmJFVjBpTWZiSVYzWk9sUHQ6dzk3T0N0dnJ5eG90ancybnpzN29ldnlGMHUybEZEZWU2ZkFva3ZKbg==
x-api-key: 7yKeQ3Wecx1e671r88tq814FYEdPkYT89sdl9SRD

Sample Response

{
  "ContactID": 29,
  "FirstName": "Lara",
  "LastName": "Croft",
  "MobileNumber": "+447711212132",
  "EmailAddress": "tomb.raider@hotmail.com",
  "CompanyName": "Croft Limited",
  "AllowSMS": true,
  "ExternalReference": null,
  "DateOfBirth": "1992-02-14",
  "AddressLine1": "Croft Manor, 142 Abbingdom Road",
  "AddressLine2": null,
  "City": "Guildford",
  "Postcode": "string",
  "County": "Surrey",
  "Country": "United Kingdom",
  "CountryCode": "GB",
  "CreatedDate": "2019-10-25T21:08:54.455Z",
  "ModifiedDate": "2019-10-25T21:08:54.455Z",
  "ModifiedByApp": null,
  "CreatedByApp": null,
  "ModifiedBy": 2,
  "CreatedBy": 2,
  "AllowSMS": true,
  "TotalInboundSMS": 0,
  "TotalOutboundSMS": 0,
  "TotalLinksSent": 0,
  "TotalDistinctLinkClicks": 0,
  "OverallRating": 0,
  "LatestSMSID": 2,
  "LatestInboundSMSID": 1,
  "LatestOutboundSMSID": 2,
  "HasTags": true,
  "LastCommunicationDate": "2018-10-25"
}

GET: {root}/contacts/{id}

Retrieves a single contact record.

Path Parameters

Parameter	Type	Required	Description
id	number	true	Contact identifier

Responses

Status	Description	Schema
200	Success	Contact record

Update Contact

Code samples

PUT http://api.txtsync.com/contacts/29 HTTP/1.1
Host: api.txtsync.com
Content-Type: application/json
Authorization: Basic QjBtVmJFVjBpTWZiSVYzWk9sUHQ6dzk3T0N0dnJ5eG90ancybnpzN29ldnlGMHUybEZEZWU2ZkFva3ZKbg==
x-api-key: 7yKeQ3Wecx1e671r88tq814FYEdPkYT89sdl9SRD

Body parameters

{
  "FirstName": "Cloud",
  "LastName": "Strife",
  "CompanyName": "Shinra"
}

Sample Response

{
  "ContactID": 29,
  "FirstName": "Cloud",
  "LastName": "Strife",
  "MobileNumber": "+447711212132",
  "EmailAddress": "tomb.raider@hotmail.com",
  "CompanyName": "Shinra",
  "AllowSMS": true,
  "ExternalReference": null,
  "DateOfBirth": "1992-02-14",
  "AddressLine1": "Croft Manor, 142 Abbingdom Road",
  "AddressLine2": null,
  "City": "Guildford",
  "Postcode": "string",
  "County": "Surrey",
  "Country": "United Kingdom",
  "CountryCode": "GB",
  "CreatedDate": "2019-10-25T21:08:54.455Z",
  "ModifiedDate": "2019-10-25T21:08:54.455Z",
  "ModifiedByApp": null,
  "CreatedByApp": null,
  "ModifiedBy": 2,
  "CreatedBy": 2,
  "AllowSMS": true,
  "TotalInboundSMS": 0,
  "TotalOutboundSMS": 0,
  "TotalLinksSent": 0,
  "TotalDistinctLinkClicks": 0,
  "OverallRating": 0,
  "LatestSMSID": 2,
  "LatestInboundSMSID": 1,
  "LatestOutboundSMSID": 2,
  "HasTags": true,
  "LastCommunicationDate": "2018-10-25"
}

PUT: {root}/contacts/{id}

Updates a single contact record.

Path Parameters

Parameter	Type	Required	Description
id	number	true	Contacts identifier

Body Parameters

Parameter	Type	Required	Description
MobilePhone	string	false	The codes mobile phone number. This must be in E164 format otherwise your operating country code will be assumed
CountryCode	string	false	The ISO ALPHA-2 country code that the contact belongs to
AllowSMS	number	false	Whether the contact wishes to receive text messages or not
DateOfBirth	date	false	The contacts date of birth
CompanyName	string	false	The name of the company that the contact belongs to
Twitter	string	false	The URL to the contacts Twitter page
Facebook	string	false	The URL to the contacts Facebook page
LinkedIn	string	false	The URL to the contacts LinkedIn page
GooglePlus	string	false	The URL to the contacts GooglePlus page
Website	string	false	The URL to the contacts website
FirstName	string	false	The contacts Firstname
LastName	string	false	The contacts lastname
AddressLine1	string	false	Address field
AddressLine2	string	false	Address field
City	string	false	Address field
Postcode	string	false	Address field (zipcode)
County	string	false	Address field
Country	string	false	Address field
EmailAddress	string	false	Contacts email address

Responses

Status	Description	Schema
200	Success	Contact record
400	Validation Error	ErrorMessage

Delete Contact

Code samples

DELETE http://api.txtsync.com/contacts/1 HTTP/1.1
Host: api.txtsync.com
Content-Type: application/json
Authorization: Basic QjBtVmJFVjBpTWZiSVYzWk9sUHQ6dzk3T0N0dnJ5eG90ancybnpzN29ldnlGMHUybEZEZWU2ZkFva3ZKbg==
x-api-key: 7yKeQ3Wecx1e671r88tq814FYEdPkYT89sdl9SRD

Sample Response

true

DELETE: {root}/contact/{id}

Deletes a single contact record. Any history thats attached to the contact will be removed

Path Parameters

Parameter	Type	Required	Description
id	number	true	Contact identifier

Responses

Status	Description	Schema
200	Success

Bulk Get Contacts

Code samples

GET http://api.txtsync.com/contacts HTTP/1.1
Host: api.txtsync.com
Content-Type: application/json
Authorization: Basic QjBtVmJFVjBpTWZiSVYzWk9sUHQ6dzk3T0N0dnJ5eG90ancybnpzN29ldnlGMHUybEZEZWU2ZkFva3ZKbg==
x-api-key: 7yKeQ3Wecx1e671r88tq814FYEdPkYT89sdl9SRD

GET: {root}/contacts

Retrieves a list of paginated contacts. Can can also perform a search on the tags associated to the contact

Querystring parameters

  "select": "*",
  "where": "ContactID = 1",
  "limit": 1,
  "offset": 0,
  "orderby": "Name ASC",
  "recordcount": true,
  "count": false

Sample Response

[{
  "ContactID": 29,
  "FirstName": "Lara",
  "LastName": "Croft",
  "MobileNumber": "+447711212132",
  "EmailAddress": "tomb.raider@hotmail.com",
  "CompanyName": "Croft Limited",
  "AllowSMS": true,
  "ExternalReference": null,
  "DateOfBirth": "1992-02-14",
  "AddressLine1": "Croft Manor, 142 Abbingdom Road",
  "AddressLine2": null,
  "City": "Guildford",
  "Postcode": "string",
  "County": "Surrey",
  "Country": "United Kingdom",
  "CountryCode": "GB",
  "CreatedDate": "2019-10-25T21:08:54.455Z",
  "ModifiedDate": "2019-10-25T21:08:54.455Z",
  "ModifiedByApp": null,
  "CreatedByApp": null,
  "ModifiedBy": 2,
  "CreatedBy": 2,
  "AllowSMS": true,
  "TotalInboundSMS": 0,
  "TotalOutboundSMS": 0,
  "TotalLinksSent": 0,
  "TotalDistinctLinkClicks": 0,
  "TotalFailedSMS": 0,
  "OverallRating": 0,
  "LatestSMSID": 2,
  "LatestInboundSMSID": 1,
  "LatestOutboundSMSID": 2,
  "HasTags": true,
  "LastCommunicationDate": "2018-10-25"
}]

Querystring Parameters

Parameter	Type	Required	Description
select	string	false	CSV of columns for Contact
where	string	false	A where clause to perform
tagwhere	string	false	A where clause to perform against the tags that are linked to the contact
limit	number	false	The number of records to retrieve. Maximum is 250 at a time
offset	number	false	The position to start the retrieval of records from
orderby	string	false	The Contact columns to order on
recordcount	boolean	false	whether to return the overall record within the response headers
count	boolean	false	Whether to just return the record count

Responses

Status	Description	Schema
200	Success	Contact[]

Bulk Update Contacts

Code samples

PUT http://api.txtsync.com/contacts HTTP/1.1
Host: api.txtsync.com
Content-Type: application/json
Authorization: Basic QjBtVmJFVjBpTWZiSVYzWk9sUHQ6dzk3T0N0dnJ5eG90ancybnpzN29ldnlGMHUybEZEZWU2ZkFva3ZKbg==
x-api-key: 7yKeQ3Wecx1e671r88tq814FYEdPkYT89sdl9SRD

PUT: {root}/contacts

Updates contacts in bulk based on the where clause passed in the querystring

Body parameters

{
  "FirstName": "Tifa",
  "LastName": "Lockhart"
}

Querystring parameters

  "where": "FullName = \"2B\"",

Sample Response

true

Body Parameters

Parameter	Type	Required	Description
MobilePhone	string	false	The codes mobile phone number. This must be in E164 format otherwise your operating country code will be assumed
CountryCode	string	false	The ISO ALPHA-2 country code that the contact belongs to
AllowSMS	number	false	Whether the contact wishes to receive text messages or not
DateOfBirth	date	false	The contacts date of birth
CompanyName	string	false	The name of the company that the contact belongs to
Twitter	string	false	The URL to the contacts Twitter page
Facebook	string	false	The URL to the contacts Facebook page
LinkedIn	string	false	The URL to the contacts LinkedIn page
GooglePlus	string	false	The URL to the contacts GooglePlus page
Website	string	false	The URL to the contacts website
FirstName	string	false	The contacts Firstname
LastName	string	false	The contacts lastname
AddressLine1	string	false	Address field
AddressLine2	string	false	Address field
City	string	false	Address field
Postcode	string	false	Address field (zipcode)
County	string	false	Address field
Country	string	false	Address field
EmailAddress	string	false	Contacts email address

Querystring Parameters

Parameter	Type	Required	Description
where	string	false	A where clause to perform

Responses

Status	Description	Schema
200	Success

Bulk Delete Contacts

Code samples

DELETE http://api.txtsync.com/contacts HTTP/1.1
Host: api.txtsync.com
Content-Type: application/json
Authorization: Basic QjBtVmJFVjBpTWZiSVYzWk9sUHQ6dzk3T0N0dnJ5eG90ancybnpzN29ldnlGMHUybEZEZWU2ZkFva3ZKbg==
x-api-key: 7yKeQ3Wecx1e671r88tq814FYEdPkYT89sdl9SRD

DELETE: {root}/contacts

Deletes contacts in bulk based on the where clause passed in the querystring. The history of any contact that is deleted will also be deleted

Querystring parameters

  "where": "FullName = \"Nathan Drake\"",

Sample Response

true

Querystring Parameters

Parameter	Type	Required	Description
where	string	false	A where clause to perform

Responses

Status	Description	Schema
200	Success

Get Associated Tags

Code samples

GET http://api.txtsync.com/contacts/1/tags HTTP/1.1
Host: api.txtsync.com
Content-Type: application/json
Authorization: Basic QjBtVmJFVjBpTWZiSVYzWk9sUHQ6dzk3T0N0dnJ5eG90ancybnpzN29ldnlGMHUybEZEZWU2ZkFva3ZKbg==
x-api-key: 7yKeQ3Wecx1e671r88tq814FYEdPkYT89sdl9SRD

GET: {root}/contacts/{id}/tags

Retrieves a list of tags that are associated with the contact. The querystring parameters can be used to filter the results of the search.

Querystring parameters

  "select": "*",
  "where": "ContactID = 1",
  "limit": 1,
  "offset": 0,
  "orderby": "Name ASC",
  "recordcount": true,
  "count": false,
  "subscribed": true

Sample Response

[{
  "TagID": 1,
  "Name": "Food Offers",
  "CreatedBy": 1,
  "CreatedByName": "David Cabaniuk",
  "CreatedDate": "2018-10-25T22:33:49.000Z",
  "ModifiedBy": 1,
  "ModifiedByName": "David Cabaniuk",
  "ModifiedDate": "2018-10-25T22:33:49.000Z",
  "Subscribed": true
}]

Querystring Parameters

Parameter	Type	Required	Description
select	string	false	CSV of columns for Tag
where	string	false	A where clause to perform
limit	number	false	The number of records to retrieve. Maximum is 250 at a time
offset	number	false	The position to start the retrieval of records from
orderby	string	false	The Tag columns to order on
recordcount	boolean	false	whether to return the overall record within the response headers
count	boolean	false	Whether to just return the record count
subscribed	boolean	false	Whether to retrieve a list of tags that are subscribed to the contact or have unsubscribed. This parameter can be left blank for both

Responses

Status	Description	Schema
200	Success	Tag[]

Create Tag Contact Associations

Code samples

POST http://api.txtsync.com/Contacts/1/Tags HTTP/1.1
Host: api.txtsync.com
Content-Type: application/json
Authorization: Basic QjBtVmJFVjBpTWZiSVYzWk9sUHQ6dzk3T0N0dnJ5eG90ancybnpzN29ldnlGMHUybEZEZWU2ZkFva3ZKbg==
x-api-key: 7yKeQ3Wecx1e671r88tq814FYEdPkYT89sdl9SRD

POST: {root}/contacts/{id}/tags

Associates a list of tags to a contact.

Body parameters

{
  "TagIDs": [1,2,3]
}

Sample Response

true

Path Parameters

Parameter	Type	Required	Description
id	number	true	Contact identifier

Body Parameters

Parameter	Type	Required	Description
TagIDs	number[]	true	A list of tag identifiers that are to be associated to the contact

Responses

Status	Description	Schema
200	Success

Delete Tag Contact Associations

Code samples

DELETE http://api.txtsync.com/contacts/1/tags HTTP/1.1
Host: api.txtsync.com
Content-Type: application/json
Authorization: Basic QjBtVmJFVjBpTWZiSVYzWk9sUHQ6dzk3T0N0dnJ5eG90ancybnpzN29ldnlGMHUybEZEZWU2ZkFva3ZKbg==
x-api-key: 7yKeQ3Wecx1e671r88tq814FYEdPkYT89sdl9SRD

DELETE: {root}/contacts/{id}/tags

Dissociates a list of tags from a contact.

Body parameters

{
  "TagIDs": [1,2,3]
}

Sample Response

true

Path Parameters

Parameter	Type	Required	Description
id	number	true	Contact identifier

Body Parameters

Parameter	Type	Required	Description
TagIDs	number[]	true	A list of tag identifiers that are to be dissociates from the contact

Responses

Status	Description	Schema
200	Success

Contact Duplication Check

Code samples

GET http://api.txtsync.com/contacts/duplicates HTTP/1.1
Host: api.txtsync.com
Content-Type: application/json
Authorization: Basic QjBtVmJFVjBpTWZiSVYzWk9sUHQ6dzk3T0N0dnJ5eG90ancybnpzN29ldnlGMHUybEZEZWU2ZkFva3ZKbg==
x-api-key: 7yKeQ3Wecx1e671r88tq814FYEdPkYT89sdl9SRD

GET: {root}/contacts/duplicates

Retrieves a list of duplicated contacts against the associated mobile phone.

Sample Response

[{
  "MobileNumber": "+447711212132",
  "Contacts" : [{
    "ContactID": 29,
    "FirstName": "Lara",
    "LastName": "Croft",
    "MobileNumber": "+447711212132",
    "EmailAddress": "tomb.raider@hotmail.com",
    "CompanyName": "Croft Limited",
    "AllowSMS": true,
    "ExternalReference": null,
    "DateOfBirth": "1992-02-14",
    "AddressLine1": "Croft Manor, 142 Abbingdom Road",
    "AddressLine2": null,
    "City": "Guildford",
    "Postcode": "string",
    "County": "Surrey",
    "Country": "United Kingdom",
    "CountryCode": "GB",
    "CreatedDate": "2019-10-25T21:08:54.455Z",
    "ModifiedDate": "2019-10-25T21:08:54.455Z",
    "ModifiedByApp": null,
    "CreatedByApp": null,
    "ModifiedBy": 2,
    "CreatedBy": 2,
    "AllowSMS": true,
    "TotalInboundSMS": 0,
    "TotalOutboundSMS": 0,
    "TotalLinksSent": 0,
    "TotalDistinctLinkClicks": 0,
    "TotalFailedSMS": 0,
    "OverallRating": 0,
    "LatestSMSID": 2,
    "LatestInboundSMSID": 1,
    "LatestOutboundSMSID": 2,
    "HasTags": true,
    "LastCommunicationDate": "2018-10-25"
  },
  {
    "ContactID": 30,
    "FirstName": "Richard",
    "LastName": "Croft",
    "MobileNumber": "+447711212132",
    "EmailAddress": "original.tomb.raider@hotmail.com",
    "CompanyName": "Croft Limited",
    "AllowSMS": true,
    "ExternalReference": null,
    "DateOfBirth": "1992-02-14",
    "AddressLine1": "Croft Manor, 142 Abbingdom Road",
    "AddressLine2": null,
    "City": "Guildford",
    "Postcode": "string",
    "County": "Surrey",
    "Country": "United Kingdom",
    "CountryCode": "GB",
    "CreatedDate": "2019-10-25T21:08:54.455Z",
    "ModifiedDate": "2019-10-25T21:08:54.455Z",
    "ModifiedByApp": null,
    "CreatedByApp": null,
    "ModifiedBy": 2,
    "CreatedBy": 2,
    "AllowSMS": true,
    "TotalInboundSMS": 0,
    "TotalOutboundSMS": 0,
    "TotalLinksSent": 0,
    "TotalDistinctLinkClicks": 0,
    "TotalFailedSMS": 0,
    "OverallRating": 0,
    "LatestSMSID": 2,
    "LatestInboundSMSID": 1,
    "LatestOutboundSMSID": 2,
    "HasTags": true,
    "LastCommunicationDate": "2018-10-25"
  }]
}]

Responses

Status	Description	Schema
200	Success	ContactDuplicates[]

Links

TxtSync allows URLS and Media to be saved within a link library that can be used for applying links to a text message using the special tag {{#link:1}}. The purpose of the link library is represent a URLs or media items that can be made trackable for reporting purposes. When a link is placed into a text message the system will generate a trackable tiny url which will be placed into the text message.

Add Link

Code samples

POST http://api.txtsync.com/library/links HTTP/1.1
Host: api.txtsync.com
Content-Type: application/json
Authorization: Basic QjBtVmJFVjBpTWZiSVYzWk9sUHQ6dzk3T0N0dnJ5eG90ancybnpzN29ldnlGMHUybEZEZWU2ZkFva3ZKbg==
x-api-key: 7yKeQ3Wecx1e671r88tq814FYEdPkYT89sdl9SRD

Body parameter

{
  "Name": "A picture",
  "URL": "https://www.bbc.co.uk/sport/football/45730077",
}

Sample Response

{
  "Name": "A picture",
  "URL": "https://www.bbc.co.uk/sport/football/45730077",
  "ImageURL": "https://ichef.bbci.co.uk/onesport/cps/624/cpsprodpb/5B8E/production/_103683432_av.jpg",
  "CreatedDate": "2018-10-03T12:59:31.123Z",
  "ModifiedDate": "2018-10-03T12:59:31.123Z",
  "ModifiedBy": 1,
  "CreatedBy": 1,
  "Type": 0,
  "LinkLibraryID": 12
}

POST: {root}/library/links

Creates a link record

Body Parameters

Parameter	Type	Required	Description
Name	string	true	The name that is given to the link. This will be displayed to the contact when clicking through from a text message
URL	string	false	The URL that is to be turned into a link. (URL or MediaLibraryID must be specified)
MediaLibraryID	number	false	The media file that is to be turned into a link (URL or MediaLibraryID must be specified)

Responses

Status	Description	Schema
200	Success	Link
400	Validation Error	ErrorMessage

Get Links

Code samples

GET http://api.txtsync.com/library/links HTTP/1.1
Host: api.txtsync.com
Content-Type: application/json
Authorization: Basic QjBtVmJFVjBpTWZiSVYzWk9sUHQ6dzk3T0N0dnJ5eG90ancybnpzN29ldnlGMHUybEZEZWU2ZkFva3ZKbg==
x-api-key: 7yKeQ3Wecx1e671r88tq814FYEdPkYT89sdl9SRD

Querystring parameters

  "select": "*",
  "where": "LinkLibraryID = 1",
  "limit": 1,
  "offset": 0,
  "orderby": "Name ASC",
  "recordcount": true,
  "count": false

Sample Response

[{
  "LinkLibraryID": 1,
  "InUse": false,
  "ImageURL": "https://ichef.bbci.co.uk/onesport/cps/624/cpsprodpb/5B8E/production/_103683432_av.jpg",
  "MediaLibraryID": 27,
  "Name": "Oh dear oh dear",
  "URL": "https://www.bbc.co.uk/sport/football/45730077",
  "Type": 0,
  "CreatedByApp": null,
  "CreatedByAppName": null,
  "CreatedBy": 1,
  "CreatedByName": "David Cabaniuk",
  "CreatedDate": "2018-10-08T09:47:59.000Z",
  "ModifiedBy": 1,
  "ModifiedByApp": null,
  "ModifiedByAppName": null,
  "ModifiedByName": "David Cabaniuk",
  "ModifiedDate": "2018-10-08T09:47:59.000Z"
}]

GET: {root}/library/links

Retrieves a list of paginated links

Querystring Parameters

Parameter	Type	Required	Description
select	string	false	CSV of columns for Link
where	string	false	A where clause to perform
limit	number	false	The number of records to retrieve. Maximum is 250 at a time
offset	number	false	The position to start the retrieval of records from
orderby	string	false	The Link columns to order on
recordcount	boolean	false	whether to return the overall record within the response headers
count	boolean	false	Whether to just return the record count

Responses

Status	Description	Schema
200	Success	Link[]

Update Link

Code samples

PUT http://api.txtsync.com/library/links/1 HTTP/1.1
Host: api.txtsync.com
Content-Type: application/json
Authorization: Basic QjBtVmJFVjBpTWZiSVYzWk9sUHQ6dzk3T0N0dnJ5eG90ancybnpzN29ldnlGMHUybEZEZWU2ZkFva3ZKbg==
x-api-key: 7yKeQ3Wecx1e671r88tq814FYEdPkYT89sdl9SRD

Body parameters

{
  "Name": "Another name for the link"
}

Sample Response

{
  "LinkLibraryID": 1,
  "InUse": false,
  "ImageURL": "https://ichef.bbci.co.uk/onesport/cps/624/cpsprodpb/5B8E/production/_103683432_av.jpg",
  "MediaLibraryID": 27,
  "Name": "Another name for the link",
  "URL": "https://www.bbc.co.uk/sport/football/45730077",
  "Type": 0,
  "CreatedByApp": null,
  "CreatedByAppName": null,
  "CreatedBy": 1,
  "CreatedByName": "David Cabaniuk",
  "CreatedDate": "2018-10-08T09:47:59.000Z",
  "ModifiedBy": 1,
  "ModifiedByApp": null,
  "ModifiedByAppName": null,
  "ModifiedByName": "David Cabaniuk",
  "ModifiedDate": "2018-10-08T09:47:59.000Z"
}

PUT: {root}/library/links/{id}

Updates a link record.

Path Parameters

Parameter	Type	Required	Description
id	number	true	Link identifier

Body Parameters

Parameter	Type	Required	Description
Name	string	true	The name of the link that will be displayed to the contact receiving the message

Responses

Status	Description	Schema
200	Success	Link record
400	Validation Error	ErrorMessage

Delete Link

Code samples

DELETE http://api.txtsync.com/library/link/1 HTTP/1.1
Host: api.txtsync.com
Content-Type: application/json
Authorization: Basic QjBtVmJFVjBpTWZiSVYzWk9sUHQ6dzk3T0N0dnJ5eG90ancybnpzN29ldnlGMHUybEZEZWU2ZkFva3ZKbg==
x-api-key: 7yKeQ3Wecx1e671r88tq814FYEdPkYT89sdl9SRD

Sample Response

true

DELETE: {root}/library/links/{id}

Deletes a single link record if the link record has not been published to contacts via a text message.

Path Parameters

Parameter	Type	Required	Description
id	number	true	Link identifier

Responses

Status	Description	Schema
200	Success

Media

TxtSync allows media, such as images to be uploaded to TxtSync and made publicly available over the web. Media records once uploaded can be attached to a Link so that it may be included within a text message and tracked through the use of an automatically generated unique tiny URL. By uploading media you will start to build up a library of images that you can include in any text message.

The process of including media in a text message is first to make a request to upload the media file, using the returned data you can then upload your file. Taking the generated MediaLibraryID you can then create a Link record that references the MediaLibraryID. Once you finally have created the Link you will be able to include it into a SMS in the usual way with the tag {{#link:1}} where 1 is the LinkLibraryID.

When including media it is recommended that you place your link at the very start or very end of the text message. Latest software on modern smart phones will detect the link and automatically show a preview of the link (if settings permit).

Upload Media

Code samples

POST http://api.txtsync.com/library/media/upload HTTP/1.1
Host: api.txtsync.com
Content-Type: application/json
Authorization: Basic QjBtVmJFVjBpTWZiSVYzWk9sUHQ6dzk3T0N0dnJ5eG90ancybnpzN29ldnlGMHUybEZEZWU2ZkFva3ZKbg==
x-api-key: 7yKeQ3Wecx1e671r88tq814FYEdPkYT89sdl9SRD

Body parameter

{
  "Name": "This is a really interesting picture",
  "FileName": "test.png"
}

Sample Response

{
  "URL": "https://s3-eu-west-1.amazonaws.com/media.txtsync.com/",
  "Fields": {
    "x-amz-server-side-encryption": "AES256",
    "x-amz-meta-filetype": "image/png",
    "x-amz-meta-medialibraryid": "5",
    "key": "1/4HGcwAmZUcSYBNOHeG3Z/test.png",
    "bucket": "media.txtsync.com",
    "AWSAccessKeyId": "AKIAITCFAFVIYHP2HRZA",
    "acl": "public-read",
    "policy": "eyJleHBpcmF0aW9uIjoiMjAxOC0xMC0wM1QyMToyNzowNC4zNjZaIiwiY29uZGl0aW9ucyI6W3siYnVja2V0IjoiZGV2Lm1lZGlhLnR4dGNoaW1wLmNvbSJ9LFsic3RhcnRzLXdpdGgiLCIka2V5IiwiMS80SEdjd0FtWlVjU1lCTk9IZUczWi90ZXN0LnBuZyJdLHsiYWNsIjoicHVibGljLXJlYWQifSx7InN1Y2Nlc3NfYWN0aW9uX3N0YXR1cyI6IjIwMSJ9LFsic3RhcnRzLXdpdGgiLCIkQ29udGVudC1UeXBlIiwiaW1hZ2UvcG5nIl0sWyJzdGFydHMtd2l0aCIsIiRDb250ZW50LURpc3Bvc2l0aW9uIiwiYXR0YWNobWVudDsgZmlsZW5hbWU9XCJ0ZXN0LnBuZ1wiIl0sWyJzdGFydHMtd2l0aCIsIiRDYWNoZS1Db250cm9sIiwibm8tY2FjaGUiXSxbImNvbnRlbnQtbGVuZ3RoLXJhbmdlIiwwLDUwMDAwNDg1NzYwXSx7IngtYW16LXNlcnZlci1zaWRlLWVuY3J5cHRpb24iOiJBRVMyNTYifSx7IngtYW16LW1ldGEtZmlsZXR5cGUiOiJpbWFnZS9wbmcifSx7IngtYW16LW1ldGEtbWVkaWFsaWJyYXJ5aWQiOiI1In1dfQ==",
    "signature": "BWUjvlyhU4IaXTp05cBnkvJwPwk=",
    "Content-Type": "image/png",
    "Content-Disposition": "attachment; filename=\"test.png\"",
    "Cache-Control": "no-cache",
    "success_action_status": 201
  },
  "Policy": {
    "expiration": "2018-10-03T21:27:04.366Z",
    "conditions": [
      {
        "bucket": "media.txtsync.com"
      },
      [
        "starts-with",
        "$key",
        "1/4HGcwAmZUcSYBNOHeG3Z/test.png"
      ],
      {
        "acl": "public-read"
      },
      {
        "success_action_status": "201"
      },
      [
        "starts-with",
        "$Content-Type",
        "image/png"
      ],
      [
        "starts-with",
        "$Content-Disposition",
        "attachment; filename=\"test.png\""
      ],
      [
        "starts-with",
        "$Cache-Control",
        "no-cache"
      ],
      [
        "content-length-range",
        0,
        50000485760
      ],
      {
        "x-amz-server-side-encryption": "AES256"
      },
      {
        "x-amz-meta-filetype": "image/png"
      },
      {
        "x-amz-meta-medialibraryid": "5"
      }
    ]
  },
  "MediaLibrary": 5
}

POST: {root}/library/media/upload

Retrieves the policy required for uploading an image to TxtSync

Body Parameters

Parameter	Type	Required	Description
Name	string	true	The name given to the media file
FileName	string	true	The filename of the media file including the extension

Responses

Status	Description	Schema
200	Success
400	Validation Error	ErrorMessage

Uploading File JavaScript Sample

function sendFile(e) {
    e.preventDefault();

    // get the reference to the actual file in the input
    var theFormFile = $('#theFile').get()[0].files[0];

    $.ajax({
      type: 'PUT',
      url: "",
      // Content type must match with the parameter you signed your URL with
      contentType: 'binary/octet-stream',
      // this flag is important, if not set, it will try to send data as a form
      processData: false,
      // the actual file is sent raw
      data: theFormFile
    })
    .success(function() {
      alert('File uploaded');
    })
    .error(function() {
      alert('File NOT uploaded');
      console.log( arguments);
    });

    return false;
  });
}

Get Media

Code samples

GET http://api.txtsync.com/library/media HTTP/1.1
Host: api.txtsync.com
Content-Type: application/json
Authorization: Basic QjBtVmJFVjBpTWZiSVYzWk9sUHQ6dzk3T0N0dnJ5eG90ancybnpzN29ldnlGMHUybEZEZWU2ZkFva3ZKbg==
x-api-key: 7yKeQ3Wecx1e671r88tq814FYEdPkYT89sdl9SRD

Querystring parameters

  "select": "*",
  "where": "MediaLibraryID = 1",
  "limit": 1,
  "offset": 0,
  "orderby": "Name ASC",
  "recordcount": true,
  "count": false

Sample Response

[{
  "MediaLibraryID": 19,
  "FileName": "someimage.jpg",
  "Name": "Logan",
  "S3SizeBytes": 298542,
  "URL": "https://someurl.com/rchOdMsbZ40XK4L670mr/someimage.jpg",
  "ContentType": "image/jpeg",
  "CreatedByApp": null,
  "CreatedByAppName": null,
  "CreatedBy": 1,
  "CreatedByName": "David Cabaniuk",
  "CreatedDate": "2018-10-08T00:08:43.000Z",
  "ModifiedByAppName": null,
  "ModifiedByName": "David Cabaniuk",
  "ModifiedDate": "2018-10-27T15:11:25.571Z",
  "ModifiedBy": 1,
  "ModifiedByApp": null
}]

GET: {root}/library/media

Retrieves a list of paginated Media items

Querystring Parameters

Parameter	Type	Required	Description
select	string	false	CSV of columns for Media
where	string	false	A where clause to perform
limit	number	false	The number of records to retrieve. Maximum is 250 at a time
offset	number	false	The position to start the retrieval of records from
orderby	string	false	The Media columns to order on
recordcount	boolean	false	whether to return the overall record within the response headers
count	boolean	false	Whether to just return the record count

Responses

Status	Description	Schema
200	Success	Media[]

Update Media

Code samples

PUT http://api.txtsync.com/library/media/1 HTTP/1.1
Host: api.txtsync.com
Content-Type: application/json
Authorization: Basic QjBtVmJFVjBpTWZiSVYzWk9sUHQ6dzk3T0N0dnJ5eG90ancybnpzN29ldnlGMHUybEZEZWU2ZkFva3ZKbg==
x-api-key: 7yKeQ3Wecx1e671r88tq814FYEdPkYT89sdl9SRD

Body parameters

{
  "Name": "Some name for the media file"
}

Sample Response

{
  "MediaLibraryID": 19,
  "FileName": "someimage.jpg",
  "Name": "Logan",
  "S3SizeBytes": 298542,
  "URL": "https://someurl.com/rchOdMsbZ40XK4L670mr/someimage.jpg",
  "ContentType": "image/jpeg",
  "CreatedByApp": null,
  "CreatedByAppName": null,
  "CreatedBy": 1,
  "CreatedByName": "David Cabaniuk",
  "CreatedDate": "2018-10-08T00:08:43.000Z",
  "ModifiedByAppName": null,
  "ModifiedByName": "David Cabaniuk",
  "ModifiedDate": "2018-10-27T15:11:25.571Z",
  "ModifiedBy": 1,
  "ModifiedByApp": null
}

PUT: {root}/library/media/{id}

Updates a media file.

Path Parameters

Parameter	Type	Required	Description
id	number	true	Media identifier

Body Parameters

Parameter	Type	Required	Description
Name	string	false	The name given to the media file

Responses

Status	Description	Schema
200	Success	Media record
400	Validation Error	ErrorMessage

Delete Media

Code samples

DELETE http://api.txtsync.com/library/media/1 HTTP/1.1
Host: api.txtsync.com
Content-Type: application/json
Authorization: Basic QjBtVmJFVjBpTWZiSVYzWk9sUHQ6dzk3T0N0dnJ5eG90ancybnpzN29ldnlGMHUybEZEZWU2ZkFva3ZKbg==
x-api-key: 7yKeQ3Wecx1e671r88tq814FYEdPkYT89sdl9SRD

Sample Response

true

DELETE: {root}/library/media/{id}

Deletes a single media record if the media record is not linked to a link thats been published to contacts via a text message.

Path Parameters

Parameter	Type	Required	Description
id	number	true	Media identifier

Responses

Status	Description	Schema
200	Success

Numbers

A number represents an E164 number or Sender ID that is capable of sending text messages. In order to send a text message you must send from a valid number.

TxtSync allows access to a set of global shared numbers which can be used for free. The downside to these numbers are that inbound messages to the shared numbers are routed to the relevant customer system on best guess. If you require guarantee delivery of inbound messages or require a number to represent your business you should purchase a dedicated number from within the TxtSync web UI.

Sender IDs, which are upto 11 characters long can also be purchased from the web UI. A Sender ID would typically be a name that best represents your business name, for example TxtSync. The Sender ID will be displayed on the targets mobile device. It is not possible to route inbound messages back into the system for a Sender ID so they are best used for on way notices where your customers my not have your business number in their mobile devices contact list. Please note that not all countries, for example the US allow Sender IDs.

It is also possible to add your own mobile phone number as an available number within the system. This allows messages to be sent from, and appear to come from your mobile device. Inbound messages to your mobile number will still be delivered to your mobile device and not into the system. The TxtSync web UI can be used to add your mobile number as an available number within the system.

Get Number

Code samples

GET http://api.txtsync.com/numbers/1?select=* HTTP/1.1
Host: api.txtsync.com
Content-Type: application/json
Authorization: Basic QjBtVmJFVjBpTWZiSVYzWk9sUHQ6dzk3T0N0dnJ5eG90ancybnpzN29ldnlGMHUybEZEZWU2ZkFva3ZKbg==
x-api-key: 7yKeQ3Wecx1e671r88tq814FYEdPkYT89sdl9SRD

Sample Response

{
  "NumberID": 25,
  "CostGBP": 5,
  "CostLocal": 5,
  "CurrencyCode": "GBP",
  "IsDedicatedNumber": true,
  "IsSenderID": false,
  "IsExpiring": false,
  "IsShared": false,
  "IsPersonal": false,
  "Name": "Main Marketing Number",
  "Number": "+447480046418",
  "CountryCode": "GB",
  "IsAutoReply": false,
  "AutoReplyMessage": null,
  "IncomingCallMessageURL": null
}

GET: {root}/numbers/{id}

Retrieves a single dedicated number or sender id record.

Path Parameters

Parameter	Type	Required	Description
id	number	true	Number identifier

Querystring Parameters

Parameter	Type	Required	Description
select	string	false	Comma seperated list of fields to select or the use of * for all fields

Responses

Status	Description	Schema
200	Success	Contact record

Update Number

Code samples

PUT http://api.txtsync.com/numbers/1 HTTP/1.1
Host: api.txtsync.com
Content-Type: application/json
Authorization: Basic QjBtVmJFVjBpTWZiSVYzWk9sUHQ6dzk3T0N0dnJ5eG90ancybnpzN29ldnlGMHUybEZEZWU2ZkFva3ZKbg==
x-api-key: 7yKeQ3Wecx1e671r88tq814FYEdPkYT89sdl9SRD

PUT: {root}/numbers/{id}

Updates a single number record.

Body parameters

{
  "Name": "My Number",
  "IsAutoReply": false,
  "AutoReplyMessage": ""
}

Sample Response

{
  "NumberID": 1,
  "CostGBP": 5,
  "CostLocal": 5,
  "CurrencyCode": "GBP",
  "IsDedicatedNumber": true,
  "IsSenderID": false,
  "IsExpiring": false,
  "IsShared": false,
  "IsPersonal": false,
  "Name": "My Number",
  "Number": "+447480046418",
  "CountryCode": "GB",
  "IsAutoReply": false,
  "AutoReplyMessage": null,
  "IncomingCallMessageURL": null
}

Path Parameters

Parameter	Type	Required	Description
id	number	true	Number identifier

Body Parameters

Parameter	Type	Required	Description
Name	string	false	The name that is given to the number to identify it within the web UI
IsAutoReply	boolean	false	Whether the system will send out an automatic reply message on receiving an inbound call
AutoReplyMessage	string	false	The automatic reply message that will go out if IsAutoReply is true

Responses

Status	Description	Schema
200	Success	Number record
400	Validation Error	ErrorMessage

Bulk Get Numbers

Code samples

GET http://api.txtsync.com/numbers HTTP/1.1
Host: api.txtsync.com
Content-Type: application/json
Authorization: Basic QjBtVmJFVjBpTWZiSVYzWk9sUHQ6dzk3T0N0dnJ5eG90ancybnpzN29ldnlGMHUybEZEZWU2ZkFva3ZKbg==
x-api-key: 7yKeQ3Wecx1e671r88tq814FYEdPkYT89sdl9SRD

GET: {root}/numbers

Retrieves a list of paginated dedicated numbers, sender ids or personal mobile numbers

Querystring parameters

  "select": "*",
  "where": "NumberID = 1",
  "limit": 1,
  "offset": 0,
  "orderby": "Name ASC",
  "recordcount": true,
  "count": false

Sample Response

[{
  "NumberID": 1,
  "CostGBP": 5,
  "CostLocal": 5,
  "CurrencyCode": "GBP",
  "IsDedicatedNumber": true,
  "IsSenderID": false,
  "IsExpiring": false,
  "IsShared": false,
  "IsPersonal": false,
  "Name": "Main Marketing Number",
  "Number": "+447480046418",
  "CountryCode": "GB",
  "IsAutoReply": false,
  "AutoReplyMessage": null,
  "IncomingCallMessageURL": null
}]

Querystring Parameters

Parameter	Type	Required	Description
select	string	false	CSV of columns for Number
where	string	false	A where clause to perform
limit	number	false	The number of records to retrieve. Maximum is 250 at a time
offset	number	false	The position to start the retrieval of records from
orderby	string	false	The Number columns to order on
recordcount	boolean	false	whether to return the overall record within the response headers
count	boolean	false	Whether to just return the record count

Responses

Status	Description	Schema
200	Success	Number[]

Get Shared Number

Code samples

GET http://api.txtsync.com/numbers/shared/1?select=* HTTP/1.1
Host: api.txtsync.com
Content-Type: application/json
Authorization: Basic QjBtVmJFVjBpTWZiSVYzWk9sUHQ6dzk3T0N0dnJ5eG90ancybnpzN29ldnlGMHUybEZEZWU2ZkFva3ZKbg==
x-api-key: 7yKeQ3Wecx1e671r88tq814FYEdPkYT89sdl9SRD

Sample Response

[{
  "NumberID": 1,
  "CostGBP": 5,
  "CostLocal": 5,
  "CurrencyCode": "GBP",
  "IsDedicatedNumber": false,
  "IsSenderID": false,
  "IsExpiring": false,
  "IsShared": true,
  "IsPersonal": false,
  "Name": "Shared UK Number",
  "Number": "+447482878694",
  "CountryCode": "GB",
  "IsAutoReply": false,
  "AutoReplyMessage": null,
  "IncomingCallMessageURL": null
}]

GET: {root}/numbers/shared/{id}

Retrieves a single global shared number record.

Path Parameters

Parameter	Type	Required	Description
id	number	true	Shared Number identifier

Querystring Parameters

Parameter	Type	Required	Description
select	string	false	Comma seperated list of fields to select or the use of * for all fields

Responses

Status	Description	Schema
200	Success	Number record

Bulk Get Shared Numbers

Code samples

GET http://api.txtsync.com/numbers/shared HTTP/1.1
Host: api.txtsync.com
Content-Type: application/json
Authorization: Basic QjBtVmJFVjBpTWZiSVYzWk9sUHQ6dzk3T0N0dnJ5eG90ancybnpzN29ldnlGMHUybEZEZWU2ZkFva3ZKbg==
x-api-key: 7yKeQ3Wecx1e671r88tq814FYEdPkYT89sdl9SRD

Sample Response

[{
  "NumberID": 1,
  "CostGBP": 5,
  "CostLocal": 5,
  "CurrencyCode": "GBP",
  "IsDedicatedNumber": false,
  "IsSenderID": false,
  "IsExpiring": false,
  "IsShared": true,
  "IsPersonal": false,
  "Name": "Shared UK Number",
  "Number": "+447482878694",
  "CountryCode": "GB",
  "IsAutoReply": false,
  "AutoReplyMessage": null,
  "IncomingCallMessageURL": null
}]

GET: {root}/numbers/shared

Retrieves a list of paginated global shared numbers

Querystring parameters

  "select": "*",
  "where": "NumberID = 1",
  "limit": 1,
  "offset": 0,
  "orderby": "Name ASC",
  "recordcount": true,
  "count": false

Querystring Parameters

Parameter	Type	Required	Description
select	string	false	CSV of columns for Number
where	string	false	A where clause to perform
limit	number	false	The number of records to retrieve. Maximum is 250 at a time
offset	number	false	The position to start the retrieval of records from
orderby	string	false	The Number columns to order on
recordcount	boolean	false	whether to return the overall record within the response headers
count	boolean	false	Whether to just return the record count

Responses

Status	Description	Schema
200	Success	Number[]

Add Voice Message

Code samples

POST http://api.txtsync.com/numbers/1/voicemessage HTTP/1.1
Host: api.txtsync.com
Content-Type: application/json
Authorization: Basic QjBtVmJFVjBpTWZiSVYzWk9sUHQ6dzk3T0N0dnJ5eG90ancybnpzN29ldnlGMHUybEZEZWU2ZkFva3ZKbg==
x-api-key: 7yKeQ3Wecx1e671r88tq814FYEdPkYT89sdl9SRD

POST: {root}/numbers/{id}/voicemessage

Takes the message and converts it to a spoken audio file which the target number will play if dialled

Body parameter

{
  "Message": "Sorry but this number is used only for text messaging",
  "VoiceID": "Raveena"
}

Sample Response

true

Body Parameters

Parameter	Type	Required	Description
Message	string	true	The message that is to be converted into audio speech
VoiceID	string	true	The identifier of the speaker to use

Responses

Status	Description	Schema
200	Success
400	Validation Error	ErrorMessage

Delete Voice Message

Code samples

DELETE http://api.txtsync.com/numbers/1/voicemessage HTTP/1.1
Host: api.txtsync.com
Content-Type: application/json
Authorization: Basic QjBtVmJFVjBpTWZiSVYzWk9sUHQ6dzk3T0N0dnJ5eG90ancybnpzN29ldnlGMHUybEZEZWU2ZkFva3ZKbg==
x-api-key: 7yKeQ3Wecx1e671r88tq814FYEdPkYT89sdl9SRD

Sample Response

true

DELETE: {root}/numbers/{id}/voicemessage

Removes the audio voice message that is configured against the number

Path Parameters

Parameter	Type	Required	Description
id	number	true	Number identifier

Responses

Status	Description	Schema
200	Success

Get Voice Message Speakers

Code samples

GET http://api.txtsync.com/numbers/voicemessages HTTP/1.1
Host: api.txtsync.com
Content-Type: application/json
Authorization: Basic QjBtVmJFVjBpTWZiSVYzWk9sUHQ6dzk3T0N0dnJ5eG90ancybnpzN29ldnlGMHUybEZEZWU2ZkFva3ZKbg==
x-api-key: 7yKeQ3Wecx1e671r88tq814FYEdPkYT89sdl9SRD

Sample Response

[{
  "Gender": "Female",
  "Id": "Amy",
  "LanguageCode": "en-GB",
  "LanguageName": "British English",
  "Name": "Amy",
}]

GET: {root}/numbers/voicemessages

Retrieves a list of the available speakers that can be used in turning a voice message into audio speech.

Responses

Status	Description	Schema
200	Success	Speaker[]

Reports

Reports aid in providing statistics on the system usage.

System Report

Code samples

GET http://api.txtsync.com/system/report HTTP/1.1
Host: api.txtsync.com
Content-Type: application/json
Authorization: Basic QjBtVmJFVjBpTWZiSVYzWk9sUHQ6dzk3T0N0dnJ5eG90ancybnpzN29ldnlGMHUybEZEZWU2ZkFva3ZKbg==
x-api-key: 7yKeQ3Wecx1e671r88tq814FYEdPkYT89sdl9SRD

Sample Response

{
  "TotalInboundMessages": 31,
  "TotalOutboundMessages": 20,
  "TotalFrozenOutboundMessages": 51,
  "TotalMessages": 9,
  "TotalCampaigns": 1,
}

GET: {root}/system/report

Retrieves overall statistics for text message usage.

Responses

Status	Description	Schema
200	Success	ReportSystem record

SMSes

A SMS record represent a text message that has been sent from, or received by the system. It is possible to send SMS individually like you would do if you are typically having a conversation or it is possible to send text messages out in bulk.

Send Single SMS

POST: {root}/sms/send

Sends out a text message from the system to a destination number or contact. When sending out a text message you account balance will be checked and charged at the rate assigned to your destination numbers country of origin.

It is posible to include mergeable data in the message body by specifying a Contact field to merge on within {{}} tags. For example Hi {{FirstName}} would replace FirstName with the contacts actual first name

You can include links directly and the system will replace these links with trackable tiny urls which will allow the system to report back on open and click through rates. Alternatively you can include links from the Link Library using the following tag {{#link:1}} where 1 is the ID of the link you want to include in your SMS as a trackable tiny url

When sending a message and no From number is specified the system will automatically try and select a relevant number to send from. The system will try and find an available number on account or global share number thats in the same country as the target contacts number.

Code samples

POST http://api.txtsync.com/sms/send HTTP/1.1
Host: api.txtsync.com
Content-Type: application/json
Authorization: Basic QjBtVmJFVjBpTWZiSVYzWk9sUHQ6dzk3T0N0dnJ5eG90ancybnpzN29ldnlGMHUybEZEZWU2ZkFva3ZKbg==
x-api-key: 7yKeQ3Wecx1e671r88tq814FYEdPkYT89sdl9SRD

Body parameter

{
  "From": "+447411111111",
  "To": "+447722222222",
  "Message": "Hi {{FirstName}}, check out www.bbc.co.uk its an awesome site"
}

Sample Response

[{
  "FromNumber": "+447411111111",
  "ToNumber": "+447722222222",
  "ContactID": 1,
  "UserID": 1,
  "Direction": 0,
  "Message": "Hi {{FirstName}}, check out www.bbc.co.uk its an awesome site",
  "Status": 0,
  "IsAutoReply": false,
  "LinkDetails": "[]",
  "CreatedDate": "2018-10-26T10:59:50.301Z",
  "SMSID": 1
}]

Body Parameters

Parameter	Type	Required	Description
From	string	false	The number the text message is to be sent from
To	string	false	The destination number of the text message (To or ToContactID must be populated)
ToContactID	string	false	The contact to send the text message to (To or ToContactID must be populated)
Message	string	true	The message to send

Responses

Status	Description	Schema
200	Success	SMS
400	Validation Error	ErrorMessage

Send Bulk SMS

POST: {root}/sms/bulk

Sends out bulk text message from the system to a collection of destination numbers or contacts. When sending out a text message you account balance will be checked and charged at the rate assigned to your destination numbers country of origin.

It is posible to include mergeable data in the message body by specifying a Contact field to merge on within {{}} tags. For example Hi {{FirstName}} would replace FirstName with the contacts actual first name

You can include links directly and the system will replace these links with trackable tiny urls which will allow the system to report back on open and click through rates. Alternatively you can include links from the Link Library using the following tag {{#link:1}} where 1 is the ID of the link you want to include in your SMS as a trackable tiny url

When sending a bulk sms the system will setup a campaign behind the scenes. This campaign record exists for historical purchases of the bulk send but it can also be interrogated for statistics on the bulk message that went out

Code samples

POST http://api.txtsync.com/sms/bulk HTTP/1.1
Host: api.txtsync.com
Content-Type: application/json
Authorization: Basic QjBtVmJFVjBpTWZiSVYzWk9sUHQ6dzk3T0N0dnJ5eG90ancybnpzN29ldnlGMHUybEZEZWU2ZkFva3ZKbg==
x-api-key: 7yKeQ3Wecx1e671r88tq814FYEdPkYT89sdl9SRD

Body parameter

{
  "From": "+447411111111",
  "ToTagID": [1],
  "Message": "Morning {{FirstName}} - Happy Bulk Txt Message Day!"
}

Sample Response

{
  "CustomerNumber": "+447411111111",
  "Name": "Bulk SMS 1538313166559",
  "TextMessage": "Morning {{FirstName}} - Happy Bulk Txt Message Day!",
  "Type": 0,
  "NumberID": 25,
  "Status": 1,
  "CreatedDate": "2018-09-30T13:12:46.559Z",
  "ModifiedDate": "2018-09-30T13:12:46.559Z",
  "ModifiedBy": 1,
  "CreatedBy": 1,
  "CampaignID": 22
}

Body Parameters

Parameter	Type	Required	Description
From	string	true	The number the text message is to be sent from
To	string[]	false	A list of destination numbers to send the text message to
ToContactID	number[]	false	A list of contacts to send the text message to
ToTagID	number[]	false	A list of Tags to send the text message to
Message	string	true	The message to send

Responses

Status	Description	Schema
200	Success	SMS
400	Validation Error	ErrorMessage

Preview SMS

POST: {root}/sms/preview

Allows for text messages to be previewed and the associated costs to be estimated before sending out the messages

Code samples

POST http://api.txtsync.com/sms/preview HTTP/1.1
Host: api.txtsync.com
Content-Type: application/json
Authorization: Basic QjBtVmJFVjBpTWZiSVYzWk9sUHQ6dzk3T0N0dnJ5eG90ancybnpzN29ldnlGMHUybEZEZWU2ZkFva3ZKbg==
x-api-key: 7yKeQ3Wecx1e671r88tq814FYEdPkYT89sdl9SRD

Body parameter

{
  "To": "+447711111111",
  "Message": "Hi Sarah, hows the zerg doing today?",
  "Index": 0
}

Sample Response

{
  "Contact": {
    "ContactID": 1,
    "LatestSMSID": 718,
    "LatestInboundSMSID": 713,
    "LatestOutboundSMSID": 718,
    "OverallRating": 20.25,
    "TotalDistinctLinkClicks": 1,
    "TotalLinksSent": 27,
    "TotalInboundSMS": 39,
    "TotalOutboundSMS": 106,
    "CountryCode": null,
    "AllowSMS": true,
    "DateOfBirth": null,
    "CompanyName": "Zerg",
    "FirstName": "Sarah",
    "LastName": "Kerrigan",
    "FullName": "Sarah Kerrigan",
    "LastCommunicationDate": "2018-10-26T10:59:52.000Z",
    "CreatedBy": 1,
    "CreatedDate": "2018-09-25T17:06:25.000Z",
    "ModifiedBy": 1,
    "ModifiedDate": "2018-10-26T10:59:52.000Z",
    "CreatedByApp": null,
    "ModifiedByApp": null,
    "AddressLine1": null,
    "AddressLine2": null,
    "City": null,
    "Postcode": null,
    "County": null,
    "Country": null,
    "MobileNumber": "+447711111111",
    "EmailAddress": null
  },
  "Message": "Hi Sarah, hows the zerg doing today?",
  "FoundContact": true,
  "BalanceGBP": 64.7105,
  "BalanceLocal": 64.7105,
  "CurrencyCode": "GBP",
  "AllowSMS": true,
  "TotalSendableContacts": 1,
  "ContainsEmojis": false,
  "ApproxSegmentsPerSms": 1,
  "ApproxCostGBP": 0.04,
  "ApproxCostLocal": 0.04,
  "LinkDetails": []
}

Body Parameters

Parameter	Type	Required	Description
To	string[]	false	The destination number of the text message
ToContactID	number[]	false	The contact to send the text message to
ToTagID	number[]	false	The tags to send the text message to
Message	string	true	The message to send
Index	number	true	The position to return data back from.

Responses

Status	Description	Schema
200	Success	SMS
400	Validation Error	ErrorMessage

Bulk Get SMS

Code samples

GET http://api.txtsync.com/sms/ HTTP/1.1
Host: api.txtsync.com
Content-Type: application/json
Authorization: Basic QjBtVmJFVjBpTWZiSVYzWk9sUHQ6dzk3T0N0dnJ5eG90ancybnpzN29ldnlGMHUybEZEZWU2ZkFva3ZKbg==
x-api-key: 7yKeQ3Wecx1e671r88tq814FYEdPkYT89sdl9SRD

Querystring parameters

  "select": "*",
  "where": "SMSID = 1",
  "limit": 1,
  "offset": 0,
  "orderby": "SMSID ASC",
  "recordcount": true,
  "count": false

Sample Response

[{
  "SMSID": 71,
  "LinkDetails": null,
  "ProfileURL": null,
  "FlaggedDate": "2018-10-27T17:26:25.000Z",
  "CampaignID": null,
  "IsFlagged": true,
  "FlaggedDescription": "This is an important message",
  "UserName": null,
  "ContactName": "David Cabaniuk",
  "CreatedDate": "2018-10-27T20:58:46.000Z",
  "FromNumber": "+447411111111",
  "ToNumber": "+447422222222",
  "Message": "I just wanted to say hello",
  "Direction": 0,
  "CostGBP": 0.04,
  "CostLocal": 0.04,
  "CurrencyCode": "GBP",
  "Segments": 1,
  "DeliveredDate": "2018-10-27T17:26:25.000Z",
  "ErrorCode": null,
  "Status": 3,
  "ContactID": 1,
  "UserID": 1,
}]

GET: {root}/sms

Retrieves a list of paginated sms records

Querystring Parameters

Parameter	Type	Required	Description
select	string	false	CSV of columns for SMS
where	string	false	A where clause to perform
limit	number	false	The number of records to retrieve. Maximum is 250 at a time
offset	number	false	The position to start the retrieval of records from
orderby	string	false	The SMS columns to order on
recordcount	boolean	false	whether to return the overall record within the response headers
count	boolean	false	Whether to just return the record count

Responses

Status	Description	Schema
200	Success	SMS[]

Get Latest SMS

Code samples

GET http://api.txtsync.com/sms/latest HTTP/1.1
Host: api.txtsync.com
Content-Type: application/json
Authorization: Basic QjBtVmJFVjBpTWZiSVYzWk9sUHQ6dzk3T0N0dnJ5eG90ancybnpzN29ldnlGMHUybEZEZWU2ZkFva3ZKbg==
x-api-key: 7yKeQ3Wecx1e671r88tq814FYEdPkYT89sdl9SRD

Querystring parameters

  "select": "*",
  "direction": 0,
  "limit": 10,
  "offset": 0,

Sample Response

[{
  "SMSID": 71,
  "LinkDetails": null,
  "ProfileURL": null,
  "FlaggedDate": "2018-10-27T17:26:25.000Z",
  "CampaignID": null,
  "IsFlagged": true,
  "FlaggedDescription": "This is an important message",
  "UserName": null,
  "ContactName": "David Cabaniuk",
  "CreatedDate": "2018-10-27T20:58:46.000Z",
  "FromNumber": "+447411111111",
  "ToNumber": "+447422222222",
  "Message": "I just wanted to say hello",
  "Direction": 0,
  "CostGBP": 0.04,
  "CostLocal": 0.04,
  "CurrencyCode": "GBP",
  "Segments": 1,
  "DeliveredDate": "2018-10-27T17:26:25.000Z",
  "ErrorCode": null,
  "Status": 3,
  "ContactID": 1,
  "UserID": 1,
}]

GET: {root}/sms/latest

Retrieves a list of paginated latest sms records

Querystring Parameters

Parameter	Type	Required	Description
select	string	false	CSV of columns for SMS
limit	number	false	The number of records to retrieve. Maximum is 250 at a time
offset	number	false	The position to start the retrieval of records from
recordcount	boolean	false	whether to return the overall record within the response headers
count	boolean	false	Whether to just return the record count
direction	boolean	false	Not specifying a direction gets the latest text messages regardless of direction. Speifying a direction (0 = outbound, 1 = inbound) wgets the latest text messages in that direction

Responses

Status	Description	Schema
200	Success	SMS[]

Flag SMS

Code samples

PUT http://api.txtsync.com/sms/1/flag HTTP/1.1
Host: api.txtsync.com
Content-Type: application/json
Authorization: Basic QjBtVmJFVjBpTWZiSVYzWk9sUHQ6dzk3T0N0dnJ5eG90ancybnpzN29ldnlGMHUybEZEZWU2ZkFva3ZKbg==
x-api-key: 7yKeQ3Wecx1e671r88tq814FYEdPkYT89sdl9SRD

Body parameters

{
  "FlaggedDescription": "Contains important information about the contacts case with us"
}

Sample Response

true

PUT: {root}/sms/{id}/flag

Flags a text message as being important and allows a description to be saved against the text.

Path Parameters

Parameter	Type	Required	Description
id	number	true	SMS identifier

Body Parameters

Parameter	Type	Required	Description
FlaggedDescription	string	true	A description to be given for the flagging of the text message

Responses

Status	Description	Schema
200	Success	true
400	Validation Error	ErrorMessage

Unflag SMS

Code samples

DELETE http://api.txtsync.com/sms/1/unflag HTTP/1.1
Host: api.txtsync.com
Content-Type: application/json
Authorization: Basic QjBtVmJFVjBpTWZiSVYzWk9sUHQ6dzk3T0N0dnJ5eG90ancybnpzN29ldnlGMHUybEZEZWU2ZkFva3ZKbg==
x-api-key: 7yKeQ3Wecx1e671r88tq814FYEdPkYT89sdl9SRD

Body parameters

{
}

Sample Response

true

PUT: {root}/sms/{id}/unflag

Removes a flag that has been placed against the text mesage.

Path Parameters

Parameter	Type	Required	Description
id	number	true	SMS identifier

Responses

Status	Description	Schema
200	Success	true
400	Validation Error	ErrorMessage

SMS Templates

An SMS Template allows a message body of a text message to be saved so that it can be reused at a later date in other outbound text messages. Within the SMS Template it is possible to save text, emojis, links and media.

Add SMS Template

Code samples

POST http://api.txtsync.com/sms/templates HTTP/1.1
Host: api.txtsync.com
Content-Type: application/json
Authorization: Basic QjBtVmJFVjBpTWZiSVYzWk9sUHQ6dzk3T0N0dnJ5eG90ancybnpzN29ldnlGMHUybEZEZWU2ZkFva3ZKbg==
x-api-key: 7yKeQ3Wecx1e671r88tq814FYEdPkYT89sdl9SRD

Body parameter

{
  "Name": "My First Template",
  "Template": "This is a message to say hi"
}

Sample Response

{
  "SMSTemplateID": 1,
  "Name": "My First Template",
  "Template": "This is a message to say hi",
  "CreatedDate": "2018-10-14T10:40:19.232Z",
  "ModifiedDate": "2018-10-14T10:40:19.232Z",
  "ModifiedByApp": 2,
  "CreatedByApp": 2,
  "ModifiedBy": null,
  "CreatedBy": null,
}

POST: {root}/sms/templates

Create a new SMS Template

Body Parameters

Parameter	Type	Required	Description
Name	string	true	The name given to the template. This must be unique and less than 50 characters
Template	string	true	The body of the message within the template

Responses

Status	Description	Schema
200	Success	SMSTemplate
400	Validation Error	ErrorMessage

Get SMS Template

Code samples

GET http://api.txtsync.com/sms/templates/1 HTTP/1.1
Host: api.txtsync.com
Content-Type: application/json
Authorization: Basic QjBtVmJFVjBpTWZiSVYzWk9sUHQ6dzk3T0N0dnJ5eG90ancybnpzN29ldnlGMHUybEZEZWU2ZkFva3ZKbg==
x-api-key: 7yKeQ3Wecx1e671r88tq814FYEdPkYT89sdl9SRD

Sample Response

{
  "SMSTemplateID": 1,
  "Name": "My First Template",
  "Template": "This is a message to say hi",
  "CreatedDate": "2018-10-14T10:40:19.232Z",
  "ModifiedDate": "2018-10-14T10:40:19.232Z",
  "ModifiedByApp": 2,
  "CreatedByApp": 2,
  "ModifiedBy": null,
  "CreatedBy": null,
}

GET: {root}/sms/templates/{id}

Retrieves a single SMS Template record.

Path Parameters

Parameter	Type	Required	Description
id	number	true	SMS Template identifier

Responses

Status	Description	Schema
200	Success	SMS Template record

Update SMS Template

Code samples

PUT http://api.txtsync.com/sms/templates/1 HTTP/1.1
Host: api.txtsync.com
Content-Type: application/json
Authorization: Basic QjBtVmJFVjBpTWZiSVYzWk9sUHQ6dzk3T0N0dnJ5eG90ancybnpzN29ldnlGMHUybEZEZWU2ZkFva3ZKbg==
x-api-key: 7yKeQ3Wecx1e671r88tq814FYEdPkYT89sdl9SRD

Body parameters

{
  "Name": "My Second SMS Template"
}

Sample Response

{
  "SMSTemplateID": 1,
  "Name": "My Second SMS Template",
  "Template": "This is a message to say hi",
  "CreatedDate": "2018-10-14T10:40:19.232Z",
  "ModifiedDate": "2018-10-14T10:40:19.232Z",
  "ModifiedByApp": 2,
  "CreatedByApp": 2,
  "ModifiedBy": null,
  "CreatedBy": null,
}

PUT: {root}/sms/templates/{id}

Updates a single sms template record.

Path Parameters

Parameter	Type	Required	Description
id	number	true	SMS Template identifier

Body Parameters

Parameter	Type	Required	Description
Name	string	false	The name given to the template. This must be unique and less than 50 characters
Template	string	false	The body of the message within the template

Responses

Status	Description	Schema
200	Success	SMS Template record
400	Validation Error	ErrorMessage

Delete SMS Template

Code samples

DELETE http://api.txtsync.com/sms/templates/1 HTTP/1.1
Host: api.txtsync.com
Content-Type: application/json
Authorization: Basic QjBtVmJFVjBpTWZiSVYzWk9sUHQ6dzk3T0N0dnJ5eG90ancybnpzN29ldnlGMHUybEZEZWU2ZkFva3ZKbg==
x-api-key: 7yKeQ3Wecx1e671r88tq814FYEdPkYT89sdl9SRD

Sample Response

true

DELETE: {root}/sms/templates/{id}

Deletes a single SMS Template record.

Path Parameters

Parameter	Type	Required	Description
id	number	true	SMS Template identifier

Responses

Status	Description	Schema
200	Success

Bulk Get SMS Templates

Code samples

GET http://api.txtsync.com/sms/templates HTTP/1.1
Host: api.txtsync.com
Content-Type: application/json
Authorization: Basic QjBtVmJFVjBpTWZiSVYzWk9sUHQ6dzk3T0N0dnJ5eG90ancybnpzN29ldnlGMHUybEZEZWU2ZkFva3ZKbg==
x-api-key: 7yKeQ3Wecx1e671r88tq814FYEdPkYT89sdl9SRD

Querystring parameters

  "select": "*",
  "where": "SMSTemplateID = 1",
  "limit": 1,
  "offset": 0,
  "orderby": "Name ASC",
  "recordcount": true,
  "count": false

Sample Response

[{
  "SMSTemplateID": 1,
  "Name": "My Second SMS Template",
  "Template": "This is a message to say hi",
  "CreatedDate": "2018-10-14T10:40:19.232Z",
  "ModifiedDate": "2018-10-14T10:40:19.232Z",
  "ModifiedByApp": 2,
  "CreatedByApp": 2,
  "ModifiedBy": null,
  "CreatedBy": null,
}]

GET: {root}/sms/templates

Retrieves a list of paginated SMS Templates

Querystring Parameters

Parameter	Type	Required	Description
select	string	false	CSV of columns for SMS Template
where	string	false	A where clause to perform
limit	number	false	The number of records to retrieve. Maximum is 250 at a time
offset	number	false	The position to start the retrieval of records from
orderby	string	false	The SMS Template columns to order on
recordcount	boolean	false	whether to return the overall record within the response headers
count	boolean	false	Whether to just return the record count

Responses

Status	Description	Schema
200	Success	SMS Template[]

Tags

Tags are used to group contacts so that outbound bulk text messages can be more specific. For example You could create a tag called 'Offers' and assign all contacts to it that are interested in receiving text messages about offers. Adding a contact to the tag subscribes their interest. At any point the contact can unsubscribe from the tag by texting in "stop ".

Add Tag

Code samples

POST http://api.txtsync.com/tags HTTP/1.1
Host: api.txtsync.com
Content-Type: application/json
Authorization: Basic QjBtVmJFVjBpTWZiSVYzWk9sUHQ6dzk3T0N0dnJ5eG90ancybnpzN29ldnlGMHUybEZEZWU2ZkFva3ZKbg==
x-api-key: 7yKeQ3Wecx1e671r88tq814FYEdPkYT89sdl9SRD

Body parameter

{
  "Name": "Sample Tag"
}

Sample Response

{
  "Name": "Sample Tag",
  "CreatedDate": "2018-10-14T10:40:19.232Z",
  "ModifiedDate": "2018-10-14T10:40:19.232Z",
  "ModifiedByApp": 2,
  "CreatedByApp": 2,
  "ModifiedBy": null,
  "CreatedBy": null,
  "Type": 0,
  "TagID": 1
}

POST: {root}/tags

Create a new unique tag

Body Parameters

Parameter	Type	Required	Description
Name	string	true	The name given to the tag. This must be unique and less than 50 characters
ContactIDs	number[]	false	A list of contact ids that will be subscribed to the tag

Responses

Status	Description	Schema
200	Success	Tag
400	Validation Error	ErrorMessage

Get Tag

Code samples

GET http://api.txtsync.com/tags/1 HTTP/1.1
Host: api.txtsync.com
Content-Type: application/json
Authorization: Basic QjBtVmJFVjBpTWZiSVYzWk9sUHQ6dzk3T0N0dnJ5eG90ancybnpzN29ldnlGMHUybEZEZWU2ZkFva3ZKbg==
x-api-key: 7yKeQ3Wecx1e671r88tq814FYEdPkYT89sdl9SRD

Sample Response

{
  "Name": "Sample Tag",
  "CreatedDate": "2018-10-14T10:40:19.232Z",
  "ModifiedDate": "2018-10-14T10:40:19.232Z",
  "ModifiedByApp": 2,
  "CreatedByApp": 2,
  "ModifiedBy": null,
  "CreatedBy": null,
  "Type": 0,
  "TagID": 1
}

GET: {root}/tags/{id}

Retrieves a single tag record.

Path Parameters

Parameter	Type	Required	Description
id	number	true	Tag identifier

Responses

Status	Description	Schema
200	Success	Tag record

Update Tag

Code samples

PUT http://api.txtsync.com/tags/1 HTTP/1.1
Host: api.txtsync.com
Content-Type: application/json
Authorization: Basic QjBtVmJFVjBpTWZiSVYzWk9sUHQ6dzk3T0N0dnJ5eG90ancybnpzN29ldnlGMHUybEZEZWU2ZkFva3ZKbg==
x-api-key: 7yKeQ3Wecx1e671r88tq814FYEdPkYT89sdl9SRD

Body parameters

{
  "Name": "Freelancer"
}

Sample Response

{
  "Name": "Freelancer",
  "CreatedDate": "2018-10-14T10:40:19.232Z",
  "ModifiedDate": "2018-10-14T10:40:19.232Z",
  "ModifiedByApp": 2,
  "CreatedByApp": 2,
  "ModifiedBy": null,
  "CreatedBy": null,
  "Type": 0,
  "TagID": 1
}

PUT: {root}/tags/{id}

Updates a single tag record.

Path Parameters

Parameter	Type	Required	Description
id	number	true	Tag identifier

Body Parameters

Parameter	Type	Required	Description
Name	string	true	A unique name given to the tag

Responses

Status	Description	Schema
200	Success	Tag record
400	Validation Error	ErrorMessage

Delete Tag

Code samples

DELETE http://api.txtsync.com/tags/1 HTTP/1.1
Host: api.txtsync.com
Content-Type: application/json
Authorization: Basic QjBtVmJFVjBpTWZiSVYzWk9sUHQ6dzk3T0N0dnJ5eG90ancybnpzN29ldnlGMHUybEZEZWU2ZkFva3ZKbg==
x-api-key: 7yKeQ3Wecx1e671r88tq814FYEdPkYT89sdl9SRD

Sample Response

true

DELETE: {root}/tags/{id}

Deletes a single tag record. Any contact associated to the tag will loose its association to the tag once deleted

Path Parameters

Parameter	Type	Required	Description
id	number	true	Tag identifier

Responses

Status	Description	Schema
200	Success

Bulk Get Tags

Code samples

GET http://api.txtsync.com/tags HTTP/1.1
Host: api.txtsync.com
Content-Type: application/json
Authorization: Basic QjBtVmJFVjBpTWZiSVYzWk9sUHQ6dzk3T0N0dnJ5eG90ancybnpzN29ldnlGMHUybEZEZWU2ZkFva3ZKbg==
x-api-key: 7yKeQ3Wecx1e671r88tq814FYEdPkYT89sdl9SRD

Querystring parameters

  "select": "*",
  "where": "TagID = 1",
  "limit": 1,
  "offset": 0,
  "orderby": "Name ASC",
  "recordcount": true,
  "count": false

Sample Response

[{
  "Name": "Freelancer",
  "CreatedDate": "2018-10-14T10:40:19.232Z",
  "ModifiedDate": "2018-10-14T10:40:19.232Z",
  "ModifiedByApp": 2,
  "CreatedByApp": 2,
  "ModifiedBy": null,
  "CreatedBy": null,
  "Type": 0,
  "TagID": 1
}]

GET: {root}/tags

Retrieves a list of paginated tags

Querystring Parameters

Parameter	Type	Required	Description
select	string	false	CSV of columns for Tag
where	string	false	A where clause to perform
limit	number	false	The number of records to retrieve. Maximum is 250 at a time
offset	number	false	The position to start the retrieval of records from
orderby	string	false	The Tag columns to order on
recordcount	boolean	false	whether to return the overall record within the response headers
count	boolean	false	Whether to just return the record count

Responses

Status	Description	Schema
200	Success	Tag[]

Bulk Delete Tags

Code samples

DELETE http://api.txtsync.com/tags HTTP/1.1
Host: api.txtsync.com
Content-Type: application/json
Authorization: Basic QjBtVmJFVjBpTWZiSVYzWk9sUHQ6dzk3T0N0dnJ5eG90ancybnpzN29ldnlGMHUybEZEZWU2ZkFva3ZKbg==
x-api-key: 7yKeQ3Wecx1e671r88tq814FYEdPkYT89sdl9SRD

DELETE: {root}/tags

Deletes tags in bulk based on the where clause passed in the querystring. Any contact associated to the tag will loose its association to the tag once deleted

Querystring parameters

  "where": "TagID = 1",

Sample Response

true

Querystring Parameters

Parameter	Type	Required	Description
where	string	false	A where clause to perform

Responses

Status	Description	Schema
200	Success

Get Associated Contacts

Code samples

GET http://api.txtsync.com/tags/1/contacts HTTP/1.1
Host: api.txtsync.com
Content-Type: application/json
Authorization: Basic QjBtVmJFVjBpTWZiSVYzWk9sUHQ6dzk3T0N0dnJ5eG90ancybnpzN29ldnlGMHUybEZEZWU2ZkFva3ZKbg==
x-api-key: 7yKeQ3Wecx1e671r88tq814FYEdPkYT89sdl9SRD

GET: {root}/tags/{id}/contacts

Retrieves a list of contacts that are associated with the tag. The querystring parameters can be used to filter the results of the search.

Querystring parameters

  "select": "*",
  "where": "TagID = 1",
  "limit": 1,
  "offset": 0,
  "orderby": "Name ASC",
  "recordcount": true,
  "count": false,
  "subscribed": true

Sample Response

[{
  "ContactID": 2,
  "CountryCode": null,
  "AllowSMS": 1,
  "ExternalReference": null,
  "DateOfBirth": null,
  "CompanyName": null,
  "FirstName": "Ellie",
  "LastName": "Williams",
  "FullName": "Ellie Williams",
  "LastCommunicationDate": null,
  "CreatedBy": null,
  "CreatedByName": null,
  "CreatedDate": null,
  "ModifiedBy": null,
  "ModifiedByName": null,
  "ModifiedDate": null,
  "AddressLine1": null,
  "AddressLine2": null,
  "City": null,
  "Postcode": null,
  "County": null,
  "Country": null,
  "MobileNumber": "+447411111111",
  "EmailAddress": null,
  "Subscribed": 1
}}

Querystring Parameters

Parameter	Type	Required	Description
select	string	false	CSV of columns for Contact
where	string	false	A where clause to perform
limit	number	false	The number of records to retrieve. Maximum is 250 at a time
offset	number	false	The position to start the retrieval of records from
orderby	string	false	The Contact columns to order on
recordcount	boolean	false	whether to return the overall record within the response headers
count	boolean	false	Whether to just return the record count
subscribed	boolean	false	Whether to retrieve a list of contacts that are subscribed to the tag or have unsubscribed. This parameter can be left blank for both

Responses

Status	Description	Schema
200	Success	Contact[]

Create Contact Tag Associations

Code samples

POST http://api.txtsync.com/tags/1/contacts HTTP/1.1
Host: api.txtsync.com
Content-Type: application/json
Authorization: Basic QjBtVmJFVjBpTWZiSVYzWk9sUHQ6dzk3T0N0dnJ5eG90ancybnpzN29ldnlGMHUybEZEZWU2ZkFva3ZKbg==
x-api-key: 7yKeQ3Wecx1e671r88tq814FYEdPkYT89sdl9SRD

POST: {root}/tags/{id}/contacts

Associates a list of contacts to a tag.

Body parameters

{
  "ContactIDs": [1,2,3]
}

Sample Response

true

Path Parameters

Parameter	Type	Required	Description
id	number	true	Tag identifier

Body Parameters

Parameter	Type	Required	Description
ContactIDs	number[]	true	A list of contact identifiers that are to be associated to the tag

Responses

Status	Description	Schema
200	Success

Delete Contact Tag Associations

Code samples

DELETE http://api.txtsync.com/tags/1/contacts HTTP/1.1
Host: api.txtsync.com
Content-Type: application/json
Authorization: Basic QjBtVmJFVjBpTWZiSVYzWk9sUHQ6dzk3T0N0dnJ5eG90ancybnpzN29ldnlGMHUybEZEZWU2ZkFva3ZKbg==
x-api-key: 7yKeQ3Wecx1e671r88tq814FYEdPkYT89sdl9SRD

DELETE: {root}/tags/{id}/contacts

Dissociates a list of contacts from a tag.

Body parameters

{
  "ContactIDs": [1,2,3]
}

Sample Response

true

Path Parameters

Parameter	Type	Required	Description
id	number	true	Tag identifier

Body Parameters

Parameter	Type	Required	Description
ContactIDs	number[]	true	A list of contact identifiers that are to be dissociates from the tag

Responses

Status	Description	Schema
200	Success

Update Contact Tag Associations

Code samples

PUT http://api.txtsync.com/tags/1/contacts HTTP/1.1
Host: api.txtsync.com
Content-Type: application/json
Authorization: Basic QjBtVmJFVjBpTWZiSVYzWk9sUHQ6dzk3T0N0dnJ5eG90ancybnpzN29ldnlGMHUybEZEZWU2ZkFva3ZKbg==
x-api-key: 7yKeQ3Wecx1e671r88tq814FYEdPkYT89sdl9SRD

PUT: {root}/tags/{id}/contacts

Allows the contacts subscription to a tag to be updated

Body parameters

{
  "ContactIDs": [1,2,3],
  "Subscribed": false
}

Sample Response

true

Path Parameters

Parameter	Type	Required	Description
id	number	true	Tag identifier

Body Parameters

Parameter	Type	Required	Description
ContactIDs	number[]	true	A list of contact identifiers
Subscribed	boolean	true	States whether the contacts are subscribed or not to a tag

Responses

Status	Description	Schema
200	Success
400	Validation Error	ErrorMessage

Bulk Contact Tag Associations

Code samples

POST http://api.txtsync.com/tags/contacts HTTP/1.1
Host: api.txtsync.com
Content-Type: application/json
Authorization: Basic QjBtVmJFVjBpTWZiSVYzWk9sUHQ6dzk3T0N0dnJ5eG90ancybnpzN29ldnlGMHUybEZEZWU2ZkFva3ZKbg==
x-api-key: 7yKeQ3Wecx1e671r88tq814FYEdPkYT89sdl9SRD

PUT: {root}/tags/contacts

Allows multiple contacts to be associated with multiple tags.

Body parameters

{
  "ContactIDs": [1,2,3],
  "Tags": [1,2]
}

Sample Response

true

Body Parameters

Parameter	Type	Required	Description
ContactIDs	number[]	true	A list of contact identifiers that are to be associated to the tag identifiers
TagIDs	number[]	true	A list of tag identifiers that are to be associated to the contact identifiers

Responses

Status	Description	Schema
200	Success

Timeline

The timeline is a history of contact interactions with the system. Viewing the timeline for a given contact will give insight into how active that contact is with your messaging. Currently the timeline will show you inbound and outbound messages against contacts. It will show you activity such as what links the contact has opened up. It will also show you when the contact has opted in and out of messaging.

Get Timelines

Code samples

GET http://api.txtsync.com/sms/timeline HTTP/1.1
Host: api.txtsync.com
Content-Type: application/json
Authorization: Basic QjBtVmJFVjBpTWZiSVYzWk9sUHQ6dzk3T0N0dnJ5eG90ancybnpzN29ldnlGMHUybEZEZWU2ZkFva3ZKbg==
x-api-key: 7yKeQ3Wecx1e671r88tq814FYEdPkYT89sdl9SRD

Querystring parameters

  "select": "*",
  "where": "TimelineID = 1",
  "limit": 25,
  "offset": 0,
  "orderby": "TimelineID DESC",
  "recordcount": true,
  "count": false

Sample Response

[{
  "TimelineID": 508,
  "Type": 0,
  "ActivityHistoryCampaignID": null,
  "ActivityHistoryCampaignRecipientID": null,
  "ActivityHistoryContactID": null,
  "ActivityHistoryLinkID": null,
  "ActivityHistoryLinkImageURL": null,
  "ActivityHistoryLinkName": null,
  "ActivityHistoryLinkURL": null,
  "ActivityHistoryType": null,
  "ContactID": 1,
  "SMSID": 718,
  "ActivityHistoryID": null,
  "CreatedDate": "2018-10-26T10:59:50.000Z",
  "SMSLinkDetails": "[]",
  "SMSProfileURL": "",
  "SMSFlaggedDate": null,
  "SMSCampaignID": null,
  "SMSIsFlagged": false,
  "SMSFlaggedDescription": null,
  "SMSUserName": "David Cabaniuk",
  "SMSContactName": "David Cabaniuk",
  "SMSCostGBP": 0.04,
  "SMSFromNumber": "+447411111111",
  "SMSToNumber": "+447722222222",
  "SMSMessage": "Hey hows it going",
  "SMSDirection": 0,
  "SMSSegments": 1,
  "SMSDeliveredDate": "2018-10-26T11:00:11.000Z",
  "SMSErrorCode": null,
  "SMSStatus": 3,
  "SMSContactID": 1,
  "SMSUserID": 1,
}]

GET: {root}/sms/timeline

Retrieves a list of paginated timeline records

Querystring Parameters

Parameter	Type	Required	Description
select	string	false	CSV of columns for Timeline
where	string	false	A where clause to perform
limit	number	false	The number of records to retrieve. Maximum is 250 at a time
offset	number	false	The position to start the retrieval of records from
orderby	string	false	The Timeline columns to order on
recordcount	boolean	false	whether to return the overall record within the response headers
count	boolean	false	Whether to just return the record count

Responses

Status	Description	Schema
200	Success	Timeline[]

Schemas

ErrorMessage

Sample Object Definition

{
  "Message": "string",
  "Code": "string"
}

Properties

Name	Type	Description
Message	string	The error message raised raised in the customers language
Code	string	A code that represents the error message

Activity History

Sample Object Definition

{
  "ActivityHistoryID": "number",
  "LinkName": "string",
  "LinkURL": "string",
  "LinkImageURL": "string",
  "CampaignRecipientID": "number",
  "ContactID": "number",
  "CreatedDate": "date",
  "Type": "enum",
  "CampaignID": "number",
  "LinkID": "number"
}

Properties

Name	Type	Required	Readonly	Description
ActivityHistoryID	number	false	true	The unique identifier of the activity history
LinkName	string	false	true	The name given to the link
LinkURL	string	false	true	The URL of the link
LinkImageURL	string	false	true	The URL of the image link
CampaignRecipientID	number	false	true	The campaign recipient that the activity history is assocuated to
ContactID	number	false	true	The contact associated with the activity history
CreatedDate	date	false	true	The date at which the activity occured
Type	enum	false	true	The type of activity history
CampaignID	number	false	true	The campaign that the activity hsitory is associated with
LinkID	number	false	true	The identifier of the link

Type Enum

Name	Value
opened	0

Campaign

Sample Object Definition

{
  "CampaignID": "number",
  "ProcessedContacts": "number",
  "TotalContacts": "number",
  "IsSharedNumber": "boolean",
  "LastSentSMSDate": "date",
  "ActivatedDate": "date",
  "CostGBP": "number",
  "CostLocal": "number",
  "CurrencyCode": "string",
  "Name": "string",
  "NumberID": "number",
  "CustomerNumber": "string",
  "TextMessage": "string",
  "TotalOpenedLinks": "number",
  "TotalDistinctOpenedLinks": "number",
  "Status": "enum",
  "CreatedByApp": "number",
  "CreatedByAppName": "string",
  "CreatedBy": "number",
  "CreatedByName": "string",
  "CreatedDate": "date",
  "ModifiedByApp": "number",
  "ModifiedByAppName": "string",
  "ModifiedBy": "number",
  "ModifiedByName": "string",
  "ModifiedDate": "date"
}

Properties

Name	Type	Required	Readonly	Description
CampaignID	number	true	false	The unique identifier of the campaign
ProcessedContacts	number	false	true	The number of contacts that have been processed
TotalContacts	number	false	true	The total number of contacts that need to be processed
IsSharedNumber	boolean	false	true	Whether the campaign is running from a shared number
LastSentSMSDate	date	false	true	When the last SMS was sent
ActivatedDate	date	false	true	When the campaign was activated
CostGBP	number	false	true	The cost of the campaign
CostLocal	number	false	true	The cost of the campaign in local currency
CurrencyCode	string	false	true	The local currency code
Name	string	false	false	The name that is given to the campaign to identify it
NumberID	number	false	false	The identifier of the from number
CustomerNumber	string	false	true	The number that the campaign has used to send from
TextMessage	string	false	true	The message that is to go out
TotalOpenedLinks	number	false	true	The total number of link clicks for the campaign
TotalDistinctOpenedLinks	number	false	true	The total number of unique link clicks for the campaign
Status	enum	false	true	The status of the campaign
CreatedByApp	number	false	true	The identifier of the client application who created the record
CreatedByAppName	string	false	true	The name of the client application who created the record
CreatedBy	number	false	true	The identifier of the user who created the record
CreatedByName	string	false	true	The name of the user who created the record
CreatedDate	date	false	true	When the record was created (UTC)
ModifiedByApp	number	false	true	The identifier of the client application who last modified the record
ModifiedByAppName	string	false	true	The name of the client application who last modified the record
ModifiedBy	number	false	true	The identifier of the user who last modified the record
ModifiedByName	string	false	true	The name of the user who last modified the record
CreatedDate	date	false	true	When the record was last modified (UTC)

Campaign Connection

Sample Object Definition

{
  "CampaignConnectionID": "number",
  "ToNumber": "string",
  "ContactID": "number",
  "TagID": "number",
  "CampaignID": "number",
  "ContactName": "string",
  "TagName": "string"
}

Properties

Name	Type	Required	Readonly	Description
CampaignConnectionID	number	false	true	The unique identifier of the campaign connection
ToNumber	string	false	true	The phone number associated with the campaign connection
ContactID	number	false	true	The contact that represents the campaign connection
TagID	number	false	true	The tag that represents the campaign connection
ContactName	string	false	true	The name of the contact
TagName	string	false	true	The name of the tag

Campaign Recipient

Sample Object Definition

{
  "CampaignRecipientID": "number",
  "SMSID": "number",
  "ContactID": "number",
  "CampaignID": "number",
  "FullName": "string",
  "Status": "enum",
  "FromNumber": "string",
  "ToNumber": "string",
  "OpenSummary": "number",
}

Properties

Name	Type	Required	Readonly	Description
CampaignRecipientID	number	false	true	The unique identifier of the campaign recipient
SMSID	number	false	true	The SMS that went out for this campaign recipient
ContactID	number	false	true	The contact that represents the campaign recipient
FullName	string	false	true	The campaign recipients name
Status	enum	false	true	The sms status
FromNumber	string	false	true	The number the message was sent from
ToNumber	string	false	true	The number the message was sent to
OpenSummary	string	false	true	The open summary for this recipient

Campaign Report

Sample Object Definition

{
  "Links": [
    {
      "Name": "string",
      "URL": "string",
      "ImageURL": "string",
      "OpenCount": "number"
    }
  ],
  "Name": "string",
  "ActivatedDate": "date",
  "LastSentSMSDate": "date",
  "CampaignCost": "number",
  "CurrencyCode": "string",
  "PendingCount": "number",
  "QueuedCount": "number",
  "SentCount": "number",
  "DeliveredCount": "number",
  "UndeliveredCount": "number",
  "FailedCount": "number",
  "FrozenCount": "number",
  "TotalOpenedLinks": "number",
  "TotalDistinctOpenedLinks": "number",
  "RecipientCount": "number"
}

Properties

Name	Type	Required	Readonly	Description
Name	string	false	true	The name of the campaign
ActivatedDate	date	false	true	The date when the campaign was activated
LastSentSMSDate	date	false	true	The date the latest SMS was sent from the campaign
CampaignCost	number	false	true	The cost of the campaign
CurrencyCode	string	false	true	The curreny code for the local cost
PendingCount	number	false	true	The total count of messages pending
QueuedCount	number	false	true	The total count of messages queued
SentCount	number	false	true	The total count of messages sent
DeliveredCount	number	false	true	The total count of messages delivered
UndeliveredCount	number	false	true	The total count of messages undelivered
FailedCount	number	false	true	The total count of messages failed
FrozenCount	number	false	true	The total count of messages frozen
RecipientCount	number	false	true	The total count of recipents
TotalOpenedLinks	number	false	true	The total number of link clicks for the campaign
TotalDistinctOpenedLinks	number	false	true	The total number of unique link clicks for the campaign
Links	Link[]	false	true	Collection of link stats

Contact

Sample Object Definition

{
  "ContactID": "number",
  "CountryCode": "string",
  "AllowSMS": "boolean",
  "ExternalReference": "string",
  "DateOfBirth": "date",
  "CompanyName": "string",
  "FirstName": "string",
  "LastName": "string",
  "FullName": "string",
  "LastCommunicationDate": "date",
  "AddressLine1": "string",
  "AddressLine2": "string",
  "City": "string",
  "Postcode": "string",
  "County": "string",
  "Country": "string",
  "MobileNumber": "string",
  "EmailAddress": "string",
  "LatestSMSID": "number",
  "LatestInboundSMSID": "number",
  "LatestOutboundSMSID": "number",
  "OverallRating": "number",
  "TotalDistinctLinkClicks": "number",
  "TotalLinksSent": "number",
  "TotalInboundSMS": "number",
  "TotalOutboundSMS": "number",
  "TotalFailedSMS": "number",
  "HasTags": "boolean",
  "Subscribed": "boolean",
  "CreatedBy": "number",
  "CreatedByName": "string",
  "CreatedByApp": "number",
  "CreatedByAppName": "string",
  "CreatedDate": "date",
  "ModifiedByApp": "number",
  "ModifiedByAppName": "string",
  "ModifiedBy": "number",
  "ModifiedByName": "string",
  "ModifiedDate": "date",
}

Properties

Name	Type	Required	Readonly	Description
ContactID	number	true	false	The unique identifier of the contact
MobilePhone	string	true	false	The codes mobile phone number. This must be in E164 format otherwise your operating country code will be assumed
CountryCode	string	false	false	The ISO ALPHA-2 country code that the contact belongs to
AllowSMS	number	false	false	Whether the contact wishes to receive text messages or not
ExternalReference	string	false	false	The identifier of the contact from an external system
DateOfBirth	date	false	false	The contacts date of birth
CompanyName	string	false	false	The name of the company that the contact belongs to
FirstName	string	false	false	The contacts Firstname
LastName	string	false	false	The contacts lastname
FullName	string	false	true	The Contacts fullname
AddressLine1	string	false	false	Address field
AddressLine2	string	false	false	Address field
City	string	false	false	Address field
Postcode	string	false	false	Address field (zipcode)
County	string	false	false	Address field
Country	string	false	false	Address field
LastCommunicationDate	date	false	true	The last time there was a text message sent from or received from the contact
EmailAddress	string	false	false	Contacts email address
Subscribed	boolean	false	true	Determines whether the contact is subscribed or not to a tag. This is only available when working with tags
LatestSMSID	number	false	true	States the indentifier of the latest text message associated with the contact
LatestInboundSMSID	number	false	true	States the indentifier of the latest inbound text message associated with the contact
LatestOutboundSMSID	number	false	true	States the indentifier of the latest outbound text message associated with the contact
OverallRating	number	false	true	A rating that represents how reliable a contact is at replying to text messages and opening text message links
TotalDistinctLinkClicks	number	false	true	A counter for the number of links the contact has opened in total
TotalLinksSent	number	false	true	A counter for the number of links that has been sent to the contact
TotalInboundSMS	number	false	true	A counter for the total number of text messages the system has receieved from the contact
TotalOutboundSMS	number	false	true	A counter for the total number of text messages the system has sent to the contact
TotalFailedSMS	number	false	true	A counter for the total number of text messages the system has not been able to send to the destination mobile number
HasTags	number	false	true	States whether the contact is associated with at least one tag
CreatedByApp	number	false	true	The identifier of the client application who created the record
CreatedByAppName	string	false	true	The name of the client application who created the record
CreatedBy	number	false	true	The identifier of the user who created the record
CreatedByName	string	false	true	The name of the user who created the record
CreatedDate	date	false	true	When the record was created (UTC)
ModifiedByApp	number	false	true	The identifier of the client application who last modified the record
ModifiedByAppName	string	false	true	The name of the client application who last modified the record
ModifiedBy	number	false	true	The identifier of the user who last modified the record
ModifiedByName	string	false	true	The name of the user who last modified the record
CreatedDate	date	false	true	When the record was last modified (UTC)

Status Enum

Name	Value
draft	0
active	1
completed	2

Types Enum

Name	Value
bulkSms	0
campaign	1

Contact Duplicates

Sample Object Definition

{
  "MobileNumber": "string",
  "Contacts": "Contact[]",
}

Properties

Name	Type	Required	Readonly	Description
MobileNumber	string	false	true	The mobile number that duplicates have been detected on
Contacts	Contact[]	false	true	The contacts that share the same mobile number

Link

Sample Object Definition

{
  "LinkLibraryID": "number",
  "InUse": "boolean",
  "ImageURL": "string",
  "MediaLibraryID": "number",
  "Name": "string",
  "URL": "string",
  "Type": "enum",
  "CreatedByApp": "number",
  "CreatedByAppName": "string",
  "CreatedBy": "number",
  "CreatedByName": "string",
  "CreatedDate": "date",
  "ModifiedByApp": "number",
  "ModifiedByAppName": "string",
  "ModifiedBy": "number",
  "ModifiedByName": "string",
  "ModifiedDate": "date",
}

Properties

Name	Type	Required	Readonly	Description
LinkLibraryID	number	true	false	The unique identifier of the Link
InUse	boolean	false	true	Whether the link has been published
ImageURL	string	false	true	The URL of the metadata image for the link
URL	string	false	true	The public address of the link
Name	string	false	false	The name that is given to the link and is displayed to the contact
Type	enum	false	true	The type of link
ContentType	string	false	true	The content type of the file
CreatedByApp	number	false	true	The identifier of the user who created the record
CreatedByAppName	string	false	true	The name of the user who created the record
CreatedBy	number	false	true	The identifier of the user who created the record
CreatedByName	string	false	true	The name of the user who created the record
CreatedDate	date	false	true	When the record was created (UTC)
ModifiedByApp	number	false	true	The identifier of the application who last modified the record
ModifiedByAppName	string	false	true	The name of the application who last modified the record
ModifiedBy	number	false	true	The identifier of the user who last modified the record
ModifiedByName	string	false	true	The name of the user who last modified the record
CreatedDate	date	false	true	When the record was last modified (UTC)

Type Enum

Name	Value	Description
url	0	Represents a URL that points to an external web page
image	1	Represents a URL that points to a TxtSync hosted media file

Media

Sample Object Definition

{
  "MediaLibraryID": "number",
  "FileName": "string",
  "S3SizeBytes": "number",
  "URL": "string",
  "ContentType": "string",
  "CreatedByApp": "number",
  "CreatedByAppName": "string",
  "CreatedBy": "number",
  "CreatedByName": "string",
  "CreatedDate": "date",
  "ModifiedByApp": "number",
  "ModifiedByAppName": "string",
  "ModifiedBy": "number",
  "ModifiedByName": "string",
  "ModifiedDate": "date",
}

Properties

Name	Type	Required	Readonly	Description
MediaLibraryID	number	true	false	The unique identifier of the Media
FileName	string	true	false	The name of the file including the extension
S3SizeBytes	number	false	true	The size of the file in bytes
URL	string	false	true	The public address of the file
ContentType	string	false	true	The content type of the file
CreatedByApp	number	false	true	The identifier of the user who created the record
CreatedByAppName	string	false	true	The name of the user who created the record
CreatedBy	number	false	true	The identifier of the user who created the record
CreatedByName	string	false	true	The name of the user who created the record
CreatedDate	date	false	true	When the record was created (UTC)
ModifiedByApp	number	false	true	The identifier of the application who last modified the record
ModifiedByAppName	string	false	true	The name of the application who last modified the record
ModifiedBy	number	false	true	The identifier of the user who last modified the record
ModifiedByName	string	false	true	The name of the user who last modified the record
CreatedDate	date	false	true	When the record was last modified (UTC)

Number

Sample Object Definition

{
  "NumberID": "number",
  "Name": "string",
  "Number": "string",
  "CostGBP": "number",
  "CostLocal": "number",
  "CurrencyCode": "string",
  "IsDedicatedNumber": "boolean",
  "IsSenderID": "boolean",
  "IsExpiring": "boolean",
  "IsShared": "boolean",
  "IsPersonal": "boolean",
  "CountryCode": "string",
  "IsAutoReply": "boolean",
  "AutoReplyMessage": "string",
  "IncomingCallMessageURL": "string",
  "CallMessage": "string",
}

Properties

Name	Type	Required	Readonly	Description
NumberID	number	true	false	The unique identifier of the number
Name	string	true	false	The name given to the number. This name is used to identify the number within the web UI
Number	string	true	true	The actual number or the sender id that will be shown on the receiving mobile device
CostGBP	number	false	true	The cost of the number in GBP
CostLocal	number	false	true	The cost of the number in the chosen local currency
CurrencyCode	string	false	true	When the record was created (UTC)
IsDedicatedNumber	boolean	false	true	Denotes that the number is a dedicated number
IsSenderID	boolean	false	true	States that the numbers is a dedicated sender id
IsShared	boolean	false	true	States that the number is a global shared number
IsPersonal	boolean	false	true	States that the number is a personal number
IsExpiring	boolean	false	true	States that the number number has been cancelled and will be released at the end of the billing period
CountryCode	string	false	true	The country code that the number belongs to
IsAutoReply	boolean	false	true	States whether auto reply is turned on or not
AutoReplyMessage	string	false	true	The text message that is to be sent out if auto reply is turned on
IncomingCallMessageURL	string	false	true	The web URL of the audio file to play if someone tries to call the number
CallMessage	string	false	true	The message that will be played within the audio file

Report System

Sample Object Definition

{
  "TotalInboundMessages": "number",
  "TotalOutboundMessages": "number",
  "TotalMessages": "number",
  "TotalCampaigns": "number",
  "TotalFrozenOutboundMessages": "number",
}

Properties

Name	Type	Required	Readonly	Description
TotalInboundMessages	number	false	true	The number of inbound text messages that have been received
TotalOutboundMessages	number	false	true	The number of outbound text messages that have been send
TotalMessages	number	false	true	The total text messages that have been handled by the system, this is both inbound and outbound
TotalCampaigns	number	false	true	The total amount of campaigns that have been initiated
TotalFrozenOutboundMessages	number	false	true	The total amount of outbound messages that have been frozen due to requiring a payment on account

SMS

Sample Object Definition

{
  "SMSID": "number",
  "FromNumber": "string",
  "ToNumber": "string",
  "Message": "string",
  "Direction": "number",
  "Segments": "number",
  "DeliveredDate": "date",
  "CampaignID": "number",
  "ApplicationID": "number",
  "ApplicationName": "string",
  "UserName": "string",
  "ContactName": "string",
  "ProfileURL": "string",
  "LinkDetails": "string",
  "IsFlagged": "boolean",
  "FlaggedDate": "date",
  "FlaggedDescription": "string",
  "CurrencyCode": "string",
  "CreatedDate": "date",
  "CostLocal": "number",
  "CostGBP": "number",
  "ErrorCode": "string",
  "Status": "number",
  "ContactID": "number",
  "UserID": "number",
}

Properties

Name	Type	Required	Readonly	Description
SMSID	number	true	false	The unique identifier of the sms
FromNumber	string	false	false	The number that the text message was sent from
ToNumber	string	false	false	The number that the text message was sent to
Message	string	false	false	The message that was sent
Direction	number	false	false	The direction of the number
Segments	number	false	false	The number of segments that the text message takes up
DeliveredDate	date	false	false	The date at which the text message was delivered
CampaignID	number	false	false	The campaign that the text message might be associated to
ApplicationID	number	false	false	The client application that the text message might be associated to
ApplicationName	string	false	false	The name of the client application that the text message might be associated to
UserID	number	false	false	The user identifier that is associated to the text message
UserName	string	false	false	The username of the client application that the text message might be associated to
ContactID	number	false	false	The contact identifier that is associated to the text message
ContactName	string	false	false	The name of the contact that the text message has been sent to
ProfileURL	string	false	false	The profile URl of the contact
LinkDetails	string	false	false	JSON object of the link details that are attached to the text message
IsFlagged	boolean	false	false	States whether the text message has been flagged with a message
FlaggedDate	date	false	false	The date when the text message was flagged with a message
FlaggedDescription	string	false	false	The message that has been flagged on the text message
CurrencyCode	string	false	false	The currency code of the local cost
CostLocal	number	false	false	The local currency cost of the text message
CostGBP	number	false	false	The GBP currency cost of the text message
CreatedDate	date	false	false	The date time in UTC of when the text message was created
ErrorCode	number	false	false	The error code of the text message if there was an issue in sending
Status	number	false	false	The status of the text message

Direction Enum

Name	Value
outbound	0
inbound	1

Status Enum

Name	Value	Description
pending	0	The text message is currently pending processing
queued	1	The text message is now queued for sending
sent	2	The text message has been sent
delivered	3	The text message has been delivered
undelivered	4	The text message cannot be delivered
failed	6	An error has occured when attempting to send the text message
frozen	7	The text message has been frozen due to a zero balance on the account

ErrorCodes Enum

Name	Value	Description
Invalid message	10	The message content is blank or exceeds the character limit of 1600 for messages encoded with GMS and 737 for messaged encoded with Unicode. Note that while we provide a separate error code to indicate if a message is too long, some carriers only send an “invalid message” error and don’t differentiate between blank messages and long message errors.
Network error	20	The carrier delivering the text message had network issues. To resolve this, you can retry at a later time when the carrier network is unaffected.
Spam detected	30	One of the most common reasons for SMS delivery failure is carrier level spam filters. Carriers have added systems and algorithms that detect spam content and then block them before they even get delivered. Unfortunately, these filters are always hidden, subject to carrier preferences, vary from carrier to carrier, and can be changed without notice. Another common reason why this error code could be returned is that you may have attempted to send too many messages using long code phone numbers in US & Canada. Long codes are 10-digit phone numbers and are intended only for peer-to-peer (P2P) communication. If this issue persists, we highly recommend using short codes for sending bulk messages within US and Canada. However, if you are confident that your message content is compliant, then retry sending the message again. You can also contact our support team to whitelist your message one time with our downstream carriers.
Invalid source number	40	The source number you entered is either not in the correct format or not SMS-enabled. Check the “src” phone number in your application and ensure that it is in the correct format and has the ability to send text messages. All phone numbers in your application should include country code, area code, and phone number without spaces or dashes (e.g., +14155555555 for US or +491155555555 for Berlin, Germany).
Invalid destination number	50	The destination number you entered is either not entered correctly, not SMS-enabled or is a PSTN landline. Check the “dst” phone number in your application to ensure that it is able to receive text messages. All phone numbers in your application should include country code, area code, and phone number without spaces or dashes (e.g., +14155555555).
Loop detected	60	The carrier is not able to route your SMS because certain settings in your application are corresponding to an endless loop of messages being sent and received between your source and destination phone numbers. This can occur when two auto-responding SMS applications start to talk to each other and end up in a loop. Carriers detect loops by comparing messages within a predefined period of time to previous messages sent and received. SMS loops can increase unnecessary spend, so to ensure that your applications do not trigger loops, it’s a good idea to create loop filters in your application because not all carriers have loop detection. In some cases, this error code is returned when the carrier determines that it is impossible to route the SMS and the message has to be dropped as it is being looped between platforms.
Destination permanently unavailable	70	The destination phone number is not active and there is no indication of when it will become available again. Note that this is a broad error code where the carrier has not indicated the reason for the destination unavailability. Check the “dst” phone number to ensure that it is correct. Also, try sending messages to an alternative number to ensure that all other parts of your application are working.
Destination temporarily unavailable	80	The destination phone number is not reachable. Note that this is a broad error code and often times, the carrier does not indicate the reason for the destination to be temporarily unavailable. Though, possible reasons could be due to the handset being turned off or out of coverage. To resolve this, retry your messages at a later time.
No route available	90	The carrier and fallback carriers were not able to deliver the SMS message because the route was not available. Please note that carriers do not offer the reason for why the route is unavailable.
Prohibited by carrier	100	The carrier rejected the text message because the network did not support the message being sent. This could occur if the destination network does not support SMS.
Message too long	110	The message content exceeds the character limit of 1600 for GSM and 737 for UTF encoded messages. Note that depending on the byte size, Emoji characters can also increase the message character count significantly.
Source number blocked by STOP from destination number	200	The destination has opted out from your campaign and blocked all messages sent from your phone number. Opt-outs are typically received via text message replies with a opt-out keyword including “STOP”. All messages to destinations that have opted out will be blocked until the destination opts in with another response
Outbound messages from US Toll-Free numbers to Canadian destination numbers are blocked	201	Your application is attempting to send text messages from a United States Toll-Free phone number to a Canadian phone number destination. Unfortunately, carriers limit US Toll-Free phone numbers to only send SMS to US phone numbers.
Failed to dispatch message	300	An error was encountered while passing on the message to downstream carriers.
Unknown error	1000	Delivering your message failed for reasons that are unknown to us and to our carriers.

SMS Template

Sample Object Definition

{
  "SMSTemplateID": "number",
  "Name": "string",
  "Template": "string",
  "CreatedByApp": "number",
  "CreatedByAppName": "string",
  "CreatedBy": "number",
  "CreatedByName": "string",
  "CreatedDate": "date",
  "ModifiedByApp": "number",
  "ModifiedByAppName": "string",
  "ModifiedBy": "number",
  "ModifiedByName": "string",
  "ModifiedDate": "date",
}

Properties

Name	Type	Required	Readonly	Description
SMSTemplateID	number	true	false	The unique identifier of the SMS Template
Name	string	true	false	The name given to the SMS Template. This must be unique and less than 50 characters
Template	string	true	false	The body of the template
CreatedByApp	number	false	true	The identifier of the application who created the record
CreatedByAppName	string	false	true	The name of the application who created the record
CreatedBy	number	false	true	The identifier of the user who created the record
CreatedByName	string	false	true	The name of the user who created the record
CreatedDate	date	false	true	When the record was created (UTC)
ModifiedByApp	number	false	true	The identifier of the application who last modified the record
ModifiedByAppName	string	false	true	The name of the application who last modified the record
ModifiedBy	number	false	true	The identifier of the user who last modified the record
ModifiedByName	string	false	true	The name of the user who last modified the record
CreatedDate	date	false	true	When the record was last modified (UTC)

Speaker

Sample Object Definition

{
  "Gender": "string",
  "Id": "string",
  "LanguageCode": "string",
  "LanguageName": "name",
  "Name": "string",
}

Properties

Name	Type	Required	Readonly	Description
Gender	string	false	true	The gender of the speaker
Id	string	false	false	The identifier of the speaker
LanguageCode	string	false	true	The language code of the speaker
LanguageName	string	false	true	The language of the speaker
Name	string	false	true	The name of the speaker

Tag

Sample Object Definition

{
  "TagID": "number",
  "Name": "string",
  "Type": "enum",
  "CreatedBy": "number",
  "CreatedByName": "string",
  "CreatedDate": "date",
  "ModifiedBy": "number",
  "ModifiedByName": "string",
  "ModifiedDate": "date",
}

Properties

Name	Type	Required	Readonly	Description
TagID	number	true	false	The unique identifier of the tag
Name	string	true	false	The name given to the tag. This must be unique and less than 50 characters
Type	number	false	true	The type of tag
CreatedBy	number	false	true	The identifier of the user who created the record
CreatedByName	string	false	true	The name of the user who created the record
CreatedDate	date	false	true	When the record was created (UTC)
ModifiedBy	number	false	true	The identifier of the user who last modified the record
ModifiedByName	string	false	true	The name of the user who last modified the record
CreatedDate	date	false	true	When the record was last modified (UTC)

Type Enum

Name	Value
List	0
Location	1

Timeline

Sample Object Definition

{
  "TimelineID": "number",
  "Type": "enum",
  "ActivityHistoryCampaignID": "number",
  "ActivityHistoryCampaignRecipientID": "number",
  "ActivityHistoryContactID": "number",
  "ActivityHistoryLinkID": "number",
  "ActivityHistoryLinkImageURL": "string",
  "ActivityHistoryLinkName": "string",
  "ActivityHistoryLinkURL": "string",
  "ActivityHistoryType": "enum",
  "ContactID": "number",
  "SMSID": "number",
  "ActivityHistoryID": "number",
  "CreatedDate": "date",
  "SMSLinkDetails": "string",
  "SMSProfileURL": "string",
  "SMSFlaggedDate": "date",
  "SMSCampaignID": "number",
  "SMSIsFlagged": "boolean",
  "SMSFlaggedDescription": "string",
  "SMSUserName": "string",
  "SMSContactName": "string",
  "SMSCostGBP": "number",
  "SMSFromNumber": "string",
  "SMSToNumber": "string",
  "SMSMessage": "string",
  "SMSDirection": "enum",
  "SMSSegments": "string",
  "SMSDeliveredDate": "date",
  "SMSErrorCode": "string",
  "SMSStatus": "enum",
  "SMSContactID": "number",
  "SMSUserID": "number",
}

Properties

Name	Type	Required	Readonly	Description
TimelineID	number	false	true	The unique identifier of the timeline
SMSID	number	false	true	The unique identifier of the sms
CreatedDate	date	false	true	The date in which the timeline record was created (UTC)
SMSLinkDetails	string	false	true	JSON object of the link details that are attached to the text message
SMSProfileURL	string	false	true	The profile URl of the contact
SMSFlaggedDate	date	false	true	The date when the text message was flagged with a message
SMSCampaignID	number	false	true	The campaign that the text message might be associated to
SMSIsFlagged	boolean	false	true	States whether the text message has been flagged with a message
SMSFlaggedDescription	string	false	true	The message that has been flagged on the text message
SMSUserName	string	false	true	The username of the client application that the text message might be associated to
SMSContactName	string	false	true	The name of the contact that the text message has been sent to
SMSCostGBP	number	false	true	The GBP currency cost of the text message
SMSCostLocal	number	false	true	The local currency cost of the text message
SMSCurrencyCode	string	false	true	The currency code of the local cost
SMSFromNumber	string	false	true	The number that the text message was sent from
SMSToNumber	string	false	true	The number that the text message was sent to
SMSMessage	string	false	true	The message that was sent
SMSDirection	number	false	true	The direction of the number
SMSSegments	number	false	true	The number of segments that the text message takes up
SMSDeliveredDate	date	false	true	The date at which the text message was delivered
SMSErrorCode	number	false	true	The error code of the text message if there was an issue in sending
SMSStatus	number	false	true	The status of the text message
SMSUserID	number	false	true	The user identifier that is associated to the text message
SMSContactID	number	false	true	The contact identifier that is associated to the text message
SMSApplicationID	number	false	true	The client application that the text message might be associated to
SMSApplicationName	string	false	true	The name of the client application that the text message might be associated to
Type	enum	false	true	The type of timeline record
ActivityHistoryCampaignID	number	false	true	The campaign that the history item occured against
ActivityHistoryCampaignRecipientID	number	false	true	The reciptient that the history item occured against
ActivityHistoryContactID	number	false	true	The contact that the history item occured against
ActivityHistoryLinkID	number	false	true	The link that the action occured against
ActivityHistoryLinkImageURL	string	false	true	The URL of the link image
ActivityHistoryLinkName	string	false	true	The name of the link image
ActivityHistoryLinkURL	string	false	true	The URL of the link
ActivityHistoryType	enum	false	true	What type of action has occured
ContactID	number	false	true	The contact that is associated to the
ActivityHistoryType	enum	false	true	What type of action has occured
ActivityHistoryID	number	false	true	The identifier of the activity history item

Types Enum

Name	Value
sms	0
activity	1
opIn	2
opOut	3

ActivityHistoryTypes Enum

Name	Value
opened	0

SMSDirection Enum

Name	Value
outbound	0
inbound	1

SMSStatus Enum

Name	Value	Description
pending	0	The text message is currently pending processing
queued	1	The text message is now queued for sending
sent	2	The text message has been sent
delivered	3	The text message has been delivered
undelivered	4	The text message cannot be delivered
failed	6	An error has occured when attempting to send the text message
frozen	7	The text message has been frozen due to a zero balance on the account

Webhooks

TxtSync has the cabability of informing your application about given events occuring within the TxtSync platform. This is achieved through a set of webhooks which can be setup within the web UI against your client application.

All webhooks, if configured perform a HTTP POST request to the configured URL. TxtSync webhooks expect to receieve a 200 response back. If this is not the case the webhook will retry every 30 minutes for 4 hours.

The following webhooks can be created.

Webhook Container Object

{
  "Type": "number",
  "TypeName": "string",
  "WebHookID": "number",
  "ApplicationID": "number",
  "Identifier": "string",
  "Timestamp": "date",
  "Content": "any",
}

Inbound SMS

Sample Inbound Message

{
  "ApplicationID": 2,
  "Content": {
    "Contact": {
      "AddressLine1": "",
      "AddressLine2": "",
      "AllowSMS": true,
      "City": "",
      "CompanyName": "",
      "ContactID": 24,
      "Country": "United Kingdom",
      "CountryCode": null,
      "County": "",
      "CreatedBy": 31,
      "CreatedByApp": null,
      "CreatedDate": "2018-10-03T11:58:18.000Z",
      "DateOfBirth": null,
      "EmailAddress": "icantthinkofanemailaddress@hotmail.com",
      "ExternalReference": null,
      "Facebook": null,
      "FirstName": "David",
      "FullName": "David Cabaniuk",
      "GooglePlus": null,
      "LastCommunicationDate": "2018-10-19T15:18:18.000Z",
      "LastName": "Cabaniuk",
      "LatestInboundSMSID": 627,
      "LatestOutboundSMSID": 700,
      "LatestSMSID": 700,
      "LinkedIn": null,
      "MobileNumber": "+447711111111",
      "ModifiedBy": 31,
      "ModifiedByApp": null,
      "ModifiedDate": "2018-10-19T15:18:18.000Z",
      "OverallRating": 100,
      "Postcode": "LE16 9HT",
      "Source": 0,
      "TotalDistinctLinkClicks": 4,
      "TotalInboundSMS": 40,
      "TotalLinksSent": 2,
      "TotalOutboundSMS": 23,
      "Twitter": null,
      "Website": null
    },
    "SMS": {
      "ContactID": 24,
      "ContactName": "David Cabaniuk",
      "CostGBP": 0,
      "CostLocal": 0,
      "CreatedDate": "2018-10-25T20:58:46.074Z",
      "CurrencyCode": "GBP",
      "DeliveredDate": "2018-10-25T20:58:46.074Z",
      "Direction": 1,
      "FromNumber": "+447711111111",
      "Message": "Test inbound message",
      "SMSID": 714,
      "Segments": 1,
      "Status": 3,
      "ToNumber": "+447222222222"
    }
  },
  "Identifier": "701915a1-f12f-6e8e-ed91-7c6b57858da3",
  "Timestamp": "2018-10-25T20:58:46.489Z",
  "Type": 0,
  "TypeName": "INBOUND_SMS",
  "WebHookID": 1
}

Raised when the TxtSync platform receives a text message.

Outbound SMS

Sample Outbound Message

{
  "ApplicationID": 2,
  "Content": {
    "ApplicationID": 2,
    "ContactID": 1,
    "CostGBP": 0.040,
    "CostLocal": 0.040,
    "CreatedDate": "2018-10-25T20:55:53.271Z",
    "CurrencyCode": "GBP",
    "Direction": 0,
    "FromNumber": "TxtSync",
    "LinkDetails": "[]",
    "Message": "Hi David, \r\n\r\nThis is a sample outbound message! 😁",
    "SMSID": 712,
    "Status": 0,
    "StatusName": "PENDING",
    "ToNumber": "+447711111111"
  },
  "Identifier": "1d443727-970d-aad9-c8d7-df5f1fb82d7c",
  "Timestamp": "2018-10-25T20:55:59.744Z",
  "Type": 1,
  "TypeName": "OUTBOUND_STATUS",
  "WebHookID": 2
}

Raised when the TxtSync platform sends out a text message. This webhook will be fired multiple times to give the delivery status of the outbound text message

The different outbound states of a text message are as follows

Status	Description
pending	The text message is currenting pending being sent to the carrier
sent	The text message has been sent to the carrier
delivered	The text message has been delivered to the destination device
undelivered	The carrier was unable to deliver the text message to the destination device
failed	An error occurred in attempting to send out the text message
frozen	The text message is in a holding state due to not enough credit being on account

Campaign Start

Sample Campaign Start Message

{
  "ApplicationID": 2,
  "Content": {
    "CampaignID": 150,
    "CampaignName": "A message to say hi",
    "From": "+447422222222",
    "Message": "Hi {{FirstName}} - campaign Start / Stop Test",
    "TotalContacts": 1
  },
  "Identifier": "88e3c21b-bf23-0915-75d1-0fa5eafe24ec",
  "Timestamp": "2018-10-25T21:07:56.586Z",
  "Type": 3,
  "TypeName": "CAMPAIGN_START",
  "WebHookID": 6
}

Raised when a Campaign / Bulk SMS is started within the TxtSync platform

Campaign End

Sample Campaign Start Message

{
  "ApplicationID": 2,
  "Content": {
    "CampaignID": 150,
    "CampaignName": "A message to say hi",
    "From": "+447422222222",
    "Message": "Hi {{FirstName}} - campaign Start / Stop Test",
    "TotalContacts": 1
  },
  "Identifier": "099efc9d-a630-0915-219f-ea1aee3fb38d",
  "Timestamp": "2018-10-25T21:07:59.917Z",
  "Type": 4,
  "TypeName": "CAMPAIGN_END",
  "WebHookID": 7
}

Raised when a Campaign / Bulk SMS has finished within the TxtSync platform

Account Charge

Sample Account Charge

{
  "ApplicationID": 2,
  "Content": {
    "AmountGBP": 5,
    "AmountLocal": 6,
    "BalanceGBP": 64.8205,
    "BalanceLocal": 64.8205,
    "CurrencyCode": "GBP",
    "ExchangeRate": 1
  },
  "Identifier": "ec9226e6-cc94-6fb4-48b9-58c4157bb943",
  "Timestamp": "2018-10-25T21:10:56.471Z",
  "Type": 2,
  "TypeName": "ACCOUNT_CHARGE",
  "WebHookID": 5
}

Raised when TxtSync places a charge onto the accounts payment method