> ## 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. # Get a user > Returns one user in full, by id. ## OpenAPI ````yaml /openapi/kira-api.2026-04-14.json get /v1/users/{user_id} 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/{user_id}: get: tags: - Users summary: Get a user description: Returns one user in full, by id. operationId: get_v1-users-user-id parameters: - in: path name: user_id required: true schema: type: string format: uuid description: >- The id of the user, as returned when you created it. It must be a UUID. - 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' responses: '200': description: The user. content: application/json: schema: $ref: '#/components/schemas/UserDetail' example: id: e687484f-74ef-43a8-a68a-5bf78aa2e721 type: business email: ops@example.com status: CREATED verification_status: unverified created_at: '2026-09-01T12:00:00.000Z' updated_at: '2026-09-01T12:00:00.000Z' verification_mode: automatic capabilities: requested_banks: [] 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 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 associated_persons: - first_name: Alice last_name: Smith email: alice@example.com person_id: 0123456789abcdef0123456789abcdef birth_date: '1980-05-15' nationality: USA document_type: passport document_number: X1234567 document_country: USA has_ownership: true ownership_percentage: 100 identifying_information: - type: ssn number: 000-00-0000 issuing_country: USA eligible_products: - product_id: usa-virtual-accounts product_code: usa-virtual-accounts product_name: USA Virtual Accounts eligible: false missing_fields: - identifying_information:file_portfolio_statement - identifying_information:file_board_minutes missing_fields: usa-virtual-accounts: - identifying_information:file_portfolio_statement - identifying_information:file_board_minutes general: - identifying_information:file_portfolio_statement - identifying_information:file_board_minutes '400': description: The id in the path is not a UUID. `details` names the field. content: application/json: schema: type: object properties: error: type: string description: Always `Invalid request data`. details: type: array description: One entry per problem. items: type: object properties: path: type: string message: type: string code: type: string example: error: Invalid request data details: - path: user_id message: Invalid user ID format code: invalid_string '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. '404': description: >- No user with that id exists under your account. A well-formed id that belongs to someone else reads the same way. A path or method that is not routed answers `404` instead, with `code: route_not_found` and a different message. `PATCH` is not routed on any user path. content: application/json: schema: type: object properties: code: type: string description: Always `not_found`. message: type: string description: Names the id that was not found. example: code: not_found message: User with ID 11111111-2222-3333-4444-555555555555 not found security: - bearerAuth: [] apiKeyAuth: [] servers: - url: https://api.balampay.com/sandbox description: Sandbox - url: https://api.balampay.com description: Production components: schemas: UserDetail: type: object description: One user, in full. 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. 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. 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. missing_fields: type: object description: >- The gaps that remain, grouped by product code, plus a `general` key holding every token once. A product with nothing outstanding is left out of the map, so it can come back with only `general`, or empty. additionalProperties: type: array items: type: string 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. ````