Skip to content
Request a demo

Enrich businesses in bulk

Use an enrichment job to submit between 1 and 10,000 business records and retrieve results asynchronously.

Submit an enrichment job

Each object in pois uses the POST /v1/enrich request contract. Replace the sample names, addresses, and coordinates with the businesses you want to enrich. 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).

curl https://api.voygr.tech/v1/jobs/enrich \
  --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,
        "country": "US",
        "attributes": ["phone", "website"]
      },
      {
        "id": "cafe-002",
        "poi_name": "Example Cafe",
        "address": "456 Sample Avenue",
        "latitude": 37.7755,
        "longitude": -122.4183,
        "country": "US",
        "attributes": ["opening_hours"]
      }
    ]
  }'

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 enrichment job

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

Stop polling when status is completed, failed, or cancelled. A completed response provides a compressed JSON Lines download in results.files. Download from url before expires_at; poll again for a fresh URL if needed.

Each line follows the single-place enrichment response contract and corresponds to the input row in the same position.

Handle enrichment-job 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.