> ## Documentation Index > Fetch the complete documentation index at: https://docs.vitawallet.io/llms.txt > Use this file to discover all available pages before exploring further. # Get beneficiary > This endpoint allows you to **check whether a beneficiary is registered in Vita and able to receive funds** through a withdrawal in a specific country. It's typically used as a **pre-flight check** before creating a withdrawal — letting you verify the recipient's eligibility, retrieve their existing information, and improve the user experience by avoiding failed transactions. If the beneficiary exists, the endpoint returns their full profile (name, document, status). If they don't exist yet, **you can still proceed with the withdrawal** — Vita will automatically create the beneficiary using the information provided in the withdrawal request. > **Note:** **Don't worry if the beneficiary is not found.** Submit the withdrawal directly and the beneficiary will be created on the fly from the data you provide. --- #### Why Use This Endpoint - **Validate recipient eligibility** before initiating a withdrawal. - **Retrieve known beneficiary data** to pre-fill fields and reduce user input errors. - **Confirm the beneficiary's status** (e.g., active vs. blocked) before sending funds. --- #### Request Structure | Key | Description | Required | | --- | --- | --- | | `document_number` | Beneficiary's identification document number. | Required | | `country_iso_code` | ISO country code of the beneficiary's country (e.g., `CL`, `CO`, `US`). | Required | | `document_type` | Type of identification document (e.g., `RUT`, `CC`, `CURP`, `SSN, CPF`). | **Conditional** — is required when the country does not require `beneficiary_type`, or the `beneficiary_type` is set to `Individual`. | | `beneficiary_type` | Type of beneficiary, e.g., `Individual` or `Business`. | **Conditional** — Is required only when the destination country mandates it (e.g., the United States). | --- #### Request Example ```javascript { "document_number": "1111111111", "document_type": "RUT", "country_iso_code": "CL" } ``` --- #### Response Structure When the beneficiary is found, the API returns the beneficiary's full profile inside a `beneficiary` object. #### Response Example ```javascript { "beneficiary": { "id": 1, "type": "beneficiary", "attributes": { "first_name": "Jhon", "last_name": "Doe", "company_name": null, "beneficiary_type": null, "document_type": "RUT", "document_number": "1111111111", "country_iso_code": "CL", "status": "active", "is_received": true } } } ``` #### Response Fields | Field | Description | | --- | --- | | `id` | Unique identifier of the beneficiary in Vita Business. | | `type` | Resource type — always `"beneficiary"`. | | `attributes.first_name` | First name of the beneficiary (for individuals). | | `attributes.last_name` | Last name of the beneficiary (for individuals). | | `attributes.company_name` | Legal name of the beneficiary (for businesses). `null` for individuals. | | `attributes.beneficiary_type` | Beneficiary classification (`Individual`, `Business`, or `null` if not applicable to the country). | | `attributes.document_type` | Type of identification document on file. | | `attributes.document_number` | Identification document number on file. | | `attributes.country_iso_code` | ISO country code of the beneficiary's country. | | `attributes.status` | Current status of the beneficiary (e.g., `active`, `banned`). | | `attributes.is_received` | Indicates whether the beneficiary has previously received funds through your account. Useful for distinguishing recurring vs. first-time recipients. | --- #### Important Considerations #### Beneficiary Not Found Is Not an Error - If the beneficiary doesn't exist in Vita, this is **not a failure condition**. You can still proceed with the withdrawal, and Vita will create the beneficiary automatically using the information sent in the withdrawal request. #### Country-Specific Field Requirements - Always verify which fields are required for the destination country. Calling `GET /api/businesses/withdrawal_rules` is the recommended way to confirm country-specific requirements before submitting this request. #### Status Validation - Even if a beneficiary exists, check the \`status\` field. A beneficiary marked as \`blocked\` or \`inactive\` will not be able to receive funds, and the withdrawal will fail. #### Recurring Beneficiaries - The \`is_received\` field indicates whether this beneficiary has previously received funds from your account. Use it to differentiate between new and recurring recipients in your UI or reporting. ## OpenAPI ````yaml /openapi.yaml post /api/businesses/beneficiaries/get_beneficiary openapi: 3.0.0 info: title: Vita Business API description: >- Vita Wallet Business API — integra payins, payouts, exchange, transactions, users y webhooks para operar pagos en LatAm y el mundo. version: 1.0.0 contact: name: Vita Wallet Support url: https://vitawallet.io email: empresas@vitawallet.io servers: - url: https://api.vitawallet.io description: Production - url: https://api.stage.vitawallet.io description: Sandbox security: - xLogin: [] xTransKey: [] xDate: [] hmacSignature: [] tags: - name: Create Payin - name: Direct Payment - name: Exchange - name: Vita Sent - name: Bank Payouts - name: External Crypto Payouts - name: Transactions - name: Users Creation - name: User Information - name: Webhooks externalDocs: url: https://vitawallet.io description: Vita Wallet paths: /api/businesses/beneficiaries/get_beneficiary: post: tags: - Bank Payouts summary: Get beneficiary description: >- This endpoint allows you to **check whether a beneficiary is registered in Vita and able to receive funds** through a withdrawal in a specific country. It's typically used as a **pre-flight check** before creating a withdrawal — letting you verify the recipient's eligibility, retrieve their existing information, and improve the user experience by avoiding failed transactions. If the beneficiary exists, the endpoint returns their full profile (name, document, status). If they don't exist yet, **you can still proceed with the withdrawal** — Vita will automatically create the beneficiary using the information provided in the withdrawal request. > **Note:** **Don't worry if the beneficiary is not found.** Submit the withdrawal directly and the beneficiary will be created on the fly from the data you provide. --- #### Why Use This Endpoint - **Validate recipient eligibility** before initiating a withdrawal. - **Retrieve known beneficiary data** to pre-fill fields and reduce user input errors. - **Confirm the beneficiary's status** (e.g., active vs. blocked) before sending funds. --- #### Request Structure | Key | Description | Required | | --- | --- | --- | | `document_number` | Beneficiary's identification document number. | Required | | `country_iso_code` | ISO country code of the beneficiary's country (e.g., `CL`, `CO`, `US`). | Required | | `document_type` | Type of identification document (e.g., `RUT`, `CC`, `CURP`, `SSN, CPF`). | **Conditional** — is required when the country does not require `beneficiary_type`, or the `beneficiary_type` is set to `Individual`. | | `beneficiary_type` | Type of beneficiary, e.g., `Individual` or `Business`. | **Conditional** — Is required only when the destination country mandates it (e.g., the United States). | --- #### Request Example ```javascript { "document_number": "1111111111", "document_type": "RUT", "country_iso_code": "CL" } ``` --- #### Response Structure When the beneficiary is found, the API returns the beneficiary's full profile inside a `beneficiary` object. #### Response Example ```javascript { "beneficiary": { "id": 1, "type": "beneficiary", "attributes": { "first_name": "Jhon", "last_name": "Doe", "company_name": null, "beneficiary_type": null, "document_type": "RUT", "document_number": "1111111111", "country_iso_code": "CL", "status": "active", "is_received": true } } } ``` #### Response Fields | Field | Description | | --- | --- | | `id` | Unique identifier of the beneficiary in Vita Business. | | `type` | Resource type — always `"beneficiary"`. | | `attributes.first_name` | First name of the beneficiary (for individuals). | | `attributes.last_name` | Last name of the beneficiary (for individuals). | | `attributes.company_name` | Legal name of the beneficiary (for businesses). `null` for individuals. | | `attributes.beneficiary_type` | Beneficiary classification (`Individual`, `Business`, or `null` if not applicable to the country). | | `attributes.document_type` | Type of identification document on file. | | `attributes.document_number` | Identification document number on file. | | `attributes.country_iso_code` | ISO country code of the beneficiary's country. | | `attributes.status` | Current status of the beneficiary (e.g., `active`, `banned`). | | `attributes.is_received` | Indicates whether the beneficiary has previously received funds through your account. Useful for distinguishing recurring vs. first-time recipients. | --- #### Important Considerations #### Beneficiary Not Found Is Not an Error - If the beneficiary doesn't exist in Vita, this is **not a failure condition**. You can still proceed with the withdrawal, and Vita will create the beneficiary automatically using the information sent in the withdrawal request. #### Country-Specific Field Requirements - Always verify which fields are required for the destination country. Calling `GET /api/businesses/withdrawal_rules` is the recommended way to confirm country-specific requirements before submitting this request. #### Status Validation - Even if a beneficiary exists, check the \`status\` field. A beneficiary marked as \`blocked\` or \`inactive\` will not be able to receive funds, and the withdrawal will fail. #### Recurring Beneficiaries - The \`is_received\` field indicates whether this beneficiary has previously received funds from your account. Use it to differentiate between new and recurring recipients in your UI or reporting. operationId: get-beneficiary requestBody: content: application/json: schema: type: object example: document_number: '1111111111' document_type: RUT country_iso_code: CL responses: '200': description: Successful response. content: application/json: examples: ClActivedBeneficiary: summary: CL Actived Beneficiary value: beneficiary: id: 1 type: beneficiary attributes: first_name: Jhon last_name: Doe company_name: null beneficiary_type: null document_type: RUT document_number: 1111111111 country_iso_code: CL status: active is_received: true ClBannedBeneficiary: summary: CL Banned Beneficiary value: beneficiary: id: 1 type: beneficiary attributes: first_name: Jhon last_name: Doe company_name: null beneficiary_type: null document_type: RUT document_number: 1111111111 country_iso_code: CL status: banned is_received: false BoActivedBeneficiary: summary: BO Actived Beneficiary value: beneficiary: id: 1 type: beneficiary attributes: first_name: Jhon last_name: Doe company_name: null beneficiary_type: Individual document_type: CI document_number: 1111111111 country_iso_code: BO status: active is_received: true UsActivedIndividual: summary: US Actived Individual value: beneficiary: id: 1 type: beneficiary attributes: first_name: Jhon last_name: Doe company_name: null beneficiary_type: Individual document_type: DNI document_number: 1111111111 country_iso_code: US status: active is_received: true UsActivedCorporate: summary: US Actived Corporate value: beneficiary: id: 1 type: beneficiary attributes: first_name: null last_name: null company_name: Test company beneficiary_type: Corporate document_type: null document_number: 1111111111 country_iso_code: US status: active is_received: true UsBannedIndividual: summary: US Banned Individual value: beneficiary: id: 1 type: beneficiary attributes: first_name: Jhon last_name: Doe company_name: null beneficiary_type: Individual document_type: DNI document_number: 1111111111 country_iso_code: US status: banned is_received: false UsBannedCorporate: summary: US Banned Corporate value: beneficiary: id: 1 type: beneficiary attributes: first_name: null last_name: null company_name: Test company beneficiary_type: Corporate document_type: null document_number: 1111111111 country_iso_code: US status: banned is_received: false BeneficiaryNotFound: summary: Beneficiary not found value: error: code: 404 message: Beneficiary was not found components: securitySchemes: xLogin: type: apiKey in: header name: x-login description: Business xLogin xTransKey: type: apiKey in: header name: x-trans-key description: Business xTransKey xDate: type: apiKey in: header name: x-date description: ISO8601 datetime hmacSignature: type: apiKey in: header name: Authorization description: 'V2-HMAC-SHA256 signature. Example: `V2-HMAC-SHA256, Signature: `' ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.