v2: Introducing TextIt's new API

API v1 is now deprecated and will be removed on March 1st 2017

A new version of the TextIt API is now available. The purpose of this release is to ensure our operations are performant at scale. TextIt needs an API that is always fast.

We also cleaned it up, providing an interface that's now more consistent across different endpoints. We even put some thought into ensuring this version will be future-proof. 

Changes to look out for...

If you're migrating code that uses our API, be sure to reference the API v2 documentation. Below are the general changes to look out for:

  • All operations which list objects use cursor pagination rather than the typical Django page=1,... etc pagination. This means we do not return a total count value for result sets. Count values tend to be expensive to calculate on very large datasets so this was not sustainable as databases grow.
  • Filtering options are limited to single values. For example, in v1 you could fetch runs like runs.json?id=1131241,436364,464363... but now the 'id' parameter can only contain a single value. If you find yourself needing to fetching lots of objects repeatedly, then it may be better to restructure your code so that you fetch all objects of that type as they are created or modified.
  • When updating objects, the identifier is sent as a query string parameter rather than a field in the JSON body. This is more RESTful and makes POSTs more consistent with GETs and DELETEs, e.g. changing a contact's name:

    POST contacts.json
      "uuid": "1c904f04-af6f-4f2b-89e1-9ebf0c5aef73",
      "name": "Bob"


    POST contacts.json?uuid=1c904f04-af6f-4f2b-89e1-9ebf0c5aef73
      "name": "Bob"
  • Status code usage is more consistent. In v1, the status code 201 was used for both successful create operations and update operations. Trying to update a non-existent object returned 400 but trying to delete the same object returned 404. In v2, the rules for status codes are more explicit:
    • 200: A list or update request was successful.
    • 201: A resource was successfully created (only returned for POST requests).
    • 204: An empty response - used for both successful DELETE requests and POST requests that update multiple resources.
    • 400: The request failed due to invalid parameters. Do not retry with the same values, and the body of the response will contain details.
    • 403: You do not have permission to access this resource.
    • 404: The resource was not found (returned by POST and DELETE methods).
  • Objects are referenced in more consistent ways:
    • messages, runs and broadcasts are always referenced by their id value.
    • contact fields by their key.
    • groups and labels by name or UUID.
    • everything else is referenced by its UUID.
  • Datetime values are always returned with microsecond accuracy (v1 used only millisecond accuracy).
  • Phone numbers must now always include country codes, i.e. we won't accept a URN like "tel:0964153001" but we will accept "tel:+260964153001". 
  • The message bulk action endpoint is limited to 100 messages, so if you need to update more messages than that, make sure you batch your requests.
  • Some vocabulary has been removed. In v1 messages could sometimes be sms and channels could be relayers. In v2 it's always messages and channels.
  • All endpoints are rate-limited. If you're making lots of requests then expect to get some 429 responses. These will include a Retry-After header which provides a number of seconds to wait before retrying.

API Explorer

You can use the API Explorer to test these new operations against your account's data. 

If you have any questions about migrating to v2, don't hesitate to ping us here.