> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ebury.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Get beneficiary metadata

Describes the fields required to provision a valid beneficiary for a given country/currency combination:

* All supported countries are described by this API;
* For each supported country, any currency that has *specific* requirements is defined in the currencies list. If there are no specific requirements the value `default` should be used.
* The response of this endpoint is in line with the SWIFT ISO20022 standards. Please note, the mandatory fields and business rules around beneficiary address defined via this endpoint, does not apply to Ebury Mass Payments customers. Should you have any doubts, please reach out to us.


## OpenAPI

````yaml /openapi.json get /metadata/beneficiary
openapi: 3.0.0
info:
  description: |
    Ebury API allows customers:
      to retrieve accounts, balances, beneficiaries, and transactions;
      to get buy/sell estimates and quotes, book trades and retrieve trade history;
      to allocate payments to a trade and beneficiary, and to submit payments in bulk;
      to download documents such as trade receipt, payment instruction and payment receipt;
      to manage the authorised persons on their account.
    The Metadata API allows applications to clarify some parts of the Ebury API
      that are impractical to express schematically.
  termsOfService: https://docs.ebury.io/#terms-of-use
  title: Ebury API
  version: '0.1'
servers:
  - url: https://{environment}.ebury.io
    variables:
      environment:
        default: api
        enum:
          - api
          - sandbox
security:
  - api_key: []
paths:
  /metadata/beneficiary:
    get:
      tags:
        - Metadata
      summary: Get beneficiary metadata
      description: Describe a new beneficiary.
      responses:
        '200':
          $ref: '#/components/responses/BeneficiaryMetadata'
        '400':
          $ref: '#/components/responses/ValidationError'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '502':
          $ref: '#/components/responses/IntegrationError'
components:
  responses:
    BeneficiaryMetadata:
      description: Beneficiary metadata.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/BeneficiaryMetadata'
    ValidationError:
      description: >-
        Formatting, parameter or schema validation error. See error message for
        further details.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorMessage'
    Unauthorized:
      description: Access denied due to authentication failure.
    Forbidden:
      description: >-
        Could not complete action due to data constraints. Refer to error
        message for additional details.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorMessage'
    IntegrationError:
      description: Internal integration error.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorMessage'
  schemas:
    BeneficiaryMetadata:
      items:
        $ref: '#/components/schemas/BeneficiaryMetadataItem'
      type: array
    ErrorMessage:
      description: An error message.
      properties:
        code:
          type: string
          description: The code for the error.
        details:
          description: Error details
          type: string
        message:
          type: string
          description: A short description of the cause of the error.
      required:
        - code
        - message
        - details
      type: object
    BeneficiaryMetadataItem:
      properties:
        country:
          description: The country, expressed as an ISO 3166-1 alpha-2 value.
          type: string
        currencies:
          description: The requirements for a given currency for this country.
          items:
            properties:
              currency:
                description: >-
                  The currency code, expressed as an ISO 4217 alpha code. The
                  value 'default' means the requirements for any currency not
                  otherwise listed for this country.
                type: string
              mandatory_data:
                description: >-
                  The data that must provided to provision a beneficiary for the
                  country and currency, provided in groups i.e. one of the
                  groups must be matched to provision a beneficiary for the
                  country/currency combination.
                items:
                  description: >-
                    A list of field names. Additional context available where |
                    then a value is included in the definition e.g.
                    bank_identifier|Sort Code.
                  items:
                    type: string
                  type: array
                type: array
              optional_data:
                description: >-
                  Data that can optionally be included to provision a
                  beneficiary. Additional context available where  then a value
                  is included in the definition e.g. bank_identifierSort Code.
                items:
                  type: string
                type: array
            type: object
          type: array
        reason_required:
          description: >-
            Whether or not a reason for trade for the country needs to be
            supplied.
          type: boolean
      type: object
  securitySchemes:
    api_key:
      description: An API Key.
      in: header
      name: x-api-key
      type: apiKey

````