Skip to content
Request a demo

Validate businesses in bulk

Use a validation job to submit between 1 and 10,000 business records and retrieve their results asynchronously.

Submit a validation job

Each object in pois uses the same request body as POST /v1/validate. Replace the sample names, addresses, and coordinates with the businesses you want to validate. Set IDEMPOTENCY_KEY to a unique value for this request; reuse it only when retrying the same body.

When providing coordinates, send both latitude and longitude in decimal degrees (WGS84). Include the address alongside the coordinate pair for validation.

curl https://api.voygr.tech/v1/jobs/validate \
  --request POST \
  --header "X-API-Key: $VOYGR_API_KEY" \
  --header "Idempotency-Key: $IDEMPOTENCY_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "pois": [
      {
        "id": "bakery-001",
        "poi_name": "Example Bakery",
        "address": "123 Example Street",
        "latitude": 37.7749,
        "longitude": -122.4194
      },
      {
        "id": "cafe-002",
        "poi_name": "Example Cafe",
        "address": "456 Sample Avenue",
        "latitude": 37.7755,
        "longitude": -122.4183
      }
    ]
  }'

The submission response contains batch_id, status, created_at, total_items, eta_seconds, and eta_completion_at. Set BATCH_ID to the returned batch_id before polling.

Retry a submission safely

Keep the returned batch_id and use GET to check it; do not repeat POST to poll. If the submission response was lost, retry promptly with the same Idempotency-Key and identical body. This returns the original job only while its idempotency record is retained and the job has not been cancelled.

After cancellation, the same key can create a new job and incur new charges. Replay also stops after the retention window expires. Do not use an old key as a permanent deduplication guarantee. If you no longer know whether replay applies, check the saved job or contact support@voygr.tech before resubmitting.

While replay applies, a different body under the same key returns 409 with error_code: IDEMPOTENCY_CONFLICT. Use a new key when you intentionally want new work.

Poll the validation job

Poll the returned identifier until the job reaches a terminal state.

curl "https://api.voygr.tech/v1/jobs/$BATCH_ID" \
  --header "X-API-Key: $VOYGR_API_KEY"

queued means the job is waiting to start, and running means rows are being processed. Terminal states include completed, failed, and cancelled; stop polling when one is returned.

When status is completed, read results.format, results.total_items, and results.files. Download the compressed JSON Lines file from a file’s url before expires_at; poll the status endpoint again if you need a fresh URL. Each line follows the POST /v1/validate response contract, and lines preserve input order.

Handle validation errors

  • 400: correct the request. For VALIDATION_ERROR, detail lists each invalid field, message, and error type.
  • 401 or 403: check the key and its access to the operation.
  • 402: the available credit balance cannot cover the request; add credits before retrying.
  • 409: inspect error_code, including IDEMPOTENCY_CONFLICT as described above.
  • 429: wait and follow Retry-After when returned.

Keep the returned batch_id and request_id when contacting support@voygr.tech.