Skip to main content
The TingTing API is a REST API. All requests and responses use JSON. You interact with the API over HTTPS using standard HTTP methods.

​
Base URL

All endpoints are relative to: 
https://app.tingting.io/api/v1/

​
Authentication

Every request must include a valid Bearer token in the Authorization header. 
Authorization: Bearer <your_api_token>
Generate your API token from the Authentication endpoints. Tokens are long-lived, but you can rotate them at any time using the Generate API Token endpoint.

​
Request format

Set Content-Type: application/json on all requests that include a body. 
curl --request POST \
  --url https://app.tingting.io/api/v1/campaign/create/ \
  --header 'Authorization: Bearer <your_api_token>' \
  --header 'Content-Type: application/json' \
  --data '{"name": "My Campaign"}'

​
Response format

All responses are JSON. Successful responses return the relevant data at the top level or nested under a named key (for example, results on list endpoints). 
{
  "message": "Operation successful",
  "data": { ... }
}

​
Pagination

List endpoints support cursor-based pagination using limit and offset query parameters.
ParameterTypeDescription
limitintegerMaximum number of results to return per page.
offsetintegerNumber of results to skip before returning results.
Paginated responses include the following fields:
FieldTypeDescription
countintegerTotal number of matching results across all pages.
total_pagesintegerTotal number of pages given the current limit.
nextstring | nullURL of the next page, or null if on the last page.
previousstring | nullURL of the previous page, or null if on the first page.
resultsarrayArray of result objects for the current page.
Example paginated response: 
{
  "count": 42,
  "total_pages": 5,
  "next": "https://app.tingting.io/api/v1/contacts/?limit=10&offset=10",
  "previous": null,
  "results": [
    { "id": 1, "name": "Ram Thapa" },
    { "id": 2, "name": "Sita Sharma" }
  ]
}
If you omit limit and offset, the API returns the default page size. Check individual endpoint documentation for default values.

​
Credit system

TingTing uses a credit-based billing model. Phone calls consume phone credits and SMS messages consume SMS credits. Most call and message responses include your remaining credit balances.
FieldDescription
remaining_sms_creditsSMS credits remaining after the current request.
remaining_phone_creditsPhone credits remaining after the current request.
Requests will fail if you do not have enough credits. Monitor your balances and top up before running large campaigns.

​
HTTP status codes

CodeMeaningWhen it occurs
200OKThe request succeeded.
201CreatedA new resource was created successfully.
400Bad RequestThe request body or parameters are invalid or missing.
401UnauthorizedThe token is missing, expired, or invalid.
403ForbiddenYou are authenticated but lack permission for this resource.
404Not FoundThe requested resource does not exist.
429Too Many RequestsYou have exceeded the rate limit. Retry after a short delay.
500Internal Server ErrorAn unexpected error occurred on the server.

​
Error responses

Errors return a JSON body with a message or detail field describing what went wrong. 
{
  "message": "No refresh token provided"
}

{
  "detail": "Invalid token payload."
}
Some endpoints return errors under a detail key while others use message. Check the specific endpoint reference for the exact error shape.