---
title: "Validate places in bulk"
method: POST
path: "/v1/jobs/validate"
tags: ["core"]
---

# Validate places in bulk

`POST /v1/jobs/validate`

## Request

- Base URL: `https://api.voygr.tech`
- URL: `https://api.voygr.tech/v1/jobs/validate`
- Auth: API key in header `X-API-Key`

Submit 1 to 10,000 places for asynchronous validation. Each downloaded JSON Lines row follows the POST /v1/validate response contract. 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 new work.

## Headers

- `Idempotency-Key` string, nullable

## Request body

- ValidateJobSubmit: Submit 1 to 10,000 places for validation.
  - `pois` POIValidateRequest[], required: Inline POIs to validate
    - `id` string, nullable: Client-provided identifier
    - `poi_name` string, required: POI name
    - `street` string, nullable: Street address
    - `city` string, nullable: City
    - `region` string, nullable: State/province
    - `postcode` string, nullable: Postal/ZIP code
    - `country` string, nullable: 2-letter ISO country code
    - `address` string, nullable: Unstructured address string. May also be sent as `freeform_address` (input-only alias).
    - `latitude` number, nullable: Latitude in decimal degrees (WGS84). Optional but recommended.
    - `longitude` number, nullable: Longitude in decimal degrees (WGS84). Optional but recommended.

## Response `200`

Successful Response

- ValidationJobSubmitResponse: Accepted validation or enrichment job submission.
  - `batch_id` string, required
  - `type` 'validate' | 'enrich', nullable
  - `status` 'queued' | 'running' | 'completed' | 'failed' | 'cancelled', required
  - `created_at` string, required
  - `total_items` integer, required
  - `eta_seconds` integer, required
  - `eta_completion_at` string, required

## Other responses

- `400`: Invalid request. Correct the fields before retrying.
- `401`: Missing or invalid X-API-Key.
- `402`: The available balance cannot cover the request's credit hold. Nothing ran.
- `403`: The key lacks the entitlement this operation requires.
- `409`: IDEMPOTENCY_CONFLICT: this Idempotency-Key was already used with a different body. Use a new key for new work.
- `429`: BATCH_CONCURRENCY_LIMIT: the key already has 20 jobs in progress; wait retry_after_seconds (no Retry-After header) or until one finishes. Any other 429 is the rate limit: wait and follow Retry-After when returned. Free keys are limited to 10 requests per second and 120 requests per minute, and can place 1 call at a time, up to 25 calls per day. Paid keys are limited to 10 requests per second and 120 requests per minute. A top-up raises a key's daily cap to 5,000 calls and its concurrent-call ceiling to 10. Enterprise limits are set per contract.
- `502`: The service behind the gateway failed. The job may still have been created: retry promptly with the same Idempotency-Key and body, which returns it if it exists.
- `504`: The service behind the gateway did not answer in time. The job may still have been created: retry promptly with the same Idempotency-Key and body.

## Changes

- **2026-10-29** `03b7688c4c40`: 7 info
  - added the non-success response with the status `401`
  - added the non-success response with the status `402`
  - added the non-success response with the status `403`
  - added the non-success response with the status `409`
  - …3 more
- **2026-09-16** `892990bd38e1`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/voygr/apis/voygr-calls-api/changes/v1/jobs/validate/post.md)

---

[API](https://skmtc.dev/voygr/apis/voygr-calls-api.md) - [All operations](https://skmtc.dev/voygr/apis/voygr-calls-api/llms.txt) - [OpenAPI document](https://skmtc.dev/voygr/apis/voygr-calls-api/revisions/7199881ed19e?raw)