# Create a buyer

Buyers are identities representing a business. Once on-boarded, Buyers can create and manage their own instruments via your plugin. 

The information provided must be accurate and will be passed on for KYB verification with our partner.

Endpoint: POST /v1/buyers
Version: v1
Security: apiKey

## Header parameters:

  - `idempotency-ref` (string)
    A unique call reference generated by the caller that, taking into consideration the payload as well as the operation itself, helps avoid duplicate operations. Idempotency reference uniqueness is maintained for at least 24 hours.

## Request fields (application/json):

  - `tag` (string)
    The tag field is a custom field that can be used to search and filter.

  - `adminUser` (object, required)
    The admin user needs to be a director or a legal representative of the buyer that is being onboarded - this user cannot be deactivated.

Admin users need to verify their email address and mobile number, as well as complete KYC as part of the Buyer's due diligence process.

  - `adminUser.name` (string, required)
    The first name of the admin user.

  - `adminUser.surname` (string, required)
    The last name of the admin user.

  - `adminUser.email` (string, required)
    E-mail Address of the user

  - `adminUser.mobile` (object, required)
    Mobile number of the user

  - `adminUser.mobile.countryCode` (string, required)
    The country code of the Buyer's admin user mobile number (e.g. +44).

  - `adminUser.mobile.number` (string, required)
    The mobile number of the Buyer's admin user - excluding country code.

  - `adminUser.companyPosition` (string, required)
    The company position of the Buyer Admin User.
    Enum: "DIRECTOR", "AUTHORISED_REPRESENTATIVE"

  - `adminUser.dateOfBirth` (object)

  - `adminUser.dateOfBirth.year` (integer, required)

  - `adminUser.dateOfBirth.month` (integer, required)

  - `adminUser.dateOfBirth.day` (integer, required)

  - `company` (object, required)
    The details associated with the company being on-boarded. The details provided need to match exactly with the details provided during KYB.

  - `company.type` (string, required)
    Supported company types - if company type is not listed, please contact our support team to check if the company type can be supported.
    Enum: "LLC", "PUBLIC_LIMITED_COMPANY", "LIMITED_LIABILITY_PARTNERSHIP"

  - `company.name` (string, required)
    The registered name of the company.

  - `company.registrationNumber` (string)
    The company registration number.

  - `company.businessAddress` (object)
    The address where the business is based.

  - `company.businessAddress.addressLine1` (string, required)
    The first line of the address.

  - `company.businessAddress.addressLine2` (string)
    The second line of the address.

  - `company.businessAddress.city` (string, required)
    The city of the address.

  - `company.businessAddress.postCode` (string, required)
    The post cost associated with the address.

  - `company.businessAddress.state` (string)
    The state of the address.

  - `company.businessAddress.country` (string, required)
    The country of the address expressed in ISO 3166 alpha-2 format.

  - `company.countryOfRegistration` (string, required)
    The country of company registration in ISO 3166 alpha-2.
    Enum: "GB", "AT", "BE", "BG", "HR", "CY", "CZ", "DK", "EE", "FI", "FR", "DE", "GI", "GR", "HU", "IS", "IE", "IT", "LV", "LI", "LT", "LU", "MT", "NL", "NO", "PL", "PT", "RO", "SK", "SI", "ES", "SE"

  - `acceptedTerms` (boolean, required)
    Must be set to true to indicate that the buyer admin user has accepted the terms and conditions.

  - `ipAddress` (string, required)
    The IP address of the buyer user doing the registration.

  - `supportedCurrencies` (array, required)
    Enum: "GBP", "EUR"

## Response 200 fields (application/json):

  - `id` (string, required)
    Id of the buyer.

  - `tag` (string)
    The tag field is a custom field that can be used to search and filter.

  - `adminUser` (object, required)
    The admin user of the Buyer Identity.

  - `adminUser.id` (string, required)
    The identifier of the user.

  - `adminUser.name` (string, required)
    First name of the admin user.

  - `adminUser.surname` (string, required)
    Last name of the admin user.

  - `adminUser.email` (string, required)
    E-mail Address of the user

  - `adminUser.mobile` (object, required)
    Mobile number of the user

  - `adminUser.mobile.countryCode` (string, required)
    The country code of the Buyer's admin user mobile number (e.g. +44).

  - `adminUser.mobile.number` (string, required)
    The mobile number of the Buyer's admin user - excluding country code.

  - `adminUser.companyPosition` (string, required)
    The company position of the Buyer Admin User.
    Enum: "DIRECTOR", "AUTHORISED_REPRESENTATIVE"

  - `adminUser.dateOfBirth` (object)
    Date of birth of the authorised user.

  - `adminUser.dateOfBirth.year` (integer, required)

  - `adminUser.dateOfBirth.month` (integer, required)

  - `adminUser.dateOfBirth.day` (integer, required)

  - `adminUser.active` (boolean, required)
    The state of the admin user. If false, then the user will not be able to log in.

  - `adminUser.emailVerified` (boolean, required)
    Indicates if the admin user's email has been verified.

  - `adminUser.mobileNumberVerified` (boolean, required)
    Indicates if the admin user's mobile number has been verified.

  - `adminUser.roles` (array, required)
    Roles define the level of access assigned to the user.

* CREATOR: Users assigned this role can create, view and update payment runs.
* CONTROLLER: Users assigned this role can view and link their company's bank accounts as well as fund payment runs.
* ADMIN: Users assigned to this role can create a business and ensure that systems and processes are effectively managed.
    Enum: "ADMIN", "CREATOR", "CONTROLLER"

  - `company` (object, required)
    The details associated with the company being on-boarded. The details provided need to match exactly with the details provided during KYB.

  - `company.type` (string, required)
    Supported company types - if company type is not listed, please contact our support team to check if the company type can be supported.
    Enum: "LLC", "PUBLIC_LIMITED_COMPANY", "LIMITED_LIABILITY_PARTNERSHIP"

  - `company.name` (string, required)
    The registered name of the company.

  - `company.registrationNumber` (string)
    The company registration number.

  - `company.businessAddress` (object)
    The address where the business is based.

  - `company.businessAddress.addressLine1` (string, required)
    The first line of the address.

  - `company.businessAddress.addressLine2` (string)
    The second line of the address.

  - `company.businessAddress.city` (string, required)
    The city of the address.

  - `company.businessAddress.postCode` (string, required)
    The post cost associated with the address.

  - `company.businessAddress.state` (string)
    The state of the address.

  - `company.businessAddress.country` (string, required)
    The country of the address expressed in ISO 3166 alpha-2 format.

  - `company.countryOfRegistration` (string, required)
    The country of company registration in ISO 3166 alpha-2.
    Enum: "GB", "AT", "BE", "BG", "HR", "CY", "CZ", "DK", "EE", "FI", "FR", "DE", "GI", "GR", "HU", "IS", "IE", "IT", "LV", "LI", "LT", "LU", "MT", "NL", "NO", "PL", "PT", "RO", "SK", "SI", "ES", "SE"

  - `company.registeredAddress` (object)
    The legal address of the company. This information is captured via the Due Diligence (KYB) process.

  - `company.registeredAddress.addressLine1` (string, required)

  - `company.registeredAddress.addressLine2` (string)

  - `company.registeredAddress.city` (string, required)

  - `company.registeredAddress.postCode` (string)

  - `company.registeredAddress.state` (string)

  - `company.registeredAddress.country` (string, required)
    Country of the identity in ISO 3166 alpha-2 format.

  - `company.incorporatedOn` (object)
    The company's date of incorporation

  - `acceptedTerms` (boolean, required)
    Must be set to true to indicate that the admin user has accepted the terms and conditions.

  - `supportedCurrencies` (array, required)

  - `supportedCurrencies.currency` (string, required)
    The currency expressed in ISO-4217 code.
    Enum: "GBP", "EUR"

  - `supportedCurrencies.status` (string, required)
    The status of the currency, which can include the following values

* PENDING_KYB_APPROVAL: The buyer’s KYB process is pending approval.
    Enum: "PENDING_KYB_APPROVAL"

  - `creationTimestamp` (integer, required)
    The time when the Buyer was created, expressed in Epoch timestamp using millisecond precision.

  - `ipAddress` (string)
    The IP address of the user doing the registration.

## 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 403 fields (application/json):

  - `errorCode` (string)
    Enum: "INSUFFICIENT_PERMISSIONS"

## Response 409 fields (application/json):

  - `errorCode` (string)
    Enum: "ADMIN_EMAIL_NOT_UNIQUE", "CURRENCY_UNSUPPORTED", "COUNTRY_INVALID", "TERMS_NOT_ACCEPTED", "MOBILE_OR_COUNTRY_CODE_INVALID", "COUNTRY_UNSUPPORTED", "COMPANY_TYPE_UNSUPPORTED", "IDEMPOTENT_REQUEST_IN_PROGRESS"

## Response default fields (application/json):

  - `code` (string)

  - `message` (string)


## Response 401 fields

## Response 413 fields

## Response 422 fields

## Response 429 fields

## Response 500 fields

## Response 503 fields