> ## Documentation Index > Fetch the complete documentation index at: https://docs.etherfuse.com/llms.txt > Use this file to discover all available pages before exploring further. # Get KYC status > Returns the current KYC verification status for a customer, resolved from the customer's account. The overall `status` matches the logic used for orders, so it stays consistent with whether the customer can transact, and `approved` is the only value that lets them. Submission details such as rejection reasons and timestamps are visible only to the partner that submitted the data. ## The requirements breakdown Pass `?requirements=true` to add a `requirements` array describing, step by step, what this customer's verification still needs. Each entry carries a `type`, a `status`, and a `requiresLaunch` flag, which is what separates "I still owe data over the API" from "it is time to launch the customer". It is opt-in because resolving it costs upstream calls; omit the parameter and the response is unchanged. The breakdown covers personal verification only. Requesting it for a business customer returns `400`; track a business with [`GET /ramp/organization/{id}/kyb/status`](/api-reference/organizations/get-kyb-status) instead. `requirements` is omitted entirely until the customer has been routed to their country's requirements. Before that there is no country-specific requirement set to describe, and reporting the router's own steps would read as "this customer is done" precisely when nothing has happened. After that the list holds the customer's current stage, plus requirements already satisfied. It never lists a later stage's requirements, so it grows as they advance: `proof_of_address` appears only when the identity document carried no address, and `customer_agreement` appears last. Send only what is listed as `pending` or `action_required`; a requirement sent before it is listed is accepted and then refused in the background. Re-read the list after every `kyc_updated`; no single response is the full list. See [Requirements unlock in stages](/guides/onboarding#requirements-unlock-in-stages). ## Prefer the webhook `kyc_updated` is how you learn that something changed. Read this endpoint on demand, or in response to that webhook when you need to know what specifically is outstanding. With `?requirements=true` it resolves against the verification provider on every call, so it is not built for tight polling. See [Tracking verification status](/guides/onboarding#tracking-verification-status). ## OpenAPI ````yaml /openapi.json get /ramp/customer/{customer_id}/kyc openapi: 3.1.0 info: title: Etherfuse FX API description: Partner-facing ramp API for onramps, offramps, swaps, and KYC. license: name: Proprietary version: 1.0.0 servers: - url: https://api.sand.etherfuse.com description: Sandbox security: - ApiKeyAuth: [] tags: - name: Authentication description: >- Partner JWT authentication — exchange a JWT for an access token, or launch a user into the app. - name: Lookup description: >- Public reference data: exchange rates, stablebonds, bond costs, country codes. - name: Assets description: Rampable stablecoins and stablebonds available per blockchain. - name: Bank Accounts description: Register and retrieve customer bank accounts. - name: Quotes description: Price quotes for onramps, offramps, and swaps. - name: Orders description: Create, track, and manage ramp orders. - name: Swaps description: Crypto-to-crypto swaps. - name: Sponsored description: Token approvals for sponsored (gasless) offramps. - name: Customers description: Customer (child-organization) records. - name: Wallets description: Register and manage customer wallets. - name: KYC description: >- Submit a customer's verification data, documents and questionnaire answers, import a verification they already passed elsewhere, and check where their KYC stands. - name: Webhooks description: Event notification subscriptions. - name: Organizations description: Organization identity, child orgs, and partner fees. - name: Statements description: >- Monthly revenue share statements for closed months, as a list or as a CSV or PDF download. - name: Deprecated description: >- Endpoints kept working until their sunset date and then removed. See the deprecations page for replacements and dates. paths: /ramp/customer/{customer_id}/kyc: get: tags: - KYC summary: Get KYC status description: >- Returns the current KYC verification status for a customer, resolved from the customer's account. The overall `status` matches the logic used for orders, so it stays consistent with whether the customer can transact, and `approved` is the only value that lets them. Submission details such as rejection reasons and timestamps are visible only to the partner that submitted the data. ## The requirements breakdown Pass `?requirements=true` to add a `requirements` array describing, step by step, what this customer's verification still needs. Each entry carries a `type`, a `status`, and a `requiresLaunch` flag, which is what separates "I still owe data over the API" from "it is time to launch the customer". It is opt-in because resolving it costs upstream calls; omit the parameter and the response is unchanged. The breakdown covers personal verification only. Requesting it for a business customer returns `400`; track a business with [`GET /ramp/organization/{id}/kyb/status`](/api-reference/organizations/get-kyb-status) instead. `requirements` is omitted entirely until the customer has been routed to their country's requirements. Before that there is no country-specific requirement set to describe, and reporting the router's own steps would read as "this customer is done" precisely when nothing has happened. After that the list holds the customer's current stage, plus requirements already satisfied. It never lists a later stage's requirements, so it grows as they advance: `proof_of_address` appears only when the identity document carried no address, and `customer_agreement` appears last. Send only what is listed as `pending` or `action_required`; a requirement sent before it is listed is accepted and then refused in the background. Re-read the list after every `kyc_updated`; no single response is the full list. See [Requirements unlock in stages](/guides/onboarding#requirements-unlock-in-stages). ## Prefer the webhook `kyc_updated` is how you learn that something changed. Read this endpoint on demand, or in response to that webhook when you need to know what specifically is outstanding. With `?requirements=true` it resolves against the verification provider on every call, so it is not built for tight polling. See [Tracking verification status](/guides/onboarding#tracking-verification-status). operationId: get_kyc_org parameters: - name: customer_id in: path description: >- The customer (child org) ID. Must belong to the caller's organization or a direct child. required: true schema: type: string format: uuid - name: requirements in: query description: >- Include the per-requirement `requirements` breakdown. Off by default. Personal customers only; a business customer returns `400`. required: false schema: type: boolean default: false responses: '200': description: The org-level KYC status for the customer content: application/json: schema: $ref: '#/components/schemas/KycStatusResponse' '400': description: '`requirements=true` was passed for a business customer.' '404': description: >- No organization exists with that `customer_id`, or it is not a customer of your organization. components: schemas: KycStatusResponse: type: object description: KYC status response required: - customerId - status - selfies - documents - needsWork properties: approvedAt: type: - string - 'null' format: date-time currentRejectionReason: type: - string - 'null' customerId: type: string format: uuid documents: type: array items: $ref: '#/components/schemas/ProofOfIdentityDocument' needsWork: type: boolean onChainMarked: type: - boolean - 'null' description: >- Whether KYC is marked on-chain. Only present for Solana wallets. For other blockchain types (Stellar, EVM), this field is omitted as on-chain marking doesn't apply. requirements: type: array description: >- What the customer's verification still needs, step by step. Present only when asked for with `?requirements=true` **and** the customer has been routed to their country's requirements; omitted otherwise. items: $ref: '#/components/schemas/RequirementState' selfies: type: array items: $ref: '#/components/schemas/ProofOfIdentityContent' status: type: string description: >- Unified KYC status for the customer's organization. - `not_started`: no KYC started - `in_progress`: the customer started the flow but hasn't submitted everything - `submitted`: submitted, awaiting review (manual or automated) - `approved`: cleared; the customer can transact - `denied`: a rejected verdict, or a previously-approved customer whose approval was revoked (reason in `currentRejectionReason`) enum: - not_started - in_progress - submitted - approved - denied userMessage: type: - string - 'null' walletPublicKey: type: - string - 'null' example: approvedAt: '2026-05-01T16:00:00Z' currentRejectionReason: null customerId: a1b2c3d4-e5f6-7890-abcd-ef1234567890 documents: [] needsWork: false selfies: [] status: approved ProofOfIdentityDocument: allOf: - $ref: '#/components/schemas/ProofOfIdentityContent' - type: object properties: extractedData: oneOf: - type: 'null' - $ref: '#/components/schemas/ProofOfIdentityUserInfo' RequirementState: type: object description: One thing a customer's verification still needs, and where it stands. required: - type - status - requiresLaunch properties: type: type: string description: >- Which requirement this is. Only the ones that apply to this customer are listed; their country decides which those are. 1. `personal_data`: name, date of birth, tax ID, country and address; Mexico also requires CURP 2. `identity_document`: a government-issued ID 3. `proof_of_address`: an address document; appears only when the identity document carried no address 4. `occupation`: job title and occupation category 5. `selfie`: a live face capture; cannot be uploaded 6. `customer_agreement`: the customer accepting the required agreements We reserve the right to add requirements, and will update these docs when we do. A country may also introduce one of its own; see [Country-specific requirements](/guides/onboarding#country-specific-requirements). enum: - personal_data - identity_document - proof_of_address - occupation - email_confirmation - selfie - customer_agreement status: type: string description: >- How far along this requirement is. - `satisfied`: accepted, nothing more to do - `pending`: nothing has been provided for this yet, so it is still owed - `awaiting_review`: provided, not yet reviewed - `action_required`: **reviewed and rejected**, so it must be provided again, corrected `pending` and `awaiting_review` are the distinction that matters: a shared verification whose identity document and selfie transferred reads `awaiting_review` for both, so do not read `pending` into it and re-send. Treat this as an **open set**: more values may be added, so key your logic off the two that carry an instruction (`satisfied` means done, `action_required` means re-send) and treat anything else as in flight. enum: - satisfied - pending - awaiting_review - action_required requiresLaunch: type: boolean description: >- True when only the customer can satisfy this in the hosted step, such as the liveness capture. A property of the requirement rather than of its progress, so it does not change as the customer advances. `selfie` reads true whether or not the selfie has been taken. A requirement with status `satisfied` needs no further action even when this flag is true. False does not mean the requirement is yours to submit. It means the API *can* submit it. The customer can always enter it in the hosted step instead, which is why launching them satisfies everything. So this flag says what the API cannot reach, not when to launch: an outstanding requirement reading true is one no API call will ever clear. example: type: identity_document status: pending requiresLaunch: false ProofOfIdentityContent: type: object required: - id - type - status properties: approvedAt: type: - string - 'null' format: date-time contentLabel: type: - string - 'null' createdAt: type: - string - 'null' format: date-time id: type: string images: type: - array - 'null' items: $ref: '#/components/schemas/ImageInfo' ipAddress: type: - string - 'null' rejectedAt: type: - string - 'null' format: date-time rejectedReason: type: - string - 'null' status: $ref: '#/components/schemas/ProofOfIdentityStatus' type: type: string videoURL: type: - string - 'null' ProofOfIdentityUserInfo: type: object required: - id properties: address: oneOf: - type: 'null' - $ref: '#/components/schemas/ProofOfIdentityAddress' dateOfBirth: type: - string - 'null' email: type: - string - 'null' id: type: string idNumbers: type: array items: $ref: '#/components/schemas/ProofOfIdentityIdNumber' name: oneOf: - type: 'null' - $ref: '#/components/schemas/ProofOfIdentityName' occupation: type: - string - 'null' organizationId: type: - string - 'null' format: uuid phoneNumber: type: - string - 'null' sourceOrganizationId: type: - string - 'null' format: uuid useEmailForMarketing: type: - boolean - 'null' walletId: type: - string - 'null' ImageInfo: type: object required: - imageURL - label properties: imageURL: type: string label: type: string ProofOfIdentityStatus: type: string enum: - approved - rejected - proposed ProofOfIdentityAddress: type: object required: - country properties: city: type: - string - 'null' country: type: string postalCode: type: - string - 'null' region: type: - string - 'null' street: type: - string - 'null' street2: type: - string - 'null' ProofOfIdentityIdNumber: type: object required: - value - type properties: type: type: string value: type: string ProofOfIdentityName: type: object required: - givenName - familyName properties: familyName: type: string givenName: type: string middleName: type: - string - 'null' motherMaidenName: type: - string - 'null' preferredName: type: - string - 'null' securitySchemes: ApiKeyAuth: type: apiKey in: header name: Authorization description: API key sent in the Authorization header. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.