Enrich places in bulk

POST /v1/jobs/enrich

https://api.voygr.tech/v1/jobs/enrich

Overview

Enrich up to 10,000 places asynchronously using /v1/enrich request bodies. Poll GET /v1/jobs/{batch_id} until completed, then download result.jsonl.gz: one result per input row, in order. One credit per row is held at submission; only rows with a billable value or non-null status are charged, and unused credits are released. Failed rows are free. Save batch_id and poll GET /v1/jobs/{batch_id} after acceptance. For an uncertain submission, retry promptly with the same Idempotency-Key and identical body. Replay only applies while the idempotency record is retained and the job is not cancelled. Reusing a key after cancellation or retention expiry can create new work and charges. While replay applies, a different body returns 409 IDEMPOTENCY_CONFLICT. Use a new key for intentional new work.

Authentication

API key in header X-API-Key: Your customer API key (pk_live_...), sent on every request. Self-serve at https://api.voygr.tech/checkout.

Parameters

Name	Location	Required	Type	Description and constraints
`Idempotency-Key`	header	optional	`string \| null`

Request body

required

application/json

Schema: EnrichJobSubmit

Responses

`200`

Successful Response

application/json

Schema: ValidationJobSubmitResponse

`400`

Invalid request. Correct the fields before retrying.

application/json

Schema: object | object

Option 1 fields

Field Type Required Description and constraints

success boolean required constant False

error string required

error_code string required constant VALIDATION_ERROR

request_id string | null required

validation_timestamp string required

detail

array of object

required

Item fields

Field	Type	Required
`field`	`string`	required
`message`	`string`	required
`type`	`string`	required

Option 2 fields

Field Type Required Description and constraints

detail

object

required

Gateway rejection, for example an invalid Idempotency-Key header.

Fields

Field	Type	Required	Description and constraints
`error`	`string`	required
`error_code`	`string`	optional

One of

Option 1: requires success, error, error_code, request_id, validation_timestamp, detail
Option 2: requires detail

invalidinput

{
  "success": false,
  "error": "Invalid input provided",
  "error_code": "VALIDATION_ERROR",
  "request_id": "example-request-id",
  "validation_timestamp": "2026-09-16T12:00:00Z",
  "detail": [
    {
      "field": "pois.0.poi_name",
      "message": "Field required",
      "type": "missing"
    }
  ]
}

Schemas

EnrichJobSubmit

Type: object

Submit body for POST /v1/jobs/enrich.

Rows are the exact /v1/enrich request model, so a batch row behaves identically to a single call by construction - same validation, same attribute set, same limits.

Field	Type	Required	Description and constraints
`pois`	`array of POIEnrichRequest`	required	Inline POIs to enrich 1 to 10000 items

Example

{
  "pois": [
    {
      "id": "bakery-001",
      "poi_name": "Example Bakery",
      "address": "123 Example Street",
      "country": "US",
      "latitude": 37.7749,
      "longitude": -122.4194,
      "attributes": [
        "opening_hours",
        "phone",
        "website"
      ]
    },
    {
      "id": "cafe-002",
      "poi_name": "Example Cafe",
      "address": "456 Sample Avenue",
      "country": "US",
      "latitude": 37.7755,
      "longitude": -122.4183,
      "attributes": [
        "opening_hours",
        "phone",
        "website"
      ]
    }
  ]
}

ValidationJobSubmitResponse

Type: object

Accepted validation or enrichment job submission.

Field	Type	Required	Description and constraints
`batch_id`	`string`	required
`type`	`string (one of validate, enrich) \| null`	optional
`status`	`string`	required	one of queued, running, completed, failed, cancelled
`created_at`	`string`	required
`total_items`	`integer`	required
`eta_seconds`	`integer`	required
`eta_completion_at`	`string`	required

POIEnrichRequest

Type: object

Request model for place attribute enrichment.

Field	Type	Required	Description and constraints
`id`	`string (max length 100) \| null`	optional	Client-provided identifier
`poi_name`	`string`	required	Place name length 1 to 200
`street`	`string \| null`	optional	Street address
`city`	`string \| null`	optional	City
`region`	`string \| null`	optional	State/province
`postcode`	`string \| null`	optional	Postal/ZIP code
`country`	`string \| null`	optional	2-letter ISO country code (e.g. US) locating the place.
`address`	`string (max length 500) \| null`	optional	Unstructured address string. May also be sent as `freeform_address` (input-only alias).
`latitude`	`number (-90.0 to 90.0) \| null`	optional	Latitude in decimal degrees (WGS84).
`longitude`	`number (-180.0 to 180.0) \| null`	optional	Longitude in decimal degrees (WGS84). Provide with latitude.
`attributes`	`array of string`	optional	Attributes to return: opening_hours, phone, website, facebook, instagram, tiktok, email. Existence and open_closed are returned under status. Defaults to opening_hours, phone, website, existence, open_closed. 1 to 9 items; default ['opening_hours', 'phone', 'website', 'existence', 'open_closed']
`include_summary`	`boolean`	optional	Also return a short factual place_summary. Default false. Does not change billing: still 1 credit. default False
`response_format`	`string`	optional	Response shape: 'attributes' (default, EnrichedAttribute) or 'cell' (the unified ResultCell shape). one of attributes, cell; default attributes

Example

{
  "id": "bakery-001",
  "poi_name": "Example Bakery",
  "address": "123 Example Street",
  "country": "US",
  "latitude": 37.7749,
  "longitude": -122.4194,
  "attributes": [
    "opening_hours",
    "phone",
    "website"
  ]
}