> ## Documentation Index > Fetch the complete documentation index at: https://docs.kirafin.ai/llms.txt > Use this file to discover all available pages before exploring further. # List users > Use `limit<=100` — `limit` is validated, and a value above `100` (or below `1`) returns a clean `400` validation error (`{"code": "validation_error", "message": "Invalid query parameters", ...}`); the same cap applies to `GET /v1/virtual-accounts` and ALL list endpoints. Pass `include_eligibility=true` to also include `capabilities.requested_banks` and `eligible_products` on every row, identical in shape to `GET /v1/users/{user_id}` — omitted by default to keep the response light for callers that don't need them. {/* version-stamp:start — generated by scripts/stamp-versions.ts, do not edit */} Stable since **2025-01-01** — unchanged in **2026-06-01**. {/* version-stamp:end */} ## OpenAPI ````yaml /openapi/kira-api.2026-06-01.json get /v1/users openapi: 3.1.0 info: title: Kira API version: '2026-06-01' description: >- REST API for users, KYC/KYB verification, virtual accounts, payouts, recipients, and webhooks. Every request requires an `x-api-key` header and a bearer access token (see Authentication). Pin your account to version `2026-04-14` before integrating. contact: name: Kira API Support email: support@kirafin.ai servers: - url: https://api.balampay.com description: Production - url: https://api.balampay.com/sandbox description: Sandbox security: - bearerAuth: [] apiKeyAuth: [] tags: - name: Authentication - name: Versioning - name: Users - name: Virtual Accounts - name: Quotations - name: Payouts - name: Recipients - name: Reference - name: RFIs paths: /v1/users: get: tags: - Users summary: List users description: >- Use `limit<=100` — `limit` is validated, and a value above `100` (or below `1`) returns a clean `400` validation error (`{"code": "validation_error", "message": "Invalid query parameters", ...}`); the same cap applies to `GET /v1/virtual-accounts` and ALL list endpoints. Pass `include_eligibility=true` to also include `capabilities.requested_banks` and `eligible_products` on every row, identical in shape to `GET /v1/users/{user_id}` — omitted by default to keep the response light for callers that don't need them. operationId: get_v1-users parameters: - in: header name: X-Api-Version required: false description: >- Optional. The date-versioned API version to apply for this request (e.g. `2026-04-14`). When sent it always wins, even over your pinned account default. When omitted, the API uses your account's pinned version if set, otherwise a baseline default. schema: type: string example: '2026-06-01' - in: query name: limit required: false description: Maximum number of users to return (1-100). schema: type: integer minimum: 1 maximum: 100 default: 10 - in: query name: offset required: false description: Number of users to skip for pagination. schema: type: integer minimum: 0 default: 0 - in: query name: status required: false description: Filter by user status. schema: type: string enum: - CREATED - VERIFYING - VERIFIED - REJECTED - REVIEW - ACTIVE - INACTIVE - SUSPENDED - in: query name: type required: false description: Filter by user type. schema: type: string enum: - individual - business - in: query name: email required: false description: Substring match against the user's email. schema: type: string - in: query name: verification_status required: false description: >- Filter by verification status. Accepts the same lowercase values the response's `verification_status` field carries. schema: type: string enum: - unverified - started - in_review - verified - rejected - needs_action - in: query name: created_after required: false description: Return users created at or after this ISO 8601 date-time. schema: type: string format: date-time - in: query name: created_before required: false description: Return users created at or before this ISO 8601 date-time. schema: type: string format: date-time - in: query name: metadata required: false description: >- Stripe-style metadata filter — `?metadata[key]=value` deep-object form. Each key must be 1-40 characters and must not contain `[` or `]`. Multiple keys are AND-ed. style: deepObject explode: true schema: type: object additionalProperties: type: string - in: query name: include_eligibility required: false description: >- When `true`, each row also includes `capabilities.requested_banks` and `eligible_products`. Omitted (`false`) by default — computing eligibility for every row costs a lookup plus in-memory evaluation per subclient, so it's opt-in rather than always paid by every list caller. schema: type: boolean default: false responses: '200': description: Success. content: application/json: schema: type: object properties: data: type: array items: $ref: '#/components/schemas/UserResponse' pagination: type: object properties: total: type: integer description: Total number of users matching the filters. limit: type: integer description: The limit applied to this page. offset: type: integer description: The offset applied to this page. has_more: type: boolean description: Whether more users exist beyond this page. '401': description: Unauthorized. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' security: - bearerAuth: [] apiKeyAuth: [] components: schemas: UserResponse: type: object properties: id: type: string format: uuid description: User UUID. type: type: string enum: - individual - business description: '`individual` or `business`.' email: type: string format: email description: Email address. status: type: string description: >- Lifecycle status: `CREATED`, `VERIFYING`, `REVIEW`, `VERIFIED`, or `REJECTED`. Gate product readiness on this, not on `verification_status`. verification_status: type: string enum: - unverified - started - in_review - verified - rejected - needs_action default: unverified description: >- KYC/KYB status: `unverified`, `started`, `in_review`, `verified`, `rejected`, or `needs_action`. verification_mode: type: string description: '`automatic` or `verification_link`.' verification_link: type: string description: Hosted KYC URL — present only in `verification_link` mode. verification_link_error: type: string description: >- Populated if hosted-link generation failed, or on PUT /v1/users/{user_id} when a bank-migration triggered by the request was deferred or failed. Freeform, human-readable text — branch on verification_link_error_severity, not this string. verification_link_error_severity: type: string enum: - deferred - failed description: >- Machine-readable companion to verification_link_error, present only alongside it on the PUT /v1/users/{user_id} response. `deferred` means nothing is wrong — the triggered bank migration is waiting on something expected or was correctly skipped by a business rule. `failed` means the migration hit a genuine problem. created_at: type: string format: date-time description: Creation timestamp (ISO 8601). updated_at: type: string format: date-time description: Last-update timestamp (ISO 8601). metadata: type: object additionalProperties: {} description: >- Your key-value pairs, plus any client-level default metadata configured for your account (merged at create time; your request keys win on conflict). first_name: type: string description: Given name (individual users). last_name: type: string description: Family name (individual users). middle_name: type: string description: Middle name (individual users), when provided. phone: type: string description: Contact phone in E.164 form (e.g. `+525512345678`). birth_date: type: string description: Date of birth, `YYYY-MM-DD` (individual users). nationality: type: string description: >- Nationality as an ISO **alpha-3** country code (e.g. `MEX`, `USA`). Users use alpha-3; recipients use alpha-2 — map accordingly. gender: type: string enum: - male - female - other description: '`male`, `female`, or `other`, when provided.' residential_address: type: object description: >- The individual's address. **The response renests and renames the flat create-request fields:** `address_street` → `street_line_1`, `address_state` → `subdivision`, `address_zip_code` → `postal_code`, `address_city` → `city`, `address_country` → `country`. Parse this nested shape — the flat `address_*` request fields do not round-trip. properties: street_line_1: type: string street_line_2: type: string city: type: string subdivision: type: string postal_code: type: string country: type: string description: >- Country as an ISO 3166-1 alpha-3 code (e.g. `USA`), returned as stored from the alpha-3 value sent on create/update. formation_country: type: string business_legal_name: type: string company_name: type: string business_type: type: string business_trade_name: type: string business_description: type: string business_industry: type: array items: type: string registered_address: type: object properties: street_line_1: type: string street_line_2: type: string city: type: string subdivision: type: string postal_code: type: string country: type: string physical_address: type: object properties: street_line_1: type: string street_line_2: type: string city: type: string subdivision: type: string postal_code: type: string country: type: string has_material_intermediary_ownership: type: boolean account_purpose: type: string description: >- Write-only in practice: accepted on create/update but currently NOT returned by GET — do not depend on reading it back. source_of_funds: type: string description: >- Write-only in practice: accepted on create/update but currently NOT returned by GET — do not depend on reading it back. eligible_products: type: array description: >- Per-product eligibility, computed from the user's supplied fields against the product matrix — present on the create response and on the single-resource GET (`GET /v1/users/{user_id}`), even before verification. On the list (`GET /v1/users`), present only when the request passed `include_eligibility=true`; omitted otherwise. Each product carries `eligible` (false until the user reaches the product's minimum status, e.g. VERIFIED) and its own `missing_fields`. Verification flips `eligible` to true and clears `missing_fields`; it does not populate the array. A product that is `eligible: false` for a reason no field can clear carries `unsupported_reason` instead of `missing_fields` — verification will not flip it. items: type: object properties: product_id: type: string description: Product UUID. product_code: type: string description: >- Product code, e.g. `usa-virtual-accounts`, `usa-virtual-accounts-act`. product_name: type: string description: Human-readable product name. eligible: type: boolean description: Whether the user can open this product now. missing_fields: type: array items: type: string description: Field tokens still required for this product. unsupported_reason: type: string enum: - enhanced_due_diligence_required description: >- Present only when `eligible` is `false` for a reason no field can clear — a capability not offered for this user yet, rather than an incomplete profile. Mutually exclusive with `missing_fields`: check this first, because supplying fields will not change the verdict. `enhanced_due_diligence_required` — the business's industry requires enhanced due diligence (EDD), which is not supported yet; `POST /v1/virtual-accounts` returns `422` with the same explanation. Branch on this value, not on the message text. missing_fields: type: object description: >- Map of `product_code` → outstanding field tokens, plus a `general` key with the deduplicated union across products. It is populated before verification too; the sole exception is that this top-level aggregate is omitted on the create response for `verification_link`-mode users or when there are zero gaps. additionalProperties: type: array items: type: string capabilities: type: object description: >- Per-subclient bank intent — which banks this subclient has declared it needs. Always present on `GET /v1/users/{id}`, including `{ "requested_banks": [] }` when nothing is declared — never omitted there. On the list (`GET /v1/users`), present only when the request passed `include_eligibility=true`; omitted otherwise. properties: requested_banks: type: array items: type: string description: >- Banks this subclient has expressed intent to use, e.g. `portage`, `slovak_savings_bank`, `austin_capital_trust`. This records intent only — it does not by itself authorize the subclient for a bank your account isn't already authorized for. required: - requested_banks required: - id - type - email - status - created_at - updated_at ErrorResponse: type: object properties: message: type: string code: type: string statusCode: type: number error: type: string timestamp: type: string path: type: string details: {} required: - message securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: JWT description: Access token from `POST /auth` (the `data.access_token` value). apiKeyAuth: type: apiKey in: header name: x-api-key description: API key issued by Kira. Required on every request, including `/auth`. ````