Create a business entity with a global API key and complete KYB: business details, representatives, KYC, documents, and submission via next_step.
A global (user-level) API key can create a business entity and run its KYB
onboarding without touching the dashboard: business details, the representatives
(beneficial owners and officers), each representative’s identity verification,
supporting documents, and the final submission. Every response includes a
next_step object that tells you what’s outstanding, so you don’t infer it from
status.
This is self-serve onboarding for entities your key owns. The key’s user is
the creator and admin, not a representative of the entity. To onboard entities
on behalf of your customers as a platform, use
Partner Onboarding instead.
A global API key (user-scoped, not entity-scoped) with the
entity:create scope for writes and accounts:read to read and list
onboarding state. Onboarding routes reject entity-scoped keys with 403.
No x-entity-id header. The entity is addressed in the URL path.
Some entities draw an extra due-diligence step (complete_due_diligence) or a
follow-up information request after submission (resolve_info_requests). These
are handled in the Meow dashboard; the API surfaces them in next_step so you
know when to direct the business there.
POST /entities creates the entity and returns its public ID. The creating user
is granted admin, so the same key can act on the entity immediately. Send an
empty body to create a bare entity, or seed any KYB business details up front.
Save id. It’s the {entity_id} for every call below, and the x-entity-id
header once the entity is onboarded and you call entity-scoped APIs.legal_structure is one of: ccorp, corp, scorp, llc, llp, lp,
partnership, soleprop, nonprofit, trust, estate, foreign_entity,
scheme.
Pass your own reference_id to make creation idempotent. Retrying a create with
a reference_id you’ve already used returns the original entity instead of
creating a duplicate, so a network timeout never leaves you with two entities.
PATCH /entities/{entity_id}/business-details fills in or corrects KYB details
before the application is submitted. Send only the fields you want to change;
anything you omit keeps its current value. Use it for the business profile the
create call didn’t include, and to answer the account-purpose and
digital-currency questions (collect_additional_details).
The response is the refreshed onboarding status, including the updated
next_step. Send physical_address together with business_address; omitting
it keeps any physical address already on file, or uses the legal address when
none is set.
POST /entities/{entity_id}/representatives records a beneficial owner or
officer and returns its representative_id. This step is create-only.
Verify the representative separately (section 4).Mark exactly one representative as the signer with is_primary: true; setting it
demotes any previous primary. A primary representative is required before the
application can be submitted.
title_id is one of: chief executive officer, chief financial officer,
chief operating officer, president, general partner, managing member,
finance manager.
percent_ownership is required when is_beneficial_owner is true, between
25 and 100. Total beneficial ownership across representatives cannot
exceed 100.
Each email is unique per entity. Re-posting the same address returns 400.
Verification completes asynchronously. Track it via the entity’s
next_step (the complete_identity_verification
step clears once a representative is verified) or the identity_verification.*
webhooks. The entity’s own kyc_status reflects the primary user, not an added
representative.
next_step.required_proof_types lists exactly which documents the entity still
owes. For a US entity that’s typically ["incorporation", "address"]. Each
one uses a three-step flow: get a pre-signed URL, PUT the bytes, then
confirm. Repeat the flow for each proof type — for example, the incorporation
certificate first, then the proof of physical address:
Pass each value from required_proof_types as the proof_type. For US
entities, required_proof_types includes both incorporation and address
as standard requirements. address is proof of physical address at the
entity level — a utility bill, bank statement, or lease/rental agreement
evidencing the entity’s relationship to its physical address. The address
requirement applies to US entities only; foreign entities are not asked for
it. Other common
values include articles_of_organization, bylaws, operating_agreement,
ein, bank_statement, and beneficial_owner_id.
Address documents uploaded for a representative do not satisfy the
entity-level address requirement — the document must evidence the
entity’s physical address. next_step.can_submit stays false until every
proof type in required_proof_types has been uploaded.
Once next_step.can_submit is true, submit the application with
POST /entities/{entity_id}/submit. Choose the checking account product to open,
and attest that you are authorized to submit on the business’s behalf. If
anything is still outstanding, this returns 400 with the remaining
requirements; check next_step.can_submit first.
banking_account_product_type is grasshopper or crb.
attestation must be true.
Once submitted, the application moves to review and can no longer be edited. Meow
moves status to under_review, then approved or rejected. Watch for the
outcome with webhooks (below) or by polling the status endpoint.
In sandbox and development environments there is no human compliance review, so
a submitted application would otherwise sit in under_review forever. Simulate
the approval with
POST /simulations/entities/{entity_id}/application_approval. It approves the
application as if compliance review had passed and kicks off checking-account
onboarding.
The body is optional. banking_account_product_type defaults to
grasshopper; crb is also supported.
Use a global (user) API key with the simulations:write scope; the key’s
user must be an admin of the entity.
The application must already be submitted (section 6).
After calling it, the application’s status moves to submitted immediately
and to approved once the checking account activates. Poll
GET /entities/{entity_id} or subscribe to the application.* webhook events
to observe the transition.
Simulation endpoints are only available in sandbox and development
environments. In production they return 404 Not Found.
Subscribe to identity_verification.* for KYC outcomes and application.* for
KYB lifecycle changes, then update your records from the delivered payloads.
See the webhooks guide for signing, retries, and
out-of-order handling.
