Ordering

The order query parameter of the Call list endpoint accepts two values:

• qualified, which is the time when a given Call processing in our system has been completed.
• timestamp, the date at which a given Call started.

The default behaviour orders by qualified.

You don't have time to read this whole article? We've done a TL;DR at the end 😎

To understand why the qualified option is important, take a look at this timeline showing when 2 calls start and end:

Imagine you run a cronjob every minute. It runs a script that consume the Activate API, and stores the Calls data into some database. In order to only save the Calls you don't have, you keep in memory the unique_id of the last Call you saved in database.

Keep in mind that the Activate API purpose is to expose Calls we have finished to process and enrich with analytics. We are not exposing Call undergoing transcription or qualification.

Order by timestamp

Ordering by timestamp will expose Calls by starting date, from the newest to the oldest.

Here is the cronjob behaviour, with a simplified payload for the sake of documentation.

15:27 No new data.

{
  "data": []
}

15:28 Call 2 has hang up, is qualified. Save it to database and keep "Call 2" as pointer for next cron

{
  "data": [
    {
      "unique_id": "Call 2",
      "duration": 120,
      "timestamp": "2020-07-24T15:26:00Z",
      "qualified": "2020-07-24T15:28:00Z",
      "qualification": "Cold Lead"
    }
  ]
}

15:29 No new data.

{
  "data": [
    {
      "unique_id": "Call 2",
      "duration": 120,
      "timestamp": "2020-07-24T15:26:00Z",
      "qualified": "2020-07-24T15:28:00Z",
      "qualification": "Cold Lead"
    }
  ]
}

15:30 No new data before Call 2, despite there is now the Call 1 data after Call 2. Call 1 will never be saved to the database! "Call 2" remains the pointer.

{
  "data": [
    {
      "unique_id": "Call 2",
      "duration": 120,
      "timestamp": "2020-07-24T15:26:00Z",
      "qualified": "2020-07-24T15:28:00Z",
      "qualification": "Cold Lead"
    },
    {
      "unique_id": "Call 1",
      "duration": 300,
      "timestamp": "2020-07-24T15:25:00Z",
      "qualified": "2020-07-24T15:30:00Z",
      "qualification": "Warm Lead"
    }
  ]
}

Order by qualified

Ordering by qualified will expose Calls by end of processing date, from the newest to the oldest.

Here is the cronjob behaviour, with a simplified payload for the sake of documentation.

15:27 No new data.

{
  "data": []
}

15:28 Call 2 has hang up, is qualified. Save it to database and keep "Call 2" as pointer for next cron.

{
  "data": [
    {
      "unique_id": "Call 2",
      "duration": 120,
      "timestamp": "2020-07-24T15:26:00Z",
      "qualified": "2020-07-24T15:28:00Z",
      "qualification": "Cold Lead"
    }
  ]
}

15:29 No new data.

{
  "data": [
    {
      "unique_id": "Call 2",
      "duration": 120,
      "timestamp": "2020-07-24T15:26:00Z",
      "qualified": "2020-07-24T15:28:00Z",
      "qualification": "Cold Lead"
    }
  ]
}

15:30 Call 1 has hang up, is qualified. It is displayed above our pointer. Save Call 1 to database and keep "Call 1" as pointer for next cron.

{
  "data": [
    {
      "unique_id": "Call 1",
      "duration": 300,
      "timestamp": "2020-07-24T15:25:00Z",
      "qualified": "2020-07-24T15:30:00Z",
      "qualification": "Warm Lead"
    },
    {
      "unique_id": "Call 2",
      "duration": 120,
      "timestamp": "2020-07-24T15:26:00Z",
      "qualified": "2020-07-24T15:28:00Z",
      "qualification": "Cold Lead"
    }
  ]
}

When to use each ordering option?

So now you know how each ordering option works, but you're still stuck on which one is better suited for your need?

Well, to sum it up...

Go with order=qualified if you request the API on a very regular basis, on a minutes or hour periodicity.

Go with order=timestamp if you request the API once a day to retrieve all the data from the past 24 hours.