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. 

• 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"
}
  
  Becomes...
  
  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.