> ## Documentation Index
> Fetch the complete documentation index at: https://docs.machines.cash/llms.txt
> Use this file to discover all available pages before exploring further.
# KYC Flow
> Collect and verify identity.
Prerequisite: have a session token. See Authentication.
## Flow
```mermaid theme={null}
sequenceDiagram
participant Backend as Your Backend
participant MachinesAPI as Machines API
Backend->>MachinesAPI: POST /sessions (create session)
Backend->>MachinesAPI: GET /kyc/values
Backend->>MachinesAPI: POST /kyc/applications
MachinesAPI-->>Backend: status = pending
loop poll
Backend->>MachinesAPI: GET /kyc/status
MachinesAPI-->>Backend: status = approved | needs_information | denied
end
Backend->>MachinesAPI: GET /agreements
Backend->>MachinesAPI: POST /agreements
```
## Steps
GET /kyc/values to see required fields and allowed values.
POST /kyc/applications with the fields below. Sandbox: set lastName to approved to auto‑approve.
We return a completionLink (or externalVerificationLink). Open it in a browser for document upload and face match. Users finish verification there — you don’t need to handle media.
Poll GET /kyc/status until the status becomes approved (or an actionable state such as needs\_information).
After approval, fetch the agreements and collect user consent. See Agreements.
## States
* approved
* pending
* needs\_information
* needs\_verification
* manual\_review
* denied
* locked
* canceled
## Fields (submit application)
Given name.
Family name. Sandbox shortcut: set to approved to auto-approve.
YYYY-MM-DD (e.g., 1990-01-01).
Government ID number (letters, numbers, dashes only).
ISO-3166-1 alpha-2 country code (e.g., US). Case-insensitive.
Email address.
Optional phone dial code digits only (e.g., 1).
Optional phone number digits only (include area code).
Street address (line 1).
Street address (line 2).
City.
State/region (e.g., CA).
Postal/ZIP code.
ISO-3166-1 alpha-2 country code (e.g., US). Case-insensitive.
SOC occupation code (e.g., 49-3023). Full list: KYC Field Values.
Choose one label (we map to the underlying range for you):
* \<40k
* 50k–99k
* 100k–149k
* 150k+
Choose one:
* everyday spend
* subscriptions
* business expenses
* testing
* other
Choose one label (we map to the underlying range for you):
* under \$1k
* $1k–$5k
* $5k–$20k
* \$20k+
## Response (status)
One of: approved, pending, needs\_information, needs\_verification, manual\_review, denied, locked, canceled.
Identifier for the submitted application (when available).
Additional context for non-approved statuses.
Sandbox shortcut: set lastName to approved to auto‑approve. See KYC Field Values for allowed field values.