1. Overview
The Public Pull API is an HTTPS API mounted at /v1/*. Most of it is read-only: it is designed for enterprise integrations where push delivery (outbound webhooks) isn’t a fit — for example, batch CRM syncs, data-warehouse loaders, or iPaaS recipes that prefer a polling model. It can also create cases (section 7), record a decision on a screening hit and an exit a customer led (section 4), and run company registry lookups (section 8) and sanctions and PEP screening (section 9).
Every response is scoped to the tenant that owns the access token. Cross-tenant requests return 404 uniformly — there is no existence leak.
What you can pull: cases, documents (with extracted data), case decisions, screening hits, and a unified event feed that mirrors our outbound webhook payloads.
2. Authentication
Mint a client_id and client_secret in Compliance Configuration → Public Pull API (the API Console in an API-only workspace). You need the Compliance Admin role or above. The secret is shown once — store it in your CRM/iPaaS secret manager.
Exchange the credentials for a 1-hour Bearer token via the OAuth2 client-credentials grant:
curl -X POST https://www.firstmilelabs.com/v1/oauth/token \
-H "Content-Type: application/json" \
-d '{
"grant_type": "client_credentials",
"client_id": "pk_live_abc123",
"client_secret": "sk_live_xxxxxxxxxxxx"
}'
# → { "access_token": "eyJhbGciOi…", "token_type": "Bearer",
# "expires_in": 3600, "scope": "read:cases read:documents read:events read:decisions read:screening" }Pass the token as Authorization: Bearer … on every API call. Tokens are signed JWTs that last an hour. Rotating a key stops its old secret at once, but a token it has already issued runs until it expires. Revoking the client stops its tokens on the next call: ask First Mile Labs to revoke one.
Scopes: read:cases, read:documents, read:events, read:decisions, read:screening, read:full_case (full-parity case egress — only returns data when the tenant has full-parity egress enabled), plus the write scopes cases:write (one-click onboarding initiation — see section 7), screening:write (a decision on a screening hit — see section 4), documents:request (asking a customer for what they still owe — see section 4) and cases:exit (an exit a customer led — see section 4), which is offered only while customer exits are switched on for your workspace. Subset at creation time if you want to follow least-privilege.
Product scopes: read:registry, read:registry_enhanced and read:registry_ubo (section 8) need the KYB product, and screening:run (section 9) the Screening product. What your workspace holds is checked on every call: without API access a call returns 403 api_access_disabled, and without the product behind a scope, 403 product_not_entitled.
Deactivated workspaces: for the 12 months of its download window, a deactivated workspace keeps its case data: GET calls needing read:cases, read:full_case, read:documents, read:decisions, read:screening or read:events still work. Every other call returns 403 workspace_deactivated, and once the window ends every call returns 403 workspace_deactivated_expired. Reactivating the workspace brings your keys back unchanged.
3. Pagination & rate limits
List endpoints return at most limit rows (default 50, max 200) in data, plus an opaque nextCursor and a boolean hasMore. Pass the cursor back verbatim on the next call:
GET /v1/cases?limit=100&cursor=eyJ0Ijoi…Default rate limit is 120 requests / minute / client on each route (the token endpoint is limited to 30 req/min per client). When throttled we return 429 with a Retry-After header in seconds. UK company lookups also draw on a limit every client shares, which answers the same way, with the code registry_rate_limited. A refused lookup isn't billed.
4. Cases
GET /v1/cases returns the case list. Filters: status, updatedSince, createdSince. GET /v1/cases/{caseId} returns a single case including its current decision and risk band, and /v1/cases/{caseId}/decisions, /v1/cases/{caseId}/screening and /v1/cases/{caseId}/documents expose the case’s decision, its screening hits and its documents. A case holds one decision, the current one, so /decisions returns at most one row and is not a history.
caseId is the UUID to pass back to the API. friendlyRef is the human-readable reference, for display and search.
curl https://www.firstmilelabs.com/v1/cases?limit=50 \
-H "Authorization: Bearer eyJhbGciOi…"
# → { "data": [ { "caseId": "8a0e8d9c-…", "friendlyRef": "BCB-2026-00123",
# "companyName": "Acme Ltd", "status": "approved",
# "updatedAt": "2026-05-14T09:18:42Z", … } ],
# "nextCursor": "eyJ0Ijoi…", "hasMore": true }Periodic review dates. Early access Both case reads carry nextReviewDueOn, the day an approved customer’s next periodic review is due (YYYY-MM-DD; a day before today is overdue), and lastReviewedAt, when they were last reviewed. Both are null unless periodic review is switched on for your workspace, on Lift and above. updatedAt and updatedSince move when either changes.
The full case record. Early access GET /v1/cases/{caseId}/full returns everything we hold on a case in one response: the company profile, the ownership roster, each document with its extracted data, and the decision, risk and screening summary. It needs the read:full_case scope and full-parity egress, which First Mile Labs unlocks for a workspace and your compliance admin then switches on. Until both are done it answers 403 full_parity_not_enabled.
Screening hits. POST /v1/cases/{caseId}/screening/disposition records a decision on a hit from your CRM. Send hitId, action (dismiss, approve or escalate), note and officerName. It needs the screening:write scope, and does what the same action does in the analyst console, including assessing the case’s risk again.
Exited customers. Early access Only where customer exits are switched on for your workspace. Once a customer’s exit has ended, the case’s status is exited and exitedOn is the day the relationship ended. updatedAt and updatedSince move when an exit ends, and when one is reversed. Why a relationship ended is never on the API.
An exit the customer led. Early access POST /v1/cases/{caseId}/exit records one when your own system hears first: send reasonCode (customer_request or ceased_trading), reasonNote, endOn and evidenceDocumentId, a document already on the case. An end date of today or earlier ends it at once; the reply holds ids, states and dates, never the reason. It needs the cases:exit scope, and customer exits switched on for your workspace: without them it answers 403 exits_not_enabled. An exit the firm leads needs two people, so it is recorded in the app.
Asking the customer for documents. GET /v1/cases/{caseId}/outstanding-items lists what the customer still owes by your rules for the case’s jurisdiction: documents, identity documents and, with the EDD workflow, EDD evidence and each person’s Source of Wealth. POST /v1/cases/{caseId}/document-requests asks for those items, or the ones you send. With delivery: "email" we email the customer in your template, brand and their language. With delivery: "link" we send nothing and return uploadUrl, once, for you to send through your own channel: anyone holding it can upload to the request until it expires. A request still open to the same person takes the new items, so the customer keeps one link. GET /v1/cases/{caseId}/document-requests says where each item stands, and the document_request.created and document_request.submitted webhooks follow. Asking needs the documents:request scope; reading needs read:cases.
5. Documents
GET /v1/documents lists every document across the tenant (filter by caseId or status). GET /v1/documents/{id} returns the full record including the structured extractedData JSON produced by AI document intelligence — perfect for hydrating your CRM with the company name, registration number, directors, and so on.
6. Event feed (your webhook events, pulled)
GET /v1/events mirrors the payloads we send via outbound webhooks, deduped by eventId. The shape of data is identical to the corresponding webhook event.
It is not a feed of everything that happens. It reads the record of webhook deliveries, so it holds an event only if an active webhook endpoint in your workspace was subscribed to that event type when the event happened. A workspace with no endpoint has an empty feed, so the feed can’t replace webhooks: set up an endpoint for the event types you want, then use the feed to pull the same events in batches, or to catch up after an outage on your side.
curl "https://www.firstmilelabs.com/v1/events?event_type=case.decision.made&limit=100" \
-H "Authorization: Bearer eyJhbGciOi…"
# → { "data": [ { "eventId": "evt_…", "eventType": "case.decision.made", "eventVersion": 1,
# "occurredAt": "2026-05-14T09:18:42Z", "data": { … } } ],
# "nextCursor": "eyJ0Ijoi…", "hasMore": false }
#
# The shape of `data` for each `eventType` is identical to what you
# receive on push delivery. /schemas/webhooks/index.json lists the event
# types that have a JSON Schema, at /schemas/webhooks/<eventType>.v1.json.For a full payload reference, see the Outbound Webhook Guide.
7. Initiate onboarding (one-click from your CRM)
POST /v1/cases starts onboarding from your CRM. A single call creates a case in First Mile Labs, sends the customer their tenant-branded magic-link invite, and starts emitting case.created outbound webhooks back to your CRM. Requires the cases:write scope.
It creates business cases only: there is no call that opens a case for an individual customer. A workspace set up for individual onboarding only is refused with 403, code onboarding_scope_blocked.
curl -X POST https://www.firstmilelabs.com/v1/cases \
-H "Authorization: Bearer eyJhbGciOi…" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: sfdc-0015g00000abc123" \
-d '{
"customerEmail": "ceo@acme.example",
"customerName": "Jane Doe",
"companyName": "Acme Holdings Ltd",
"country": "United Kingdom",
"crmRecordId": "0015g00000abc123",
"crmSource": "salesforce",
"sendInvite": true
}'
# → 201 Created
# {
# "caseId": "8a0e8d9c-…",
# "customerEmail": "ceo@acme.example",
# "customerName": "Jane Doe",
# "companyName": "Acme Holdings Ltd",
# "crmRecordId": "0015g00000abc123",
# "crmSource": "salesforce",
# "source": "api",
# "status": "in-progress",
# "inviteSentAt": "2026-05-15T09:14:11.421Z",
# "customerPortalUrl": "https://app.firstmilelabs.com/",
# "analystUrl": "https://cases.firstmilelabs.com/?case=8a0e8d9c-…"
# }
#
# A second call with the same Idempotency-Key OR the same crmRecordId
# returns the existing case (200 OK, Idempotent-Replay header set) instead
# of minting a duplicate.Idempotency. Three independent dedup layers, all per-tenant:
Idempotency-Keyheader — caller-supplied. Replays return the original status + body withIdempotent-Replay: true.(orgId, crmRecordId)— passcrmRecordIdand a second call for the same upstream record returns the existing case (200 OK,Idempotent-Replay: crm-record-id). Bypass with{"allowDuplicateCrmRecord": true}when you genuinely want a second case.(orgId, customerEmail)open-case guard — a second call for a customer who already has an open (non-closed) case in this tenant returns409with{ error: 'duplicate_open_case', existing: { caseId, … } }. Bypass with{"allowDuplicate": true}when you genuinely want to mint a parallel case — the override is recorded in the tenant's configuration audit log.
Case allowance. A tenant on a case allowance (a proof of concept, for instance) that has opened all the cases it covers gets 402 with { error: 'case_allowance_reached', allowance, used }, and no case is created. First Mile Labs can raise the allowance; the Idempotency-Key is released, so the same key can be retried after that.
Cases minted this way appear in the analyst dashboard with a coloured API · {CRM} badge so analysts can tell at a glance which rows came in via sales rather than the upload portal.
CRM admins: see the end-to-end Salesforce integration guide (named-credential, Apex helper, Lightning quick-action) or the HubSpot integration guide (Workflow + Custom Code action), or the Zapier integration guide (Webhooks by Zapier — no custom Zapier app required) for the full one-click recipe.
8. Company registry
Look a company up on its register without opening a case. A key that holds only these scopes can’t reach your cases. There are three tiers, each with its own scope:
- LITE (
read:registry):GET /v1/registry/searchandGET /v1/registry/company. Legal name, registration number, status, legal form, incorporation date and registered address, from the national register. - ENHANCED (
read:registry_enhanced):GET /v1/registry/enhanced/searchreturns candidates, andGET /v1/registry/enhanced/companythe profile: LITE plus company activity, directors and officers, registered shareholders, capital, direct ownership percentages and registered agents. - UBO (
read:registry_ubo):GET /v1/registry/ubo/companywalks ownership to natural persons, with their effective percentages and a graph of the chain.ubos: []doesn’t mean a company has no owner: readunresolvedBranchesandnonContinuationReasonsbefore you conclude anything.uboThreshold(default 25),maxLayers(default 5) andmaxCreditCost(default 50) can be set, within limits.
curl "https://www.firstmilelabs.com/v1/registry/search?country=FR&q=ACME" \
-H "Authorization: Bearer eyJhbGciOi…"
# → { "jurisdiction": { "country": "FR", "name": "France",
# "registry": "INSEE / RNE (France)", "band": "A" },
# "query": "ACME", "count": 1,
# "results": [ { "schemaVersion": "registry.entity/v1", "tier": "lite",
# "legalName": "ACME SANDBOX SARL", "registrationNumber": "909090901",
# "status": "active", "legalForm": "SARL",
# "source": { "registry": "INSEE / RNE (France)", … }, … } ],
# "retrievedAt": "2026-10-30T08:45:28.015Z" }Parameters. country takes an ISO alpha-2 code or a country name, and q a company name or number. The company endpoints take companyNumber, which is preferred, or companyName.
Coverage. GET /v1/registry/jurisdictions lists the national registers behind LITE, with each one’s band, price per tier and any caveat. It needs read:registry, whichever tier you use. ENHANCED and UBO reach further, and take any country. UK companies are on every tier: LITE reads Companies House, so /v1/registry/search?country=GB searches the UK register directly.
One shape everywhere. An entity has the same keys in every country, and a field a register can’t fill is null, so branch on null, not on whether the key is there. source.registry and source.retrievedAt say which register answered, and when.
Slow registers. POST /v1/registry/jobs takes a tier, a country and a company, and answers 202 with a job id. Poll GET /v1/registry/jobs/{id} for a result in the same shape as the direct call. Submitting and polling a job both need read:registry, on every tier; an ENHANCED or UBO job needs that tier’s scope as well, so a key holding only read:registry_enhanced or read:registry_ubo can make the direct calls but can’t use jobs. Collect it within 7 days of the job finishing; after that the job answers 410 expired. Nothing is sent when a job finishes. A job still queued when your workspace is deactivated doesn't run and isn't billed: it fails with workspace_deactivated, and stays failed if the workspace is reactivated, so submit a new job with a new Idempotency-Key.
Billing. A search with a match, or a company found, is billed by tier and by the country’s pricing band. A search with no match, or a 404 not_found, isn’t billed. ENHANCED search is billed at the search rate, not the profile rate, and a UBO lookup is a base fee plus a charge for each person or company resolved. A monthly hard cap set in Usage & billing refuses a lookup with 402 billing_hard_cap before it runs.
Idempotency. Send an Idempotency-Key of up to 200 characters. A retry within 24 hours replays the stored response with Idempotent-Replay: true and isn’t billed again. After 24 hours it runs, and is billed, as a new lookup. The same key on a different request returns 409 idempotency_key_conflict.
Sandbox. A sandbox client, which First Mile Labs issues, serves fixed test data: no register is called and nothing is billed. Responses carry "sandbox": true, and a q, companyNumber or companyName containing NOMATCH gives you the no-match path.
9. Screening
POST /v1/screening/run screens up to 100 people and companies in one call, for sanctions and PEPs. It needs the screening:run scope. No case is created and no hits are stored: the results come back in the response, against your own subject id.
curl -X POST https://www.firstmilelabs.com/v1/screening/run \
-H "Authorization: Bearer eyJhbGciOi…" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: onboarding-8841" \
-d '{
"subjects": [
{ "id": "s1", "type": "person", "name": "Jane Roe",
"birthDate": "1980-01-01", "country": "GB" },
{ "id": "s2", "type": "company", "name": "NOMATCH Ltd",
"registrationNumber": "01234567", "country": "GB" }
],
"checks": ["sanctions_pep"]
}'
# → { "sandbox": true, "vendor": "sandbox",
# "results": [
# { "id": "s1", "sanctioned": true, "pep": false,
# "hits": [ { "caption": "JANE ROE", "schema": "Person", "score": 0.97,
# "topics": ["sanction"], "isSanctioned": true, … } ] },
# { "id": "s2", "hits": [], "sanctioned": false, "pep": false }
# ] }Sanctions and PEP vendor. One vendor screens both: your sanctions vendor, OpenSanctions or ComplyAdvantage. If your sanctions or PEP vendor is anything else, or they differ, the request returns 409 sanctions_vendor_unavailable before anything runs or is billed.
Adverse media. Add "adverse_media" to checks, and each result also carries adverseMedia and adverseMediaHits, with links to the articles. It needs ComplyAdvantage as your adverse-media vendor. Without it, the whole request returns 409 adverse_media_vendor_unavailable before anything runs or is billed.
Subjects not screened again. On ComplyAdvantage’s Mesh platform, a subject screened before is not screened again, and its result carries notRescreened. With earlierResultKnown: true the hits are the earlier screen’s, from lastScreenedAt. With false, empty hits say nothing: treat the subject as not confirmed clear.
Billing. Each check you ask for is billed once per call, by the number of subjects, whether or not anything matched. A request that fails before the vendor answers isn’t billed.
Idempotency. As for registry lookups: a retry with the same Idempotency-Key within 24 hours replays the response and isn’t billed again. For those 24 hours we hold the response, and a hash of your request rather than the names in it.
Sandbox. A subject whose name contains NOMATCH comes back clean, one containing PEP gets a PEP hit, and anything else gets one hit for each check. Adverse media works in the sandbox whichever vendor your workspace has.
10. Versioning policy
The API namespace is /v1/*. We follow the same additive compatibility policy as our outbound webhooks: new fields may be added at any time, and consumers must ignore unknown fields. Breaking changes ship under a new /v2/* namespace; /v1/* remains supported for the announced sunset window.
11. OpenAPI spec
The machine-readable spec lives at /v1/openapi.json. It covers the OAuth endpoints, cases (reading them, creating one, screening dispositions, exits, outstanding items and document requests), documents, the event feed, the company registry and screening. It does not yet describe GET /v1/cases/{caseId}/full or the policy set-up endpoint, /v1/mcp. Drop it into Postman, Insomnia, or your code-generator of choice to scaffold a typed client in minutes. The registry Postman collection arrives with the token exchange already wired.
12. AI assistants
AI tool connections don’t run through this API. They use a dedicated connector with its own sign-in and controls: off until your workspace admin switches them on, each person connects their own account, and every call is logged. See the setup guide and what a connection can do.
Policy set-up has an MCP endpoint of its own, /v1/mcp, for a team whose own agent drafts its risk model from its policy. It can draft a model, never switch one on. Policy set-up is in early access too.
For the model we run on your behalf inside the platform, what data each AI feature sees, and our encryption / tenant-isolation posture, see the Trust & AI page.
Building your own OAuth-based integration? The authorization-code flow is documented in the OpenAPI spec (see /v1/oauth/authorize, /v1/oauth/token with grant_type=authorization_code + refresh_token, and /v1/oauth/revoke). Email partners@firstmilelabs.com to register your client_id and redirect URIs.