# Get a payee

Payees (previously "beneficiaries"). Retrieves a payee identified by the id path parameter.

Endpoint: GET /beneficiaries/{id}
Version: v3
Security: auth_token, api-key

## Security:

  - `auth_token` (unknown)
    http bearer JWT

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

## Path parameters:

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

## Response 200:

  - `200` (unknown)
    Success

## Response 200 fields (application/json):

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

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

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

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

  - `beneficiaryInformation.businessName` (string, required)
    The business beneficiary name. The allowed length and pattern is dependent on the beneficiary details type:
`InstrumentDetailsBeneficiary` or `BankAccountDetailsBeneficiary` with `IBANDetails`: >= `1` character and <= `150` characters
`BankAccountDetailsBeneficiary` with `FasterPaymentsBankDetailsOrBACSBankDetails`: >= `1` character and <= `140` characters with a pattern of `^[a-zA-Z0-9\/\-?:().,’+\s#=!"%&*<>;\{@\r\n]*$`
(please note that the `’` symbol is the unicode value U+2019 (right single quotation mark) and not the unicode value U+0027 (apostrophe))

  - `beneficiaryInformation.nationality` (string)
    The nationality of the consumer. Must be a valid ISO 3166-1 alpha-2 country code (e.g., 'GB', 'FR').

  - `beneficiaryInformation.dateOfBirth` (string)
    The date of birth of the consumer. Must be a valid date in ISO 8601 format (YYYY-MM-DD) and should not be a future date.

  - `beneficiaryInformation.fullName` (string, required)
    The person beneficiary name. The allowed length and pattern is dependent on the beneficiary details type:
`InstrumentDetailsBeneficiary` or `BankAccountDetailsBeneficiary` with `IBANDetails`: >= `1` character and <= `150` characters
`BankAccountDetailsBeneficiary` with `FasterPaymentsBankDetailsOrBACSBankDetails`: >= `1` character and <= `140` characters with a pattern of `^[a-zA-Z0-9\/\-?:().,’+\s#=!"%&*<>;\{@\r\n]*$`
(please note that the `’` symbol is the unicode value U+2019 (right single quotation mark) and not the unicode value U+0027 (apostrophe))

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

  - `beneficiaryDetails.instrument` (object, required)

  - `beneficiaryDetails.instrument.id` (string, required)

  - `beneficiaryDetails.instrument.type` (string, required)
    Enum: "managed_cards", "managed_accounts"

  - `beneficiaryDetails.address` (string)
    **Deprecated** — use `postalAddress` instead. This field is passed to the
provider as unstructured address lines and cannot carry a town name or country
code, which some payment schemes require.
The beneficiary's address.

  - `beneficiaryDetails.postalAddress` (object)
    The beneficiary's address in structured form.

  - `beneficiaryDetails.postalAddress.line1` (string)
    The primary line of the beneficiary's address — the street name, building
number and postal code.

  - `beneficiaryDetails.postalAddress.line2` (string)
    Additional address information — the building name, floor, room, department
or other location details.

  - `beneficiaryDetails.postalAddress.townName` (string)
    The town or city of the beneficiary's address. It cannot be derived from the
address lines, so send it here rather than inside `line1` or `line2`.

  - `beneficiaryDetails.postalAddress.countryCode` (string)
    The country of the beneficiary's address in ISO 3166 alpha-2 format. It cannot
be derived from the address lines, so send it here rather than inside `line1`
or `line2`.

  - `beneficiaryDetails.bankName` (string)
    The beneficiary's bank name.

  - `beneficiaryDetails.bankAddress` (string)
    The beneficiary's bank address.

  - `beneficiaryDetails.bankCountry` (string)
    The beneficiary's bank country in ISO 3166 alpha-2 format.

  - `beneficiaryDetails.bankAccountDetails` (any, required)
    Details of the beneficiary bank account, depending on the type of transfer chosen.

  - `beneficiaryDetails.bankAccountDetails.iban` (string, required)
    International Bank Account Number, required for wire transfer over SEPA or RIX

  - `beneficiaryDetails.bankAccountDetails.bankIdentifierCode` (string)
    BIC, for wire transfer over SEPA or RIX

  - `beneficiaryDetails.bankAccountDetails.accountNumber` (string, required)
    Account number, required for wire transfer over Faster Payments.

  - `beneficiaryDetails.bankAccountDetails.sortCode` (string, required)
    Sort code, required for wire transfer over Faster Payments.

  - `beneficiaryDetails.bankAccountDetails.secondaryReference` (string)

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

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

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

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

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

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

## 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 404:

  - `404` (unknown)
    Not found - The requested resource couldn't be found.

## Response 404 fields (application/json):

  - `code` (string)

  - `message` (string)

## Response 404 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)