Currencycloud Beneficiaries API

openapi: 3.2.0
info:
  description: The Currencycloud API is a robust, predictable, easy-to-use API for converting money between currencies and making payments around the world. Dynamically register sub-accounts to provide white labeled money transfer services to your own customers.
  version: 2.43.0
  title: Currencycloud Beneficiaries API
  termsOfService: https://www.currencycloud.com/terms-and-conditions/
  contact:
    name: support
    email: support@currencycloud.com
servers:
- url: https://devapi.currencycloud.com/v2
tags:
- name: Beneficiaries
  description: Create, search and manage the list of individuals or companies that you send payments to.
paths:
  /beneficiaries/find:
    post:
      tags:
      - Beneficiaries
      x-api-group: pay
      summary: Find Beneficiaries
      description: Returns beneficiaries attached to the account or any sub-account owned by the authenticated user.
      operationId: FindBeneficiariesPost
      parameters:
      - name: X-Auth-Token
        in: header
        required: true
        description: Authentication token
        schema:
          type: string
          minLength: 32
      responses:
        '200':
          description: Success.
          headers:
            X-Request-Id:
              description: A unique reference for the request.
              schema:
                type: string
          content:
            application/json:
              schema:
                type: object
                properties:
                  beneficiaries:
                    type: array
                    items:
                      $ref: '#/components/schemas/Beneficiary'
                  pagination:
                    $ref: '#/components/schemas/Pagination'
        '400':
          description: Client error.
          x-errors:
          - code: bank_account_holder_name_is_too_short
            category: bank_account_holder_name
            message: bank_account_holder_name can not be shorter than 1 character(s)
            params: '{ "minlength" => 1 }'
          - code: bank_account_holder_name_is_too_long
            category: bank_account_holder_name
            message: bank_account_holder_name can not be longer than 255 character(s)
            params: '{ "maxlength" => 255 }'
          - code: beneficiary_country_is_in_invalid_format
            category: beneficiary_country
            message: beneficiary_country is in invalid format
            params: ''
          - code: currency_is_in_invalid_format
            category: currency
            message: currency is in invalid format
            params: ''
          - code: bank_name_is_too_short
            category: bank_name
            message: bank_name can not be shorter than 1 character(s)
            params: '{ "minlength" => 1 }'
          - code: bank_account_type_not_in_range
            category: bank_account_type
            message: 'bank_account_type should be in range: checking, savings'
            params: '{ "range" => "checking, savings" }'
          - code: account_number_is_too_short
            category: account_number
            message: account_number can not be shorter than 1 character(s)
            params: '{ "minlength" => 1 }'
          - code: account_number_is_too_long
            category: account_number
            message: account_number can not be longer than 50 character(s)
            params: '{ "maxlength" => 50 }'
          - code: incorrect_mapping
            category: base
            message: Following parameters must have same keys
            params: '{ "parameters" => "routing_code_value,routing_code_type" }'
          - code: routing_code_type_is_too_short
            category: routing_code_type
            message: routing_code_type can not be shorter than 1 character(s)
            params: '{ "minlength" => 1, "indices" => ["0", "1"] }'
          - code: routing_code_type_is_too_long
            category: routing_code_type
            message: routing_code_type can not be longer than 50 character(s)
            params: '{ "maxlength" => 50, "indices" => ["0", "1"] }'
          - code: routing_code_type_not_included_in_list
            category: routing_code_type
            message: One or more of routing_code_type items are not included in list
            params: '{ "list" => "sort_code,bsb_code,institution_no,bank_code,branch_code,aba,clabe }'
          - code: beneficiary_date_of_birth_type_is_wrong
            category: beneficiary_date_of_birth
            message: beneficiary_date_of_birth should be of date type
            params: '{ "type" => "date" }'
          - code: beneficiary_date_of_birth_is_earlier
            category: beneficiary_date_of_birth
            message: beneficiary_date_of_birth should be later than 1900-01-01
            params: '{ "min_date" => "1900-01-01" }'
          - code: beneficiary_date_of_birth_is_after
            category: beneficiary_date_of_birth
            message: beneficiary_date_of_birth should be earlier than todays date
            params: '{ "max_date" => "Todays Date" }'
          - code: routing_code_value_is_too_short
            category: routing_code_value
            message: routing_code_value can not be shorter than 1 character(s)
            params: '{ "minlength" => 1, "indices" => ["0", "1"] }'
          - code: routing_code_value_is_too_long
            category: routing_code_value
            message: routing_code_value can not be longer than 50 character(s)
            params: '{ "maxlength" => 50, "indices" => ["0", "1"] }'
          - code: routing_code_value_type_is_wrong
            category: routing_code_value
            message: routing_code_value should be of hash type
            params: '{ "type" => "hash" }'
          - code: bic_swift_is_in_invalid_format
            category: bic_swift
            message: bic_swift is in invalid format
            params: ''
          - code: iban_is_too_long
            category: iban
            message: iban can not be longer than 34 character(s)
            params: '{ "maxlength" => 34 }'
          - code: iban_is_too_short
            category: iban
            message: iban can not be shorter than 1 character(s)
            params: '{ "minlength" => 1 }'
          - code: iban_is_in_invalid_format
            category: iban
            message: iban is in invalid format
            params: ''
          - code: default_beneficiary_type_is_wrong
            category: default_beneficiary
            message: default_beneficiary should be of boolean type
            params: '{ "type" => "boolean" }'
          - code: name_is_too_short
            category: name
            message: name can not be shorter than 1 character(s)
            params: '{ "minlength" => 1 }'
          - code: name_is_too_long
            category: name
            message: name can not be longer than 100 character(s)
            params: '{ "maxlength" => 100 }'
          - code: order_asc_desc_not_in_range
            category: order_asc_desc
            message: 'order_asc_desc should be in range: asc, desc'
            params: '{ "range" => "asc, desc" }'
          - code: order_not_in_range
            category: order
            message: 'order should be in range: bank_account_holder_name, beneficiary_country, currency, account_number, bic_swift, iban, default_beneficiary, bank_address, name, bank_account_type, beneficiary_entity_type, beneficiary_city, beneficiary_address, beneficiary_company_name, beneficiary_first_name, beneficiary_last_name, beneficiary_state_or_province, beneficiary_postcode, created_at, updated_at'
            params: '{ "range" => "bank_account_holder_name, beneficiary_country, currency, account_number, bic_swift, iban, default_beneficiary, bank_address, name, bank_account_type, beneficiary_entity_type, beneficiary_city, beneficiary_address, beneficiary_company_name, beneficiary_first_name, beneficiary_last_name, beneficiary_state_or_province, beneficiary_postcode, created_at, updated_at" }'
          - code: on_behalf_of_self
            category: on_behalf_of
            message: You cannot act on behalf of your own Contact
            params: ''
          - code: contact_not_found
            category: on_behalf_of
            message: Contact was not found for this id
            params: ''
          - code: on_behalf_of_is_not_valid_uuid
            category: on_behalf_of
            message: on_behalf_of should be in UUID format
            params: ''
          - code: beneficiary_external_reference_is_too_short
            category: beneficiary_external_reference
            message: beneficiary_external_reference can not be shorter than 1 character(s)
            params: '{ "minlength" => 1 }'
          - code: beneficiary_external_reference_is_too_long
            category: beneficiary_external_reference
            message: beneficiary_external_reference can not be longer than 255 character(s)
            params: '{ "maxlength" => 255 }'
          - code: cope_not_in_range
            category: scope
            message: 'scope should be in range: own, all, clients'
            params: '{ "range" => "own, all, clients" }'
          - code: beneficiary_entity_type_not_in_range
            category: beneficiary_entity_type
            message: 'beneficiary_entity_type should be in range: individual, company'
            params: '{ "range" => "individual, company" }'
          - code: beneficiary_company_name_is_too_short
            category: beneficiary_company_name
            message: beneficiary_company_name can not be shorter than 1 character(s)
            params: '{ "minlength" => 1 }'
          - code: beneficiary_company_name_is_too_long
            category: beneficiary_company_name
            message: beneficiary_company_name can not be longer than 255 character(s)
            params: '{ "maxlength" => 255 }'
          - code: beneficiary_first_name_is_too_short
            category: beneficiary_first_name
            message: beneficiary_first_name can not be shorter than 1 character(s)
            params: '{ "minlength" => 1 }'
          - code: beneficiary_first_name_is_too_long
            category: beneficiary_first_name
            message: beneficiary_first_name can not be longer than 255 character(s)
            params: '{ "maxlength" => 255 }'
          - code: beneficiary_last_name_is_too_short
            category: beneficiary_last_name
            message: beneficiary_last_name can not be shorter than 1 character(s)
            params: '{ "minlength" => 1 }'
          - code: beneficiary_last_name_is_too_long
            category: beneficiary_last_name
            message: beneficiary_last_name can not be longer than 255 character(s)
            params: '{ "maxlength" => 255 }'
          - code: beneficiary_city_is_too_short
            category: beneficiary_city
            message: beneficiary_city can not be shorter than 1 character(s)
            params: '{ "minlength" => 1 }'
          - code: beneficiary_city_is_too_long
            category: beneficiary_city
            message: beneficiary_city can not be longer than 255 character(s)
            params: '{ "maxlength" => 255 }'
          - code: beneficiary_postcode_is_too_short
            category: beneficiary_postcode
            message: beneficiary_postcode can not be shorter than 1 character(s)
            params: '{ "minlength" => 1 }'
          - code: beneficiary_postcode_is_too_long
            category: beneficiary_postcode
            message: beneficiary_postcode can not be longer than 255 character(s)
            params: '{ "maxlength" => 255 }'
          - code: beneficiary_state_or_province_is_too_short
            category: beneficiary_state_or_province
            message: beneficiary_state_or_province can not be shorter than 1 character(s)
            params: '{ "minlength" => 1 }'
          - code: beneficiary_state_or_province_is_too_long
            category: beneficiary_state_or_province
            message: beneficiary_state_or_province can not be longer than 255 character(s)
            params: '{ "maxlength" => 255 }'
          - code: page_type_is_wrong
            category: page
            message: page should be of integer type
            params: '{ "type" => "integer" }'
          - code: page_is_too_small
            category: page
            message: page can not be smaller than 1
            params: '{ "minvalue" => 1 }'
          - code: per_page_type_is_wrong
            category: per_page
            message: per_page should be of integer type
            params: '{ "type" => "integer" }'
          - code: per_page_is_too_small
            category: per_page
            message: per_page can not be smaller than 1
            params: '{ "minvalue" => 1 }'
          - code: order_asc_desc_not_in_range
            category: order_asc_desc
            message: 'order_asc_desc should be in range: asc, desc'
            params: '{ "range" => "asc, desc" }'
          headers:
            X-Request-Id:
              description: A unique reference for the request.
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FindBeneficiariesError'
        '401':
          description: Unauthorized.
          x-errors:
          - code: invalid_supplied_credentials
            category: username
            message: Authentication failed with the supplied credentials
            params: ''
          headers:
            X-Request-Id:
              description: A unique reference for the request.
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedError'
        '404':
          description: Resource not found.
          headers:
            X-Request-Id:
              description: A unique reference for the request.
              schema:
                type: string
        '429':
          description: Too many requests.
          x-errors:
          - code: too_many_requests
            category: base
            message: Too many requests have been made to the api. Please refer to the Developer Center for more information
            params: ''
          headers:
            X-Request-Id:
              description: A unique reference for the request.
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RateLimitError'
        '500':
          description: Internal server error
          x-errors:
          - code: internal_server_error
            category: base
            message: Internal server error
            params: ''
          headers:
            X-Request-Id:
              description: A unique reference for the request.
              schema:
                type: string
        '503':
          description: Service is temporary unavailable
          x-errors:
          - code: service_unavailable
            category: base
            message: Service is temporarily unavailable
            params: ''
          headers:
            X-Request-Id:
              description: A unique reference for the request.
              schema:
                type: string
        default:
          description: Unexpected error.
          headers:
            X-Request-Id:
              description: A unique reference for the request.
              schema:
                type: string
      requestBody:
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                on_behalf_of:
                  type: string
                  format: uuid
                  description: A contact UUID for the sub-account you're acting on behalf of.
                bank_account_holder_name:
                  type: string
                  maxLength: 255
                  minLength: 1
                  description: Bank account holder's name.
                beneficiary_country:
                  type: string
                  format: iso3166-1-alpha-2
                  pattern: ^[A-Z]{2}$
                  description: Two-letter ISO country code. If the beneficiary is a company, this is the country in which the company is registered. If the beneficiary is an individual, this is the country in which the beneficiary is based.
                currency:
                  type: string
                  format: iso-4217
                  pattern: ^[A-Z]{3}$
                  description: Currency in which money is held in the beneficiary's bank account. Three-letter currency code.
                account_number:
                  type: string
                  maxLength: 50
                  minLength: 1
                  description: Bank account number.
                routing_code_type[0]:
                  type: string
                  enum:
                  - aba
                  - bank_code
                  - branch_code
                  - bsb_code
                  - clabe
                  - cnaps
                  - ifsc
                  - institution_no
                  - sort_code
                  description: Local payment routing system. If supplied, a value for routing_code_value[0] must also be supplied.
                routing_code_value[0]:
                  type: string
                  maxLength: 50
                  minLength: 1
                  description: The value for any routing system specified in routing_code_type[0]. If supplied, a value for routing_code_type[0] must also be supplied.
                bic_swift:
                  type: string
                  pattern: ^(\w{8}|\w{11})$
                  description: BIC/Swift code
                iban:
                  type: string
                  pattern: ([A-Z0-9]\s*){15,34}
                  description: IBAN code
                default_beneficiary:
                  type: boolean
                  description: Payments are made automatically to default beneficiaries when a beneficiary is not specified.
                bank_name:
                  type: string
                  minLength: 1
                  description: Bank name
                bank_account_type:
                  type: string
                  enum:
                  - checking
                  - savings
                  description: Bank account type.
                name:
                  type: string
                  maxLength: 100
                  minLength: 1
                  pattern: \S+
                  description: Beneficiary's name.
                beneficiary_entity_type:
                  type: string
                  enum:
                  - company
                  - individual
                  description: Beneficiary's legal entity type - individual or company.
                beneficiary_company_name:
                  type: string
                  maxLength: 255
                  minLength: 1
                  description: Required if "beneficiary_entity_type" is "company".
                beneficiary_first_name:
                  type: string
                  maxLength: 255
                  minLength: 1
                  description: Required if "beneficiary_entity_type" is "individual".
                beneficiary_last_name:
                  type: string
                  maxLength: 255
                  minLength: 1
                  description: Required if "beneficiary_entity_type" is "individual".
                beneficiary_city:
                  type: string
                  maxLength: 255
                  minLength: 1
                  description: City
                beneficiary_postcode:
                  type: string
                  maxLength: 12
                  description: Post code
                beneficiary_state_or_province:
                  type: string
                  maxLength: 255
                  minLength: 1
                  description: State or province.
                beneficiary_date_of_birth:
                  type: string
                  format: date
                  description: If "beneficiary_entity_type" is "company", date of registration. If "beneficiary_entity_type" is "individual", date of birth. ISO 8601 format YYYY-MM-DD.
                scope:
                  type: string
                  enum:
                  - all
                  - clients
                  - own
                  default: own
                  description: Search "own" account, "clients" sub-accounts, or "all" accounts.
                page:
                  type: integer
                  pattern: ^\d+$
                  description: Page number
                per_page:
                  type: integer
                  pattern: ^\d+$
                  description: Number of results per page.
                order:
                  type: string
                  maxLength: 255
                  minLength: 1
                  description: Any field name to change the sort order.
                order_asc_desc:
                  type: string
                  enum:
                  - asc
                  - desc
                  default: asc
                  description: Sort records in ascending or descending order.
                beneficiary_external_reference:
                  type: string
                  maxLength: 255
                  minLength: 1
                  description: Beneficiary external reference.
  /beneficiaries/{id}:
    get:
      tags:
      - Beneficiaries
      x-api-group: pay
      summary: Get Beneficiary
      description: Gets a beneficiary with the given ID.
      operationId: GetBeneficiary
      parameters:
      - name: X-Auth-Token
        in: header
        required: true
        description: Authentication token
        schema:
          type: string
          minLength: 32
      - name: id
        in: path
        required: true
        description: Beneficiary UUID
        schema:
          type: string
          format: uuid
      - name: on_behalf_of
        in: query
        required: false
        description: A contact UUID for the sub-account you're acting on behalf of.
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Success.
          headers:
            X-Request-Id:
              description: A unique reference for the request.
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Beneficiary'
        '400':
          description: Client error.
          x-errors:
          - code: beneficiary_not_found
            category: id
            message: Beneficiary was not found for this id
            params: ''
          - code: contact_not_found
            category: on_behalf_of
            message: Contact was not found for this id
            params: ''
          - code: on_behalf_of_self
            category: on_behalf_of
            message: You cannot act on behalf of your own Contact
            params: ''
          headers:
            X-Request-Id:
              description: A unique reference for the request.
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetBeneficiaryError'
        '401':
          description: Unauthorized.
          x-errors:
          - code: invalid_supplied_credentials
            category: username
            message: Authentication failed with the supplied credentials
            params: ''
          headers:
            X-Request-Id:
              description: A unique reference for the request.
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedError'
        '404':
          description: Resource not found.
          headers:
            X-Request-Id:
              description: A unique reference for the request.
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundError'
        '429':
          description: Too many requests.
          x-errors:
          - code: too_many_requests
            category: base
            message: Too many requests have been made to the api. Please refer to the Developer Center for more information
            params: ''
          headers:
            X-Request-Id:
              description: A unique reference for the request.
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RateLimitError'
        '500':
          description: Internal server error
          x-errors:
          - code: internal_server_error
            category: base
            message: Internal server error
            params: ''
          headers:
            X-Request-Id:
              description: A unique reference for the request.
              schema:
                type: string
        '503':
          description: Service is temporary unavailable
          x-errors:
          - code: service_unavailable
            category: base
            message: Service is temporarily unavailable
            params: ''
          headers:
            X-Request-Id:
              description: A unique reference for the request.
              schema:
                type: string
        default:
          description: Unexpected error.
          headers:
            X-Request-Id:
              description: A unique reference for the request.
              schema:
                type: string
    post:
      tags:
      - Beneficiaries
      x-api-group: pay
      summary: Update Beneficiary
      description: 'Updates an existing beneficiary. Returns the updated beneficiary entity on success.

        Please note that it''s not possible to change a beneficiary''s entity type (company or individual) by an update. To achieve this, you should create a new beneficiary.'
      operationId: UpdateBeneficiary
      parameters:
      - name: X-Auth-Token
        in: header
        required: true
        description: Authentication token
        schema:
          type: string
          minLength: 32
      - name: id
        in: path
        required: true
        description: Beneficiary UUID
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Success.
          headers:
            X-Request-Id:
              description: A unique reference for the request.
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Beneficiary'
        '400':
          description: Client error.
          x-errors:
          - code: id_is_not_valid_uuid
            category: id
            message: id should be in UUID format
            params: ''
          - code: beneficiary_not_found
            category: id
            message: Beneficiary was not found for this id
            params: ''
          - code: bank_account_holder_name_is_too_short
            category: bank_account_holder_name
            message: bank_account_holder_name can not be shorter than 1 character(s)
            params: '{ "minlength" => 1 }'
          - code: bank_account_holder_name_is_too_long
            category: bank_account_holder_name
            message: bank_account_holder_name can not be longer than 255 character(s)
            params: '{ "maxlength" => 255 }'
          - code: email_is_too_long
            category: email
            message: email can not be longer than 255 character(s)
            params: '{ "maxlength" => 255 }'
          - code: beneficiary_address_is_too_short
            category: beneficiary_address
            message: beneficiary_address can not be shorter than 1 character(s)
            params: '{ "minlength" => 1 }'
          - code: beneficiary_address_is_too_long
            category: beneficiary_address
            message: beneficiary_address can not be longer than 255 character(s)
            params: '{ "maxlength" => 255 }'
          - code: account_number_is_too_short
            category: account_number
            message: account_number can not be shorter than 1 character(s)
            params: '{ "minlength" => 1 }'
          - code: account_number_is_too_long
            category: account_number
            message: account_number can not be longer than 50 character(s)
            params: '{ "maxlength" => 50 }'
          - code: account_number_is_missing
            category: account_number
            message: Account number is missing
            params: ''
          - code: account_number_is_invalid
            category: account_number
            message: Account number is in invalid format
            params: ''
          - code: routing_code_value_1_is_too_short
            category: routing_code_value_1
            message: routing_code_value_1 can not be shorter than 1 character(s)
            params: '{ "minlength" => 1 }'
          - code: routing_code_value_1_is_too_long
            category: routing_code_value_1
            message: routing_code_value_1 can not be longer than 50 character(s)
            params: '{ "maxlength" => 50 }'
          - code: routing_code_value_2_is_too_short
            category: routing_code_value_2
            message: routing_code_value_2 can not be shorter than 1 character(s)
            params: '{ "minlength" => 1 }'
          - code: routing_code_value_2_is_too_long
            category: routing_code_value_2
            message: routing_code_value_2 can not be longer than 50 character(s)
            params: '{ "maxlength" => 50 }'
          - code: iban_is_too_short
            category: iban
            message: iban can not be shorter than 1 character(s)
            params: '{ "minlength" => 1 }'
          - code: iban_is_too_long
            category: iban
            message: iban can not be longer than 34 character(s)
            params: '{ "maxlength" => 34 }'
          - code: iban_is_missing
            category: iban
            message: IBAN is missing
            params: ''
          - code: iban_is_invalid
            category: iban
            message: IBAN is in invalid format
            params: ''
          - code: bic_swift_is_missing
            category: bic_swift
            message: BIC/Swift is missing
            params: ''
          - code: bic_swift_is_invalid
            category: bic_swift
            message: BIC/Swift is in invalid format
            params: ''
          - code: bank_address_is_missing
            category: bank_address
            message: Bank address is missing
            params: ''
          - code: bank_address_is_too_short
            category: bank_address
            message: bank_address can not be shorter than 1 character(s)
            params: '{ "minlength" => 1 }'
          - code: bank_address_is_too_long
            category: bank_address
            message: bank_address can not be longer than 100 character(s)
            params: '{ "maxlength" => 100 }'
          - code: bank_name_is_too_short
            category: bank_name
            message: bank_name can not be shorter than 1 character(s)
            params: '{ "minlength" => 1 }'
          - code: bank_name_is_missing
            category: bank_name
            message: Bank name is missing
            params: ''
          - code: bank_account_type_not_in_range
            category: bank_account_type
            message: 'bank_account_type should be in range: checking, savings'
            params: '{ "range" => "checking, savings" }'
          - code: bank_account_type_is_missing
            category: bank_account_type
            message: Beneficiary bank account type is missing
            params: ''
          - code: name_is_in_invalid_format
            category: name
            message: name is in invalid format
            params: ''
          - code: name_is_too_short
            category: name
            message: name can not be shorter than 1 character(s)
            params: '{ "minlength" => 1 }'
          - code: name_is_too_long
            category: name
            message: name can not be longer than 100 character(s)
       

# --- truncated at 32 KB (140 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/currencycloud/refs/heads/main/openapi/currencycloud-beneficiaries-api-openapi.yml