Make your first API call – Indivd

This article takes you from zero to a working API response. By the end you will have retrieved real zone visitor data for a location using the zone_visitors endpoint.

Included in: ✓ Indivd Basic ✓ Indivd Pro ✓ Indivd Complete

Related articles

This article contains the following topics:

Before you begin
Step 1: Find your location ID
Step 2: Find your zone IDs
Step 3: Request visitor data
Step 4: Read the response
Next steps

Before you begin

You need an API token to follow this guide. Tokens are not self-serve. Email support@indivd.com to request one before continuing. For details on how tokens work and how to include them in requests, see Authentication.

This guide uses the zone_visitors endpoint because it is the primary zone-based endpoint and returns the richest data: visits, unique visits, dwell time, and bounce count. Once you have a working request here, the same pattern applies to line_crosses and drop_in_rate.

Step 1: Find your location ID

All data requests are scoped to a location. Start by fetching the list of locations your token has access to.

To fetch your locations:

Run the following request, replacing [your-token-here] with your token:

curl --location --request GET \
'https://api.indivd.com/filters/locations' \
--header 'Authorization: Token [your-token-here]' \
--header 'Content-Type: application/json'

Find the location you want to query in the response and note its id value.

The response returns one object per location. A typical location object looks like this:

{
  "id": 124,
  "name": "Sample Location - Stockholm",
  "city": "Stockholm",
  "country": "SE",
  "timezone": "Europe/Stockholm"
}

In this example the location ID is 124. Use your own value in the steps below.

Note: The timezone field matters if your locations span multiple time zones. The zone_visitors endpoint uses the timezone of the first location in the request by default. Use the tz parameter to override this. See How to query visitor data for details.

Step 2: Find your zone IDs

Zone visitor data is returned per zone. You need at least one zone ID to get a meaningful response.

To fetch your zones:

Run the following request:

curl --location --request GET \
'https://api.indivd.com/filters/zones' \
--header 'Authorization: Token [your-token-here]' \
--header 'Content-Type: application/json'

Find the zone or zones you want to query and note their id values.

The response returns one object per zone:

[
  {
    "id": 201,
    "name": "Entrance",
    "organization": 13,
    "bounce_threshold": 120
  },
  {
    "id": 202,
    "name": "Womenswear",
    "organization": 13,
    "bounce_threshold": 60
  }
]

Note: The bounce_threshold is the number of seconds used to classify a visit as a bounce. It is set per zone and used as the default unless you override it with the bounce_threshold parameter in your data request. Different zones can have different thresholds, so always check this value before interpreting bounce data.

Step 3: Request visitor data

You now have a location ID and one or more zone IDs. The example below requests visitor data for location 124, zone 201, over a seven-day period:

curl --location --request GET \
'https://api.indivd.com/api/v1/rnd/insights/external/zone_visitors/?start_date=2025-03-01&end_date=2025-03-07&location=124&zones=201' \
--header 'Authorization: Token [your-token-here]'

Replace 2025-03-01, 2025-03-07, 124, and 201 with your own values.

Note: No aggregate_by parameter is set in this example. For a 7-day range the API applies daily intervals automatically. Add &aggregate_by=hour to the URL to change this. For the full list of aggregation options and default interval rules, see How to query visitor data.

Step 4: Read the response

A successful response looks like this:

{
  "current": {
    "startdate": "2025-03-01",
    "enddate": "2025-03-07",
    "insights": [
      {
        "visits": 284,
        "unique_visits": 251,
        "bounce": 43,
        "dwell_time": 187.5,
        "dwell_time_stats": {
          "mean": 187.5,
          "min": 12.0,
          "max": 1843.0,
          "quantiles": [95.0, 148.0, 231.0],
          "n": 251
        },
        "exclude": {
          "min_dwell_time": 0,
          "max_dwell_time": 0
        },
        "aggregation": {
          "dayofmonth": 1,
          "month": 3,
          "year": 2025,
          "zone_id": 201,
          "zone_name": "Entrance",
          "bounce_threshold": 120
        }
      }
    ]
  },
  "comparison": {}
}

Each object in the insights array represents one time interval for one zone. With a 7-day request and daily aggregation you will receive up to seven objects per zone.

Here is what the key fields mean:

Field	Type	What it tells you
`visits`	Integer	Total number of zone entries in the interval. Available on all plans.
`unique_visits`	Integer	Number of distinct visitors identified by re-identification. Returns `0` on Basic plans. Requires Indivd Pro.
`bounce`	Integer	Number of visits shorter than the `bounce_threshold` in seconds. Returns `0` on Basic plans. Requires Indivd Pro.
`dwell_time`	Float	Mean time spent in the zone, in seconds. Returns `0` on Basic plans. Requires Indivd Pro.
`dwell_time_stats.mean`	Float	Mean dwell time in seconds. Equivalent to `dwell_time`.
`dwell_time_stats.min`	Float	Shortest dwell time recorded in the interval, in seconds.
`dwell_time_stats.max`	Float	Longest dwell time recorded in the interval, in seconds.
`dwell_time_stats.quantiles`	Array of floats	25th, 50th, and 75th percentile dwell times in seconds.
`dwell_time_stats.n`	Integer	Number of visits included in the dwell time calculation. Visits excluded by `min_dwell` or `max_dwell` filters are not counted here.
`exclude.min_dwell_time`	Integer	Number of visits shorter than the `min_dwell` filter threshold. These visits are still counted in `visits`. Zero if no `min_dwell` filter was set.
`exclude.max_dwell_time`	Integer	Number of visits longer than the `max_dwell` filter threshold. These visits are still counted in `visits`. Zero if no `max_dwell` filter was set.
`aggregation`	Object	The time period and zone this row of data covers. Always present.
`aggregation.bounce_threshold`	Integer	The bounce threshold in seconds that was applied to this row. Reflects either the zone default or the value you passed in the `bounce_threshold` parameter.
`comparison`	Object	Empty unless you added `comparison_start_date` and `comparison_end_date` to the request. When populated, has the same structure as `current`.

Note: unique_visits, bounce, dwell_time, and dwell_time_stats are Pro-only fields. They are present in the response object on Basic plans but return 0 or empty values. Check your plan if you are seeing unexpected zeroes. Contact support@indivd.com for plan information.

Next steps

Now that you have a working request, here are the most common directions to go next.

Expand your zone visitors query:

Query multiple zones in one request by passing their IDs comma-separated: zones=201,202. Compare unique_visits across zones to analyse cross-visitation.
Add a comparison period for period-over-period analysis by including comparison_start_date and comparison_end_date. The response will include a populated comparison object with the same structure as current.
Get a single total per zone for the full date range, bypassing time-based intervals, by setting aggregate_by=zone. Useful for summary dashboards.
Filter by dwell time using min_dwell and max_dwell to focus on visits within a meaningful engagement window.

Query other endpoints:

For raw traffic counts at specific entrances, aisles, or floor boundaries, use line_crosses. Note that counts are per crossing, not per visitor.
For conversion rate of passing foot traffic to zone entry, use drop_in_rate. This requires passing-by lines to be configured at your location first. Contact support@indivd.com to request setup.

Reference:

For the full parameter reference for all three data endpoints, see How to query visitor data.
For all five filter endpoints and their response fields, see How to use the Indivd filter endpoints.