Using API and form schemas

Call Get the API schema API or Get the form schema API to retrieve the corresponding schemas and validation rules based on the parameters provided:

• bank_country_code: The 2-letter ISO 3166-2 country code of the beneficiary’s bank.
• account_currency: The 3-letter ISO 4217 currency code for the beneficiary’s account.
• transfer_method: The transfer method for the payout (LOCAL or SWIFT). Note that for API versions prior to 2024-09-27, use payment_method instead of transfer_method.
• local_clearing_system: The local clearing system for LOCAL payouts where applicable (a default value will apply when this parameter is not specified and transfer_method is LOCAL). To learn more about supported local clearing systems, see Payout network.
• entity_type: The type of the beneficiary, COMPANY (business) or PERSONAL (individual).
• country_code: The 2-letter ISO 3166-2 country code for the beneficiary's address (as opposed to bank country above). Specify this parameter to retrieve the country-specific schema for fields under the beneficiary.address object.

While all of the above parameters are needed for retrieving a specific beneficiary schema for the payout scenario, you can call the endpoints with none or some of the parameters for possible values accepted in the others. This is to support dynamic rendering of your product/system experience to narrow down to the specific schema and validation rules via multiple interactions with the schema APIs.

A 400 error SCHEMA_DEFINITION_NOT_FOUND will be returned in case of invalid or unsupported requests. If you are unsure which values are acceptable for each parameter, call the endpoint without any parameters to retrieve the possible values and retry again.

A successful response returns the condition specified in the request and the fields containing the following parameters:

• key: The name of the request parameter.
• path: A hierarchical representation of the key using the parent objects up to the top-level parent.
• required: Indicates whether the field is required for the given payout scenario.
• rule: Validation rules for the field, including:
  • pattern: The acceptable value for this field, or a required format under regular expression.
  • type: The data type for the field.

A successful response returns the condition specified in the request and the fields containing the following elements:

• enabled: Whether a field should be enabled for end users on the user interface.
• field: An object containing attributes defining how each field can be rendered:
  • default: Recommended default prefilled value for this field.
  • description: Short description of the field to provide more context.
  • example: Example value of the field.
  • key: Name of the field per API request.
  • label: Name of the field to render on the UI.
  • placeholder: Placeholder text for the field if applicable.
  • refresh: Whether updating this field triggers a UI reload event.
  • tip: Additional information if prompted by mouse hover.
  • type*: The type of UI component. Could be INPUT, SELECT, DYNAMIC_SELECT, RADIO, or TRANSFER_METHOD.
  • options: An array of objects specifying the possible values for this field, each with a label, an acceptable enum value, and an optional description for UI rendering.
    • This object will be returned when type is one of SELECT,RADIO, or TRANSFER_METHOD
    • When type is TRANSFER_METHOD, the following attributes will also be returned under options where applicable:
      • transfer_limit with min and/or max objects, each composed of amount and currency.
      • flight_time with min and/or max fields in ISO 8601 format (e.g. "max": "P3D", "min:"P0D" means 0-3 business days).
  • dynamic_options: An object providing structural instructions for dynamically searching and retrieving options for this field via additional API requests.
    • This object will be returned when type is DYNAMIC_SELECT, which suggests that the options need to be loaded dynamically as the full list cannot be provided at once. The following attributes will be included:
    • query_params: An array of objects each specifying a request parameter for the API call. The following fields will be included:
      • name: The parameter key on the new API, e.g., country_code.
      • value_of: The path to a field as defined by the current API, e.g., beneficiary.bank_details.bank_country_code. Use the current user input on this field when making the new API request so that requests are dynamically populated.
      • required: Boolean indicating whether the parameter is mandatory.
      • A pattern field is included only when name is keyword. It specifies the input requirements in regular expression. For example, ^[0-9a-zA-Z]{3,}$ means that a minimum of 3 alphanumeric characters should be provided.
    • query_url: Path to the API endpoint to request with the parameters above.
• path: A hierarchical representation of the key using the parent objects up to the top-level parent.
• required: Indicates whether the field is required for the given payout scenario.
• rule: Validation rules for the field containing the following fields:
  • pattern: The acceptable value for this field, or a required format under regular expression.
  • type: The data type for the field.

*Note that for bank routing value fields such as account_routing_value1, account_routing_value2, and swift_code, the type returned depends on whether the capability to retrieve supoorted bank lists is enabled:

** The INPUT field type only applies to the account_routing_value1 and account_routing_value2 for Australia BPAY® beneficiaries, as the billing information is always verified in real-time and a biller list is not available. For all other transfer methods, a dropdown element is recommended.

If you are using an earlier API version and wish to leverage this capability, please contact your Airwallex Account Manager.