> ## Documentation Index > Fetch the complete documentation index at: https://docs.repromptai.com/llms.txt > Use this file to discover all available pages before exploring further. # Submit a batch of places for enrichment > Submit a batch of places for enrichment ``` ## OpenAPI ````yaml /openapi-v1.json post /place_enrichment/batches openapi: 3.1.0 info: title: Reprompt Place Enrichment API description: > ## Batch Processing Guide The `/place_enrichment/batches` endpoint allows you to submit multiple places in a single batch for attribute enrichment. The batch will be processed asynchronously, and you can track its status using the returned batch ID. #### Typical workflow: 1. Prepare your batch payload with: - A unique batch name for identification - List of places with their IDs and input data - Optional attribute set specification 2. Submit the batch using the POST `/place_enrichment/batches` endpoint 3. Use the returned batch ID to: - Check batch status at GET `/place_enrichment/batches/{batch_id}` - Retrieve results at GET `/place_enrichment/jobs?batchId={batch_id}` #### Submitting a Batch: Use POST `/place_enrichment/batches` to submit a batch. **Example Batch Payload:** ```json { "batch_name": "NYC Restaurants March 2024", "attributes": ["websites", "phoneNumbers", "socialHandles", "openingHours", "categories", "closed_permanently"], "jobs": [ { "place_id": "place_nyc_123", "inputs": { "name": "Joe's Pizza", "latitude": 40.7359, "longitude": -73.9911, "full_address": "7 Carmine St, New York, NY 10014", "street": "Carmine St", "city": "New York", "state": "NY", "postalCode": "10014", "house": "7", "country": "United States", "country_code": "US", "type": "restaurant", "website": "http://www.joespizzanyc.com", "phone": "+12122555803" } } ] } ``` **Place Input Parameters:** For more details on the place input parameters, see the ```UniversalPlace``` schema in the schemas section below. **Attributes:** The `attributes` parameter in your request specifies which attributes will be enriched. You can specify individual attributes like: - `["websites", "phoneNumbers"]` - Only enrich website and phone information - `["closed_permanently"]` - Only check if the business is permanently closed - `["websites", "phoneNumbers", "socialHandles", "openingHours", "categories", "closed_permanently"]` - Core business attributes - `["websites", "phoneNumbers", "socialHandles", "openingHours", "categories", "closed_permanently", "cuisine", "price_tier", "menu_url"]` - Comprehensive enrichment For a full list of available attributes, see the enrichment schema documentation below. **`attribute_set`:** Deprecated preset for common enrichment requests. Prefer an explicit `attributes` list. `open_closed` checks whether a place is open or permanently closed, while `core` and `all` both request `closed_permanently`, `websites`, `phoneNumbers`, `openingHours`, `names`, `address`, and `categories`. #### Tracking Batch Status: Use GET `/place_enrichment/batches/{batch_id}` to monitor the progress of your batch. The response includes: ```json { "id": "batch_2024_03_15_123456", "batch_name": "NYC Restaurants March 2024", "status": "in_progress", "jobs": { "pending": ["place_id_2", "place_id_3"], "in_progress": ["place_id_1"], "completed": ["place_id_4", "place_id_5"], "failed": [] }, "created_at": "2024-03-15T10:30:00Z", "updated_at": "2024-03-15T10:35:00Z" } ``` The status field will be one of: - `pending`: Batch is queued but not yet started - `in_progress`: Batch is currently being processed - `completed`: All jobs in the batch are finished - `failed`: Batch encountered critical errors #### Retrieving Job Results: Once jobs are completed, use GET `/place_enrichment/jobs?batchId={batch_id}` to get the enrichment results. The response includes: ```json { "jobs": [ { "place_id": "place_nyc_123", "status": "completed", "outputs": { "website": "https://www.joespizzanyc.com", "phone": "+12122555803", "social_profiles": { "instagram": "joespizzanyc", "facebook": "joespizzanyc" }, "open_closed_status": "Open", "price_tier": "$$", "last_enriched": "2024-03-15T10:35:00Z" }, "job_metadata": { "created_at": "2024-03-15T10:30:00Z", "completed_at": "2024-03-15T10:35:00Z", "processing_time_seconds": 300 } } ], "total_count": 1, "completed_count": 1 } ``` Each job result includes: - Original place ID for tracking - Enrichment outputs based on the requested attribute set - Job metadata including timing information - Processing status and any error details if failed **Attribute Statuses:** Attributes like name, address, phone number, and website include an `attribute_status` field indicating the verification state: | Status | Description | |--------|-------------| | NOT_RUN | The attribute was not processed | | RUN_CONDITION_FAILED | The attribute was processed but failed the run condition | | RUN | The attribute was processed | | ERROR | The attribute processing failed | Example response with attribute statuses: ```json { "outputs": { "website": "https://www.joespizzanyc.com", "phone": "+12122555803" }, "job_metadata": { "attribute_status": { "website": "RUN", "phone": "RUN", "address": "RUN", "name": "RUN" } } } ``` version: '1.0' servers: - url: https://api.repromptai.com/v1/{org} variables: org: default: reprompt description: The organization slug to use for the API security: [] paths: /place_enrichment/batches: post: tags: - batches summary: Submit a batch of places for enrichment description: |- Submit a batch of places for enrichment ``` operationId: submit_batch__org_slug__place_enrichment_batches_post parameters: - name: apiKey in: header required: false schema: anyOf: - type: string - type: 'null' title: Apikey requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/PlaceBatchPayload' examples: basic_batch: summary: Basic batch without prefilled data value: batch_id: d98e206f-ff1d-4b5a-b0d8-18fff0757fef batch_name: NYC Restaurants March 2024 jobs: - place_id: place_nyc_123 inputs: name: Joe's Pizza latitude: 40.7359 longitude: -73.9911 full_address: 7 Carmine St, New York, NY 10014 attributes: - websites - phoneNumbers - socialHandles - openingHours - categories - closed_permanently kick_off_jobs_now: true upload_only_batch: summary: Upload-only batch (no immediate processing) value: batch_id: d98e206f-ff1d-4b5a-b0d8-18fff0757fef batch_name: NYC Restaurants Upload Only jobs: - place_id: place_nyc_999 inputs: name: Upload Only Test Place latitude: 40.7128 longitude: -74.006 full_address: 1 City Hall Park, New York, NY 10007 kick_off_jobs_now: false responses: '200': description: Successfully submitted batch for processing content: application/json: schema: $ref: '#/components/schemas/SubmittedPlaceBatchResponse' example: id: batch_2024_03_15_123456 batch_name: NYC Restaurants March 2024 status: pending jobs: pending: - place_nyc_123 - place_nyc_456 in_progress: [] completed: [] failed: [] '400': description: >- Batch size exceeds maximum limit of 50,000 records or invalid input format '401': description: Invalid API credentials security: - HTTPBearer: [] components: schemas: PlaceBatchPayload: properties: batch_id: anyOf: - type: string - type: 'null' title: Batch Id description: >- Optional unique identifier for the batch. If not provided, a new UUID will be generated. If an existing batch ID is provided, new jobs will be added to that batch. batch_name: type: string title: Batch Name description: >- The name of the batch. Only for display purposes. Recommended to use a descriptive human readable name. jobs: items: $ref: '#/components/schemas/PlaceJob' type: array title: Jobs description: List of jobs to process. Maximum of 50,000 jobs per batch. attribute_set: anyOf: - $ref: '#/components/schemas/AttributeSet' - type: 'null' description: >- Deprecated preset applied to every job. Prefer an explicit `attributes` list. `open_closed` checks whether a place is open or permanently closed, while `core` and `all` both request `closed_permanently`, `websites`, `phoneNumbers`, `openingHours`, `names`, `address`, and `categories`. Merged with any explicit `attributes`. attributes: anyOf: - items: type: string type: array - type: 'null' title: Attributes description: >- Batch-level attribute keys applied to every job (copied onto each `PlaceJob`; same merge rules as a single job: combined with `attribute_set`). kick_off_jobs_now: type: boolean title: Kick Off Jobs Now description: >- When true, jobs are enqueued for immediate processing and either attributes or attribute_set must be provided. When false, the batch is created without starting processing (upload only); attributes and attribute_set are optional. default: true owner_id: anyOf: - type: string - type: 'null' title: Owner Id include_in_schema: false type: object required: - batch_name - jobs title: PlaceBatchPayload SubmittedPlaceBatchResponse: properties: id: type: string title: Id description: Unique identifier for tracking the batch example: batch_2024_03_15_123456 batch_name: type: string title: Batch Name description: User-provided name to identify the batch example: NYC Restaurants March 2024 status: $ref: '#/components/schemas/BatchJobStatus' description: >- Current processing status of the batch. Initially PENDING, changes to IN_PROGRESS when processing starts default: pending example: pending jobs: type: object metadata: anyOf: - type: 'null' description: >- Batch statistics and metadata. Basic stats available to all organizations, detailed stats only for Reprompt. attribute_statuses: anyOf: - additionalProperties: $ref: '#/components/schemas/AttributeStatusDistribution' type: object - type: 'null' title: Attribute Statuses description: >- Status distribution per attribute (only populated when enrichments query param is provided) type: object required: - id - batch_name - jobs title: SubmittedPlaceBatchResponse description: >- Represents the response when submitting a new batch of places for enrichment example: batch_name: NYC Restaurants March 2024 id: batch_2024_03_15_123456 jobs: completed: [] failed: [] in_progress: [] pending: - place_nyc_123 - place_nyc_456 - place_nyc_789 status: pending PlaceJob: properties: place_id: type: string title: Place Id description: >- The customer-identifier for the place and retained as external_customer_id in the database. When not set, will automatically generate a UUID. example: place_nyc_123 inputs: $ref: '#/components/schemas/UniversalPlace' description: The place to enrich example: country_code: US full_address: 7 Carmine St, New York, NY 10014 latitude: 40.7359 longitude: -73.9911 name: Joe's Pizza attributes: anyOf: - items: type: string type: array - type: 'null' title: Attributes description: >- List of attribute keys to enrich. See `GET /{org_slug}/place_enrichment/attributes_internal` for available keys and their required inputs. If both attribute_set and attributes are provided, both are merged (explicit attributes are added to the set from attribute_set). example: - websites - categories - closed_permanently attribute_set: anyOf: - $ref: '#/components/schemas/AttributeSet' - type: 'null' description: >- Deprecated preset for common enrichment requests. Prefer an explicit `attributes` list. `open_closed` checks whether a place is open or permanently closed, while `core` and `all` both request `closed_permanently`, `websites`, `phoneNumbers`, `openingHours`, `names`, `address`, and `categories`. attributes_enrichments: anyOf: - items: type: object type: array - type: 'null' title: Attributes Enrichments refresh: type: boolean title: Refresh description: >- If true, will force a refresh of the place even if it has already been enriched. default: false type: object required: - place_id - inputs title: PlaceJob AttributeSet: type: string enum: - open_closed - core - all title: AttributeSet description: Predefined attribute group presets exposed by the API. BatchJobStatus: type: string enum: - pending - queued - in_progress - completed - failed title: BatchJobStatus AttributeStatusDistribution: properties: RUN: $ref: '#/components/schemas/AttributeStatusGroup' ERROR: $ref: '#/components/schemas/AttributeStatusGroup' NOT_RUN: $ref: '#/components/schemas/AttributeStatusGroup' RUN_CONDITION_FAILED: $ref: '#/components/schemas/AttributeStatusGroup' type: object required: - RUN - ERROR - NOT_RUN - RUN_CONDITION_FAILED title: AttributeStatusDistribution description: Distribution of statuses for a single attribute. UniversalPlace: properties: name: type: string title: Name description: >- Required. The business name, most important parameter for researching correct website and profiles. Assumed to be in the local language. full_address: anyOf: - type: string - type: 'null' title: Full Address description: >- Optional but HIGHLY IMPORTANT. Next to the name and coordinates will significantly boost accuracy of outputs if provided. This is the full address like you would see it on a letterhead. country_code: anyOf: - type: string pattern: ^[A-Z]{2}$ - type: 'null' title: Country Code description: >- Two-letter country code (ISO 3166-1 alpha-2 or special codes like XK). If not provided, will be inferred from coordinates category: anyOf: - type: string - type: 'null' title: Category description: >- Optional. A string describing the primary category of the place. Very important for disambiguating, for example, hotels with hotel bars. Reprompt will be able to correct wrong types. website: anyOf: - type: string - type: 'null' title: Website description: >- Optional. If provided will be validated and corrected and prefered as source. Even if wrong still better to provide the website if available. phone: anyOf: - type: string - type: 'null' title: Phone description: >- Optional. Phone in international format. If no international format is provided, based on the latitude/longitude the country pre-fix will be assumed id: anyOf: - type: string - type: 'null' title: Id description: Optional identifier for tracking the place input_type: type: string const: place title: Input Type default: place latitude: anyOf: - type: number - type: 'null' title: Latitude description: >- Optional. The latitude coordinate of the place. Must be between -90 and 90 if provided longitude: anyOf: - type: number - type: 'null' title: Longitude description: >- Optional. The longitude coordinate of the place. Must be between -180 and 180 if provided wkt_geometry: anyOf: - type: string - type: 'null' title: Wkt Geometry description: >- Optional. Instead of latitude and longitude put in a WKT geometry string. This will be converted into latitude and longitude. WKT uses (longitude latitude) coordinate order. street: anyOf: - type: string - type: 'null' title: Street description: Street name component of the address city: anyOf: - type: string - type: 'null' title: City description: City name house: anyOf: - type: string - type: 'null' title: House description: Building number or house identifier state: anyOf: - type: string - type: 'null' title: State description: State or region postalCode: anyOf: - type: string - type: 'null' title: Postalcode description: Postal or ZIP code country: anyOf: - type: string - type: 'null' title: Country description: Full country name opening_hours: anyOf: - additionalProperties: type: string type: object - type: 'null' title: Opening Hours description: Opening hours in a structured format source: anyOf: - type: string - type: 'null' title: Source description: >- Data source this place came from (e.g., 'reprompt', 'overture', 'foursquare') additionalProperties: true type: object required: - name - full_address - latitude - longitude - country_code title: UniversalPlace AttributeStatusGroup: properties: total: type: integer title: Total description: Total count of places with this status ids: items: type: string type: array title: Ids description: List of all place IDs with this status type: object required: - total - ids title: AttributeStatusGroup description: Status group with counts and all IDs. securitySchemes: HTTPBearer: type: http scheme: bearer ````