# Get all payee batches

Payees (previously "beneficiaries"). Retrieves all payee batches matching the query parameters and that belong to the logged-in identity.

Endpoint: GET /beneficiaries/batch
Version: v3
Security: auth_token, api-key

## Security:

  - `auth_token` (unknown)
    http bearer JWT

  - `api-key` (unknown)
    apiKey in header api-key

## Query parameters:

  - `offset` (integer)
    The offset value for paging, indicating the initial item number to be returned from the data set satisfying the given criteria. Leave out to fetch the first page of results.

  - `limit` (integer)
    The limit of the results for paging, starting at the offset. Limit is always capped at 100.

  - `state` (array)

  - `operation` (array)

  - `tag` (array)
    Filter by the payee batch tag. The exact tag must be provided, as wildcards are not supported. Leave out to fetch all entries.

## Response 200:

  - `200` (unknown)
    Success

## Response 200 fields (application/json):

  - `batches` (array)

  - `batches.operationBatchId` (object, required)

  - `batches.operationBatchId.batchId` (string, required)
    The unique identifier of a Beneficiary.

  - `batches.operationBatchId.operation` (string, required)
    Enum: "CREATE", "REMOVE"

  - `batches.tag` (string)
    The tag field is a custom field that can be used to search and filter.

  - `batches.state` (string, required)
    Enum: "INITIALISED", "FAILED", "PENDING_CHALLENGE", "CHALLENGE_FAILED", "CHALLENGE_COMPLETED", "COMPLETED"

  - `count` (integer)
    The total number of records (excluding the paging limit).

  - `responseCount` (integer)
    The total number of records returned in this response (always capped at 100).

## Response 200 headers (application/json):

  - `request-ref` (string, required)
    A request identifier. Providing this reference when contacting our support team will help us investigate your query.

## Response 400:

  - `400` (unknown)
    Bad Request Error - Your request is invalid.

## Response 400 fields (application/json):

  - `message` (string)
    When present helps to identify and fix the problem.

  - `syntaxErrors` (object)
    Is returned as part of an HTTP error response whenever a syntax error is detected. A list of the fields together with their syntax error will be provided.

  - `syntaxErrors.invalidFields` (array)

  - `syntaxErrors.invalidFields.params` (array)

  - `syntaxErrors.invalidFields.fieldName` (string)

  - `syntaxErrors.invalidFields.error` (string)
    Enum: "REQUIRED", "HAS_TEXT", "REQUIRES", "SIZE", "RANGE", "IN", "NOT_IN", "REGEX", "EXACTLY", "AT_LEAST", "AT_MOST", "ALL_OR_NONE"

## Response 400 headers (application/json):

  - `request-ref` (string, required)
    A request identifier. Providing this reference when contacting our support team will help us investigate your query.

## Response 401:

  - `401` (unknown)
    Unauthorized - Your credentials or access token are invalid.

## Response 401 headers:

  - `request-ref` (string, required)
    A request identifier. Providing this reference when contacting our support team will help us investigate your query.

## Response 403:

  - `403` (unknown)
    Forbidden - Access to the requested resource or action is forbidden.

## Response 403 fields (application/json):

  - `errorCode` (string)
    Enum: "INSUFFICIENT_PERMISSIONS"

## Response 403 headers (application/json):

  - `request-ref` (string, required)
    A request identifier. Providing this reference when contacting our support team will help us investigate your query.

## Response 429:

  - `429` (unknown)
    Too many requests.

## Response 429 headers:

  - `request-ref` (string, required)
    A request identifier. Providing this reference when contacting our support team will help us investigate your query.

  - `x-ratelimit-limit` (string, required)
    Example: `20, 10;w=60, 20;w=3600, 200;w=86400`
The first number (20) is the limit that has been exceeded.
The remaining numbers are the limits that are in force, with 'w' meaning 'window in seconds'. In this example `20;w=3600` was exceeded. 20 calls in 3600secs (1hr)

  - `x-ratelimit-reset` (integer, required)
    The number of seconds until the window is reset.

## Response 500:

  - `500` (unknown)
    Internal Server Error - There is a problem with the server. Please try again later.

## Response 500 headers:

  - `request-ref` (string, required)
    A request identifier. Providing this reference when contacting our support team will help us investigate your query.

## Response 503:

  - `503` (unknown)
    Service Unavailable - The requested service is temporarily unavailable. Please try again later.

## Response 503 headers:

  - `request-ref` (string, required)
    A request identifier. Providing this reference when contacting our support team will help us investigate your query.

## Response default:

  - `default` (unknown)
    Error

## Response default fields (application/json):

  - `code` (string)

  - `message` (string)