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.
/api/v1
application/json
X-API-Key: uk_live_...
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.
All POST and PUT requests must send:
In production, always use secure HTTPS connections. Insecure plain HTTP requests are blocked.
Sandbox & Testing
Use Sandbox mode to test your API integration safely before going live with real store customers.
- 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). |
{
"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.
Log in with your email and password by calling POST /api/v1/auth/login to get an access token.
Use this token in the Authorization: Bearer <token> header to manage API keys.
Call POST /api/v1/integrations/api-keys to generate an API key (starts with uk_live_ or uk_test_).
Pass your API key in the X-API-Key header to stream search queries directly from your store.
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. |
API Keys
API keys let your store plugins, servers, or apps talk to our API automatically without sharing your personal password.
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. |
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> |
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.
X-API-Key header.
You do not need user logins or session tokens to send searches.
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.