# Get all beneficiaries

Retrieves the beneficiaries that match the query parameters.

Endpoint: GET /beneficiaries
Version: 3.63.5
Security: auth_token, 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.

  - `batchId` (array)
    Search by the beneficiary batch id.

  - `group` (array)
    Search by the beneficiary group.

## Response 200 fields (application/json):

  - `beneficiaries` (array)

  - `beneficiaries.trustLevel` (string, required)
    The value that determines whether a Beneficiary is trusted or not.
    Enum: "TRUSTED"

  - `beneficiaries.externalRefs` (array)
    The id of the entity as it is represented on the caller system.

  - `beneficiaries.group` (string)
    A custom field that can be used to categorise a beneficiary for easier searching and filtering.

  - `beneficiaries.beneficiaryInformation` (any, required)
    The object representing the beneficiary details.

  - `beneficiaries.beneficiaryDetails` (any, required)
    The object representing the beneficiary instrument details.

  - `beneficiaries.id` (string, required)
    The unique identifier of a Beneficiary.

  - `beneficiaries.relatedOperationBatches` (array, required)
    The object representing the list of batch IDs and the operations that occurred for each batch.

  - `beneficiaries.relatedOperationBatches.batchId` (string, required)
    The unique identifier of a Beneficiary.

  - `beneficiaries.relatedOperationBatches.operation` (string, required)
    Describes the operation that has occurred on a beneficiary batch.
    Enum: "CREATE", "REMOVE"

  - `beneficiaries.state` (string, required)
    Enum: "INITIALISED", "INVALID", "PENDING_CHALLENGE", "CHALLENGE_FAILED", "ACTIVE", "REMOVED"

  - `beneficiaries.validationFailure` (string)
    Enum: "INSTRUMENT_DETAILS_NOT_FOUND", "BENEFICIARY_DETAILS_ALREADY_EXIST", "BENEFICIARY_BELONGS_TO_SAME_IDENTITY"

  - `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 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 default fields (application/json):

  - `code` (string)

  - `message` (string)


## Response 401 fields

## Response 403 fields

## Response 429 fields

## Response 500 fields

## Response 503 fields