API Documentation

Archives Endpoint

This endpoint allows you to list the data archives associated with your account.

Listing Archives

A GET returns the archives for your organization with the following fields.

• archive_type - the type of the archive, one of message or run (filterable as archive_type).
• start_date - the UTC date of the archive (string) (filterable as before and after).
• period - daily for daily archives, monthly for monthly archives (filterable as period).
• record_count - number of records in the archive (int).
• size - size of the gzipped archive content (int).
• hash - MD5 hash of the gzipped archive (string).
• download_url - temporary download URL of the archive (string).

Example:

GET /api/v2/archives.json?archive_type=message&before=2017-05-15&period=daily

Response is a list of the archives on your account:

{
  "next": null,
  "previous": null,
  "count": 248,
  "results": [
    {
      "archive_type": "message",
      "start_date": "2017-02-20",
      "period": "daily",
      "record_count": 1432,
      "size": 2304,
      "hash": "feca9988b7772c003204a28bd741d0d0",
      "download_url": "https://..."
    },
    ...
  ]
}

Boundaries Endpoint

This endpoint allows you to list the administrative boundaries for the country associated with your account, along with the simplified GPS geometry for those boundaries in GEOJSON format.

Listing Boundaries

A GET returns the boundaries for your organization with the following fields. To include geometry, specify geometry=true.

• osm_id - the OSM ID for this boundary prefixed with the element type (string).
• name - the name of the administrative boundary (string).
• parent - the id of the containing parent of this boundary or null if this boundary is a country (string).
• level - the level: 0 for country, 1 for state, 2 for district (int).
• geometry - the geometry for this boundary, which will usually be a MultiPolygon (GEOJSON).

Note that including geometry may produce a very large result so it is recommended to cache the results on the client side.

Example:

GET /api/v2/boundaries.json?geometry=true

Response is a list of the boundaries on your account:

{
  "next": null,
  "previous": null,
  "results": [
    {
      "osm_id": "1708283",
      "name": "Kigali City",
      "parent": {"osm_id": "171496", "name": "Rwanda"},
      "level": 1,
      "aliases": ["Kigari"],
      "geometry": {
        "type": "MultiPolygon",
        "coordinates": [
          [
            [
              [7.5251021, 5.0504713],
              [7.5330272, 5.0423498]
            ]
          ]
        ]
      }
    },
    ...
  ]
}

Broadcasts Endpoint

This endpoint allows you to send new message broadcasts and list existing broadcasts in your account.

Listing Broadcasts

A GET returns the outgoing message activity for your organization, listing the most recent messages first.

• id - the id of the broadcast (int), filterable as id.
• urns - the URNs that received the broadcast (array of strings).
• contacts - the contacts that received the broadcast (array of objects).
• groups - the groups that received the broadcast (array of objects).
• text - the message text translations (dict of strings).
• attachments - the attachment translations (dict of lists of strings).
• base_language - the default translation language (string).
• status - the status, one of pending, queued, started, completed, failed, interrupted.
• created_on - when this broadcast was created (datetime) (filterable as before and after).

Example:

GET /api/v2/broadcasts.json

Response is a list of recent broadcasts:

{
  "next": null,
  "previous": null,
  "results": [
    {
      "id": 123456,
      "urns": ["tel:+250788123123", "tel:+250788123124"],
      "contacts": [{"uuid": "09d23a05-47fe-11e4-bfe9-b8f6b119e9ab", "name": "Joe"}],
      "groups": [],
      "text": {"eng": "hello world"},
      "attachments": {"eng": []},
      "base_language": "eng",
      "created_on": "2013-03-02T17:28:12.123456Z"
    },
    ...
  ]
}

Sending Broadcasts

A POST allows you to create and send new broadcasts. Attachments are media object UUIDs returned from POSTing to the media endpoint.

• urns - the URNs of contacts to send to (array of up to 100 strings, optional).
• contacts - the UUIDs of contacts to send to (array of up to 100 strings, optional).
• groups - the UUIDs of contact groups to send to (array of up to 100 strings, optional).
• text - the message text translations (dict of strings).
• attachments - the attachment translations (dict of lists of strings).
• base_language - the default translation language (string, optional).

Example:

POST /api/v2/broadcasts.json

{
  "urns": ["tel:+250788123123", "tel:+250788123124"],
  "contacts": ["09d23a05-47fe-11e4-bfe9-b8f6b119e9ab"],
  "text": {"eng": "Hello @contact.name!", "spa": "Hola @contact.name!"},
  "base_language": "eng"
}

You will receive a response containing the message broadcast created:

{
  "id": 1234,
  "urns": ["tel:+250788123123", "tel:+250788123124"],
  "contacts": [{"uuid": "09d23a05-47fe-11e4-bfe9-b8f6b119e9ab", "name": "Joe"}],
  "groups": [],
  "text": {"eng": "Hello @contact.name!", "spa": "Hola @contact.name!"},
  "attachments": {"eng": [], "spa": []},
  "base_language": "eng",
  "created_on": "2013-03-02T17:28:12.123456Z"
}

Campaigns Endpoint

This endpoint allows you to list campaigns in your account.

Listing Campaigns

A GET returns the campaigns, listing the most recently created campaigns first.

• uuid - the UUID of the campaign (string), filterable as uuid.
• name - the name of the campaign (string).
• archived - whether this campaign is archived (boolean).
• group - the group this campaign operates on (object).
• created_on - when the campaign was created (datetime), filterable as before and after.

Example:

GET /api/v2/campaigns.json

Response is a list of the campaigns on your account:

{
  "next": null,
  "previous": null,
  "results": [
    {
      "uuid": "f14e4ff0-724d-43fe-a953-1d16aefd1c00",
      "name": "Reminders",
      "archived": false,
      "group": {"uuid": "7ae473e8-f1b5-4998-bd9c-eb8e28c92fa9", "name": "Reporters"},
      "created_on": "2013-08-19T19:11:21.088Z"
    },
    ...
  ]
}

Adding Campaigns

A POST can be used to create a new campaign, by sending the following data. Don't specify a UUID as this will be generated for you.

• name - the name of the campaign (string, required).
• group - the UUID of the contact group this campaign will be run against (string, required).

Example:

POST /api/v2/campaigns.json

{
  "name": "Reminders",
  "group": "7ae473e8-f1b5-4998-bd9c-eb8e28c92fa9"
}

You will receive a campaign object as a response if successful:

{
  "uuid": "f14e4ff0-724d-43fe-a953-1d16aefd1c00",
  "name": "Reminders",
  "archived": false,
  "group": {"uuid": "7ae473e8-f1b5-4998-bd9c-eb8e28c92fa9", "name": "Reporters"},
  "created_on": "2013-08-19T19:11:21.088Z"
}

Updating Campaigns

A POST can also be used to update an existing campaign if you specify its UUID in the URL.

Example:

POST /api/v2/campaigns.json?uuid=f14e4ff0-724d-43fe-a953-1d16aefd1c00

{
  "name": "Reminders II",
  "group": "7ae473e8-f1b5-4998-bd9c-eb8e28c92fa9"
}

Campaign Events Endpoint

This endpoint allows you to list campaign events in your account.

Listing Campaign Events

A GET returns the campaign events, listing the most recently created events first.

• uuid - the UUID of the campaign event (string), filterable as uuid.
• campaign - the UUID and name of the campaign (object), filterable as campaign with UUID.
• relative_to - the key and label of the date field this event is based on (object).
• offset - the offset from our contact field (positive or negative integer).
• unit - the unit for our offset, one of minutes, hours, days or weeks.
• delivery_hour - the hour of the day to deliver the message (integer 0-24, -1 indicates send at the same hour as the contact field).
• message - the message to send to the contact by language (object).
• flow - the UUID and name of the flow if this is a flow event (object).
• created_on - when the event was created (datetime).

Example:

GET /api/v2/campaign_events.json

Response is a list of the campaign events on your account:

{
  "next": null,
  "previous": null,
  "results": [
    {
      "uuid": "f14e4ff0-724d-43fe-a953-1d16aefd1c00",
      "campaign": {"uuid": "f14e4ff0-724d-43fe-a953-1d16aefd1c00", "name": "Reminders"},
      "relative_to": {"key": "registration", "name": "Registration Date"},
      "offset": 7,
      "unit": "days",
      "delivery_hour": 9,
      "flow": {"uuid": "09d23a05-47fe-11e4-bfe9-b8f6b119e9ab", "name": "Survey"},
      "message": null,
      "created_on": "2013-08-19T19:11:21.088Z"
    },
    ...
  ]
}

Adding Campaign Events

A POST can be used to create a new campaign event, by sending the following data. Don't specify a UUID as this will be generated for you.

• campaign - the UUID of the campaign this event should be part of (string, can't be changed for existing events).
• relative_to - the field key that this event will be relative to (string).
• offset - the offset from our contact field (positive or negative integer).
• unit - the unit for our offset (minutes, hours, days or weeks).
• delivery_hour - the hour of the day to deliver the message (integer 0-24, -1 indicates send at the same hour as the field).
• message - the message to send to the contact (string, required if flow is not specified).
• flow - the UUID of the flow to start the contact down (string, required if message is not specified).

Example:

POST /api/v2/campaign_events.json

{
  "campaign": "f14e4ff0-724d-43fe-a953-1d16aefd1c00",
  "relative_to": "last_hit",
  "offset": 160,
  "unit": "weeks",
  "delivery_hour": -1,
  "message": "Feeling sick and helpless, lost the compass where self is."
}

You will receive an event object as a response if successful:

{
  "uuid": "6a6d7531-6b44-4c45-8c33-957ddd8dfabc",
  "campaign": {"uuid": "f14e4ff0-724d-43fe-a953-1d16aefd1c00", "name": "Hits"},
  "relative_to": {"key": "last_hit", "name": "Last Hit"},
  "offset": 160,
  "unit": "W",
  "delivery_hour": -1,
  "message": {"eng": "Feeling sick and helpless, lost the compass where self is."},
  "flow": null,
  "created_on": "2013-08-19T19:11:21.088453Z"
}

Updating Campaign Events

A POST can also be used to update an existing campaign event if you specify its UUID in the URL.

Example:

POST /api/v2/campaign_events.json?uuid=6a6d7531-6b44-4c45-8c33-957ddd8dfabc

{
  "relative_to": "last_hit",
  "offset": 100,
  "unit": "weeks",
  "delivery_hour": -1,
  "message": "Feeling sick and helpless, lost the compass where self is."
}

Deleting Campaign Events

A DELETE can be used to delete a campaign event if you specify its UUID in the URL.

Example:

DELETE /api/v2/campaign_events.json?uuid=6a6d7531-6b44-4c45-8c33-957ddd8dfabc

You will receive either a 204 response if an event was deleted, or a 404 response if no matching event was found.

Channels Endpoint

This endpoint allows you to list channels in your account.

Listing Channels

A GET returns the list of channels for your organization, in the order of last created. Note that for Android devices, all status information is as of the last time it was seen and can be null before the first sync.

• uuid - the UUID of the channel (string), filterable as uuid.
• name - the name of the channel (string).
• address - the address (e.g. phone number, Twitter handle) of the channel (string), filterable as address.
• country - which country the sim card for this channel is registered for (string, two letter country code).
• device - information about the device if this is an Android channel:
  • name - the name of the device (string).
  • power_level - the power level of the device (int).
  • power_status - the power status, either CHA (charging) or DIS (discharging) (string).
  • power_source - the source of power as reported by Android (string).
  • network_type - the type of network the device is connected to as reported by Android (string).
• last_seen - the datetime when this channel was last seen (datetime).
• created_on - the datetime when this channel was created (datetime).

Example:

GET /api/v2/channels.json

Response containing the channels for your organization:

{
    "next": null,
    "previous": null,
    "results": [
    {
        "uuid": "09d23a05-47fe-11e4-bfe9-b8f6b119e9ab",
        "name": "Android Phone",
        "address": "+250788123123",
        "country": "RW",
        "device": {
            "name": "Nexus 5X",
            "power_level": 99,
            "power_status": "STATUS_DISCHARGING",
            "power_source": "BATTERY",
            "network_type": "WIFI",
        },
        "last_seen": "2016-03-01T05:31:27.456",
        "created_on": "2014-06-23T09:34:12.866",
    }]
}

Classifiers Endpoint

This endpoint allows you to list the active natural language understanding classifiers on your account.

Listing Classifiers

A GET returns the classifiers for your organization, most recent first.

• uuid - the UUID of the classifier, filterable as uuid.
• name - the name of the classifier.
• intents - the list of intents this classifier exposes (list of strings).
• type - the type of the classifier, one of wit, luis or bothub.
• created_on - when this classifier was created.

Example:

GET /api/v2/classifiers.json

Response:

{
    "next": null,
    "previous": null,
    "results": [
    {
        "uuid": "9a8b001e-a913-486c-80f4-1356e23f582e",
        "name": "Temba Classifier",
        "intents": ["book_flight", "book_car"],
        "type": "wit",
        "created_on": "2013-02-27T09:06:15.456"
    },
    ...
    ]
}

Contacts Endpoint

This endpoint allows you to list, create, update and delete contacts in your account.

Listing Contacts

A GET returns the list of contacts for your organization, in the order of last modified.

• uuid - the UUID of the contact (string), filterable as uuid.
• name - the name of the contact (string).
• status - the status of the contact, one of active, blocked, stopped or archived.
• language - the preferred language of the contact (string).
• urns - the URNs associated with the contact (string array), filterable as urn.
• groups - the UUIDs of any groups the contact is part of (array of objects), filterable as group with group name or UUID.
• fields - any contact fields on this contact (object).
• flow - the flow that the contact is currently in, if any (object).
• created_on - when this contact was created (datetime).
• modified_on - when this contact was last modified (datetime), filterable as before and after.
• last_seen_on - when this contact last communicated with us (datetime).

Example:

GET /api/v2/contacts.json

Response containing the contacts for your organization:

{
    "next": null,
    "previous": null,
    "results": [
    {
        "uuid": "09d23a05-47fe-11e4-bfe9-b8f6b119e9ab",
        "name": "Ben Haggerty",
        "status": "active",
        "language": null,
        "urns": ["tel:+250788123123"],
        "groups": [{"name": "Customers", "uuid": "5a4eb79e-1b1f-4ae3-8700-09384cca385f"}],
        "fields": {
            "nickname": "Macklemore",
            "side_kick": "Ryan Lewis"
        },
        "flow": {"uuid": "c1bc5fcf-3e27-4265-97bf-f6c3a385c2d6", "name": "Registration"},
        "created_on": "2015-11-11T13:05:57.457742Z",
        "modified_on": "2020-08-11T13:05:57.576056Z",
        "last_seen_on": "2020-07-11T13:05:57.576056Z"
    }]
}

Adding Contacts

You can add a new contact to your account by sending a POST request to this URL with the following JSON data:

• name - the full name of the contact (string, optional).
• language - the preferred language for the contact (3 letter iso code, optional).
• urns - a list of URNs you want associated with the contact (array of up to 100 strings, optional).
• groups - a list of the UUIDs of any groups this contact is part of (array of up to 100 strings, optional).
• fields - the contact fields you want to set or update on this contact (dictionary of up to 100 items, optional).

Example:

POST /api/v2/contacts.json

{
    "name": "Ben Haggerty",
    "language": "eng",
    "urns": ["tel:+250788123123", "twitter:ben"],
    "groups": ["6685e933-26e1-4363-a468-8f7268ab63a9"],
    "fields": {
        "nickname": "Macklemore",
        "side_kick": "Ryan Lewis"
    }
}

You will receive a contact object as a response if successful:

{
    "uuid": "09d23a05-47fe-11e4-bfe9-b8f6b119e9ab",
    "name": "Ben Haggerty",
    "status": "active",
    "language": "eng",
    "urns": ["tel:+250788123123", "twitter:ben"],
    "groups": [{"name": "Devs", "uuid": "6685e933-26e1-4363-a468-8f7268ab63a9"}],
    "fields": {
        "nickname": "Macklemore",
        "side_kick": "Ryan Lewis"
    },
    "flow": null,
    "created_on": "2015-11-11T13:05:57.457742Z",
    "modified_on": "2015-11-11T13:05:57.576056Z",
    "last_seen_on": null
}

Updating Contacts

A POST can also be used to update an existing contact if you specify either its UUID or one of its URNs in the URL. Only those fields included in the body will be changed on the contact.

If providing a URN in the URL then don't include URNs in the body. Also note that we will create a new contact if there is no contact with that URN. You will receive a 201 response if this occurs.

Examples:

POST /api/v2/contacts.json?uuid=09d23a05-47fe-11e4-bfe9-b8f6b119e9ab

{
    "name": "Ben Haggerty",
    "language": "eng",
    "urns": ["tel:+250788123123", "twitter:ben"],
    "groups": [{"name": "Devs", "uuid": "6685e933-26e1-4363-a468-8f7268ab63a9"}],
    "fields": {}
}

POST /api/v2/contacts.json?urn=tel%3A%2B250783835665

{
    "fields": {"nickname": "Ben"}
}

Deleting Contacts

A DELETE can also be used to delete an existing contact if you specify either its UUID or one of its URNs in the URL.

Examples:

DELETE /api/v2/contacts.json?uuid=27fb583b-3087-4778-a2b3-8af489bf4a93
DELETE /api/v2/contacts.json?urn=tel%3A%2B250783835665

You will receive either a 204 response if a contact was deleted, or a 404 response if no matching contact was found.

Contact Actions Endpoint

Bulk Contact Updating

A POST can be used to perform an action on a set of contacts in bulk.

• contacts - the contact UUIDs or URNs (array of up to 100 strings).
• action - the action to perform, a string one of:
  • add - add the contacts to the given group.
  • remove - remove the contacts from the given group.
  • block - block the contacts.
  • unblock - unblock the contacts.
  • interrupt - interrupt and end any of the contacts' active flow runs.
  • delete - permanently delete the contacts.
• group - the UUID or name of a contact group (string, optional).

Example:

POST /api/v2/contact_actions.json

{
    "contacts": ["7acfa6d5-be4a-4bcc-8011-d1bd9dfasff3", "tel:+250783835665"],
    "action": "add",
    "group": "Testers"
}

You will receive an empty response with status code 204 if successful.

Fields Endpoint

This endpoint allows you to list custom contact fields in your account.

Listing Fields

A GET returns the list of custom contact fields for your organization, in the order of last created.

• key - the unique key of this field (string), filterable as key.
• name - the display name of this field (string).
• type - the data type of this field, one of text, number, datetime, state, district or ward.

Example:

GET /api/v2/fields.json

Response containing the fields for your organization:

{
    "next": null,
    "previous": null,
    "results": [
        {
            "key": "nick_name",
            "name": "Nick name",
            "type": "text"
        },
        ...
    ]
}

Adding Fields

A POST can be used to create a new contact field. Don't specify a key as this will be generated for you.

• name - the display name (string)
• type - one of the data type codes (string)

Example:

POST /api/v2/fields.json

{
    "name": "Nick name",
    "type": "text"
}

You will receive a field object (with the new field key) as a response if successful:

{
    "key": "nick_name",
    "name": "Nick name",
    "type": "text"
}

Updating Fields

A POST can also be used to update an existing field if you include its key in the URL.

Example:

POST /api/v2/fields.json?key=nick_name

{
    "name": "New label",
    "type": "text"
}

You will receive the updated field object as a response if successful:

{
    "key": "nick_name",
    "name": "New label",
    "type": "text"
}

Flow Starts Endpoint

This endpoint allows you to list manual flow starts in your account, and add or start contacts in a flow.

Listing Flow Starts

By making a GET request you can list all the manual flow starts on your organization, in the order of last modified. Each flow start has the following attributes:

• uuid - the UUID of this flow start (string), filterable as uuid.
• flow - the flow which was started (object).
• contacts - the list of contacts that were started in the flow (objects).
• groups - the list of groups that were started in the flow (objects).
• status - the status, one of pending, queued, started, completed, failed, interrupted.
• params - the dictionary of extra parameters passed to the flow start (object).
• created_on - the datetime when this flow start was created (datetime).
• modified_on - the datetime when this flow start was modified (datetime).

Example:

GET /api/v2/flow_starts.json

Response is the list of flow starts on your organization, most recently modified first:

{
    "next": "http://example.com/api/v2/flow_starts.json?cursor=cD0yMDE1LTExLTExKzExJTNBM40NjQlMkIwMCUzRv",
    "previous": null,
    "results": [
        {
            "uuid": "09d23a05-47fe-11e4-bfe9-b8f6b119e9ab",
            "flow": {"uuid": "f5901b62-ba76-4003-9c62-72fdacc1b7b7", "name": "Thrift Shop"},
            "groups": [
                {"uuid": "f5901b62-ba76-4003-9c62-72fdacc1b7b7", "name": "Ryan & Macklemore"}
            ],
            "contacts": [
                {"uuid": "f5901b62-ba76-4003-9c62-fjjajdsi15553", "name": "Wanz"}
            ],
            "status": "complete",
            "params": {
                "first_name": "Ryan",
                "last_name": "Lewis"
            },
            "created_on": "2013-08-19T19:11:21.082Z",
            "modified_on": "2013-08-19T19:11:21.082Z"
        },
        ...
    ]
}

Starting contacts down a flow

By making a POST request with the contacts, groups and URNs you want to start down a flow you can trigger a flow start. Note that that contacts will be added to the flow asynchronously, you can use the runs endpoint to monitor the runs created by this start.

• flow - the UUID of the flow to start contacts in (required)
• groups - the UUIDs of the groups you want to start in this flow (array of up to 100 strings, optional)
• contacts - the UUIDs of the contacts you want to start in this flow (array of up to 100 strings, optional)
• urns - the URNs you want to start in this flow (array of up to 100 strings, optional)
• restart_participants - whether to restart participants already in this flow (optional, defaults to true)
• exclude_active - whether to exclude contacts currently in other flow (optional, defaults to false)
• params - extra parameters to pass to the flow start (object, accessible via @trigger.params in the flow)

Example:

POST /api/v2/flow_starts.json

{
    "flow": "f5901b62-ba76-4003-9c62-72fdacc1b7b7",
    "groups": ["f5901b62-ba76-4003-9c62-72fdacc15515"],
    "contacts": ["f5901b62-ba76-4003-9c62-fjjajdsi15553"],
    "urns": ["twitter:sirmixalot", "tel:+12065551212"],
    "params": {"first_name": "Ryan", "last_name": "Lewis"}
}

Response is the created flow start:

{
    "uuid": "09d23a05-47fe-11e4-bfe9-b8f6b119e9ab",
    "flow": {"uuid": "f5901b62-ba76-4003-9c62-72fdacc1b7b7", "name": "Thrift Shop"},
    "groups": [
        {"uuid": "c24813d2-3bc7-4467-8916-255b6525c6be", "name": "Ryan & Macklemore"}
    ],
    "contacts": [
        {"uuid": "f1ea776e-c923-4c1a-b3a3-0c466932b2cc", "name": "Wanz"}
    ],
    "status": "pending",
    "params": {
        "first_name": "Ryan",
        "last_name": "Lewis"
    },
    "created_on": "2013-08-19T19:11:21.082Z",
    "modified_on": "2013-08-19T19:11:21.082Z"
}

Flows Endpoint

This endpoint allows you to list flows in your account.

Listing Flows

A GET returns the list of flows for your organization, in the order of last created.

• uuid - the UUID of the flow (string), filterable as uuid.
• name - the name of the flow (string).
• type - the type of the flow (one of "message", "voice", "survey"), filterable as type.
• archived - whether this flow is archived (boolean), filterable as archived.
• labels - the labels for this flow (array of objects).
• expires - the time (in minutes) when this flow's inactive contacts will expire (integer).
• runs - the counts of active, completed, interrupted and expired runs (object).
• results - the results that this flow may create (array).
• parent_refs - the keys of the parent flow results referenced in this flow (array).
• created_on - when this flow was created (datetime).
• modified_on - when this flow was last modified (datetime), filterable as before and after.

Example:

GET /api/v2/flows.json

Response containing the flows for your organization:

{
    "next": null,
    "previous": null,
    "results": [
        {
            "uuid": "5f05311e-8f81-4a67-a5b5-1501b6d6496a",
            "name": "Survey",
            "type": "message",
            "archived": false,
            "labels": [{"name": "Important", "uuid": "5a4eb79e-1b1f-4ae3-8700-09384cca385f"}],
            "expires": 600,
            "runs": {
                "active": 47,
                "completed": 123,
                "interrupted": 2,
                "expired": 34
            },
            "results": [
                {
                    "key": "has_water",
                    "name": "Has Water",
                    "categories": ["Yes", "No", "Other"],
                    "node_uuids": ["99afcda7-f928-4d4a-ae83-c90c96deb76d"]
                }
            ],
            "parent_refs": [],
            "created_on": "2016-01-06T15:33:00.813162Z",
            "modified_on": "2017-01-07T13:14:00.453567Z"
        },
        ...
    ]
}

Globals Endpoint

This endpoint allows you to list, create, and update active globals on your account.

Listing Globals

A GET returns the globals for your organization, most recently modified first.

• key - the key of the global.
• name - the name of the global.
• value - the value of the global.
• modified_on - when this global was modified.

Example:

Response:

{
"next": null,
"previous": null,
"results": [
{
"key": "org_name",
"name": "Org Name",
"value": "Acme Ltd",
"modified_on": "2013-02-27T09:06:15.456"
},
...
]
}

Adding a Global

A POST can be used to create a new Global. Don't specify a key as this will be generated for you.

• name - the name of the global
• value - the value of the global

Example:

{
"name": "Org Name",
"value": "Acme Ltd"
}

You will receive a global object as a response if successful:

{
"key": "org_name",
"name": "Org Name",
"value": "Acme Ltd",
"modified_on": "2013-02-27T09:06:15.456"
}

Updating a Global

A POST can also be used to update an existing global if you specify its key in the URL.

Example:

{
"value": "Acme Ltd"
}

You will receive the updated global object as a response if successful:

{
"key": "org_name",
"name": "Org Name",
"value": "Acme Ltd",
"modified_on": "2013-02-27T09:06:15.456"
}

Groups Endpoint

This endpoint allows you to list, create, update and delete contact groups in your account.

Listing Groups

A GET returns the list of contact groups for your organization, in the order of last created.

• uuid - the UUID of the group (string), filterable as uuid.
• name - the name of the group (string), filterable as name.
• query - the query if a smart group (string).
• status - the status, one of initializing, evaluating or ready.
• system - whether this is a system group that can't be edited (bool).
• count - the number of contacts in the group (int).

Example:

Response containing the groups for your organization:

{
"next": null,
"previous": null,
"results": [
{
"uuid": "5f05311e-8f81-4a67-a5b5-1501b6d6496a",
"name": "Reporters",
"query": null,
"status": "ready",
"system": false,
"count": 315
},
...
]
}

Adding a Group

A POST can be used to create a new contact group. Don't specify a UUID as this will be generated for you.

• name - the group name (string)

Example:

{
"name": "Reporters"
}

You will receive a group object as a response if successful:

{
"uuid": "5f05311e-8f81-4a67-a5b5-1501b6d6496a",
"name": "Reporters",
"count": 0,
"query": null
}

Updating a Group

A POST can also be used to update an existing contact group if you specify its UUID in the URL.

Example:

{
"name": "Checked"
}

You will receive the updated group object as a response if successful:

{
"uuid": "5f05311e-8f81-4a67-a5b5-1501b6d6496a",
"name": "Checked",
"count": 0,
"query": null
}

Deleting a Group

A DELETE can be used to delete a contact group if you specify its UUID in the URL.

Notes: cannot delete groups with associated active campaigns or triggers. You first need to delete related objects through the web interface

Example:

You will receive either a 204 response if a group was deleted, or a 404 response if no matching group was found.

Labels Endpoint

This endpoint allows you to list, create, update and delete message labels in your account.

Listing Labels

A GET returns the list of message labels for your organization, in the order of last created.

• uuid - the UUID of the label (string), filterable as uuid.
• name - the name of the label (string), filterable as name.
• count - the number of messages with this label (int).

Example:

Response containing the labels for your organization:

{
"next": null,
"previous": null,
"results": [
{
"uuid": "5f05311e-8f81-4a67-a5b5-1501b6d6496a",
"name": "Screened",
"count": 315
},
...
]
}

Adding a Label

A POST can be used to create a new message label. Don't specify a UUID as this will be generated for you.

• name - the label name (string)

Example:

{
"name": "Screened"
}

You will receive a label object as a response if successful:

{
"uuid": "fdd156ca-233a-48c1-896d-a9d594d59b95",
"name": "Screened",
"count": 0
}

Updating a Label

A POST can also be used to update an existing message label if you specify its UUID in the URL.

Example:

{
"name": "Checked"
}

You will receive the updated label object as a response if successful:

{
"uuid": "fdd156ca-233a-48c1-896d-a9d594d59b95",
"name": "Checked",
"count": 0
}

Deleting a Label

A DELETE can be used to delete a message label if you specify its UUID in the URL.

Example:

You will receive either a 204 response if a label was deleted, or a 404 response if no matching label was found.

Media Endpoint

This endpoint allows you to upload new media objects for use as attachments on messages.

Uploading Media

A POST can be used to upload a new media object.

• file - the file data (bytes)

You will receive a media object as a response if successful:

{
"uuid": "fdd156ca-233a-48c1-896d-a9d594d59b95",
"content_type": "image/jpeg",
"url": "https://...test.jpg",
"filename": "test.jpg",
"size": 23452
}

Messages Endpoint

This endpoint allows you to list messages in your account.

Listing Messages

A GET returns the messages for your organization, filtering them as needed. Each message has the following attributes:

• id - the ID of the message (int), filterable as id.
• broadcast - the id of the broadcast (int), filterable as broadcast.
• contact - the UUID and name of the contact (object), filterable as contact with UUID.
• urn - the URN of the sender or receiver, depending on direction (string).
• channel - the UUID and name of the channel that handled this message (object).
• direction - the direction of the message (one of incoming or outgoing).
• type - the type of the message (one of text, optin or voice).
• status - the status of the message, one of:
  • queued - incoming that has not yet been handled, or outgoing message that has not yet been sent.
  • handled - incoming that has been handled by a flow or put in the inbox.
  • wired - outgoing that has been wired to a channel.
  • sent - outgoing for which channel has confirmed that it has been sent.
  • delivered - outgoing for which channel has confirmed that it has been delivered to the contact.
  • read - outgoing for which channel has confirmed that it has been read by the contact.
  • errored - outgoing that has errored but will be retried.
  • failed - outgoing that has errored too many times and will no longer be retried.
• visibility - the visibility of the message (one of visible, archived or deleted)
• text - the text of the message received (string). Note this is the logical view and the message may have been received as multiple physical messages.
• attachments - the attachments on the message (array of objects).
• labels - any labels set on this message (array of objects), filterable as label with label name or UUID.
• flow - the UUID and name of the flow if message was part of a flow (object, optional).
• created_on - when this message was either received by the channel or created (datetime) (filterable as before and after).
• sent_on - for outgoing messages, when the channel sent the message (null if not yet sent or an incoming message) (datetime).
• modified_on - when the message was last modified (datetime).

You can also filter by folder where folder is one of inbox, flows, archived, outbox, sent or failed. Note that you cannot filter by more than one of contact, folder, label or broadcast at the same time. The sort order for the sent folder is the sent date. All other requests are sorted by the message creation date. Without any parameters this endpoint will return all incoming and outgoing messages ordered by creation date.

Example:

Response is the list of messages for that contact, most recently created first:

{
"next": "http://example.com/api/v2/messages.json?folder=inbox&cursor=cD0yMDE1LTExLTExKzExJTNBM40NjQlMkIwMCUzRv",
"previous": null,
"results": [
{
"id": 4105426,
"broadcast": 2690007,
"contact": {"uuid": "d33e9ad5-5c35-414c-abd4-e7451c69ff1d", "name": "Bob McFlow"},
"urn": "tel:+1234567890",
"channel": {"uuid": "9a8b001e-a913-486c-80f4-1356e23f582e", "name": "Vonage"},
"direction": "out",
"type": "text",
"status": "wired",
"visibility": "visible",
"text": "How are you?",
"attachments": [{"content_type": "audio/wav", "url": "http://domain.com/recording.wav"}],
"labels": [{"name": "Important", "uuid": "5a4eb79e-1b1f-4ae3-8700-09384cca385f"}],
"flow": {"uuid": "254fd2ff-4990-4621-9536-0a448d313692", "name": "Registration"},
"created_on": "2016-01-06T15:33:00.813162Z",
"sent_on": "2016-01-06T15:35:03.675716Z",
"modified_on": "2016-01-06T15:35:03.675716Z"
},
...
]
}

Sending a Message

A POST can be used to create and send a new message. Attachments are media object UUIDs returned from POSTing to the media endpoint.

• contact - the UUID of the contact (string)
• text - the text of the message (string)
• attachments - the attachments of the message (list of strings, maximum 10)

Example:

{
"contact": "d33e9ad5-5c35-414c-abd4-e7451c69ff1d",
"text": "Hi Bob",
"attachments": []
}

You will receive the new message object as a response if successful:

{
"id": 4105426,
"broadcast": null,
"contact": {"uuid": "d33e9ad5-5c35-414c-abd4-e7451c69ff1d", "name": "Bob McFlow"},
"urn": "tel:+1234567890",
"channel": {"uuid": "9a8b001e-a913-486c-80f4-1356e23f582e", "name": "Vonage"},
"direction": "out",
"type": "text",
"status": "queued",
"visibility": "visible",
"text": "Hi Bob",
"attachments": [],
"labels": [],
"flow": null,
"created_on": "2023-01-06T15:33:00.813162Z",
"sent_on": "2023-01-06T15:35:03.675716Z",
"modified_on": "2023-01-06T15:35:03.675716Z"
}

Message Actions Endpoint

Bulk Message Updating

A POST can be used to perform an action on a set of messages in bulk.

• messages - the message ids (array of up to 100 integers).
• action - the action to perform, a string one of:
  • label - apply the given label to the messages.
  • unlabel - remove the given label from the messages.
  • archive - archive the messages.
  • restore - restore the messages if they are archived.
  • delete - permanently delete the messages.
• label - the UUID or name of an existing label (string, optional).
• label_name - the name of a label which can be created if it doesn't exist (string, optional).

If labelling or unlabelling messages using label you will get an error response (400) if the label doesn't exist. If labelling with label_name the label will be created if it doesn't exist, and if unlabelling it is ignored if it doesn't exist.

Example:

{
"messages": [1234, 2345, 3456],
"action": "label",
"label": "Testing"
}

You will receive an empty response with status code 204 if successful. In the case that some messages couldn't be updated because they no longer exist, the status code will be 200 and the body will include the failed message ids:

Example response:

{"failures": [2345, 3456]}

Channels Endpoint

This endpoint allows you to list channels in your account.

Listing Channels

A GET returns the list of channels for your organization, in the order of last created. Note that for Android devices, all status information is as of the last time it was seen and can be null before the first sync.

• uuid - the UUID of the channel (string), filterable as uuid.
• name - the name of the channel (string).
• address - the address (e.g. phone number, Twitter handle) of the channel (string), filterable as address.
• country - which country the sim card for this channel is registered for (string, two letter country code).
• device - information about the device if this is an Android channel:
  • name - the name of the device (string).
  • power_level - the power level of the device (int).
  • power_status - the power status, either CHA (charging) or DIS (discharging) (string).
  • power_source - the source of power as reported by Android (string).
  • network_type - the type of network the device is connected to as reported by Android (string).
• last_seen - the datetime when this channel was last seen (datetime).
• created_on - the datetime when this channel was created (datetime).

Example:

Response containing the channels for your organization:

{
    "next": null,
    "previous": null,
    "results": [
    {
        "uuid": "09d23a05-47fe-11e4-bfe9-b8f6b119e9ab",
        "name": "Android Phone",
        "address": "+250788123123",
        "country": "RW",
        "device": {
            "name": "Nexus 5X",
            "power_level": 99,
            "power_status": "STATUS_DISCHARGING",
            "power_source": "BATTERY",
            "network_type": "WIFI",
        },
        "last_seen": "2016-03-01T05:31:27.456",
        "created_on": "2014-06-23T09:34:12.866",
    }]
}

Classifiers Endpoint

This endpoint allows you to list the active natural language understanding classifiers on your account.

Listing Classifiers

A GET returns the classifiers for your organization, most recent first.

• uuid - the UUID of the classifier, filterable as uuid.
• name - the name of the classifier.
• intents - the list of intents this classifier exposes (list of strings).
• type - the type of the classifier, one of wit, luis or bothub.
• created_on - when this classifier was created.

Example:

Response:

{
    "next": null,
    "previous": null,
    "results": [
    {
        "uuid": "9a8b001e-a913-486c-80f4-1356e23f582e",
        "name": "Temba Classifier",
        "intents": ["book_flight", "book_car"],
        "type": "wit",
        "created_on": "2013-02-27T09:06:15.456"
    },
    ...
    ]
}

Contacts Endpoint

This endpoint allows you to list, create, update and delete contacts in your account.

Listing Contacts

A GET returns the list of contacts for your organization, in the order of last modified.

• uuid - the UUID of the contact (string), filterable as uuid.
• name - the name of the contact (string).
• status - the status of the contact, one of active, blocked, stopped or archived.
• language - the preferred language of the contact (string).
• urns - the URNs associated with the contact (string array), filterable as urn.
• groups - the UUIDs of any groups the contact is part of (array of objects), filterable as group with group name or UUID.
• fields - any contact fields on this contact (object).
• flow - the flow that the contact is currently in, if any (object).
• created_on - when this contact was created (datetime).
• modified_on - when this contact was last modified (datetime), filterable as before and after.
• last_seen_on - when this contact last communicated with us (datetime).

Example:

Response containing the contacts for your organization:

{
    "next": null,
    "previous": null,
    "results": [
    {
        "uuid": "09d23a05-47fe-11e4-bfe9-b8f6b119e9ab",
        "name": "Ben Haggerty",
        "status": "active",
        "language": null,
        "urns": ["tel:+250788123123"],
        "groups": [{"name": "Customers", "uuid": "5a4eb79e-1b1f-4ae3-8700-09384cca385f"}],
        "fields": {
            "nickname": "Macklemore",
            "side_kick": "Ryan Lewis"
        },
        "flow": {"uuid": "c1bc5fcf-3e27-4265-97bf-f6c3a385c2d6", "name": "Registration"},
        "created_on": "2015-11-11T13:05:57.457742Z",
        "modified_on": "2020-08-11T13:05:57.576056Z",
        "last_seen_on": "2020-07-11T13:05:57.576056Z"
    }]
}

Adding Contacts

You can add a new contact to your account by sending a POST request to this URL with the following JSON data:

• name - the full name of the contact (string, optional).
• language - the preferred language for the contact (3 letter iso code, optional).
• urns - a list of URNs you want associated with the contact (array of up to 100 strings, optional).
• groups - a list of the UUIDs of any groups this contact is part of (array of up to 100 strings, optional).
• fields - the contact fields you want to set or update on this contact (dictionary of up to 100 items, optional).

Example:

{
    "name": "Ben Haggerty",
    "language": "eng",
    "urns": ["tel:+250788123123", "twitter:ben"],
    "groups": ["6685e933-26e1-4363-a468-8f7268ab63a9"],
    "fields": {
        "nickname": "Macklemore",
        "side_kick": "Ryan Lewis"
    }
}

You will receive a contact object as a response if successful:

{
    "uuid": "09d23a05-47fe-11e4-bfe9-b8f6b119e9ab",
    "name": "Ben Haggerty",
    "status": "active",
    "language": "eng",
    "urns": ["tel:+250788123123", "twitter:ben"],
    "groups": [{"name": "Devs", "uuid": "6685e933-26e1-4363-a468-8f7268ab63a9"}],
    "fields": {
        "nickname": "Macklemore",
        "side_kick": "Ryan Lewis"
    },
    "flow": null,
    "created_on": "2015-11-11T13:05:57.457742Z",
    "modified_on": "2015-11-11T13:05:57.576056Z",
    "last_seen_on": null
}

Updating Contacts

A POST can also be used to update an existing contact if you specify either its UUID or one of its URNs in the URL. Only those fields included in the body will be changed on the contact.

If providing a URN in the URL then don't include URNs in the body. Also note that we will create a new contact if there is no contact with that URN. You will receive a 201 response if this occurs.

Examples:

{
    "name": "Ben Haggerty",
    "language": "eng",
    "urns": ["tel:+250788123123", "twitter:ben"],
    "groups": [{"name": "Devs", "uuid": "6685e933-26e1-4363-a468-8f7268ab63a9"}],
    "fields": {}
}

{
    "fields": {"nickname": "Ben"}
}

Deleting Contacts

A DELETE can also be used to delete an existing contact if you specify either its UUID or one of its URNs in the URL.

Examples:

You will receive either a 204 response if a contact was deleted, or a 404 response if no matching contact was found.

Contact Actions Endpoint

Bulk Contact Updating

A POST can be used to perform an action on a set of contacts in bulk.

• contacts - the contact UUIDs or URNs (array of up to 100 strings).
• action - the action to perform, a string one of:
  • add - add the contacts to the given group.
  • remove - remove the contacts from the given group.
  • block - block the contacts.
  • unblock - unblock the contacts.
  • interrupt - interrupt and end any of the contacts' active flow runs.
  • delete - permanently delete the contacts.
• group - the UUID or name of a contact group (string, optional).

Example:

{
    "contacts": ["7acfa6d5-be4a-4bcc-8011-d1bd9dfasff3", "tel:+250783835665"],
    "action": "add",
    "group": "Testers"
}

You will receive an empty response with status code 204 if successful.

Fields Endpoint

This endpoint allows you to list custom contact fields in your account.

Listing Fields

A GET returns the list of custom contact fields for your organization, in the order of last created.

• key - the unique key of this field (string), filterable as key.
• name - the display name of this field (string).
• type - the data type of this field, one of text, number, datetime, state, district or ward.

Example:

Response containing the fields for your organization:

{
    "next": null,
    "previous": null,
    "results": [
        {
            "key": "nick_name",
            "name": "Nick name",
            "type": "text"
        },
        ...
    ]
}

Adding Fields

A POST can be used to create a new contact field. Don't specify a key as this will be generated for you.

• name - the display name (string)
• type - one of the data type codes (string)

Example:

{
    "name": "Nick name",
    "type": "text"
}

You will receive a field object (with the new field key) as a response if successful:

{
    "key": "nick_name",
    "name": "Nick name",
    "type": "text"
}

Updating Fields

A POST can also be used to update an existing field if you include its key in the URL.

Example:

{
    "name": "New label",
    "type": "text"
}

You will receive the updated field object as a response if successful:

{
    "key": "nick_name",
    "name": "New label",
    "type": "text"
}

Flow Starts Endpoint

This endpoint allows you to list manual flow starts in your account, and add or start contacts in a flow.

Listing Flow Starts

By making a GET request you can list all the manual flow starts on your organization, in the order of last modified. Each flow start has the following attributes:

• uuid - the UUID of this flow start (string), filterable as uuid.
• flow - the flow which was started (object).
• contacts - the list of contacts that were started in the flow (objects).
• groups - the list of groups that were started in the flow (objects).
• status - the status, one of pending, queued, started, completed, failed, interrupted.
• params - the dictionary of extra parameters passed to the flow start (object).
• created_on - the datetime when this flow start was created (datetime).
• modified_on - the datetime when this flow start was modified (datetime).

Example:

Response is the list of flow starts on your organization, most recently modified first:

{
    "next": "http://example.com/api/v2/flow_starts.json?cursor=cD0yMDE1LTExLTExKzExJTNBM40NjQlMkIwMCUzRv",
    "previous": null,
    "results": [
        {
            "uuid": "09d23a05-47fe-11e4-bfe9-b8f6b119e9ab",
            "flow": {"uuid": "f5901b62-ba76-4003-9c62-72fdacc1b7b7", "name": "Thrift Shop"},
            "groups": [
                {"uuid": "f5901b62-ba76-4003-9c62-72fdacc1b7b7", "name": "Ryan & Macklemore"}
            ],
            "contacts": [
                {"uuid": "f5901b62-ba76-4003-9c62-fjjajdsi15553", "name": "Wanz"}
            ],
            "status": "complete",
            "params": {
                "first_name": "Ryan",
                "last_name": "Lewis"
            },
            "created_on": "2013-08-19T19:11:21.082Z",
            "modified_on": "2013-08-19T19:11:21.082Z"
        },
        ...
    ]
}

Starting contacts down a flow

By making a POST request with the contacts, groups and URNs you want to start down a flow you can trigger a flow start. Note that that contacts will be added to the flow asynchronously, you can use the runs endpoint to monitor the runs created by this start.

• flow - the UUID of the flow to start contacts in (required)
• groups - the UUIDs of the groups you want to start in this flow (array of up to 100 strings, optional)
• contacts - the UUIDs of the contacts you want to start in this flow (array of up to 100 strings, optional)
• urns - the URNs you want to start in this flow (array of up to 100 strings, optional)
• restart_participants - whether to restart participants already in this flow (optional, defaults to true)
• exclude_active - whether to exclude contacts currently in other flow (optional, defaults to false)
• params - extra parameters to pass to the flow start (object, accessible via @trigger.params in the flow)

Example:

{
    "flow": "f5901b62-ba76-4003-9c62-72fdacc1b7b7",
    "groups": ["f5901b62-ba76-4003-9c62-72fdacc15515"],
    "contacts": ["f5901b62-ba76-4003-9c62-fjjajdsi15553"],
    "urns": ["twitter:sirmixalot", "tel:+12065551212"],
    "params": {"first_name": "Ryan", "last_name": "Lewis"}
}

Response is the created flow start:

{
    "uuid": "09d23a05-47fe-11e4-bfe9-b8f6b119e9ab",
    "flow": {"uuid": "f5901b62-ba76-4003-9c62-72fdacc1b7b7", "name": "Thrift Shop"},
    "groups": [
        {"uuid": "c24813d2-3bc7-4467-8916-255b6525c6be", "name": "Ryan & Macklemore"}
    ],
    "contacts": [
        {"uuid": "f1ea776e-c923-4c1a-b3a3-0c466932b2cc", "name": "Wanz"}
    ],
    "status": "pending",
    "params": {
        "first_name": "Ryan",
        "last_name": "Lewis"
    },
    "created_on": "2013-08-19T19:11:21.082Z",
    "modified_on": "2013-08-19T19:11:21.082Z"
}