The Veraset API gives you access to privacy-compliant, pseudonymized mobility data.

Whether you're building audiences, powering attribution models, or enriching existing data, our flexible RESTful endpoints make integration easy and performant.

For complete request/response formats and field definitions, see our official developer documentation.

Key Endpoints

• Movement: Access device locations and aggregated movement data
• Visits: Analyze foot traffic and dwell times at specific points of interest
• Home & Work: Identify residential and workplace clusters
• POI: Query point of interest data across industry categories, geography, and brand.
• Matchlink: Connect device IDs with hashed email and IP addresses

Technical Specifications

• RESTful API design 
• JSON response format 
• Secure authentication via API key

Authentication

All API requests require an API key. Create, manage, and learn more about API keys in your organization settings.

‍Include your key in the request header:

X-API-Key: YOUR_API_KEY

Understanding the Core Data Types

Our API provides access to three core types of movement data:

‍

We offer each of these in device-level (granular) and aggregated formats.

Additionally, users can query derived insights such as home and work locations via our Home/Work endpoints and hashed email through our Matchlink endpoints.

Movement Schema Variants

Basic provides access to the foundational Movement columns while Full provides additional access to quality fields on the data. Trips supplements our Movement schema with intelligence on where a device came from or went to.

Geolocation and Timeframe

To analyze movement or visits around a location, use the geo_radius parameter:

Define a region using geo-radius

{
  "date_range": {
    "from_date": "2025-01-01",
    "to_date": "2025-01-07"
  },
  "geo_radius": [
    {
      "poi_id": "Starbucks Chicago",
      "latitude": 41.881832,
      "longitude": -87.623177,
      "distance_in_meters": 250
    }
  ]
}

Define a region using WKT (Well-Known Text) or Placekey

You can also send geometry in WKT format or use placekeys:

WKT

{
"date_range": {
    "from_date": "2025-01-01",
    "to_date": "2025-01-02"
  },
  "geometry": [
    {
      "poi_id": "Times Square",
      "wkt": "POLYGON((-73.9876 40.756, -73.9876 40.758, -73.985 40.758, -73.985 40.756, -73.9876 40.756))"
    }
  ]
}

Placekey

{
 "date_range": {
    "from_date": "2025-01-01",
    "to_date": "2025-01-07"
  }
  "place_key": [
    {
      "poi_id": "Empire State Building",
      "placekey": "228-223@627-wbz-snq"
    }
  ]
}

Exploring POIs and Metadata

Need help targeting the right locations? Use our metadata endpoints make it easier to define meaningful and brand-aligned trade areas. 

‍

Example: GET /v1/poi/subcategories

Entering Starbucks into the “Brand” string for the GET /v1/poi/sub-categories endpoint returns that brand’s NAICS-aligned subcategory, “Snack and Nonalcoholic Beverage Bars”:

{
  "request_id": "2ea3b547-850e-4d34-8034-7cc6ccdf7a59",
  "error_code": null,
  "error_message": null,
  "data": [
    "Snack and Nonalcoholic Beverage Bars"
  ]
}

Providing the subcategory Snack and Nonalcoholic Beverage Bars as a string to the GET /v1/poi/brands endpoint returns an alphabetized list of brands that compete in that subcategory:

{
  "request_id": "5f4388ef-99d4-4b35-acbf-3c05112fd29f",
  "error_code": null,
  "error_message": null,
  "data": [
    "16 Handles",
    "Abbott's Frozen Custard",
    "Anderson's Frozen Custard",
    "Angelina",
    "Auntie Anne's",
    "Baked by Melissa",
    "Bambu",
    "Baskin Robbins",
    ... #Results omitted for brevity
    "Tim Hortons",
    "Tous Les Jours",
    "Tropical Smoothie Café",
    "Tutti Frutti",
    "U-Swirl Frozen Yogurt",
    "Uncle Louie G",
    "Vivi Bubble Tea",
    "WOW Cafe",
    "Wild Bean Cafe",
    "Yogen Früz",
    "Yogurtini"
  ]
}

The call can be focused further by leveraging the State or City string, narrowing the results to brands in only those regions.

Synchronous vs. Asynchronous Responses

Submitting a Job

Many of Veraset’s aggregate endpoints and the POI endpoints run as synchronous jobs that immediately return results in JSON format. However, most endpoints use an asynchronous job-based model. 

Within that model, you can:

1. Submit a request
2. Check job status (optional)
3. Preview or retrieve results
4. Cancel or cleanup jobs

Submit a request

Start with an endpoint such as:

• POST /v1/movement/job/pings
• POST /v1/movement/job/devices
• POST /v1/visits/job/aggregate

Each will return a job_id.

{
  "request_id": "abc123",
  "data": {
    "job_id": "job_xyz",
    "status": "SCHEDULED"
  }
}

Check job status

GET /v1/job/{job_id}

Preview or retrieve results

Inspect output structure:

GET /v1/job/{job_id}/preview

Download full results from S3:

GET /v1/job/{job_id}

Cancelling or Cleaning Up Jobs

Stop a job:

DELETE /v1/job/{job_id}