External API docs

Get business by Openmart ID

Hydrate one or more Openmart business IDs into full business records in a single call.

Overview

Use this endpoint when you already have one or more Openmart IDs (from a previous search or from your own storage) and want the same rich business records that POST /api/v1/search returns.

The response is keyed by input ID. IDs that do not match any record are silently omitted from the response, so check the returned keys if you need partial-match disambiguation. Accepts 1 to 100 IDs per call.

Before you start

Make sure you have:

  • an Openmart account
  • an API key
  • a tool to send API requests, such as Postman or curl

Authentication: send your key in the X-API-Key header. Authorization: Bearer <key> is also accepted. Each returned record costs 1 credit.

GET with a body. This endpoint uses the HTTP GET method but requires the JSON array in the request body. Some HTTP clients, proxies, and CDNs silently drop bodies on GETs. If you see an empty-body 422, confirm your client is actually sending the body.

1

Example: Fetch a business by Openmart ID

Endpoint
GET https://api.openmart.ai/api/v1/business_records/list/openmart_id

cURL request

cURL
curl --request GET \
  --url https://api.openmart.ai/api/v1/business_records/list/openmart_id \
  --header 'Accept: application/json' \
  --header 'X-API-Key: <your_api_key>' \
  --header 'Content-Type: application/json' \
  --data '["54ff8cd5-7497-4f46-9c0c-c6b8c0d10d04"]'

Response example

JSON
{
  "54ff8cd5-7497-4f46-9c0c-c6b8c0d10d04": {
    "brand_id": "cc7eb8ef-8a51-4a53-a1ab-d2a39c163952",
    "store_id": "54ff8cd5-7497-4f46-9c0c-c6b8c0d10d04",
    "business_name": "Curls are Fun",
    "store_name": "Curls Are Fun",
    "business_type": "Curly Hair Stylist & Specialist",
    "business_categories": ["BEAUTY_PERSONAL_CARE"],
    "root_domain": "antonioberducci.com",
    "website_url": "http://www.antonioberducci.com/",
    "city": "San Francisco",
    "state": "California",
    "country": "US",
    "zipcode": "94117",
    "num_stores": 4,
    "google_rating": 5,
    "google_reviews_count": 1,
    "business_emails": null,
    "business_phones": null,
    "staffs": [
      {
        "name": "Antonio Berducci",
        "role": "Curly Hair Stylist & Specialist",
        "source_urls": ["http://www.curlsarefun.com/antonioberducci"]
      }
    ],
    "from_sources": {
      "GOOGLE_MAP": {
        "id": "ChIJfeiVPq-AhYARoD84VjA_-Tg",
        "ref_url": "https://www.google.com/maps/place/?q=place_id:ChIJfeiVPq-AhYARoD84VjA_-Tg",
        "raw_associated_website": "http://www.antonioberducci.com/",
        "name": "Curls Are Fun"
      }
    },
    "info_refreshed_at": "2026-01-14T21:03:41.721668Z"
  }
}

Key elements of the API response

Response element
object keyed by openmart_id
Description
Map from each input ID to its business record. IDs that do not match any record are OMITTED from the response entirely, so the map may be smaller than your request.
Response element
<id>.business_name
Description
Canonical name of the business location.
Response element
<id>.root_domain
Description
Normalized root domain; doubles as a stable brand domain identifier.
Response element
<id>.brand_id / business_type / business_categories
Description
Brand-level attributes (brand_id is shared across all stores belonging to the same brand).
Response element
<id>.business_emails / business_phones / staffs / social_media_links
Description
Brand-level contact and people data. Same shapes as on POST /api/v1/search. Array fields may be null.
Response element
<id>.city / state / country / zipcode / latitude / longitude / street_address
Description
Store-level location for THIS specific store_id. Different store_ids under the same brand can return different locations.
Response element
<id>.google_rating / google_reviews_count / yelp_rating / yelp_reviews_count / price_tier
Description
Store-level quality signals, nullable when unknown.
Response element
<id>.from_sources
Description
Map of upstream source keys (e.g. GOOGLE_MAP, YELP) to {id, ref_url, raw_associated_website, name}.
Response element
<id>.info_refreshed_at
Description
RFC3339 UTC timestamp of the most recent refresh of this record.

All request parameters

Request body for GET /api/v1/business_records/list/openmart_id.

Request body

This endpoint takes a raw JSON array as the request body (no wrapper object).

body (raw JSON array)array[string]Required: Yes
Example: ["54ff8cd5-7497-4f46-9c0c-c6b8c0d10d04"]

Array of 1–100 Openmart IDs (UUID v4 format). The size must be in [1, 100] — outside that returns 422 "the number of ids should be between 1 and 100". Entries that are not valid UUIDs are silently dropped before the datacenter call; if every entry is invalid you get 422 "no valid UUIDs provided".

cURL example
cURL
curl --request GET \
  --url https://api.openmart.ai/api/v1/business_records/list/openmart_id \
  --header 'Accept: application/json' \
  --header 'X-API-Key: <your_api_key>' \
  --header 'Content-Type: application/json' \
  --data '["54ff8cd5-7497-4f46-9c0c-c6b8c0d10d04","3f77d0ec-15c3-40d4-8a48-b74d7c009822"]'
# Get Business by Openmart ID

## Endpoint

GET https://api.openmart.ai/api/v1/business_records/list/openmart_id

## Description

Hydrate 1–100 previously-known Openmart IDs into full business records
in one call. Response is keyed by input ID; IDs with no matching record
are silently omitted.

This is an HTTP GET that requires a JSON body — some clients / proxies
drop GET bodies, so verify your tooling forwards them.

## Authentication

- `X-API-Key: <your_api_key>` (recommended)
- `Authorization: Bearer <your_api_key>` (also accepted)

## Request body

Raw JSON array of 1–100 openmart_id strings (UUID v4):

```json
["54ff8cd5-7497-4f46-9c0c-c6b8c0d10d04","3f77d0ec-15c3-40d4-8a48-b74d7c009822"]
```

- Size outside [1, 100] → 422 `{"error":"the number of ids should be between 1 and 100"}`.
- Entries that fail uuid.Parse are silently dropped; all-invalid input
  → 422 `{"error":"no valid UUIDs provided"}`.

## Billing

1 credit per returned row.

## Example Request

```bash
curl -X GET "https://api.openmart.ai/api/v1/business_records/list/openmart_id" \
  -H "Accept: application/json" \
  -H "X-API-Key: <your_api_key>" \
  -H "Content-Type: application/json" \
  -d '["54ff8cd5-7497-4f46-9c0c-c6b8c0d10d04"]'
```

## Example Response

```json
{
  "54ff8cd5-7497-4f46-9c0c-c6b8c0d10d04": {
    "brand_id": "cc7eb8ef-8a51-4a53-a1ab-d2a39c163952",
    "store_id": "54ff8cd5-7497-4f46-9c0c-c6b8c0d10d04",
    "business_name": "Curls are Fun",
    "root_domain": "antonioberducci.com",
    "city": "San Francisco",
    "state": "California",
    "country": "US",
    "num_stores": 4,
    "business_emails": null,
    "business_phones": null,
    "staffs": [{ "name": "Antonio Berducci", "role": "Curly Hair Stylist & Specialist", "source_urls": ["http://www.curlsarefun.com/antonioberducci"] }],
    "from_sources": { "GOOGLE_MAP": { "id": "ChIJfeiVPq-AhYARoD84VjA_-Tg", "ref_url": "..." } }
  }
}
```

Value shape matches `content` objects from POST /api/v1/search.

## Errors

- 401 — missing or invalid API key
- 402 — credit limit reached
- 403 — preview token (not allowed on this route) or banned user
- 422 — size out of range / no valid UUIDs / JSON bind failure
- 400 — datacenter downstream error