Introduction

Welcome to the Tling API. Here you can find all the documentation you need to help you start creating new services powered by the Tling platform.

Authentication

Request using the ‘X-API-key’ header:

curl https://app.tling.io/api/v0/messages \
  -H 'x-api-key: <api_key>'

Partners looking to integrate with our API must register an account. In your account you have a dedicated area for API keys management. To start using our API create a valid API access token.

After having a valid API access token, all requests to our API that require authentication should send the API access token in the X-API-Key header.

Contacts

Get all user contacts

To list all user contacts:

curl https://app.tling.io/api/v0/contacts \
  -H 'content-type: application/json'

The above command returns the following JSON:

{
  "data" : [
    {
      "birthDate": "2000-01-01T00:00:00.000Z",
      "createdAt": "2023-01-25T15:38:37.434Z",
      "email": "[email protected]",
      "id": "80331aa5-ac8d-48ae-a947-462034aed497",
      "listsCount": "0",
      "name": "Foo1",
      "phoneCode": "+351",
      "phoneNumber": "987654321",
      "updatedAt": "2023-01-25T15:38:37.434Z"
    }
   ]
}

This end-point retrives all your contacts

HTTP Request

GET https://app.tling.io/api/v0/contacts

Query Parameters

Query Parameters	Default	Description
page[size]	30	The page size, maximum 100.
page[number]	1	The page number.
sort	updatedAt	The field to sort by. Use `-field` to sort in descending direction. If available, sort will default to field `updatedAt` in ascending direction.
filter[fields][op]	-	The field to filter by and the filter operation. Fields: `birthDate`, `email`, `name`, `phoneCode`, `phoneNumber`, `createdAt`
listId	-	ID of the list from which you want to get the contacts or id of the list from wich you want to get the contacts that not belongs, if id starts with `!`.

Get user contact

To get a contact with a given id:

curl https://app.tling.io/api/v0/contacts/d8c19ee5-e967-42e5-b88c-15eb0f67a52d
  -H 'content-type: application/json'

The above command returns the following JSON:

{
  "birthDate": "2000-01-01T00:00:00.000Z",
  "createdAt": "2023-01-25T15:38:37.434Z",
  "email": "[email protected]",
  "id": "d8c19ee5-e967-42e5-b88c-15eb0f67a52d",
  "listsCount": "0",
  "name": "Foo1",
  "phoneCode": "+351",
  "phoneNumber": "987654321",
  "updatedAt": "2023-01-25T15:38:37.434Z"
}

This endpoint retrieves a contact with the given id.

HTTP Request

GET https://app.tling.io/api/v0/contacts/:id

Create a contact

To create a contact:

curl https://app.tling.io/api/v0/contacts \
  -X POST
  -H 'content-type: application/json' \
  -d '{"name": "Foobar","phoneNumber": "+351911111111"}'

Returns an HTTP status code of 200 and the following JSON:

{
  "birthDate": "null",
  "createdAt": "2023-01-31T15:52:55.473Z",
  "email": "null",
  "id": "d8c19ee5-e967-42e5-b88c-15eb0f67a53d",
  "name": "Foobar",
  "phoneCode": "+351",
  "phoneNumber": "911111111",
  "updatedAt": "2023-01-31T15:52:55.473Z"
}

This endpoint creates a contact.

HTTP Request

POST https://app.tling.io/api/v0/contacts

Query Parameters

Parameters	Default	Description
birthDate	null	Date format ‘string’ of contact birth date.
email	null	Contact email.
name	null	Contact name.
phoneNumber	-	Phone code and phone number toghether in a string, starting with `+`.

Update a contact

To update a contact:

curl https://app.tling.io/api/v0/contacts/d8c19ee5-e967-42e5-b88c-15eb0f67a53d \
  -X PATCH
  -H 'content-type: application/json' \
  -d '{"phoneNumber": "+351911111122"}'

Returns an HTTP status code of 200 and the following JSON:

{
  "birthDate": "2000-01-01T00:00:00.000Z",
  "createdAt": "2023-01-31T16:20:01.392Z",
  "email": "null",
  "id": "d8c19ee5-e967-42e5-b88c-15eb0f67a53d",
  "name": "Foobar",
  "phoneCode": "+351",
  "phoneNumber": "911111122",
  "updatedAt": "2023-01-31T16:20:01.420Z"
}

This endpoint updates a contact with given id.

HTTP Request

PATCH https://app.tling.io/api/v0/contacts/:id

Query Parameters

Parameters	Default	Description
birthDate	-	Date format ‘string’ of contact birth date.
email	-	Contact email.
name	-	Contact name.
phoneNumber	-	Phone code and phone number toghether in a string, starting with `+`.

Delete a contact

To delete a contact with a given id:

curl https://app.tling.io/api/v0/contacts/d8c19ee5-e967-42e5-b88c-15eb0f67a53d
  -H 'content-type: application/json'

Returns an HTTP status code of 204 and no JSON body, in case of success.

This endpoint delete a contact.

HTTP Request

DELETE https://app.tling.io/api/v0/contacts/:id

Delete multiples contact

To delete a contact with a given a set of id:

curl https://app.tling.io/api/v0/contacts/d8c19ee5-e967-42e5-b88c-15eb0f67a53d
  -H 'content-type: application/json'

Returns an HTTP status code of 204 and no JSON body, in case of success.

This endpoint delete a contact.

HTTP Request

DELETE https://app.tling.io/api/v0/contacts/:id

Lists

Get all user contacts lists

To list all user lists:

curl https://app.tling.io/api/v0/lists \
  -H 'content-type: application/json'

The above command returns the following JSON:

{
  "data" : [
    {
      "contactsCount": "0",
      "createdAt": "2023-01-31T17:12:06.402Z",
      "id": "fd0d2033-d436-4916-bb9f-f07b84fd6120",
      "name": "List3",
      "updatedAt": "2023-01-31T17:12:06.402Z"
    },
    {
      "contactsCount": "0",
      "createdAt": "2023-01-31T17:12:06.401Z",
      "id": "af35c179-bdb8-4b35-9b18-991c4efb966f",
      "name": "List2",
      "updatedAt": "2023-01-31T17:12:06.401Z"
    },
    {
      "contactsCount": "0",
      "createdAt": "2023-01-31T17:12:06.399Z",
      "id": "9703ac26-b71d-470b-915b-f4ec48a8ce18",
      "name": "List1",
      "updatedAt": "2023-01-31T17:12:06.399Z"
    }
   ]
}

This end-point retrives all your lists

HTTP Request

GET https://app.tling.io/api/v0/lists

Query Parameters

Query Parameters	Default	Description
page[size]	30	The page size, maximum 100.
page[number]	1	The page number.
sort	updatedAt	The field to sort by. Use `-field` to sort in descending direction. If available, sort will default to field `updatedAt` in ascending direction.
filter[fields][op]	-	The field to filter by and the filter operation. Fields: `name`, `createdAt`

Get user contacts list

To get a list with a given id:

curl https://app.tling.io/api/v0/lists/9703ac26-b71d-470b-915b-f4ec48a8ce18
  -H 'content-type: application/json'

The above command returns the following JSON:

{
  "contactsCount": "0",
  "createdAt": "2023-01-31T17:20:24.023Z",
  "id": "9703ac26-b71d-470b-915b-f4ec48a8ce18",
  "name": "List1",
  "updatedAt": "2023-01-31T17:20:24.023Z"
}

This endpoint retrieves a list with the given id.

HTTP Request

GET https://app.tling.io/api/v0/lists/:id

Create a list

To create a list:

curl https://app.tling.io/api/v0/lists \
  -X POST
  -H 'content-type: application/json' \
  -d '{"name": "List1"}'

Returns an HTTP status code of 200 and the following JSON:

{
  "createdAt": "2023-01-31T17:25:04.490Z",
  "id": "261634ef-00f4-4193-89aa-c79ca2ee4637",
  "name": "List1",
  "updatedAt": "2023-01-31T17:25:04.490Z"
}

This endpoint creates a list.

HTTP Request

POST https://app.tling.io/api/v0/lists

Query Parameters

Parameters	Default	Description
name	null	List name.

Add one or multiples contacts to list

To add multiples contacts to list:

curl https://app.tling.io/api/v0/lists/05d83365-27da-4974-b735-e18923d8ab70/contacts \
  -X POST
  -H 'content-type: application/json' \
  -d '["7b3a8ca2-3c86-44f9-a508-335498d6910b", "bb18824e-a2da-4fd7-8216-a26f6b587a8c"]'

Returns an HTTP status code of 204 and no JSON body, in case of success.

This endpoint add one or multiples contacts to list.

HTTP Request

POST https://app.tling.io/api/v0/lists/:id/contacts

Update a list

To update a list:

curl https://app.tling.io/api/v0/lists/261634ef-00f4-4193-89aa-c79ca2ee4637 \
  -X PATCH
  -H 'content-type: application/json' \
  -d '{"name": "List2"}'

Returns an HTTP status code of 200 and the following JSON:

{
  "createdAt": "2023-01-31T17:25:04.490Z",
  "id": "261634ef-00f4-4193-89aa-c79ca2ee4637",
  "name": "List2",
  "updatedAt": "2023-01-31T17:34:48.643Z"
}

This endpoint updates a list with given id.

HTTP Request

PATCH https://app.tling.io/api/v0/lists/:id

Query Parameters

Parameters	Default	Description
name	-	List name.

Delete a list

To delete a list with given id:

curl https://app.tling.io/api/v0/lists/261634ef-00f4-4193-89aa-c79ca2ee4637
  -H 'content-type: application/json'

Returns an HTTP status code of 204 and no JSON body, in case of success.

This endpoint does not delete contacts that belongs to this list. This endpoint delete a contact.

HTTP Request

DELETE https://app.tling.io/api/v0/lists/:id

Delete one or multiples contacts from a list

To remove multiples contacts from a list:

curl https://app.tling.io/api/v0/lists/05d83365-27da-4974-b735-e18923d8ab70/contacts \
  -X DELETE
  -H 'content-type: application/json' \
  -d '["7b3a8ca2-3c86-44f9-a508-335498d6910b", "bb18824e-a2da-4fd7-8216-a26f6b587a8c"]'

Returns an HTTP status code of 204 and no JSON body, in case of success.

This endpoint remove multiples contacts from a list.

HTTP Request

DELETE https://app.tling.io/api/v0/lists/:id/contacts

Messages

Get all messages

To list all messages sent from your account:

curl https://app.tling.io/api/v0/messages \
  -H 'content-type: application/json'

The above command returns the following JSON:

{
  "data": [
    {
      "apiKeyId": "2606a2e5-70b5-4df3-9c94-07467a864866",
      "createdAt": "2021-07-28T11:48:54.507Z",
      "error": null,
      "id": "d8c19ee5-e967-42e5-b88c-15eb0f67a51d",
      "phoneCode": "+351",
      "phoneNumber": "911111111",
      "report": [
        {
          "status": "delivered",
          "timestamp": "2021-07-28T11:49:07.000Z"
        },
        {
          "status": "sent",
          "timestamp": "2021-07-28T11:48:55.000Z"
        },
        {
          "status": "created",
          "timestamp": "2021-07-28T11:48:54.506Z"
        },
        {
          "status": "queued",
          "timestamp": "2021-07-28T11:48:54.754Z"
        }
      ],
      "updatedAt": "2021-07-28T11:48:54.507Z"
    }
  ],
  "total": 1
}

This endpoint retrieves all messages sent from your account.

HTTP Request

GET https://app.tling.io/api/v0/messages

Query Parameters

Query Parameters	Default	Description
page[size]	30	The page size, maximum 100.
page[number]	1	The page number.
sort	updatedAt	The field to sort by. Use `-field` to sort in descending direction. If available, sort will default to field `updatedAt` in ascending direction.
filter[fields][op]	-	The field to filter by and the filter operation. Fields: `phoneCode`, `phoneNumber`, `createdAt`
status	-	The message status, one of: `buffered`, `created`, `delivered`, `expired`, `failed`, `queued`, `queue failed`, `sent`, `undelivered`

Get a message

To get a message with a given id:

curl https://app.tling.io/api/v0/messages/d8c19ee5-e967-42e5-b88c-15eb0f67a51d
  -H 'content-type: application/json'

The above command returns the following JSON:

{
  "apiKeyId": "2606a2e5-70b5-4df3-9c94-07467a864866",
  "createdAt": "2021-07-28T11:48:54.507Z",
  "error": null,
  "id": "d8c19ee5-e967-42e5-b88c-15eb0f67a51d",
  "phoneCode": "+351",
  "phoneNumber": "911111111",
  "report": [
    {
      "status": "delivered",
      "timestamp": "2021-07-28T11:49:07.000Z"
    },
    {
      "status": "sent",
      "timestamp": "2021-07-28T11:48:55.000Z"
    },
    {
      "status": "created",
      "timestamp": "2021-07-28T11:48:54.506Z"
    },
    {
      "status": "queued",
      "timestamp": "2021-07-28T11:48:54.754Z"
    }
  ],
  "updatedAt": "2021-07-28T11:48:54.507Z"
}

This endpoint retrieves a message with the given id.

HTTP Request

GET https://app.tling.io/api/v0/messages/:id

Get message cost

To get a message cost:

curl https://staging.tling.io/api/v0/messages/costs
  -X POST
  -H 'content-type: application/json'
  -d '{"text": "Foobar","to": ["+351911111111"]}'

The above command returns the following JSON:

{
  "credits": "5",
}

This endpoint retrieves the cost of a message.

HTTP Request

POST https://staging.tling.io/api/v0/messages/cost

Create a message

To create and send a message:

curl https://app.tling.io/api/v0/messages \
  -X POST
  -H 'content-type: application/json' \
  -d '{"text": "Foobar","to": ["+351911111111"]}'

Returns an HTTP status code of 204 and no JSON body, in case of success.

This endpoint creates and sends a message.

HTTP Request

POST https://app.tling.io/api/v0/messages

Query Parameters

Parameters	Default	Description
text	-	The message text. Keep in mind that a single message is limited to 160 characters. If you send a message with more than 160 characters the message is split into more messages. Limit is 1600 characters. Also keep in mind that message with UCS-2 characters have a limit of 70 characters.
to	-	Array of valid phone numbers to send the message.

Schedule message

Get all user scheduled messages

curl https://staging.tling.io/api/v0/schedule/message \
  -H 'content-type: application/json'

The above command returns the following JSON:

{
  "data" : [
    {
      "id": "f98e556f-623a-41ec-ade2-d7961a429401",
      "name": "message-scheduling",
      "data": 
        {
          "to": [ "+351987654323" ],
          "text": "foo",
          "userId": "e0cdee9b-5cfa-4516-bf73-28ca42ef73d6",
          "apiKeyId": "701ecf71-8321-4d9e-995d-57543115fa4a"
        },
      "state": "created",
      "createdon": "2023-02-07T16:37:31.741Z"
    }
   ]
}

This end-point retrives all your scheduled messages

HTTP Request

GET https://staging.tling.io/api/v0/schedule/message

Query Parameters

Query Parameters	Default	Description
page[size]	30	The page size, maximum 100.
page[number]	1	The page number.
sort	updatedAt	The field to sort by. Use `-field` to sort in descending direction. If available, sort will default to field `updatedAt` in ascending direction.
filter[fields][op]	-	The field to filter by and the filter operation. Fields: `name`, `state`, `createon`, `id`

Schedule a message

To schedule a message:

curl https://staging.tling.io/api/v0/schedule/message \
  -X POST
  -H 'content-type: application/json' \
  -d '{"date": "2025-01-01T12:30:00.000Z", "text": "foo", "to": "["+351999999999"]}'

Returns an HTTP status code of 204 and no JSON body, in case of success.

This endpoint schedule a message.

HTTP Request

POST https://staging.tling.io/api/v0/schedule/message

Query Parameters

Parameters	Default	Description
date	-	Date when the message should be sent.
text	-	The message text. Keep in mind that a single message is limited to 160 characters. If you send a message with more than 160 characters the message is split into more messages. Limit is 1600 characters. Also keep in mind that message with UCS-2 characters have a limit of 70 characters.
to	-	Array of valid phone numbers to send the message.

Update a scheduled message

To update a scheduled message:

curl https://staging.tling.io/api/v0/schedule/message/d8c19ee5-e967-42e5-b88c-15eb0f67a54d \
  -X PATCH
  -H 'content-type: application/json' \
  -d '{"text": "bar", "to": ["+351987653321", "+351987654322"]}'

Returns an HTTP status code of 200 and the following JSON:

{
  "data" : [
    {
      "id": "f98e556f-623a-41ec-ade2-d7961a429401",
      "name": "message-scheduling",
      "data": 
        {
          "to": [ "+351987653321", "+351987654322" ],
          "text": "bar",
          "userId": "e0cdee9b-5cfa-4516-bf73-28ca42ef73d6",
          "apiKeyId": "701ecf71-8321-4d9e-995d-57543115fa4a"
        },
      "state": "created",
      "createdon": "2023-02-07T17:03:00.197Z"
    }
   ]
}

This endpoint updates a scheduled message with given id.

HTTP Request

PATCH https://staging.tling.io/api/v0/schedule/message/:id

Query Parameters

Parameters	Default	Description
date	-	Date when the message should be sent.
text	-	The message text. Keep in mind that a single message is limited to 160 characters. If you send a message with more than 160 characters the message is split into more messages. Limit is 1600 characters. Also keep in mind that message with UCS-2 characters have a limit of 70 characters.
to	-	Array of valid phone numbers to send the message.

Delete a scheduled message

To delete a scheduled message with a given id:

curl https://staging.tling.io/api/v0/schedule/message/d8c19ee5-e967-42e5-b88c-15eb0f67a54d
  -H 'content-type: application/json'

Returns an HTTP status code of 204 and no JSON body, in case of success.

This endpoint delete a scheduled message.

HTTP Request

DELETE https://staging.tling.io/api/v0/schedule/message/:id

Pagination

To list a set of items from 11 to 20:

curl https://app.tling.io/api/v0/messages?page[size]=10&page[number]=2

The above command returns the following JSON:

{
  "data": [],
  "total": 0
}

Collection endpoints with large datasets supports pagination using a page-based strategy.
To control pagination in your requests use the following query parameters:

page[size] sets the size of the page.
page[number] sets the number of the page.

The response to a paginated resource will be a JSON object with two keys:

data is an array of data.
total indicates the total number of resources.

Sorting

To list a sorted collection by foo ascending:

curl https://app.tling.io/api/v0/messages?sort=createdAt

Collection endpoints may support sorting.
To control sorting in your requests use the following query parameters:

sort=field, where field is the top-level field you want to sort by.

By omission, the collection is sorted by the given field in ascending direction. To sort in descending direction prefix the field with -:

sort=-field, where field is the top-level field you want to sort by.

Filtering

To list a filtered collection by field foo with value bar OR biz AND field qux with value qix:

curl https://app.tling.io/api/v0/messages?filter[foo][eq]=bar,biz&filter[qux]=qix

Collection endpoints may support filtering.
To control filtering in your requests use the following query parameters:

filter[field][operation]=value1,value2, where field is the top-level field you want to filter by the given single or list values.

Filters support the following operations:

eq - Equals.
gt - Greater than.
gte - Greater or equal than.
ilk - Like (partial match).
lt - Lesser than.
lte - Lesser or equal than.
neq - Not equal.
n - Null
nn - Not null.

You can create more than one filter in the collection endpoint but only top-level fields are filterable.