> ## 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 organization's KYC status. The overall `status` uses the same logic as orders, so `approved` is the only value that lets the customer transact. 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 separates "I still owe data over the API" from "it is time to launch the customer". It is opt-in because it calls the verification provider; without it the response leaves `requirements` out. The breakdown covers personal verification only. Requesting it for a business organization returns `400` `invalid-request`; track a business with [`GET /organization/{organizationId}/kyb`](/v2/api-reference/kyb/get-kyb-status) instead. `requirements` is left out until the customer has been routed to their country's requirements. 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: `proofOfAddress` appears only when the identity document carried no address, and `customerAgreement` appears last. Send only what is listed as `pending` or `actionRequired`; a requirement sent before it is listed is accepted and then refused in the background. Read the list again after every `kycUpdated`; no single response is the full list. See [Requirements unlock in stages](/v2/guides/onboarding#requirements-unlock-in-stages). ## Prefer the webhook Subscribe to `kycUpdated` to learn that something changed. Read this endpoint on demand, or after that webhook when you need to know what is outstanding. With `?requirements=true` it calls the verification provider every time, so do not poll it tightly. See [Tracking verification status](/v2/guides/onboarding#tracking-verification-status). ## OpenAPI ````yaml openapi-v2.json GET /organization/{organizationId}/kyc openapi: 3.1.0 info: title: Etherfuse FX API description: >- Partner-facing ramp API, version 2: payment accounts, quotes, orders and webhooks. license: name: Proprietary version: 2.0.0 servers: - url: https://api.sand.etherfuse.com description: Sandbox security: - ApiKeyAuth: [] tags: - name: Payment Accounts description: >- Register the bank accounts and wallets that money moves from and to, and read their readiness per rail. - name: Quotes description: Price a transfer between two registered payment accounts. - name: Orders description: Create orders from quotes and track them. - name: Webhook Subscriptions description: Subscribe to webhook events. - name: Webhook Events description: Payloads Etherfuse sends to your webhook subscriptions. - name: Sandbox description: Endpoints that work only in sandbox, for testing. - name: Assets description: The markets and tokens a quote can use, and the balances of a wallet. - name: Authentication description: >- Partner JWT authentication: exchange a JWT for an access token, or launch a user into the app. - 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: KYB description: Check where a business organization's KYB stands. - name: Lookup description: >- Public reference data: exchange rates, stablebonds, bond costs, country codes. - name: Organizations description: >- Your organization, your default partner fee, and the customer organizations you create. - name: Members description: >- The people who belong to a customer business organization and complete its KYB. - name: Statements description: >- Monthly revenue share statements for closed months, as a list or as a CSV or PDF download. paths: /organization/{organizationId}/kyc: get: tags: - KYC summary: Get KYC status description: >- Returns the organization's KYC status. The overall `status` uses the same logic as orders, so `approved` is the only value that lets the customer transact. 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 separates "I still owe data over the API" from "it is time to launch the customer". It is opt-in because it calls the verification provider; without it the response leaves `requirements` out. The breakdown covers personal verification only. Requesting it for a business organization returns `400` `invalid-request`; track a business with [`GET /organization/{organizationId}/kyb`](/v2/api-reference/kyb/get-kyb-status) instead. `requirements` is left out until the customer has been routed to their country's requirements. 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: `proofOfAddress` appears only when the identity document carried no address, and `customerAgreement` appears last. Send only what is listed as `pending` or `actionRequired`; a requirement sent before it is listed is accepted and then refused in the background. Read the list again after every `kycUpdated`; no single response is the full list. See [Requirements unlock in stages](/v2/guides/onboarding#requirements-unlock-in-stages). ## Prefer the webhook Subscribe to `kycUpdated` to learn that something changed. Read this endpoint on demand, or after that webhook when you need to know what is outstanding. With `?requirements=true` it calls the verification provider every time, so do not poll it tightly. See [Tracking verification status](/v2/guides/onboarding#tracking-verification-status). operationId: v2GetKyc parameters: - $ref: '#/components/parameters/OrganizationId' - name: requirements in: query description: >- Include the per-requirement `requirements` breakdown. Off by default. Personal organizations only; a business organization returns `400`. required: false schema: type: boolean default: false responses: '200': description: The organization's KYC status. content: application/json: schema: $ref: '#/components/schemas/Kyc' '400': $ref: '#/components/responses/InvalidRequest' '401': $ref: '#/components/responses/Unauthorized' '404': $ref: '#/components/responses/OrganizationNotFound' '500': $ref: '#/components/responses/InternalError' components: parameters: OrganizationId: name: organizationId in: path required: true description: >- The organization this call acts for: your API key's organization or one of its customer organizations. Any other id returns `404` `not-found`. schema: type: string format: uuid schemas: Kyc: type: object required: - organizationId - status - currentRejectionReason - selfies - documents - approvedAt - needsWork - userMessage properties: organizationId: type: string format: uuid status: $ref: '#/components/schemas/VerificationStatus' currentRejectionReason: type: - string - 'null' description: >- Why the last review rejected the customer, when it did. Visible only to the partner that submitted the data. selfies: type: array items: $ref: '#/components/schemas/ProofOfIdentityContent' documents: type: array items: $ref: '#/components/schemas/ProofOfIdentityDocument' approvedAt: type: - string - 'null' format: date-time needsWork: type: boolean description: True when the customer has to correct something and resubmit. userMessage: type: - string - 'null' description: What the customer has to fix, when `needsWork` is true. requirements: type: array description: >- What the customer's verification still needs, step by step. Present only with `?requirements=true`, and only once the customer has been routed to their country's requirements. items: $ref: '#/components/schemas/RequirementState' example: organizationId: b2c3d4e5-f6a7-8901-bcde-f12345678901 status: inProgress currentRejectionReason: null selfies: [] documents: [] approvedAt: null needsWork: false userMessage: null requirements: - type: personalData status: satisfied requiresLaunch: false - type: identityDocument status: pending requiresLaunch: false - type: selfie status: pending requiresLaunch: true VerificationStatus: type: string enum: - notStarted - inProgress - submitted - approved - denied description: |- - `notStarted`: verification has not started. - `inProgress`: the customer started but has not submitted everything. - `submitted`: submitted and waiting for review. - `approved`: cleared. - `denied`: rejected, or a previous approval was revoked. 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' 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. - `personalData`: name, date of birth, tax id, country and address - `identityDocument`: a government-issued ID - `proofOfAddress`: an address document; appears only when the identity document carried no address - `occupation`: job title and occupation category - `taxDocument`: a region-specific tax document. In Mexico, the Constancia de Situación Fiscal - `emailConfirmation`: the customer confirming their email address - `selfie`: a live face capture; cannot be uploaded - `customerAgreement`: the customer accepting the required agreements We may add requirements, and will update these docs when we do. A country may also introduce one of its own; see [Country-specific requirements](/v2/guides/onboarding#country-specific-requirements). enum: - personalData - identityDocument - proofOfAddress - occupation - taxDocument - emailConfirmation - selfie - customerAgreement 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 - `awaitingReview`: provided, not yet reviewed - `actionRequired`: **reviewed and rejected**, so it must be provided again, corrected Tell `pending` and `awaitingReview` apart: a shared verification whose identity document and selfie transferred reads `awaitingReview` for both, so do not read `pending` into it and send them again. More values may be added, so act on the two that carry an instruction (`satisfied` means done, `actionRequired` means send again) and treat anything else as in progress. enum: - satisfied - pending - awaitingReview - actionRequired 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: identityDocument status: pending requiresLaunch: false Problem: type: object description: >- RFC 9457 problem details. Every v2 error uses this body with content type `application/problem+json`. `errors` is present only on `validation-error`. `required` and `missing` are present only on `registration-info-required`. required: - type - title - status - detail - instance properties: type: type: string format: uri description: >- `https://docs.etherfuse.com/ramp/v2/errors/` followed by the problem slug, for example `https://docs.etherfuse.com/ramp/v2/errors/quote-expired`. Switch on this value. example: https://docs.etherfuse.com/ramp/v2/errors/quote-expired title: type: string description: Short summary of the problem type. example: Quote expired status: type: integer description: The HTTP status code. example: 400 detail: type: string description: Human-readable explanation of this occurrence. Do not parse it. example: >- quote 5e6f7a8b-9c0d-4e1f-8a2b-3c4d5e6f7a8b has expired or does not exist instance: type: string description: Unique identifier for this occurrence. Quote it to support. example: >- tag:etherfuse.com,2026-08-28:R2-10120/0b1c2d3e-4f50-4a6b-8c7d-9e0f1a2b3c4d errors: type: array description: Present on `validation-error`. One entry per invalid field. items: $ref: '#/components/schemas/FieldViolation' required: type: array description: >- Present on `registration-info-required`. Every registration field the route requires, as JSON Pointers into the request, for example `#/registrationInfo/taxId`. items: type: string missing: type: array description: >- Present on `registration-info-required`. The required fields you must still send, as JSON Pointers into the request. items: type: string ImageInfo: type: object required: - imageURL - label properties: imageURL: type: string label: type: string ProofOfIdentityStatus: type: string enum: - approved - rejected - proposed 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' FieldViolation: type: object required: - pointer - detail properties: pointer: type: string description: >- JSON Pointer to the field in the request, for example `#/accountDetails/clabe`. example: '#/accountDetails/clabe' detail: type: string description: What is wrong with the field. example: This field is required. 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' responses: InvalidRequest: description: >- `invalid-request`: a path, query or body value is malformed, or `pageSize` is 0 or over 100. content: application/problem+json: schema: $ref: '#/components/schemas/Problem' Unauthorized: description: >- `unauthorized`: the `Authorization` header is missing, not ASCII, or does not hold a valid API key. content: application/problem+json: schema: $ref: '#/components/schemas/Problem' OrganizationNotFound: description: '`not-found`: your API key cannot act for this organization.' content: application/problem+json: schema: $ref: '#/components/schemas/Problem' InternalError: description: >- `internal-error`: an unexpected error on our side. Retry with backoff, and quote `instance` to support if it persists. content: application/problem+json: schema: $ref: '#/components/schemas/Problem' securitySchemes: ApiKeyAuth: type: apiKey in: header name: Authorization description: API key sent in the Authorization header, with no `Bearer` prefix. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.