> ## Documentation Index > Fetch the complete documentation index at: https://www.cashfree.com/docs/llms.txt > Use this file to discover all available pages before exploring further. # Get Beneficiary V2 > Use this API to get the details of a particular beneficiary from your account. You can pass either beneficiary_id or the combination of bank_account_number and bank_ifsc to fetch the details. | HTTP status code | Error code | Message | Next action | | :--------------- | :-------------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------ | | 200 | - | - | - | | 400 | too\_many\_parameters\_in\_request | Please provide either bank\_account\_number and bank\_ifsc together or beneficiary\_id alone. Do not include all three parameters in the request | Please provide either bank\_account\_number and bank\_ifsc together or beneficiary\_id alone. Do not include all three parameters in the request. | | 400 | bank\_ifsc\_missing | bank\_ifsc: should be provided with the request if bank\_account\_number is provided | Provide a valid bank\_ifsc if bank\_account\_number is provided. | | 400 | bank\_account\_number\_missing | bank\_account\_number: should be provided with the request if bank\_ifsc is provided | Provide a valid bank\_account\_number is bank\_ifsc is provided. | | 400 | beneficiary\_identifiers\_missing | beneficiary\_identifiers\_missing beneficiary\_identifiers: Either beneficiary\_id or the combination of bank\_account\_number and bank\_ifsc has to be provided with the request | Please provide either beneficiary\_id or the combination of bank\_account\_number and bank\_ifsc. | | 400 | beneficiary\_id\_length\_exceeded | beneficiary\_id : should not be more than 50 characters long. value received: test\_bene\_id | Enter a valid beneficiary\_id | | 400 | beneficiary\_id\_invalid | beneficiary\_id : should contain only letters, numbers, hyphen, underscore, pipe, and dot. Value received: .\qewqefwqev | Enter a valid beneficiary\_id. | | 400 | bank\_account\_number\_length\_exceeded | bank\_account\_number : should not be more than 25 characters long. value received: 235142352346523462456345263452345 | Provide a valid bank\_account\_number. | | 400 | bank\_account\_number\_length\_short | bank\_account\_number : should not be less than 4 characters long. value received: 12 | Provide a valid bank\_account\_number. | | .400 | bank\_account\_number\_invalid | bank\_account\_number : should be alphanumeric. value received: 123@ | Provide a valid bank\_account\_number. | | 400 | bank\_ifsc\_invalid | bank\_ifsc : please provide a valid IFSC. value received: SBIN00708410 | Provide a valid bank\_ifsc. | | 404 | beneficiary\_not\_found | Beneficiary does not exist | Provide the details of an existing beneficiary. If such a beneficiary does not exist, use CREATE API to create a new beneficiary. | | 404 | beneficiary\_not\_found | Beneficiary with the given bank\_account\_number and bank\_ifsc does not exist | Provide the details of an existing beneficiary. If such a beneficiary does not exist, use CREATE API to create a new beneficiary | | 404 | beneficiary\_not\_found | Beneficiary exists with the given bank\_account\_number but a different bank\_ifsc | If the required a beneficiary does not exist, use CREATE API to create a new beneficiary | ## OpenAPI ````yaml get /beneficiary openapi: 3.0.0 info: version: '2024-01-01' title: Cashfree Payout APIs license: name: Apache 2.0 url: https://www.apache.org/licenses/LICENSE-2.0.html contact: email: developers@cashfree.com name: API Support url: https://discord.com/invite/QdZkNSxXsB description: >- Cashfree's Payout APIs provide developers with a streamlined pathway to integrate advanced payout capabilities into their applications, platforms and websites. servers: - url: https://sandbox.cashfree.com/payout description: Sandbox server - url: https://api.cashfree.com/payout description: Production server security: [] tags: - name: V2 Apis description: >- Collection of APIs to transfer funds to beneficiaries and manage beneficiaries. externalDocs: url: https://api.cashfree.com/payout description: This url will have the information of all the APIs. paths: /beneficiary: get: tags: - Beneficiary v2 summary: Get Beneficiary V2 description: >- Use this API to get the details of a particular beneficiary from your account. You can pass either beneficiary_id or the combination of bank_account_number and bank_ifsc to fetch the details. operationId: PayoutFetchBeneficiary parameters: - $ref: '#/components/parameters/apiVersionHeader' - $ref: '#/components/parameters/xRequestIDHeader' - $ref: '#/components/parameters/xCfSignature' - in: query name: beneficiary_id description: >- It is the unique ID you created to identify the beneficiary while creating the beneficiary. example: JOHN18011343 schema: type: string maxLength: 50 - in: query name: bank_account_number description: >- It is the bank account number of the beneficiary. If bank_account_number is passed in query, bank_ifsc should also be passed. example: '00001111222233' schema: type: string maxLength: 25 minLength: 4 - in: query name: bank_ifsc description: >- It is the IFSC information as present in the beneficiary's bank account information. If bank_ifsc is passed in query, bank_account_number should also be passed. example: HDFC0000001 schema: type: string maxLength: 11 minLength: 11 responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/Beneficiary' examples: valid_beneficiary_id: $ref: '#/components/examples/get_beneficiary_success_v2' headers: x-request-id: $ref: '#/components/headers/x-request-id' '400': description: Bad request content: application/json: schema: $ref: '#/components/schemas/ErrorV2' examples: all_three_params_given: $ref: '#/components/examples/all_three_params_given' bank_account_given_ifsc_not_given: $ref: >- #/components/examples/bank_account_given_ifsc_not_given_in_get_v2 bank_ifsc_given_account_not_given: $ref: >- #/components/examples/bank_ifsc_given_account_not_given_in_get_v2 no_bene_identifiers_provided: $ref: '#/components/examples/no_bene_identifiers_provided_v2' bene_id_too_long: $ref: '#/components/examples/bene_id_too_large_v2' invalid_bene_id_due_unacceptable_characters: $ref: >- #/components/examples/invalid_bene_id_due_unacceptable_characters bank_account_number_too_large: $ref: '#/components/examples/bank_account_number_too_large' bank_account_number_too_short: $ref: '#/components/examples/bank_account_number_too_short' bank_account_invalid: $ref: '#/components/examples/bank_account_invalid' invalid_ifsc: $ref: '#/components/examples/invalid_ifsc' headers: x-request-id: $ref: '#/components/headers/x-request-id' '403': description: Forbidden error content: application/json: schema: $ref: '#/components/schemas/ErrorV2' examples: APIDisabled: $ref: '#/components/examples/APIsDisabledExampleV2' '404': description: Resource not found content: application/json: schema: $ref: '#/components/schemas/ErrorV2' examples: BeneficiaryIdNotFound: $ref: '#/components/examples/beneficiary_id_not_found_v2' BeneficiaryBankAccountAndIfscDoesNotExist: $ref: >- #/components/examples/beneficiary_with_account_does_not_exist_v2 BeneficiaryAccountExistWithDifferentIfsc: $ref: >- #/components/examples/bank_account_exists_with_a_different_ifsc_v2 '500': description: Internal server error content: application/json: schema: $ref: '#/components/schemas/ErrorV2' examples: InternalServerError: $ref: '#/components/examples/internal_server_error_v2' deprecated: false security: - XClientID: [] XClientSecret: [] components: parameters: apiVersionHeader: in: header name: x-api-version required: true description: It is the API version to be used. The accepted format is YYYY-MM-DD. schema: type: string description: It is the API version to be used. default: '2024-01-01' example: '2024-01-01' xRequestIDHeader: in: header name: x-request-id description: >- Request ID for the API call. Can be used to resolve tech issues. Communicate this in your tech related queries to Cashfree. required: false schema: type: string example: 4dfb9780-46fe-11ee-be56-0242ac120002 xCfSignature: in: header name: x-cf-signature description: Signature to be sent if IP is not whitelisted. required: false schema: type: string schemas: Beneficiary: title: Create Beneficiary success response description: Contains the information of the created beneficiary type: object properties: beneficiary_id: example: JOHN18011343 type: string description: It displays the unique Id you created to identify the beneficiary. beneficiary_name: example: John Doe type: string description: It displays the name of the beneficiary. beneficiary_instrument_details: type: object description: It displays the payment instrument details of the beneficiary. properties: bank_account_number: example: '00111122233' type: string description: It displays the bank account of the beneficiary. bank_ifsc: example: HDFC0000001 type: string description: >- It displays the IFSC information of the beneficiary's bank account. vpa: example: test@upi type: string description: It displays the UPI VPA information of the beneficiary. beneficiary_contact_details: type: object description: It displays the contact details of the beneficiary. properties: beneficiary_email: example: johndoe1@cashfree.com type: string description: It displays the email address of the beneficiary. beneficiary_phone: example: '9876543210' type: string description: >- It displays the phone number of the beneficiary without the country code. beneficiary_country_code: example: '+91' type: string description: It displays the country code of the beneficiary's phone number. beneficiary_address: example: 177A Bleecker Street type: string description: It displays the address of the beneficiary. beneficiary_city: example: New York City type: string description: >- It displays the name of the city as present in the beneficiary's address. beneficiary_state: example: New York type: string description: >- It displays the name of the state as present in the beneficiary's address. beneficiary_postal_code: example: '560001' type: string description: >- It displays the PIN code as present in the beneficiary's address. beneficiary_status: example: VERIFIED type: string enum: - VERIFIED - INVALID - INITIATED - CANCELLED - FAILED - DELETED description: >- It displays the current status of the beneficiary. Possible values are as follows - `VERIFIED`: Beneficiary is verified and is available for payouts - `INVALID`: Beneficiary is invalid - `INITIATED`: Beneficiary verification initiated - `CANCELLED`: Beneficiary verification cancelled - `FAILED`: Failed to verify beneficiary - `DELETED`: Beneficiary is deleted added_on: example: '2023-11-22T12:38:22Z' type: string description: It displays the time of the addition of the beneficiary in UTC. ErrorV2: title: Error description: Error Response for non-2XX cases type: object properties: type: type: string description: Type of the error received code: type: string description: Code of the error received message: type: string description: Detailed message explaining the response examples: get_beneficiary_success_v2: description: Example values for Get Beneficiary V2 success response value: beneficiary_id: JOHN18011343 beneficiary_name: John Doe beneficiary_instrument_details: bank_account_number: '1223334444' bank_ifsc: HDFC0000001 vpa: test@upi beneficiary_contact_details: beneficiary_email: sample@cashfree.com beneficiary_phone: '9876543210' beneficiary_country_code: '+91' beneficiary_address: 177A Bleecker Street beneficiary_city: New York City beneficiary_state: New York beneficiary_postal_code: '560011' beneficiary_status: VERIFIED added_on: '2023-12-04T15:50:00Z' all_three_params_given: summary: All three parameters provided description: All three parameters are provided to get beneficiary details value: type: invalid_request_error code: too_many_parameters_in_request message: >- Please provide either bank_account_number and bank_ifsc together or beneficiary_id alone. Do not include all three parameters in the request bank_account_given_ifsc_not_given_in_get_v2: description: Bank account number is provided but ifsc is not provided summary: Missing IFSC but bank account number is provided value: type: invalid_request_error code: bank_ifsc_missing message: >- bank_ifsc : should be provided with the request if bank_account_number is provided bank_ifsc_given_account_not_given_in_get_v2: summary: Missing bank account number but IFSC is provided description: Bank ifsc is provided but bank account number is not provided value: type: invalid_request_error code: bank_account_number_missing message: >- bank_account_number: should be provided with the request if bank_ifsc is provided no_bene_identifiers_provided_v2: description: No details are provided with the request to identifiy the beneficiary summary: Details are not provided with the request to identifiy the beneficiary value: type: invalid_request_error code: beneficiary_identifiers_missing message: >- beneficiary_identifiers : Either beneficiary_id or the combination of bank_account_number and bank_ifsc has to be provided with the request bene_id_too_large_v2: description: Length of beneficiary_id is more than maximum allowed summary: Length of beneficiary_id exceeded the maximum limit value: type: invalid_request_error code: beneficiary_id_length_exceeded message: >- beneficiary_id : should not be more than 50 characters long. value received: kl12b3rkh1bv234lkbr3jl24tbrlk234bkt234t134kbr1hk34jr invalid_bene_id_due_unacceptable_characters: description: Beneficiary ID contains characters that are not allowed summary: Beneficiary ID contains characters that are not allowed value: type: invalid_request_error code: beneficiary_id_invalid message: >- beneficiary_id : should contain only letters, numbers, hyphen, underscore, pipe, and dot. Value received: .\qewqefwqev bank_account_number_too_large: description: Bank account number provided is too large summary: Provided bank account number is too large value: type: invalid_request_error code: bank_account_number_length_exceeded message: >- bank_account_number : should not be more than 25 characters long. value received: 235142352346523462456345263452345 bank_account_number_too_short: description: Bank account number provided is too short summary: Provided bank account number is too short value: type: invalid_request_error code: bank_account_number_length_short message: >- bank_account_number : should not be less than 4 characters long. value received: 12 bank_account_invalid: description: Bank account number contains characters that are not allowed summary: Provided bank account number contains characters that are not allowed value: type: invalid_request_error code: bank_account_number_invalid message: 'bank_account_number : should be alphanumeric. value received: 123@' invalid_ifsc: description: Invalid value given for IFSC summary: Invalid IFSC value: type: invalid_request_error code: bank_ifsc_invalid message: 'bank_ifsc : please provide a valid IFSC. value received: SBIN00708410' APIsDisabledExampleV2: summary: APIs disabled description: Forbidden request. APIs are disabled value: type: invalid_request_error code: apis_not_enabled message: >- APIs not enabled. Please fill out the [Support Form](https://merchant.cashfree.com/merchants/landing?env=prod&raise_issue=1) beneficiary_id_not_found_v2: summary: Beneficiary with given beneficiary_id not found description: Beneficiary with the given beneficiary_id does not exist value: type: invalid_request_error code: beneficiary_not_found message: Beneficiary does not exist beneficiary_with_account_does_not_exist_v2: summary: Beneficiary with given account details not found description: Beneficiary with given account details does not exist value: type: invalid_request_error code: beneficiary_not_found message: >- Beneficiary with the given bank_account_number and bank_ifsc does not exist bank_account_exists_with_a_different_ifsc_v2: summary: >- Beneficiary exists with the provided bank account number but a different IFSC description: >- beneficiary exists with given beneficiary_bank_account_number but beneficiary_ifsc is different value: type: invalid_request_error code: beneficiary_not_found message: >- Beneficiary exists with the given bank_account_number but a different bank_ifsc internal_server_error_v2: summary: Internal server error description: Error at Cashfree Payments' server value: type: api_error code: internal_server_error message: Error at cashfree's server headers: x-request-id: schema: type: string example: some-req-id description: >- It displays the request ID for the API request. Is blank or null if no `x-request-id` is sent during the request securitySchemes: XClientID: type: apiKey in: header name: x-client-id description: >- Client app ID. You can find your app ID in the [Merchant Dashboard](https://merchant.cashfree.com/payouts/developers/api-keys). XClientSecret: type: apiKey in: header name: x-client-secret description: >- Client secret key. You can find your secret key in the [Merchant Dashboard]((https://merchant.cashfree.com/payouts/developers/api-keys). ````