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

# Create a beneficiary

> This endpoint create a beneficiary.

### Header

<ParamField header="x-client-id" type="string" required>
  `x-client-id`.
</ParamField>

<ParamField header="x-auth-token" type="string" required>
  Bearer `YOUR_TOKEN_HERE`.
</ParamField>

### Parameters

<ParamField body="bank_country" type="string" required>
  Account bank country code of the beneficiary.<br />
  Two-letter [ISO 3166-2](https://en.wikipedia.org/wiki/ISO_3166-2) country code.
</ParamField>

<ParamField body="account_currency" type="string" required>
  Account currency code of the beneficiary.<br />
  Three-letter [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) currency code.
</ParamField>

<ParamField body="entity_type" type="string" required>
  Entity type of the beneficiary.<br />
  One of `company`, `individual`<br />
</ParamField>

<ParamField body="email" type="string" required>
  Email of the beneficiary.
</ParamField>

<ParamField body="nickname" type="string" required>
  A nickname for the beneficiary.<br />
  `Maximum length 120`
</ParamField>

<ParamField body="first_name" type="string">
  Required if "entity\_type" is "individual".<br />
  First name of the beneficiary.<br />
  `Maximum length 45`
</ParamField>

<ParamField body="last_name" type="string">
  Required if "entity\_type" is "individual".
  Last name of the beneficiary.<br />
  `Maximum length 45`
</ParamField>

<ParamField body="company_name" type="string">
  Required if "entity\_type" is "company".<br />
  Company names cannot consist entirely of numbers.<br />
  `Maximum length 120`
</ParamField>

<ParamField body="payment_method" type="string" required>
  Payment method of the beneficiary.<br />
  One of `local`, `swift`.<br />
  It is related to `clearing_system`, and the relationship can be obtained from this interface [Get a list of payment methods.](/api-reference/payout/paymentmethods_v1.1)
</ParamField>

<ParamField body="bank_name" type="string" required>
  Bank name of the beneficiary's bank account.<br />
  `Maximum length 240`
</ParamField>

<ParamField body="bank_address" type="string" required>
  Bank street address.<br />
  `Maximum length 240`
</ParamField>

<ParamField body="account_holder" type="string" required>
  Account holder name of the beneficiary’s bank account.<br />
  `Maximum length 36`
</ParamField>

<ParamField body="account_number" type="string">
  Bank account number.<br />
  `Maximum length 60`<br />
  If `iban` is not required, `account_number` is **required**.
</ParamField>

<ParamField body="iban" type="string">
  International bank account number, mostly for european countries.<br />
  speaCountrys:`AD`,`AT`,`BE`,`BG`,`CY`,`HR`,`CZ`,`DK`,`EE`,`FI`,`FR`,`DE`,`GR`,`HU`,`IS`,`IE`,`IT`,`LV`,`LI`,`LT`,`LU`,`MT`,`MC`,`NL`,`NO`,`PL`,`PT`,`RO`,`SM`,`SK`,`SI`,`ES`,`SE`,`CH`,`GB`,`VA`<br />
  speaCurrency:`EUR`,`USD`<br />
  If the country and currency are in the above list, the `iban` is required.
</ParamField>

<ParamField body="swift_code" type="string">
  BIC/SWIFT code<br />
  `Maximum length 30`
</ParamField>

<ParamField body="clearing_system" type="string">
  Which clearing system should be used for this beneficiary.<br />
  `Maximum length 30`<br />
  It is related to `payment_method`, and the relationship can be obtained from this interface [Get a list of payment methods.](/api-reference/payout/paymentmethods_v1.1)
</ParamField>

<ParamField body="routing_code_type1" type="string">
  Routing code type.<br />
  When the `validation_field` value of [Get a list of payment methods](/api-reference/payout/paymentmethods_v1.1) does not find the corresponding field in the input parameter list,
  the field name is put into `routing_code_type1` and the value is put into the corresponding `routing_code_value1`.
</ParamField>

<ParamField body="routing_code_value1" type="string">
  Routing code value.<br />
  Routing code for routing\_code\_type\_1.<br />
  If supplied, routing\_code\_type\_1 should also be supplied.
</ParamField>

<ParamField body="routing_code_type2" type="string">
  Routing code sub type.<br />
  When the `validation_field` value of [Get a list of payment methods](/api-reference/payout/paymentmethods_v1.1) does not find the corresponding field in the input parameter list,
  the field name is put into `routing_code_type2` and the value is put into the corresponding `routing_code_value2`.
</ParamField>

<ParamField body="routing_code_value2" type="string">
  Routing code sub type value.<br />
  Routing code for routing\_code\_type\_2. <br />
  If supplied, routing\_code\_type\_2 should also be supplied.
</ParamField>

<ParamField body="country_code" type="string" required>
  Country code of the beneficiary<br />
  Two-letter [ISO 3166-2](https://en.wikipedia.org/wiki/ISO_3166-2) country code.
</ParamField>

<ParamField body="city" type="string" required>
  City of the beneficiary.<br />
  `Maximum length 36`
</ParamField>

<ParamField body="state" type="string" required>
  State of the beneficiary.<br />
  `Maximum length 96`
</ParamField>

<ParamField body="address" type="string" required>
  Address of the beneficiary.<br />
  `Maximum length 255`
</ParamField>

<ParamField body="postal_code" type="string" required>
  Postal code of the beneficiary.<br />
  `Maximum length 12`
</ParamField>

### Response

<ResponseField name="code" type="number">
  Indicates whether the call was successful. 200 if successful, 400 if not.
</ResponseField>

<ResponseField name="message" type="string">
  Response Message. "Success" if successful, others not.
</ResponseField>

<ResponseField name="data" type="object">
  <Expandable title="details" defaultOpen>
    <ResponseField name="beneficiary_id" type="string">
      Beneficiary UUID.
    </ResponseField>

    <ResponseField name="entity_type" type="string">
      Entity type of the beneficiary.<br />
      One of `company`, `individual`
    </ResponseField>

    <ResponseField name="payment_method" type="string">
      The payment method needs to be specified to ensure that accurate banking details are captured and validated for the specified payment method.<br />
      One of `local`, `swift`
    </ResponseField>

    <ResponseField name="beneficiary_email" type="string">
      Email of the beneficiary.
    </ResponseField>

    <ResponseField name="beneficiary_nickname" type="string">
      Nickname of the beneficiary.
    </ResponseField>

    <ResponseField name="beneficiary_company_name" type="string">
      Company name of the beneficiary.
    </ResponseField>

    <ResponseField name="account_currency_code" type="string">
      Account currency code.<br />
      Three-letter [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) currency code.
    </ResponseField>

    <ResponseField name="bank_country_code" type="string">
      Bank country code.<br />
      Two-letter [ISO 3166-2](https://en.wikipedia.org/wiki/ISO_3166-2) country code.
    </ResponseField>

    <ResponseField name="beneficiary_first_name" type="string">
      First name of the beneficiary.
    </ResponseField>

    <ResponseField name="beneficiary_last_name" type="string">
      Last name of the beneficiary.
    </ResponseField>

    <ResponseField name="beneficiary_bank_details" type="object">
      Beneficiary's bank account details where the payment will be credited.

      <Expandable title="details">
        <ResponseField name="bank_name" type="string">
          Bank name of the beneficiary's bank account.
        </ResponseField>

        <ResponseField name="bank_address" type="string">
          Bank street address.
        </ResponseField>

        <ResponseField name="bank_country_code" type="string">
          Bank country code.<br />
          Two-letter [ISO 3166-2](https://en.wikipedia.org/wiki/ISO_3166-2) country code.
        </ResponseField>

        <ResponseField name="account_holder" type="string">
          Account holder name of the beneficiary’s bank account.
        </ResponseField>

        <ResponseField name="account_currency_code" type="string">
          Account currency code.<br />
          Three-letter [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) currency code.
        </ResponseField>

        <ResponseField name="account_number" type="string">
          Account number, mostly for non-european countries, either account\_number or iban should be filled.
        </ResponseField>

        <ResponseField name="iban" type="string">
          International bank account number, mostly for european countries.
        </ResponseField>

        <ResponseField name="swift_code" type="string">
          Bank swift code.
        </ResponseField>

        <ResponseField name="clearing_system" type="string">
          Which clearing system should be used for this.
        </ResponseField>

        <ResponseField name="routing_code_type1" type="string">
          Routing code type.
        </ResponseField>

        <ResponseField name="routing_code_value1" type="string">
          Routing code value.
        </ResponseField>

        <ResponseField name="routing_code_type2" type="string">
          Routing code sub type.
        </ResponseField>

        <ResponseField name="routing_code_value2" type="string">
          Routing code sub type value.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="beneficiary_address" type="object">
      Beneficiary's address details.

      <Expandable title="details">
        <ResponseField name="country_code" type="string">
          Country code of the beneficiary.<br />
          Two-letter [ISO 3166-2](https://en.wikipedia.org/wiki/ISO_3166-2) country code.
        </ResponseField>

        <ResponseField name="city" type="string">
          City of the beneficiary.
        </ResponseField>

        <ResponseField name="street_address" type="string">
          Street address of the beneficiary.
        </ResponseField>

        <ResponseField name="postal_code" type="string">
          Postal code of the beneficiary.
        </ResponseField>

        <ResponseField name="state" type="string">
          State of the beneficiary.
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

<RequestExample>
  ```bash cURL Example Request theme={null}
  curl 'https://api.sandbox.uqpay.org/api/v1/beneficiaries/create' \
  -H 'content-type: application/json' \
  -H 'x-auth-token: Bearer 0e043e2ec6898b3220a0921466d7c203' \
  -H 'x-client-id: Up1HIsjiETPXLy7gON9PMG' \
  --data-raw '{"bank_country":"US","account_currency":"USD","entity_type":"company","email":"demo@uqpay.com","nickname":"MANY A-SUN","first_name":"","last_name":"","company_name":"Courtesy Hardware Store","payment_method":"swift","bank_name":"1ST STATE BANK","bank_address":"4929 Briarwood Drive","account_holder":"Robert Shishani","country_code":"US","city":"Montgomery","state":"Alabama","address":"1230 Stafford Dr","postal_code":"36117","clearing_system":"SWIFT","account_number":"4865393923574557","swift_code":"230"}'
  ```
</RequestExample>

<ResponseExample>
  ```json Response theme={null}
  {
    "code": 200,
    "message": "Success",
    "data": {
        "beneficiary_id": "00dcbdb4-3642-424d-88bf-76629efaa168",
        "account_currency_code": "SGD",
        "account_number": "33990319141",
        "bank_country_code": "SG",
        "beneficiary_address": "{\"country_code\":\"SG\",\"city\":\"singapore\",\"street_address\":\"7 Burn Road #07-07 Trivex Singapore 413577\",\"postal_code\":\"413577\",\"state\":\"singapore\"}",
        "beneficiary_bank_details": "{\"bank_name\":\"test bank name\",\"bank_address\":\"test bank address\",\"bank_country_code\":\"SG\",\"account_holder\":\"zuuzj\",\"account_currency_code\":\"SGD\",\"account_number\":\"33990319141\",\"iban\":\"\",\"swift_code\":\"UOVBSGSG\",\"clearing_system\":\"local\",\"routing_code_type1\":\"\",\"routing_code_value1\":\"\",\"routing_code_type2\":\"\",\"routing_code_value2\":\"\"}",
        "beneficiary_company_name": "00dcbdb4-3642-424d-88bf-76629efaa168",
        "beneficiary_entity_type": "individual",
        "beneficiary_first_name": "00dcbdb4-3642-424d-88bf-76629efaa168",
        "beneficiary_last_name": "00dcbdb4-3642-424d-88bf-76629efaa168",
        "beneficiary_email": "zuuj88@gmail.com",
        "beneficiary_nickname": "zuuj88",
        "payment_method": "local",
        "beneficiary_status": "pending"
    }
  }
  ```
</ResponseExample>