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.