UDE
Unmet Demand
API Docs
Tenant Portal
Sandbox Mode Active: You are viewing test documentation. Code examples use test API keys (uk_test_...). Testing here will not affect your real store demand.

Developer API Documentation

Connect your online store, mobile app, or search backend to the Unmet Demand. Send customer search queries and searches that returned zero results in real time to discover what products your buyers are looking for.

Environment: Production
Base URL: /api/v1
Format: application/json
API Key Header: X-API-Key: uk_live_...
Rate Limit: 1,000 req/min

Base URL & Data Formats

All API URLs start with /api/v1. Every request and response body must be formatted in valid JSON.

Request Headers

All POST and PUT requests must send:

Content-Type: application/json Accept: application/json
Secure HTTPS

In production, always use secure HTTPS connections. Insecure plain HTTP requests are blocked.

✔ Secure HTTPS Required

Sandbox & Testing

Use Sandbox mode to test your API integration safely before going live with real store customers.

How to Test in Sandbox
  • Switch to the Sandbox environment at the top right of this page.
  • Use test API keys starting with uk_test_.
  • Send test searches and test logins without affecting real store numbers.
  • When ready for real store traffic, switch to Production and use your live key (uk_live_).

Standard Response Format

All API responses follow the same simple format. Successful calls return your data inside the data field, along with request details in meta.

Whether logging in, creating API keys, or sending search events, all responses look like this:

Response Fields

Field Type Description
success boolean true when the request succeeds, false when there is an error.
data object | array The returned data (included on success).
meta object Request information, including requestId and timestamp.
pagination object? Page details for list results (page, limit, totalItems, totalPages).
Standard Response Format
{
  "success": true,
  "data": {
    "eventId": "67346fe09618f3a3f0c2a71b",
    "status": "ACCEPTED",
    "duplicate": false,
    "occurredAt": "2026-11-16T10:24:00.000Z"
  },
  "meta": {
    "requestId": "req_8a39f1c7d2e4",
    "timestamp": "2026-11-16T10:24:00.125Z"
  }
}

Status Codes & Errors

The API returns standard HTTP status codes. When something goes wrong, you get a clear error message explaining what failed.

Status Code Error Code Meaning & Resolution
200 OK SUCCESS The request worked and returned data.
201 Created RESOURCE_CREATED The resource was successfully created (for example, a new API key).
202 Accepted ACCEPTED The search event was received, saved, and queued for processing.
400 Bad Request VALIDATION_ERROR The request data is invalid or missing required fields. Check invalidParams to see what needs fixing.
401 Unauthorized UNAUTHORIZED Missing or wrong credentials (invalid API key or expired login token).
403 Forbidden FORBIDDEN You do not have permission for this action, or your account is suspended.
429 Too Many Requests RATE_LIMIT_EXCEEDED You sent too many requests (limit: 1,000 per minute). Please slow down and try again.
500 Server Error INTERNAL_ERROR Something went wrong on our side. Share the requestId with support if this continues.

How Authentication Works

We use two simple types of authentication: login tokens for managing your account, and API keys for sending searches from your store.

Step 1
User Login

Log in with your email and password by calling POST /api/v1/auth/login to get an access token.

Step 2
Get Access Token

Use this token in the Authorization: Bearer <token> header to manage API keys.

Step 3
Create API Key

Call POST /api/v1/integrations/api-keys to generate an API key (starts with uk_live_ or uk_test_).

Step 4
Send Search Events

Pass your API key in the X-API-Key header to stream search queries directly from your store.

POST /api/v1/auth/login

Log In as Tenant User (Authenticate Tenant User)

Log in with your tenant account email and password to receive an access token. Tokens stay valid for 24 hours.

Request Headers

Content-Type string REQUIRED Must be application/json

Request Body Parameters

Field Type Required Description
email string REQUIRED Your account email address (e.g. developer@store.com).
password string REQUIRED Your account password.


              
              
Response

              

API Keys

API keys let your store plugins, servers, or apps talk to our API automatically without sharing your personal password.

Save Your Key: Your full secret key is only shown once when created. Copy and save it in a safe place. You cannot see the full key again later.
POST /api/v1/integrations/api-keys

Create an API Key (Generate Integration API Key)

Creates a new API key for your organization. Requires an access token with API key management permission.

Request Headers

Authorization string REQUIRED Bearer <token> (from login response)
Content-Type string REQUIRED Must be application/json

Request Body Parameters

Field Type Required Description
name string REQUIRED A friendly name for the key (e.g. "Production Shopify Store").
permissions string[] OPTIONAL Allowed actions for this key. Defaults to ["search:ingest", "reports:read"]. Allowed scopes: search:ingest, reports:read, requests:create.
expiresInDays integer OPTIONAL Optional number of days until the key expires (1 to 365). Leave empty for no expiry.


              
              
Response

              
GET /api/v1/integrations/api-keys

List API Keys (List Active API Keys)

Returns all API keys for your organization. For security, only the start of the key (like uk_live_a1b2c3d4••••) is shown, not the full secret.

Request Headers

Authorization string REQUIRED Bearer <token>


              
              
Response

              

Search Events API (Main Integration)

This is the main API to connect to your store. Whenever a customer searches your store and finds no results, out-of-stock items, or few matches, send the search query here.

Simple Header Authentication: This endpoint only needs the X-API-Key header. You do not need user logins or session tokens to send searches.
POST /api/v1/integrations/search-events
1,000 req/min limit

Send a Search Event (Ingest Search Event)

Sends customer search data from your store. Saves the search, avoids duplicates using idempotencyKey, and queues the data for demand analysis.

Authentication & Headers

Header Type Required Description
X-API-Key string REQUIRED Your secret key (uk_live_... or uk_test_...) with search:ingest permission.
Content-Type string REQUIRED Must be application/json

Request Body Fields

Field Type Required Description & Rules
idempotencyKey string REQUIRED A unique ID for this search event (up to 128 characters). If a network issue causes a retry, this prevents the same search from being counted twice (e.g. "evt_98a72b14c3" or UUID).
searchText string REQUIRED The search query entered by the shopper (up to 500 characters). For example: "cordless brushless angle grinder 18v".
eventType string OPTIONAL Type of event. Defaults to "SEARCH".
Allowed values: "SEARCH", "PRODUCT_REQUEST", "CATEGORY_REQUEST".
source string OPTIONAL Where the search happened. Defaults to "WEB".
Allowed values: "WEB", "IOS", "ANDROID", "API".
customerName string OPTIONAL Optional customer name or buyer reference (up to 128 characters).
customerEmail string OPTIONAL Optional customer email address (up to 128 characters). Used to alert shoppers when wanted products become available.
location object OPTIONAL Location details:
• country: 2-3 letter country code (e.g. "US")
• region: State or province (e.g. "California")
• city: City name (e.g. "San Francisco")
ipAddress string OPTIONAL Shopper IP address for basic location detection and spam filtering.
language string OPTIONAL Search language code. Defaults to "en".

Duplicate Prevention (Idempotency)

We automatically prevent duplicate searches. If you send a search with an idempotencyKey that we already received, we return the saved record with duplicate: true and status 202 Accepted, so it is not counted twice.



              
              
Response