> ## 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 History
> Use this API to fetch the transaction history for a particular beneficiary and for a desired period of time.
This API will be retired soon. Please plan to migrate to the latest version, [Beneficiary V2](/api-reference/payouts/v2/beneficiary-v2/get-beneficiary-v2).
Please use this Authorization token in headers to call any payout API (Refresh this page if the token is expired)
| Sub code | Status | Message | Solution |
| :------- | :------ | :------------------------------------------------ | :------------------------------------------------------- |
| 200 | SUCCESS | Data retrieved successfully. | - |
| 403 | ERROR | Token is invalid. | Validate the generated token. |
| 405 | ERROR | Invalid request URL or HTTP method. | |
| 422 | ERROR | Requested date range is invalid. | Enter a valid date rage. |
| 422 | ERROR | Page value should be minimum 1. | Enter the page value as 1. |
| 422 | ERROR | Please provide a valid Beneficiary Id. | Enter a valid beneficiary ID. |
| 422 | ERROR | startDate should be of format yyyy-mm-dd | Enter the date range in the format: yyyy-mm-dd. |
| 422 | ERROR | endDate should be of format yyyy-mm-dd | Enter the date range in the format: yyyy-mm-dd. |
| 422 | ERROR | startDate should be less than or equal to EndDate | Enter a startDate value lesser than or equal to endDate. |
| 422 | ERROR | perPage should be at max 25 | Enter the perPage value lesser than or equal to 25. |
| 429 | ERROR | Too many requests. | |
| 520 | ERROR | Unknown error occurred. | Try again after some time. |
## OpenAPI
````yaml get /payout/v1/beneHistory
openapi: 3.0.0
info:
title: Payouts
version: 3.0.0
servers:
- url: https://payout-api.cashfree.com
description: Production
- url: https://payout-gamma.cashfree.com
description: Sandbox
security:
- {}
paths:
/payout/v1/beneHistory:
get:
summary: Get Beneficiary History
description: >-
Use this API to fetch the transaction history for a particular
beneficiary and for a desired period of time.
operationId: getbeneficiary-history
parameters:
- name: beneId
in: query
description: >-
The beneficiary id that you have created. Alphanumeric characters
accepted.
required: true
style: form
explode: true
schema:
type: string
- name: startDate
in: query
description: Start date for the desired period. Format - yyyy-mm-dd
required: false
style: form
explode: true
schema:
type: string
- name: endDate
in: query
description: >-
End date for the desired period. Format - yyyy-mm-dd. If start date
is provided, end date is a mandatory. End date has to be a day less
than current date.
required: false
style: form
explode: true
schema:
type: string
- name: perPage
in: query
description: >-
Number of transactions to be displayed on the page. Maximum = 25.
Default value set is 25.
required: false
style: form
explode: true
schema:
type: number
format: float
- name: page
in: query
description: >-
Will show the latest transfers on the first page. Minimum = 1.
Default value set is 1.
required: false
style: form
explode: true
schema:
type: number
format: float
- name: Authorization
in: header
description: Bearer auth token
required: true
style: simple
explode: false
schema:
type: string
- name: Content-Type
in: header
description: application/json
required: true
style: simple
explode: false
schema:
type: string
responses:
'200':
description: '200'
content:
application/json:
schema:
$ref: '#/components/schemas/inline_response_200_7'
examples:
Result:
value:
status: SUCCESS
subCode: '200'
message: Data retrieved successfully
data:
transfers:
- transferDate: '2020-06-16T00:00:00.000Z'
amount: '1'
mode: IMPS
beneId: John Doe
status: SUCCESS
- transferDate: '2020-05-28T00:00:00.000Z'
amount: '1'
mode: NEFT
beneId: John Doe
status: SUCCESS
- transferDate: '2020-05-15T00:00:00.000Z'
amount: '1.1'
mode: IMPS
beneId: John Doe
status: SUCCESS
- transferDate: '2020-05-15T00:00:00.000Z'
amount: '1.1'
mode: IMPS
beneId: John Doe
status: SUCCESS
- transferDate: '2020-05-15T00:00:00.000Z'
amount: '1'
mode: IMPS
beneId: John Doe
status: SUCCESS
'403':
description: '403'
content:
application/json:
schema:
$ref: '#/components/schemas/inline_response_403'
'422':
description: '422'
content:
application/json:
schema:
$ref: '#/components/schemas/inline_response_422_3'
deprecated: false
security: []
components:
schemas:
inline_response_200_7:
type: object
properties:
status:
type: string
example: SUCCESS
subCode:
type: string
example: '200'
message:
type: string
example: Data retrieved successfully
data:
$ref: '#/components/schemas/inline_response_200_7_data'
inline_response_403:
type: object
properties:
status:
type: string
example: ERROR
subCode:
type: string
example: '403'
message:
type: string
example: >-
APIs not enabled. Please fill out the [Support
Form](https://merchant.cashfree.com/merchants/landing?env=prod&raise_issue=1)
inline_response_422_3:
type: object
properties:
status:
type: string
example: ERROR
subCode:
type: string
example: '422'
message:
type: string
example: Please provide a valid beneId
inline_response_200_7_data:
type: object
properties:
transfers:
type: array
items:
$ref: '#/components/schemas/inline_response_200_7_data_transfers'
inline_response_200_7_data_transfers:
type: object
properties:
transferDate:
type: string
example: '2020-06-16T00:00:00.000Z'
amount:
type: string
example: '1'
mode:
type: string
example: IMPS
beneId:
type: string
example: John Doe
status:
type: string
example: SUCCESS
````