Skip to main content

​
Endpoints

ActionMethod & Path
Create batchPOST /v1/{org_slug}/place_enrichment/batches
Get batch statusGET /v1/{org_slug}/place_enrichment/batches/{batch_id}
Get batch resultsGET /v1/{org_slug}/place_enrichment/jobs?batchId={batch_id}&limit={n}&offset={n}
Reprocess batchPOST /v1/{org_slug}/place_enrichment/batches/{batch_id}/reprocess
List batchesGET /v1/{org_slug}/place_enrichment/batches?limit={n}&offset={n}

​
Quick Start

Submit a minimal batch via the Create batch endpoint: 
{
  "batch_name": "Q1 Store Locations",
  "jobs": [
    {
      "place_id": "store_001",
      "inputs": {
        "name": "Downtown Store",
        "full_address": "123 Main St, New York, NY 10001",
        "latitude": 40.7128,
        "longitude": -74.0060
      }
    }
  ],
  "attributes": ["websites", "phoneNumbers", "categories"]
}
Include full_address in jobs[].inputs when available — it improves enrichment accuracy.
The same response shape is returned by Create batch and Get batch status. The jobs object lists place IDs grouped by their job status (see Monitoring Progress). 
{
  "id": "d98e206f-ff1d-4b5a-b0d8-18fff0757fef",
  "batch_name": "Q1 Store Locations",
  "status": "pending",
  "jobs": {
    "pending": ["store_001"],
    "queued": [],
    "in_progress": [],
    "completed": [],
    "failed": []
  }
}

​
Batch Limits

Maximum places per request: 50,000
Requests exceeding this limit return 400 Bad Request. Split larger datasets into multiple batches (for example, up to 50,000 places per batch).

​
Batch Status Lifecycle

Batches move through a small set of statuses driven by job state. The top-level status aggregates all jobs in the batch (e.g. in_progress if any job is still running). A batch is finished when status is completed or failed.
  1. Not Started: Batch created; jobs are pending and not yet queued for processing.
  2. Queued: Jobs are scheduled and waiting to be picked up by workers.
  3. Processing: Jobs are actively being enriched by workers.
  4. Completed: All jobs finished successfully.
  5. Failed: Batch failed (e.g. too many job failures).

​
Monitoring Progress

1

Poll for batch status

Call GET /batches/{batch_id} on an interval (e.g. every 5–10 seconds).
2

Stop when terminal

Stop polling when top-level status is completed or failed.

​
Batch status response

The response exposes job-level status via the jobs object. Each key is a job status; each value is an array of place IDs whose enrichment job is in that status. Use the array lengths to derive progress (e.g. jobs.completed.length + jobs.failed.length over total).
FieldDescription
idBatch identifier
batch_nameDisplay name
statusAggregated batch status (pending, queued, in_progress, completed, failed)
jobsPlace IDs grouped by job status: pending, queued, in_progress, completed, failed
metadataOptional: total_jobs, completed_jobs, status_counts, success_rate
created_atBatch creation timestamp
jobs is keyed by job status, not counts. Each array contains the place_id values for jobs in that status. Total jobs = sum of lengths across all job arrays.
{
  "id": "d98e206f-ff1d-4b5a-b0d8-18fff0757fef",
  "batch_name": "Q1 2024 Store Locations",
  "status": "in_progress",
  "jobs": {
    "pending": ["store_001", "store_002"],
    "queued": ["store_003", "store_004"],
    "in_progress": ["store_005"],
    "completed": ["store_006", "store_007"],
    "failed": []
  },
  "created_at": "2024-01-15T10:00:00Z"
}

​
Handling Results

​
Fetch results

1

Request jobs for a batch

Use the Get batch results endpoint with batchId, limit, and offset. Returns { jobs, total, limit, offset }.
2

Paginate through all results

Increment offset by limit until offset + jobs.length >= total.

​
Success vs failed jobs

Each job in the jobs array has a status field. Filter by:
  • status === "completed" — successful enrichments; use outputs for enriched data
  • status === "failed" — failures; inspect for retry or manual review
Per-attribute run status (e.g. which enrichments ran or failed) lives under job_metadata.attribute_status. Use this for partial successes or to decide which attributes to reprocess.
ValueMeaning
RUNEnrichment ran successfully
NOT_RUNEnrichment was not executed
ERROREnrichment failed
RUN_CONDITION_FAILEDSkipped (missing required inputs)

​
Reprocessing Failed Items

POST /batches/{batch_id}/reprocess re-queues jobs for enrichment. Key options:
ParamDefaultDescription
failed_onlytrueOnly reprocess jobs with failed status
incomplete_onlyfalseOnly reprocess pending/queued/in_progress
refreshfalseForce fresh enrichment, ignore cached data
attributes—Override attributes to enrich
attribute_set—Use predefined set: core, all, open_closed
Set failed_only: false and incomplete_only: false to reprocess all jobs in the batch.

​
Listing Batches

GET /batches?limit={n}&offset={n}&query={search} returns paginated batches. Each batch includes id, batch_name, status, status_counts, created_at, and optional metadata.

​
Best Practices

  • Descriptive batch names — Use names that identify the dataset or run so you can find them in the list.
  • Chunk large datasets — Stay under 50K jobs per request; split into multiple batches or append via repeated requests with the same batch_id.
  • Handle failures — Check jobs.failed after completion; use the reprocess endpoint to retry with failed_only: true.

​
Next Steps