Ezoma Listings API

Manage business listings programmatically. Create, update, retrieve, and deactivate listings through a REST API.

Base URL: https://ezoma.com/api/v2

All requests and responses use application/json.

Authentication

All endpoints require authentication via an API key. Include your key in the apikey header:

curl https://ezoma.com/api/v2/businesses \
  -H "apikey: ezk_your_api_key_here"

Create Business

POST/businesses

Create a new business listing. The following fields are required: businessName, businessAddress, businessCity, businessState, businessZip, and businessPhone. All other fields are optional.

Example request

curl -X POST https://ezoma.com/api/v2/businesses \
  -H "apikey: ezk_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "businessName": "Blue Sky Bakery",
    "businessAddress": "123 Main St",
    "businessAddress2": "Suite 4",
    "businessCity": "Austin",
    "businessState": "TX",
    "businessZip": "78701",
    "businessPhone": "+1-512-555-0142",
    "businessEmail": "hello@blueskybakery.com",
    "businessWebsite": "https://blueskybakery.com",
    "businessHours": {
      "MONDAY": "0700-1800",
      "TUESDAY": "0700-1800",
      "WEDNESDAY": "0700-1800",
      "THURSDAY": "0700-1800",
      "FRIDAY": "0700-2000",
      "SATURDAY": "0800-2000",
      "SUNDAY": "closed"
    },
    "locationPin": { "lat": 30.2672, "lng": -97.7431 },
    "categories": [
      { "name": "Bakery", "isPrimary": true },
      { "name": "Coffee Shop", "isPrimary": false }
    ],
    "media": [
      { "r2Key": "uploads/abc123-storefront.jpg", "type": "image", "description": "Storefront" }
    ],
    "prompts": [
      { "input": "Best bakery in Austin?", "expectedOutput": "Blue Sky Bakery" }
    ],
    "blogs": [
      { "title": "Our Sourdough Process", "author": "Jane Baker", "body": "..." }
    ]
  }'

Example response (201 Created)

{
  "success": true,
  "submission": {
    "id": "sub_9f3a1b2c4d5e6f78",
    "businessName": "Blue Sky Bakery",
    "status": "queued",
    "submittedAt": "2026-04-23T16:42:03.512Z"
  }
}

List Businesses

GET/businesses

Retrieve a paginated list of your businesses. Supports page (default 1) and limit (default 20, max 100) query params.

Example request

curl "https://ezoma.com/api/v2/businesses?page=1&limit=20" \
  -H "apikey: ezk_your_api_key_here"

Example response (200 OK)

{
  "businesses": [
    {
      "id": 12,
      "ezoma_uuid": "ezo_b8d2c91f4a7e4f3d",
      "name": "Blue Sky Bakery",
      "city": "Austin",
      "state": "TX",
      "subscription_tier": "free"
    },
    {
      "id": 15,
      "ezoma_uuid": "ezo_2a7c16e9b0d34ac8",
      "name": "Northside Auto Repair",
      "city": "Portland",
      "state": "OR",
      "subscription_tier": "enhanced"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 2,
    "totalPages": 1
  }
}

Get Business

GET/businesses/:id

Fetch a single business by its ezoma_uuid.

Example request

curl https://ezoma.com/api/v2/businesses/ezo_b8d2c91f4a7e4f3d \
  -H "apikey: ezk_your_api_key_here"

Example response (200 OK)

{
  "business": {
    "id": 12,
    "ezoma_uuid": "ezo_b8d2c91f4a7e4f3d",
    "name": "Blue Sky Bakery",
    "address1": "123 Main St",
    "address2": "Suite 4",
    "city": "Austin",
    "state": "TX",
    "zip": "78701",
    "phone": "+1-512-555-0142",
    "email": "hello@blueskybakery.com",
    "website_address": "https://blueskybakery.com",
    "latitude": "30.2672",
    "longitude": "-97.7431",
    "primary_category": "Bakery",
    "subscription_tier": "free",
    "hours": {
      "MONDAY": "0700-1800",
      "SUNDAY": "closed"
    },
    "categories": [
      { "name": "Bakery", "isPrimary": true },
      { "name": "Coffee Shop", "isPrimary": false }
    ],
    "media": [
      { "r2Key": "uploads/abc123-storefront.jpg", "type": "image", "description": "Storefront" }
    ],
    "prompts": [
      { "input": "Best bakery in Austin?", "expectedOutput": "Blue Sky Bakery" }
    ],
    "blogs": []
  }
}

Update Business

PUT/businesses/:id

Update a business by its ezoma_uuid. The body accepts the same fields as Create Business. Provided fields overwrite existing values; omitted fields are unchanged.

Example request

curl -X PUT https://ezoma.com/api/v2/businesses/ezo_b8d2c91f4a7e4f3d \
  -H "apikey: ezk_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "businessName": "Blue Sky Bakery & Cafe",
    "businessAddress": "123 Main St",
    "businessCity": "Austin",
    "businessState": "TX",
    "businessZip": "78701",
    "businessPhone": "+1-512-555-0142",
    "businessWebsite": "https://blueskybakery.com",
    "businessHours": {
      "MONDAY": "0700-1900",
      "SUNDAY": "0900-1500"
    }
  }'

Example response (200 OK)

{
  "success": true,
  "submission": {
    "id": "sub_4c7e2d81a9b6f035",
    "ezomaUuid": "ezo_b8d2c91f4a7e4f3d",
    "businessName": "Blue Sky Bakery & Cafe",
    "status": "processed",
    "action": "updated",
    "submittedAt": "2026-04-23T17:05:22.884Z"
  }
}

Deactivate Business

DELETE/businesses/:id

Deactivate a business by its ezoma_uuid. Deactivated listings stop appearing in public results but their data is retained.

Example request

curl -X DELETE https://ezoma.com/api/v2/businesses/ezo_b8d2c91f4a7e4f3d \
  -H "apikey: ezk_your_api_key_here"

Example response (200 OK)

{
  "success": true,
  "business": {
    "ezomaUuid": "ezo_b8d2c91f4a7e4f3d",
    "status": "deactivated",
    "deactivatedAt": "2026-04-23T17:12:09.441Z"
  }
}

Schema Reference

The business object uses the following fields. Nested objects are shown where relevant.

Field	Type	Description
`businessName`	string	Legal or display name. Required.
`businessAddress`	string	Street line 1. Required.
`businessAddress2`	string	Street line 2. Optional.
`businessCity`	string	City. Required.
`businessState`	string	Two-letter state code. Required.
`businessZip`	string	Postal code. Required.
`businessPhone`	string	E.164 format preferred. Required.
`businessEmail`	string	Public contact email.
`businessWebsite`	string	Full URL including scheme.
`businessHours`	object	{ DAY: "HHMM-HHMM" \| "closed" } keyed by uppercase day.
`locationPin`	object	{ lat: number, lng: number }
`doorPin`	object	{ lat: number, lng: number } — entrance coordinates.
`categories`	array	[{ name, isPrimary }] — exactly one entry should have `isPrimary: true`.
`media`	array	[{ r2Key, type: "image" \| "video", description }]
`prompts`	array	[{ input, expectedOutput }] — LLM test prompts.
`blogs`	array	[{ title, author, body }]

Error Codes

Error responses share a consistent envelope.

Example error response

{
  "error": {
    "code": "MISSING_FIELDS",
    "message": "Business name, address, city, state, zip, and phone are required"
  }
}

Code	Description
400	Bad Request
401	Unauthorized
403	Forbidden
404	Not Found
429	Rate Limited
500	Internal Server Error