Getting data from the Contacts API endpoint

Nathan Begbie Updated by Nathan Begbie

Contact data changes as people interact with your service. This is how you get up to date information via the API.

Toward the end of September 2022 we made some changes to the Contacts API endpoint. If you used the endpoint before that please make sure to first read about the 3 key changes first.

Here is an example of how to retrieve Contact details via the API

Imagine we have only a single user who messages us (Bob) and a custom profile field called `current_savings`. On Monday the 12th of September 2022, they message us to say that their current savings are $100. If we run the following on Tuesday (13th) we might query this data like so:

# request a cursor for the data
$ curl -X POST "https://whatsapp.turn.io/v1/data/contacts/cursor" \
  -H "Authorization: Bearer token" \
  -H "Content-Type: application/json" \
  -H "accept: application/vnd.v1+json"
  -d '
    {
        # start of Monday the 12th
        "from": "2022-09-12T00:00:00.000Z",
        # for a period of 24 hours
        "until": "2022-09-13T00:00:00.000Z"
    }
> {
    "cursor": "an-example-cursor-1234",
    "expires_at": "2022-09-14T17:47:18.318218Z"
}
# request the data using the given cursor
$ curl -X GET "https://whatsapp.turn.io/v1/data/contacts/cursor/an-example-cursor-1234" \
    -H 'Authorization: Bearer token' \
    -H "Accept: application/vnd.v1+json" \
> {
    "data": [
        {
            "details": {
                "birthday": "1988-06-14T18:15:35.873852Z",
                "language": "eng",
                "location": null,
                "name": "bob",
                "opted_in": false,
                "opted_in_at": null,
                "surname": null,
                "whatsapp_id": "44623456700",
                "whatsapp_profile_name": "bob",
                "current_savings": 100
            },
            "id": 1,
            "inserted_at": "20222-09-12T08:30:00.000Z",
            "number_id": 1,
            "updated_at": "20222-09-12T08:30:00.000Z",
            "uuid": "f6c4e666-81ad-430e-aea5-1ba33e6f4c35"
        }
    ]
}

Great! So we have the data and can store it in our data lake, or analytics database.

Now, imagine that Bob messages again on Tuesday, to say that his savings have increased to $120. If we request the data for the same time period (Monday), on Wednesday the 14th, we will no longer receive any data for Bob:

# request a cursor for the data
$ curl -X POST "https://whatsapp.turn.io/v1/data/contacts/cursor" \
  -H "Authorization: Bearer token" \
  -H "Content-Type: application/json" \
  -H "accept: application/vnd.v1+json"
  -d '
    {
        # start of Monday the 12th
        "from": "2022-09-12T00:00:00.000Z",
        # for a period of 24 hours
        "until": "2022-09-13T00:00:00.000Z"
    }
> {
    "cursor": "another-example-cursor-5678",
    "expires_at": "2022-09-16T17:48:18.763987Z"
}
# request the data
curl -X GET "https://whatsapp.turn.io/v1/data/contacts/cursor/an-example-cursor-1234" \
    -H 'Authorization: Bearer token' \
    -H "Accept: application/vnd.v1+json" \
> {
    "data": []
}

Instead, if we want updated data, we must request the next day's data:

# request a cursor for the data
$ curl -X POST "https://whatsapp.turn.io/v1/data/contacts/cursor" \
  -H "Authorization: Bearer token" \
  -H "Content-Type: application/json" \
  -H "accept: application/vnd.v1+json"
  -d '
    {
        # start of Tuesday the 13th
        "from": "2022-09-13T00:00:00.000Z",
        # for a period of 24 hours
        "until": "2022-09-14T00:00:00.000Z"
    }
> {
    "cursor": "yet-another-example-cursor-9876",
    "expires_at": "2022-09-16T17:48:18.763987Z"
}
# request the data using the given cursor
$ curl -X GET "https://whatsapp.turn.io/v1/data/contacts/cursor/yet-another-example-cursor-9876" \
    -H 'Authorization: Bearer token' \
    -H "Accept: application/vnd.v1+json" \
> {
    "data": [
        {
            "details": {
                "birthday": "1988-06-14T18:15:35.873852Z",
                "language": "eng",
                "location": null,
                "name": "bob",
                "opted_in": false,
                "opted_in_at": null,
                "surname": null,
                "whatsapp_id": "44623456700",
                "whatsapp_profile_name": "bob",
                # note the change in value here!
                "current_savings": 120
            },
            "id": 1,
            "inserted_at": "20222-09-12T08:30:00.000Z",
            "number_id": 1,
            "updated_at": "20222-09-13T10:00:00.000Z",
            "uuid": "f6c4e666-81ad-430e-aea5-1ba33e6f4c35"
        }
    ]
}

Note: You should not need to request the data using the time-span of the number for up-to-date contact data unless you are requesting it for the first time. 

See more example calls in the API documentation.

Was this article helpful?

Notify your team over email when someone needs urgent help

Getting Suggested Replies with ChatGPT

Contact