> ## 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 > List the users under your account. The rows arrive in `data`. Alongside them, `pagination` reports the `total` number of users matching your filters, plus the `limit` and `offset` applied to this page. Use the query parameters to narrow the list — by `status`, `type`, `email`, `verification_status`, creation date, or `metadata` — and `limit` and `offset` to page through it. ## OpenAPI ````yaml /openapi/kira-api.2026-04-14.json get /v1/users openapi: 3.1.0 info: title: Kira API version: '2026-04-14' 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: Recipients - name: Quotations - name: Payouts - name: Reference paths: /v1/users: get: tags: - Users summary: List users description: >- List the users under your account. The rows arrive in `data`. Alongside them, `pagination` reports the `total` number of users matching your filters, plus the `limit` and `offset` applied to this page. Use the query parameters to narrow the list — by `status`, `type`, `email`, `verification_status`, creation date, or `metadata` — and `limit` and `offset` to page through it. operationId: get_v1-users parameters: - in: header name: X-Api-Version required: false description: >- Version applied to this request. It wins over your account's pinned version — see [Versioning](/using-the-api/versioning). schema: type: string example: '2026-04-14' - in: query name: limit required: false description: >- How many users to return. Between `1` and `100`, and `10` when you omit it. A value outside that range is rejected with a `400`. schema: type: integer minimum: 1 maximum: 100 default: 10 - in: query name: offset required: false description: >- How many users to skip before the first row returned. Use it with `limit` to walk the list: `offset=0`, then `offset=10`, and so on. `0` when you omit it. schema: type: integer minimum: 0 default: 0 - in: query name: status required: false description: >- Filter by user status. Available options: `CREATED`, `VERIFYING`, `REVIEW`, `VERIFIED`, `REJECTED`, plus the legacy `ACTIVE`, `INACTIVE` and `SUSPENDED`. See [User values](/reference/users/values#status) for what each one means. schema: type: string - in: query name: type required: false description: >- Filter by user type. Available options: `business`, `individual`. See [User values](/reference/users/values#type) for what each one means. schema: type: string - 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 the user's verification result. Available options: `unverified`, `started`, `in_review`, `verified`, `rejected`, `needs_action`. See [User values](/reference/users/values#verification_status) for what each one means. schema: type: string - 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: >- Filter by the metadata you stored on the user. Repeat the parameter once per key: `?metadata[order_id]=A-17&metadata[region]=eu`. A user matches only if it carries **every** pair you send, each with exactly that value. Extra keys on the user do not prevent a match. Keys are 1 to 40 characters and cannot contain `[` or `]`. Values are strings of up to 500 characters. schema: type: object style: deepObject explode: true - in: query name: include_eligibility required: false description: >- Set this to `true` to add `capabilities.requested_banks` and `eligible_products` to every row. It is `false` by default. Those two fields are worked out per user, so asking for them makes the response slower and larger — request them only when you need them. schema: type: boolean default: false responses: '200': description: Success. content: application/json: schema: type: object properties: data: type: array items: $ref: '#/components/schemas/UserListItem' 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. example: data: - id: 11111111-2222-3333-4444-555555555555 type: business email: ops@example.com status: VERIFIED verification_status: verified created_at: '2026-09-01T12:00:00.000Z' updated_at: '2026-09-01T12:05:00.000Z' verification_mode: automatic metadata: {} formation_country: USA business_legal_name: Northwind Trading LLC registered_address: street_line_1: 1 Market Street street_line_2: '' city: San Francisco subdivision: CA postal_code: '94105' country: USA identifying_information: - type: business_formation number: '123456789' issuing_country: USA documents: - type: file_business_formation file_name: >- 1712345678901-a1b2c3d4-business_formation-file_business_formation.pdf uploaded_at: '2026-09-01T12:00:01.000Z' content_type: application/pdf - type: file_certificate_of_good_standing file_name: >- 1712345678902-b2c3d4e5-business_formation-file_certificate_of_good_standing.pdf uploaded_at: '2026-09-01T12:00:02.000Z' content_type: application/pdf - type: business_formation issuing_country: USA documents: - type: file_ein_letter file_name: >- 1712345678903-c3d4e5f6-business_formation-file_ein_letter.pdf uploaded_at: '2026-09-01T12:00:03.000Z' content_type: application/pdf associated_persons: - person_id: 0123456789abcdef0123456789abcdef first_name: Alice last_name: Smith email: alice@example.com birth_date: '1980-05-15' gender: female nationality: USA country_of_birth: USA phone_number: '+14155550142' occupation: '111021' pep_status: false has_ownership: true ownership_percentage: 100 ssn: 000-00-0000 document_type: passport document_number: X1234567 document_country: USA residential_address: street_line_1: 742 Evergreen Terrace city: Springfield subdivision: OR postal_code: '97477' country: USA identifying_information: - type: ssn number: 000-00-0000 issuing_country: USA - type: passport number: X1234567 expiration: '2032-01-18' issuing_country: USA documents: - type: front file_name: 1712345678904-d4e5f6a7-passport-front.jpg uploaded_at: '2026-09-01T12:00:04.000Z' content_type: image/jpeg - type: back file_name: 1712345678905-e5f6a7b8-passport-back.jpg uploaded_at: '2026-09-01T12:00:05.000Z' content_type: image/jpeg pagination: total: 186 limit: 10 offset: 0 has_more: true '400': description: >- A query parameter is out of range, or is not one of the values it accepts. `errors` names each one. content: application/json: schema: type: object properties: code: type: string description: Always `validation_error`. message: type: string description: Always `Invalid query parameters`. errors: type: array description: One entry per parameter that was rejected. items: type: object properties: field: type: string description: The parameter that was rejected — `limit`. message: type: string description: What is wrong with it. example: code: validation_error message: Invalid query parameters errors: - field: limit message: Number must be less than or equal to 100 '401': description: >- Your credentials were not accepted. The message talks about routing, but it is the same body for every cause, so it is not a guide to which one: - The `Authorization` header is missing, expired or wrong. Get a new token from [Get access token](/api-reference/authentication/get-access-token). - The `x-api-key` header is missing or wrong. - One is present and the other is not. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: code: invalid_request message: >- The request could not be matched to a valid route, or was malformed. Verify the path and HTTP method against the API reference. This is a routing or request error, not a credentials or signature problem. security: - bearerAuth: [] apiKeyAuth: [] servers: - url: https://api.balampay.com/sandbox description: Sandbox - url: https://api.balampay.com description: Production components: schemas: UserListItem: type: object description: A user as it appears in the list. properties: id: type: string format: uuid description: User UUID. type: type: string description: >- Whether the user is a company or a person. Available options: `business`, `individual`. See [User values](/reference/users/values#type) for what each one means. email: type: string format: email description: Email address. status: type: string description: >- Where the user sits in its lifecycle. Available options: `CREATED`, `VERIFYING`, `REVIEW`, `VERIFIED`, `REJECTED`, plus the legacy `ACTIVE`, `INACTIVE` and `SUSPENDED`. See [User values](/reference/users/values#status) for what each one means. verification_status: type: string description: >- The result of the user's identity or business check. Available options: `unverified`, `started`, `in_review`, `verified`, `rejected`, `needs_action`. See [User values](/reference/users/values#verification_status) for what each one means. 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). 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: >- A plain-text note about something the request could not finish — the hosted verification link, or a move of this user to a different bank. The wording can change, so branch on `verification_link_error_severity`, never on this string. verification_link_error_severity: type: string enum: - deferred - failed description: >- Whether the note in `verification_link_error` asks anything of you. See [User values](/reference/users/values#verification_link_error_severity) for what each value means. metadata: type: object additionalProperties: {} description: >- The key-value pairs you stored on this user. If your account has default metadata configured, it is merged in when the user is created and your own keys win on a 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: >- The person's nationality, as an ISO **alpha-3** country code — `USA`, `MEX`. country_of_birth: type: string description: >- Where the person was born, as an ISO **alpha-3** country code. Absent when it was never set. gender: type: string description: '`male`, `female`, or `other`, when provided.' residential_address: type: object description: The person's address, as a nested object. properties: street_line_1: type: string street_line_2: type: string city: type: string subdivision: type: string description: >- The state or province. For users in the USA, the 2-letter state code (`FL`). It comes back exactly as you sent it. postal_code: type: string country: type: string description: >- Country as an ISO **alpha-3** code (`USA`). It comes back exactly as you sent it. formation_country: type: string description: Country the business was formed in, as an ISO **alpha-3** code. business_legal_name: type: string description: The registered legal name of the business. registered_address: type: object properties: street_line_1: type: string street_line_2: type: string city: type: string subdivision: type: string description: >- The state or province. For users in the USA, the 2-letter state code (`FL`). It comes back exactly as you sent it. postal_code: type: string country: type: string description: >- Country as an ISO **alpha-3** code (`USA`). It comes back exactly as you sent it. description: The registered, legal address of the business. identifying_information: type: - array - 'null' description: >- The user's identity or registration records. `null` when none are stored, and absent on users whose verification runs through a hosted link. items: $ref: '#/components/schemas/IdentifyingInformation' associated_persons: type: - array - 'null' description: >- The people tied to a business. `null` for a person, and absent on users whose verification runs through a hosted link. items: $ref: '#/components/schemas/AssociatedPerson' eligible_products: type: array description: >- What this user can already use, product by product. Each entry carries `eligible`, and when that is `false`, the reason why: - `missing_fields` — data is missing. Send it, and the product turns eligible once the user passes verification. - `unsupported_reason` — nothing you send will change the answer. A product stays `eligible: false` until the user reaches the status that product asks for, which is usually `VERIFIED`. 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 description: >- Why the product is closed to this user, when no data you send can change it. It replaces `missing_fields` — read this one first. See [User values](/reference/users/values#unsupported_reason) for what each value means. capabilities: type: object description: >- Which banks this user has said it needs. When the field comes back it always carries `requested_banks`, using an empty array when the user has declared nothing. properties: requested_banks: type: array items: type: string description: >- Banks this business has said it plans to use. See [Virtual account values](/reference/virtual-accounts/values#bank) for the accepted values. 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 IdentifyingInformation: type: object description: One identity or registration record. properties: type: type: string description: >- What the record is — `passport`, `ssn`, `drivers_license`, `business_formation`, `ein_letter`, `proof_of_address`, `source_of_wealth`. number: type: string description: The document or registration number, when the record has one. expiration: type: string description: Expiry date, `YYYY-MM-DD`, on records that expire. issuing_country: type: string description: Country that issued it, as an ISO **alpha-3** code. documents: type: array description: The files uploaded for this record. items: type: object description: One uploaded file. properties: type: type: string description: >- What the file shows — `front`, `back`, `selfie`, or a `file_*` document type. file_name: type: string description: The stored file name. It is not a download URL. uploaded_at: type: string description: When the file was uploaded, ISO 8601. content_type: type: string description: The file's MIME type — `application/pdf`, `image/jpeg`. AssociatedPerson: type: object description: >- One person tied to a business — an owner, a signer, or someone in control. properties: person_id: type: string description: >- Kira's id for this person, when there is one. Match people by `email` rather than relying on it. first_name: type: string middle_name: type: string last_name: type: string email: type: string birth_date: type: string description: Date of birth, `YYYY-MM-DD`. gender: type: string nationality: type: string description: ISO **alpha-3** country code. country_of_birth: type: string description: ISO **alpha-3** country code. phone_number: type: string description: Phone in E.164 form. occupation: type: string description: Occupation code. title: type: string description: The person's role in the business — `CEO`. pep_status: type: boolean description: Whether the person is, or has been, a politically exposed person. is_signer: type: boolean description: Whether the person can sign for the business. has_control: type: boolean description: Whether the person controls the business. has_ownership: type: boolean description: Whether the person owns part of the business. ownership_percentage: type: number description: How much of the business the person owns, as a percentage. ssn: type: string description: US Social Security number, on US people. document_type: type: string description: The person's primary document — `passport`, `drivers_license`. document_number: type: string document_country: type: string description: ISO **alpha-3** country code. address_street: type: string description: >- Flat address field. Some people carry these instead of `residential_address`. address_city: type: string address_state: type: string address_zip_code: type: string address_country: type: string description: ISO **alpha-3** country code. residential_address: $ref: '#/components/schemas/Address' identifying_information: type: array description: The person's own identity records. items: $ref: '#/components/schemas/IdentifyingInformation' Address: type: object description: A postal address. properties: street_line_1: type: string street_line_2: type: string city: type: string subdivision: type: string description: >- The state or province. For users in the USA, the 2-letter state code (`FL`). It comes back exactly as you sent it. postal_code: type: string country: type: string description: >- Country as an ISO **alpha-3** code (`USA`). It comes back exactly as you sent it. securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: JWT description: >- The `data.access_token` value from [Get access token](/api-reference/authentication/get-access-token). apiKeyAuth: type: apiKey in: header name: x-api-key description: API key issued by Kira. ````