All requests must use HTTPS and the www subdomain — requests to the bare domain are redirected with a 308, and most HTTP clients drop the Authorization header when following cross-host redirects.
The API is read-only: every endpoint is a GET. All responses are JSON. An active Kopimore subscription is required.
Authenticate with an API key in the Authorization header. Create and revoke keys on the API Keys page in your portal. Keys are shown once at creation and stored only as a hash — if you lose one, revoke it and create a new one.
Keys inherit your account's data access: all pixels, read-only. Never expose a key in client-side code, public repositories, or URLs. Requests without a valid key return 401; accounts without an active subscription return 403.
Each key may make 60 requests per minute (fixed one-minute window). Every response includes rate limit headers:
Exceeding the limit returns 429 with a Retry-After: 60 header. Back off until the next minute window. Need a higher limit? Email admin@kopimore.com.
List endpoints use cursor pagination ordered by identified_at descending (newest first). Each page returns has_more and next_cursor; pass the cursor as ?before= on the next request.
To poll for new leads instead, store the newest identified_at you've seen and pass it as ?since= on your next poll.
Errors return an appropriate HTTP status and a consistent JSON body:
| Status | Code | Meaning |
|---|---|---|
| 401 | missing_api_key | No Authorization: Bearer kp_live_... header sent. |
| 401 | invalid_api_key | The key does not exist. |
| 401 | revoked_api_key | The key was revoked in the portal. |
| 403 | subscription_required | The account has no active subscription. |
| 400 | invalid_parameter / invalid_cursor | A query parameter is malformed (e.g. a non-ISO timestamp). |
| 404 | unknown_pixel | pixel_id doesn't belong to this account. |
| 404 | not_found | Unknown endpoint path. |
| 405 | method_not_allowed | Only GET is supported. |
| 429 | rate_limit_exceeded | Per-minute rate limit hit. Honor Retry-After. |
| 500 | internal_error / query_failed | Something failed on our side — retry, or contact support. |
Returns identified visitors across your pixels, newest first.
| Query param | Type | Description |
|---|---|---|
| limit | integer | Results per page, 1–100. Default 25. |
| before | ISO 8601 | Pagination cursor — only leads identified strictly before this time. |
| since | ISO 8601 | Only leads identified at or after this time. |
| pixel_id | string | Restrict to one pixel. Must belong to your account (see GET /pixels). |
| state | string | Two-letter US state code, e.g. TX. |
| city | string | City name, case-insensitive exact match. |
| has_email | boolean | true → only leads with an email address. |
| Field | Type | Description |
|---|---|---|
| id | uuid | Unique lead event ID. |
| identified_at | ISO 8601 | When the visitor was identified. Sort/cursor field. |
| pixel_id | string | Pixel that captured the visit. |
| name | string? | Full name. |
| email / verified_email | string? | Best-known and personally-verified email. |
| phone | string? | Phone number (digits only). |
| company | string? | Employer / company name when resolved. |
| city / state | string? | Location (US state code). |
| gender, age_range, income_range, net_worth, marital_status, homeowner, children | string? | Household demographics. Ranges are bucketed strings. |
| page_url, referrer, traffic_source | string? | Session context for the identifying visit. |
Fields marked string? are null when not resolved for that visitor.
Lists the pixels on your account. Use the returned IDs with the pixel_id filter on /leads.
Request counts for the presented key. Note: calls to /usage itself count toward the totals and the rate limit.
Questions or a use case we don't cover yet? Email admin@kopimore.com — we ship fast.
Grab an API key from your portal and make your first request in under a minute.