> ## Documentation Index > Fetch the complete documentation index at: https://docs.venlyfinance.com/llms.txt > Use this file to discover all available pages before exploring further. # Get a party's KYC status > See where a party's KYC or KYB verification stands, and what the end customer still has to do. **Requires scope:** `manage:parties` — see [Required scopes](/getting-started/authentication#required-scopes-finance-api). Returns where the party's verification stands — KYC for an `INDIVIDUAL`, KYB for an `ORGANISATION` — read live from the verification platform. Use it to tell a verification that is **under review** apart from one that is **waiting on your end customer**, and to see which step needs attention. | Field | What it tells you | | - | - | | `verificationState` | The headline: `AWAITING_CUSTOMER`, `IN_REVIEW`, `RESUBMISSION_REQUESTED`, `APPROVED` or `DECLINED`. | | `requiredAction` | What the end customer still has to do — for example `COMPLETE_SUMSUB_VERIFICATION`. Omitted when nothing is required. | | `steps` | The review outcome per step, with `rejectLabels` explaining a rejection and `itemIds` listing questionnaire items that still need attention. | | `caseStatus` | The underlying case status, for support conversations. | | `lastSyncedAt` | When the state was last synchronised with the verification provider. | When `verificationState` is `AWAITING_CUSTOMER`, [issue a KYC completion link](/api-reference/Finance-API/parties/issue-a-kyc-completion-link) and hand it to your end customer. This endpoint reports **progress**, not the verdict you branch on. The party's and its accounts' `kycStatus`/`kybStatus` change only once a verdict (`APPROVED` or `DECLINED`) is reached — read those from [Get a party](/api-reference/Finance-API/parties/get-party-details). New values may be added to every enum-like field. Treat an unknown `verificationState` as still in progress. ## Errors | HTTP | `code` | When | Retry? | | - | - | - | - | | `404` | `party-not-found` | No such party for your company | **No** | | `404` | `kyc-status-not-found` | The party has no verification on record yet | **No** — start one with a [verification link](/api-reference/Finance-API/parties/create-a-verification-link) | | `500` | `identity-verification-rejected` | Verification refused the request | **No** | | `503` | `identity-verification-unavailable` | Platform unreachable | **Yes**, with backoff | See [Troubleshooting verification](/guides/finance/onboarding/troubleshooting). ## OpenAPI ````yaml api-reference/Finance-API-Specs.yaml GET /parties/{partyId}/kyc-status openapi: 3.1.0 info: title: Venly Finance API description: > REST API for the Venly Finance platform: - Party management (Individuals & Organisations) - Identity verification — hosted KYC/KYB links and Sumsub share-token forwarding - Account management with party association - Wallet balances & token allowances on supported chains - Virtual bank accounts for global pay-in (EUR SEPA, USD ACH/WIRE/RTP/SWIFT) - Fiat-to-crypto payment sessions (pay-in) - Bank pay-outs — beneficiary allow-listing, routes, and PULL/PUSH pay-outs - Account-to-account fiat & crypto transfers - EIP-2612 permits and allowances - Webhook registration for asynchronous event delivery ## Authentication All endpoints use OAuth2 client credentials. Obtain a token first, then include it in every request: **Step 1 — Get a token:** ```bash curl -X POST https://login.venly.io/auth/realms/VenlyFinance/protocol/openid-connect/token \ -H "Content-Type: application/x-www-form-urlencoded" \ -d "grant_type=client_credentials&client_id={CLIENT_ID}&client_secret={CLIENT_SECRET}" ``` **Step 2 — Use the token:** ``` Authorization: Bearer {access_token} ``` Tokens expire after **5 minutes**. Implement refresh logic in your client. ## Selecting a tenant A token that grants more than one tenant must say which one each request is for, in the `x-tenant-id` header. With a single-tenant token, omit it. Any value you send must exactly match a tenant the token grants; a missing, malformed or foreign value is answered with a generic `403 forbidden` that reveals nothing about which tenants exist. Send the header at most once. ## Request correlation Every response — including `401` and `403` — carries an `X-Correlation-Id` header identifying the operation in our logs. Quote it in a support request. You may supply your own, as `X-Correlation-Id` or (as a fallback) `X-Request-Id`, matching `^[A-Za-z0-9_.:-]{1,64}$`. A value outside that shape is replaced with a generated one rather than rejected. version: 1.10.0 contact: name: Venly Support email: support@venly.io url: https://docs.venlyfinance.com license: name: Proprietary x-logo: url: https://venlyfinance.com/logo.png x-security-contact: security@venly.io servers: - url: https://api.venlyfinance.com/v1 description: Production - url: https://api-staging.venlyfinance.com/v1 description: Staging security: - OAuth2: [] tags: - name: Parties description: Party management (Individuals & Organisations) - name: Accounts description: Account management, party-role associations - name: Wallets description: Blockchain wallet balances - name: Virtual Bank Accounts description: Virtual bank account payment references for global payments - name: Fiat-to-crypto Payment Sessions description: >- Hosted fiat-to-crypto pay-in sessions. **Coming soon** — not yet enabled; use a virtual bank account to receive fiat today. - name: Payout Bank Accounts description: Allow-listing beneficiary bank accounts as pay-out destinations - name: Payout Routes description: >- Account-scoped routes pairing a beneficiary bank account with a crypto deposit asset - name: Payouts description: Crypto-to-fiat pay-outs over a registered route - name: Transfers description: Fiat and crypto transfer operations between accounts - name: Permits description: EIP-712 permit signature management for token approvals - name: Supported Assets description: >- Discover which chains and assets your tenant can settle in, and whether an account can use them yet. - name: Allowances description: Token allowance management for wallets - name: Webhooks description: Webhook registration, delivery testing and delivery history - name: Pay-Ins description: >- The pay-in ledger — every fiat credit that settled (or failed to settle) into an account wallet - name: Billing description: The invoices Venly has issued to your company - name: API Credentials description: Self-service management of your company's OAuth client credentials - name: Company description: Your own company profile paths: /parties/{partyId}/kyc-status: parameters: - $ref: '#/components/parameters/TenantId' get: tags: - Parties summary: Get a party's KYC status description: > **Requires scope:** `manage:parties` Returns where the party's identity verification stands — KYC for an `INDIVIDUAL`, KYB for an `ORGANISATION` — relayed live from the verification platform: the `verificationState`, the underlying `caseStatus`, the action the end customer still has to take (`requiredAction`, omitted when none) and the review outcome of each step. Use it to spot a verification that is stuck waiting on the customer — `verificationState: AWAITING_CUSTOMER` with `requiredAction: COMPLETE_SUMSUB_VERIFICATION` — and then mint a link with [Issue a KYC completion link](/api-reference/Finance-API/parties/issue-a-kyc-completion-link). The party's and its accounts' `kycStatus`/`kybStatus` only change once a verdict (`APPROVED` or `DECLINED`) is reached. New values may be added to every enum-like field; treat an unknown `verificationState` as still in progress. operationId: getPartyKycStatus parameters: - $ref: '#/components/parameters/PartyId' responses: '200': description: Where the party's verification stands content: application/json: schema: $ref: '#/components/schemas/SinglePartyKycStatusResponse' example: success: true result: partyId: 7e3b9c2a-1f4d-4a8b-9c11-2d6e8f0a1b22 verificationState: AWAITING_CUSTOMER caseStatus: IN_REVIEW requiredAction: COMPLETE_SUMSUB_VERIFICATION steps: - step: IDENTITY status: REJECTED rejectLabels: - DOCUMENT_EXPIRED itemIds: [] lastSyncedAt: '2026-07-14T09:12:44Z' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': description: > - `party-not-found` — the party does not exist or belongs to another company - `kyc-status-not-found` — the party has no identity verification on record content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: >- `identity-verification-rejected` — the verification platform rejected the request itself. Not retryable. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '503': description: >- `identity-verification-unavailable` — the verification platform could not be reached. Retry with backoff. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' components: parameters: TenantId: name: x-tenant-id in: header required: false description: > Which tenant the request is scoped to, among those your token grants. Omit it when the token grants exactly one tenant; it is **required** when the token grants more than one. A supplied value must exactly match a tenant the token grants. Absent when required, blank, malformed, or naming a tenant the token does not grant — each gets the same generic `403 forbidden`, which reveals neither whether a tenant exists nor which ones you may use. Send the header once: a repeated header is rejected the same way. schema: type: string format: uuid example: 3fa85f64-5717-4562-b3fc-2c963f66afa6 PartyId: name: partyId in: path required: true description: Unique party identifier schema: type: string format: uuid example: 7e3b9c2a-1f4d-4a8b-9c11-2d6e8f0a1b22 schemas: SinglePartyKycStatusResponse: allOf: - $ref: '#/components/schemas/BaseResponse' - type: object properties: result: $ref: '#/components/schemas/PartyKycStatus' ErrorResponse: type: object description: Error response wrapper properties: success: type: boolean description: Always false for error responses example: false errors: type: array description: List of errors that occurred items: $ref: '#/components/schemas/ErrorBody' result: type: object nullable: true description: Null or omitted when success is false BaseResponse: type: object properties: success: type: boolean description: Indicates whether the request was successful PartyKycStatus: type: object description: > Where a party's identity verification stands, relayed live from the verification platform. Enum-like values are relayed as-is and new values may be added; treat an unknown `verificationState` as still in progress. required: - partyId - verificationState - steps properties: partyId: type: string format: uuid verificationState: type: string description: > - `AWAITING_CUSTOMER` — the end customer still has to act (see `requiredAction`) - `IN_REVIEW` — submitted and under review - `RESUBMISSION_REQUESTED` — the reviewer asked the customer to resubmit part of the verification - `APPROVED` — verified; the party and its accounts are updated accordingly - `DECLINED` — verification failed; the party and its accounts are updated accordingly New values may be added; treat an unknown value as still in progress. example: AWAITING_CUSTOMER caseStatus: type: string description: > The underlying verification case status: `DRAFT`, `SUBMITTED`, `IN_REVIEW`, `APPROVED`, `DECLINED` or `NEEDS_INFO`. New values may be added. example: IN_REVIEW requiredAction: type: string description: >- What the end customer still has to do; omitted when nothing is required. example: COMPLETE_SUMSUB_VERIFICATION steps: type: array description: Review outcome per step; empty when no step detail is available. items: $ref: '#/components/schemas/PartyKycStep' lastSyncedAt: type: string format: date-time description: >- When the state was last synchronised with the verification provider; omitted if never. ErrorBody: type: object description: Individual error details properties: code: type: string description: Machine-readable error code example: invalid-request message: type: string description: Human-readable error message example: The request contains invalid parameters. PartyKycStep: type: object required: - step - status - rejectLabels - itemIds properties: step: type: string description: The verification step. example: IDENTITY status: type: string description: > The step's review outcome: `NOT_SUBMITTED`, `SUBMITTED`, `APPROVED`, `REJECTED`, `MISSING` or `INVALID`. New values may be added. example: REJECTED rejectLabels: type: array description: Why the step was rejected; empty when it was not. items: type: string example: - DOCUMENT_EXPIRED itemIds: type: array description: Questionnaire items that still need attention; empty when none. items: type: string example: - annual_gross_income_band responses: Unauthorized: description: Authentication required or failed (401) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: success: false errors: - code: unauthenticated message: Please authenticate to perform this action. Forbidden: description: Caller lacks the required authority/role (403) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: success: false errors: - code: forbidden message: You do not have permission to access this resource. securitySchemes: OAuth2: type: oauth2 description: > OAuth2 client credentials flow. Token endpoints: - Staging: https://login-staging.venly.io/auth/realms/VenlyFinance/protocol/openid-connect/token - Production: https://login.venly.io/auth/realms/VenlyFinance/protocol/openid-connect/token flows: clientCredentials: tokenUrl: >- https://login-staging.venly.io/auth/realms/VenlyFinance/protocol/openid-connect/token scopes: {} ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.