A machine-readable description of every endpoint is at https://api.seekapedia.com/v1/openapi.json (OpenAPI 3.1).
Authentication
Send your key as a bearer token on every request. Requests without a valid key get 401.
Request a key.
Authorization: Bearer YOUR_API_KEY
GET /v1/health needs no key and shows record counts and data freshness.
Verify a license
GET /v1/verify?state=TX&license_number=200114825
curl -H "Authorization: Bearer YOUR_API_KEY" \
"https://api.seekapedia.com/v1/verify?state=TX&license_number=200114825"
{
"found": true,
"id": "TX:200114825",
"state": "TX",
"license_number": "200114825",
"license_type": "MB",
"legal_name": "AIR STAR CONCESSIONS LTD.",
"trade_name": "Whataburger",
"city": "Dallas",
"status": "active",
"status_raw": "Active",
"expiration_date": "2027-12-26",
"expiration_passed": false,
"source_url": "https://data.texas.gov/d/7hf9-qc9f",
"data_as_of": "2026-11-19T03:22:56.342Z",
"disclaimer": "Status is taken from the official state source as of data_as_of. It is information to check, not legal advice."
}
Shortened. Full records also include address, county, zip, tier, issue date and description. If no license matches, found is false.
Freshness and conflicts
Every license in a response carries three separate answers. They are never folded into one flag.
statusandstatus_raw: what the agency reports, exactly as published.freshness: whether that answer is recent.ingestionsays whether we fetched the source on schedule;publicationsays whether the agency published on its own schedule;reverificationsays whether this license appeared in a recent successful fetch.stateiscurrent,overdue(withreasons) orunknown. Times the agency does not publish, such as a record's own change time or a status effective date, arenull, never our fetch time.reconciliation: whether the sources agree:single_source,consistent, orunresolved_conflictwith theconflicting_fieldsandreview_required: true. No agency we cover publishes effective dates, so a conflict is never settled by assuming the newest download is the newest fact.observationslists every source row behind the answer.
"freshness": {
"state": "current",
"reasons": [],
"ingestion": "current",
"publication": "current",
"reverification": "current",
"last_successful_fetch_at": "2026-11-20T14:45:00.000Z",
"source_published_at": "2026-11-20T13:31:57.000Z",
"first_seen_at": "2026-11-19T03:22:56.342Z",
"last_seen_at": "2026-11-20T14:45:00.000Z",
"last_changed_at": null,
"present_in_latest_source": true
},
"reconciliation": {
"state": "single_source",
"conflicting_fields": [],
"review_required": false,
"flags": []
}
A license that disappears from a download is kept and flagged
(present_in_latest_source: false), not reported as closed. Absence from a file is not a revocation.
A download that looks broken (a sharp drop in records, many licenses vanishing at once, a spike in blank license numbers
or unrecognized statuses, a missing column, a login page instead of data, or the same page twice) is quarantined:
we keep serving the last validated data, and the freshness block shows it as overdue.
Same-premises licenses
Single lookups also return same_premises: other licenses at the same normalized street address and ZIP,
with separate similarity scores for the owner name and the business name. These are candidates
(link_state: "candidate"), never merged: one store can hold several licenses, and one owner can run many
businesses at one address, such as an airport. units_differ marks different suites in the same building.
If there are more than 25, truncated is true.
History and sources
GET /v1/history?state=TX&license_number=200114825 returns every recorded change to one license, newest first.
GET /v1/sources (no key needed) lists each source dataset: the agency, what it is authoritative for, its schedule,
our last successful fetch, the agency's last publication time, and whether either is overdue.
Verify in bulk
POST /v1/verify/batch with up to 500 items. Results come back in the same order.
curl -X POST -H "Authorization: Bearer YOUR_API_KEY" -H "content-type: application/json" \
-d '{"items":[{"state":"TX","license_number":"200114825"},{"state":"NY","license_number":"0340-23-123456"}]}' \
"https://api.seekapedia.com/v1/verify/batch"
Search by name
GET /v1/search?name=whataburger&state=TX&limit=25 matches legal or trade names that contain the text.
state is optional; limit is 1 to 100 (default 25).
Change feed
GET /v1/changes returns the changes found by the latest daily sync.
Add since=2026-11-01 to get every change after a date, and state=TX to filter.
limit defaults to 1,000 (max 5,000).
Change types: added, status_changed, expiration_changed,
missing_from_source, reappeared and conflict_detected.
Watches and webhooks
Watch a license and we POST to your HTTPS endpoint after any daily sync in which it changed.
curl -X POST -H "Authorization: Bearer YOUR_API_KEY" -H "content-type: application/json" \
-d '{"state":"TX","license_number":"200114825","webhook_url":"https://example.com/hooks/licenses"}' \
"https://api.seekapedia.com/v1/watches"
The response includes each watch's secret. It is shown once; store it to check signatures.
Send {"items":[...],"webhook_url":"..."} to watch up to 500 licenses at once.
GET /v1/watches lists your watches; DELETE /v1/watches/{id} removes one.
Webhook body:
{
"event": "license.changed",
"delivery_id": "...",
"watch_id": "w_...",
"license_id": "TX:200114825",
"data_as_of": "2026-11-20T10:00:00.000Z",
"changes": [{ "type": "status_changed", "from": "active", "to": "suspended" }],
"current": { "...": "the license as it now stands" }
}
Return any 2xx status to acknowledge. Failed deliveries are retried after 1, 2, 4, 8 and 16 hours, then dropped after 6 attempts. Webhook URLs must be public HTTPS addresses.
Checking signatures
Each webhook has two headers: x-license-timestamp and x-license-signature: sha256=<hex>.
The signature is HMAC-SHA256 of <timestamp>.<raw body> using the watch secret. Node example:
import crypto from 'node:crypto';
function isValid(rawBody, headers, secret) {
const ts = headers['x-license-timestamp'];
const expected = 'sha256=' + crypto.createHmac('sha256', secret).update(`${ts}.${rawBody}`).digest('hex');
const got = headers['x-license-signature'] ?? '';
return got.length === expected.length && crypto.timingSafeEqual(Buffer.from(got), Buffer.from(expected));
}
Reject deliveries whose timestamp is far from the current time to stop replays.
Fields
id | State and license number, like TX:200114825. |
record_kind | license, or application for New York pending applications. |
status | Normalized status (see the overview page). |
status_raw | The state's own wording. |
expiration_date | As published by the state. |
expiration_passed | Computed by Seekapedia: true if the expiration date is before today. |
legal_name, trade_name | Licensee and business name as published. |
source_url | The government dataset the record came from. |
data_as_of | When the data was last read from the source. |
The Cannabis License API
It uses the same schema, checks, change feed and webhooks as the Liquor License API, with its own data and its own sync at 16:30 UTC. It covers three states that publish cannabis licenses as open data:
Oregon (OLCC), New York (Office of Cannabis Management) and Connecticut (Department of Consumer Protection). Oregon words its status as ACTIVE, EXPIRED, INACTIVE, REVOKED,
SUSPENDED or CANCELLED; revoked is reported as cancelled with the agency's word kept in status_raw. New York's file also lists applicants that hold proximity protection
(In-Process and PCA Under Review), which are reported as pending, never as licenses; Amendment Under Review is reported as unknown. Connecticut's list has no status or expiration
column, so being listed is what we report as active, with no expiration date. A license here is a state license only. Federal law still treats cannabis as a controlled substance, each state regulates it differently, and we do not cover enforcement actions, conditions or local permits.
California (Department of Cannabis Control), Washington, Colorado and other states are not included yet.
California identifiers
One California file number can hold several licenses, each with its own type, status and expiration. A license is identified as
<file number>-<type> with leading zeros kept, for example 00533825-41. A duplicate copy adds -001,
and an application record adds -APP. Dropped zeros are accepted (533825-41). A bare file number (533825) is not a license: the answer is
found: false with a file_number_matches list of what it holds.
Application rows are separate records. In 545 California file numbers the application row says active while the license row is revocation-pending, so they are never compared.
/v1/search returns licenses only; add record_kind=application or record_kind=all to include applications.
Pagination and export
Every list endpoint takes limit and cursor and returns a pagination block. Cursors resume from the last row, so page 5,000 costs the same as page 1.
They are signed, last 24 hours, and are tied to the endpoint, the filters and your key.
{
"count": 50,
"pagination": { "limit": 50, "has_more": true, "next_cursor": "eyJ2Ijox..." }
}
| Endpoint | Default / max page |
|---|---|
/v1/changes | 1,000 / 5,000 |
/v1/search, /v1/portfolios/{id}/items, /v1/watches | 25 / 100, 100 / 500, 100 / 500 |
/v1/deliveries, /v1/checks, portfolio status and exceptions | 50 / 200 |
/v1/export | 1,000 / 5,000 |
A bad cursor returns 400 invalid_cursor with a reason (tampered, expired, filters_changed, wrong_owner, wrong_endpoint, malformed). Start again without it.
Export. GET /v1/export?state=CA&record_kind=license&status=active pages through whole records, filterable by state, record kind and normalized status.
Data changes only when a daily sync lands, so a cursor pinned to one sync reads one consistent snapshot. If a sync lands mid-export, the next page returns 409 snapshot_expired; start again.
Likewise the latest-sync /v1/changes feed. Reading history with since= never expires.
Standard checks and evidence
POST /v1/checks evaluates one business location and saves the result as evidence. Send an identifier, or a name with the address and ZIP when you have them.
curl -X POST -H "Authorization: Bearer YOUR_API_KEY" -H "content-type: application/json" \
-H "Idempotency-Key: onboarding-77" \
-d '{"name":"Maple Market","address":"7 Maple Avenue","zip":"75001","policy":"onboarding","reference":"vendor-77"}' \
"https://api.seekapedia.com/v1/checks"
match_outcome is exact_identifier_match, probable_match, candidates_need_review or no_match.
The result carries the subject (with freshness and reconciliation), the candidates with scores, the sources that back it, the limitations, and a billing block.
GET /v1/checks/{id} returns the saved result and GET /v1/checks lists them, neither billed. DELETE /v1/checks/{id} removes one.
POST /v1/checks/batch takes up to 50 submissions as {"items":[...],"policy":"onboarding"}, saves each as its own check, and reports items it rejected without failing the rest. One Idempotency-Key covers the whole batch.
An Idempotency-Key header makes a retry safe: the same key returns the saved result with idempotent_replay: true and is not counted again.
It also works on /v1/verify and /v1/verify/batch for metering.
Policies: your decision, kept separate
The data result says what the sources report. A policy is your rule for what to do about it, evaluated separately and returned as customer_policy_result.
The API never returns an unqualified "compliant". Outcomes are meets_policy, review_required and does_not_meet_policy, with the reasons.
curl -X POST -H "Authorization: Bearer YOUR_API_KEY" -H "content-type: application/json" \
-d '{"policy_id":"onboarding","name":"Onboarding","rules":{"allowed_statuses":["active"],"review_statuses":["pending"],"unresolved_conflict":"fail"}}' \
"https://api.seekapedia.com/v1/policies"
Each save is a new immutable version. Apply one with policy=onboarding (and optionally policy_version=1) on /v1/verify and portfolio endpoints,
or "policy" in the body of /v1/checks and /v1/verify/batch. Rules, with defaults:
allowed_statuses: ["active"] review_statuses: []
allowed_record_kinds: ["license"] max_data_age_hours: null
expiration_passed / freshness_overdue / freshness_unknown / unresolved_conflict /
missing_from_source / no_match / candidates_need_review: "ignore" | "review" | "fail" (default "review")
data_result always includes enforcement_review_state: "not_covered": enforcement actions, findings and license conditions are not part of this data.
Portfolios and exception queues
POST /v1/portfolios creates a named set of licenses. POST /v1/portfolios/{id}/items adds up to 500 at a time and, with a webhook_url, starts watching each one
(licenses you already watch are not duplicated). GET /v1/portfolios/{id}/status returns every license's current answer;
GET /v1/portfolios/{id}/exceptions returns only those needing a person, with reasons such as status_suspended, expiration_passed_while_active,
missing_from_latest_source, unresolved_conflict and freshness_overdue. Add policy= to also queue anything that does not meet that policy.
Webhook history, replay and test events
GET /v1/deliveries lists your deliveries newest first (filter by status, watch_id, license_id) with a derived state:
queued, retry_scheduled, delivered or failed. POST /v1/deliveries/{id}/replay queues one again for the next hourly run.
POST /v1/watches/{id}/test sends a signed synthetic license.test event right away so you can test your endpoint; it is not retried and not billed.
CSV export
GET /v1/export?format=csv returns the same paged export as a spreadsheet-ready download: the header row on the first page only, the next cursor in the x-next-cursor response header (empty on the last page), and x-data-as-of. Pass the cursor back to continue.
Any cell that begins with =, +, - or @ is prefixed with an apostrophe so a spreadsheet never runs agency text as a formula. Rows count as export rows in usage.
Team keys and roles
POST /v1/members (admin) creates a key for a person with a role and returns it once; DELETE /v1/members/{id} revokes it. Team keys act inside your account, so they see the same portfolios, policies and checks.
| Role | May |
|---|---|
| viewer | Read everything except the audit log and members. |
| reviewer | Viewer, plus open, assign, comment on, escalate and submit reviews, and run checks. |
| approver | Reviewer, plus approve or reject submitted reviews and read the audit log. |
| admin | Everything, including members, policies, portfolios, watches and alerts. Your account key is an admin. |
Single sign-on
An admin connects one OpenID Connect provider (Okta, Microsoft Entra, Google Workspace or any compliant provider). SAML is below. with PUT /v1/sso: issuer, client_id, client_secret,
allowed_domains (email domains that may sign in), a default_role, and optionally a group_claim with group_roles mapping group names to roles. The response gives the redirect_uri to register
with your provider and a login_url. People open the login URL, sign in at your provider, and receive a key (shown once) valid for 8 hours with their role; the highest mapped group wins and the role is re-read at every sign-in.
Members appear in GET /v1/members; revoking one ends their access at once. Sign-ins are written to the audit log. SSO cannot grant admin by default; only an explicit group mapping can.
SAML 2.0 sign-in
Alternatively, connect a SAML 2.0 provider with PUT /v1/saml: idp_sso_url, idp_issuer (the provider's entity id), idp_certificate (its signing certificate, up to three for rollover),
allowed_domains, a default_role, and optionally a group_attribute with group_roles. The response gives sp_entity_id, acs_url and a metadata_url for your provider, and a login_url for people.
Sign-in starts at our side. The assertion itself must be signed, must answer a request we made, and can be used once; unsolicited provider-initiated responses are refused. The email comes from an email or mail attribute, or the subject if it is an email address.
Provisioning with SCIM 2.0
PUT /v1/scim (admin) enables provisioning and returns a bearer token once, plus the base_url for your provider's SCIM connector. Set a default_role and optionally group_roles mapping group names to roles.
Your provider then creates people, updates them, and deactivates them (/scim/v2/Users, with userName eq and externalId eq filters and PATCH as Okta and Entra send it), and pushes groups (/scim/v2/Groups).
A person's role is the highest of their directly assigned role and their mapped groups, re-applied whenever either changes. Deactivating or deleting someone revokes their access at once, including any sign-in key they hold.
People provisioned over SCIM sign in as that same member, and while SCIM is on, nobody who was not provisioned can sign in. Rotate the token with {"rotate_token": true}; DELETE /v1/scim turns it off.
Bulk operations, sorting and ETags are not supported.
Historical evaluation
GET /v1/as-of?state=TX&license_number=123&as_of=2026-11-19T12:00:00Z returns the license as our data stood at that time, rebuilt by undoing the changes we recorded since, with the same data_result and exception reasons as today.
Add policy= to judge it: policy_version=2 for a specific version, policy_in_force=true for the version that was saved most recently before as_of, or neither for the latest.
A bare date means the end of that day (UTC). The same as_of, policy and policy_in_force parameters work on GET /v1/portfolios/{id}/status and /exceptions.
POST /v1/checks/{id}/reevaluate and GET /v1/reviews/{id}/reevaluate?policy= re-judge the data saved with a check or review under another policy, without touching the saved item or using today's data.
The answer shows the original outcome beside the new one.
This is our data as of then, not a statement of what was true at the agency, and a later agency correction is not applied backwards. We hold history only from our first sync, history_available_since in every answer; earlier times are refused.
The agency's own status text is not kept per sync, so it is not reconstructed (the normalized status is). Whether a data conflict was resolved before or after the time is not recorded; where that matters the answer lists it under uncertain.
Historical lookups count as lookups in usage.
Reviews and approvals
POST /v1/reviews opens a review for a license (license_id, optional assignee, due_at, portfolio_id). It records the data as it was, and why it needs a person
(the same reasons as the exception queue). POST /v1/reviews/from-exceptions opens one for each current exception in a portfolio.
A review moves open or in_review or escalated to pending_approval (/submit with a recommendation of acceptable or not_acceptable and a note) to approved (/approve),
or back to in_review (/reject, with a note). Other actions: /assign, /escalate (to an approver or admin) and /comment.
The person who submitted a review cannot approve it, and an approved review is closed: open a new one to look again. GET /v1/reviews lists them (filter by status, assignee, license_id).
GET /v1/reviews/{id}/package returns a decision package: the data when the review opened, the data now, and every step.
A review records who decided what about the data. It is not a finding that a business meets any legal obligation.
Audit log
Every review step, member change, alert change and successful change through the API is appended to your account's audit log with the actor and their role. Each entry's hash covers the one before it,
so an edit or deletion breaks the chain. GET /v1/audit and GET /v1/audit/export (approver or admin) page through it with filters; GET /v1/audit/verify checks the whole chain.
Exports include the rule to verify them offline, and format=ndjson on the export returns one entry per line as a download, with the next cursor and the chain tip in response headers.
Email alerts
POST /v1/alerts (admin) subscribes an address to review_assigned, approval_requested, review_decided, review_overdue and watch_changes.
Nothing is sent until the address owner clicks the confirmation link we email. Review emails carry the review id and license id only, never record details.
watch_changes is a digest after each daily update of changes to licenses you watch or hold in portfolios; review_overdue is a daily list of open reviews past their due_at (list them yourself with GET /v1/reviews?overdue=true). Webhooks remain the way to receive changes into your own systems.
Review webhooks
POST /v1/webhooks (admin, Govern plan) registers an https address for review_assigned, approval_requested and review_decided, up to five per account. The response carries a signing secret once.
Each delivery is a JSON body with event, id, sent_at and a small data object (review id, license id and the decision; never record details), and the headers x-license-timestamp and x-license-signature: sha256= plus the HMAC-SHA256 of <timestamp>.<body> with your secret. Reject old timestamps.
Redirects are not followed, a receiver gets four seconds, and there are no retries: a failed delivery is recorded as last_status and last_error in GET /v1/webhooks, and the review is always the source of truth. POST /v1/webhooks/{id}/test sends a synthetic event.
Rate limits
Each account may make about 600 requests a minute; past that the API answers 429 with retry-after and error: "rate_limited". Repeated requests with an invalid key from one address are also refused for a minute.
These burst limits are separate from your monthly plan quotas, and they are enforced per server instance, so treat the figure as approximate. Ask us if you need a higher ceiling.
Usage and billing units
GET /v1/usage reports this month's standard checks and lookups, your current monitored locations (one per premises, however many licenses), and active watches,
with the definitions. See Plans.
Read before relying on it
- Active but past expiration. States sometimes keep a license marked active after its expiration date,
often while a renewal is processed. We report the state's status and
expiration_passedside by side and don't decide between them. Treatexpiration_passed: trueas a reason to check. - Applications (New York pending, California application rows) are applications, not licenses (
record_kind: "application"). - Enforcement and conditions are not covered. Not finding any is not evidence that none exist.
- Freshness. Data is only as current as the state publishes it. We read every source once a day at 14:45 UTC, after Texas (about 13:30 UTC), New York (about 01:35 UTC) and Oregon (about 15:10 UTC the day before) publish. Colorado publishes monthly. Check the
freshnessblock on each answer. - Not legal advice and not a consumer report. Do not use it to make decisions about individuals' employment, housing, credit or insurance.
Coverage
| State | Records |
|---|---|
| Texas | 128,945 |
| California | 128,294 |
| New York | 126,335 |
| Georgia | 98,892 |
| Virginia | 59,500 |
| Florida | 55,249 |
| Michigan | 35,861 |
| Oregon | 22,182 |
| Indiana | 17,086 |
| Colorado | 16,800 |
| Washington | 16,257 |
| Missouri | 15,907 |
| Nebraska | 8,163 |
| Total | 729,471 |
Live count from the API. Data as of November 21, 2026.
