# Create a corporate

Create a corporate identity for a business customer.  The information provided must be accurate and will be passed on for KYB verification with our partner.

Endpoint: POST /corporates
Version: v3
Security: api-key

## 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):

  - `profileId` (string, required)
    The profile Id which a specific identity, instrument or transaction type is linked to.

Profiles contain configuration and determine behavioral aspects of the newly created transaction, for example, fees that may apply.

You can have one or more profiles linked to your application, and these can be used to drive different behaviors according to your product's needs.

Profile Ids can be found in the Multi Portal, in the API Credentials page.

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

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

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

  - `rootUser.name` (string, required)
    The first name of the root user.

  - `rootUser.surname` (string, required)
    The last name of the root user.

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

  - `rootUser.mobile` (object, required)

  - `rootUser.mobile.countryCode` (string, required)
    The country code of the user mobile number (e.g. +44).

  - `rootUser.mobile.number` (string, required)
    The mobile number of the user - excluding country code.

  - `rootUser.companyPosition` (string, required)
    The company position of the Corporate Root User.
    Enum: "DIRECTOR", "AUTHORISED_REPRESENTATIVE"

  - `rootUser.dateOfBirth` (object)
    Date of birth of the root user.

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

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

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

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

  - `rootUser.locale` (string)
    BCP47 locale code (e.g. en, en-US). The locale determines which email and SMS user notification templates are used.

  - `rootUser.brand` (string)
    Brand identifier used to determine the set of email and SMS user notification templates. Must be alphanumeric, up to 25 characters, and contain no spaces.

  - `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: "SOLE_TRADER", "LLC", "PUBLIC_LIMITED_COMPANY", "LIMITED_LIABILITY_PARTNERSHIP", "NON_PROFIT_ORGANISATION"

  - `company.businessAddress` (object)

  - `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 code 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.name` (string, required)
    The registered name of the company.

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

  - `company.registrationCountry` (string, required)
    The country of company registration, in ISO 3166 alpha-2 format.

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

  - `baseCurrency` (string, required)
    The currency expressed in ISO-4217 code. Example: GBP, EUR, USD.

  - `feeGroup` (string)
    Fee groups allow the possibility to charge different fees to users under the same profile. If fee groups are not required, ignore this field.

  - `industry` (string)
    The industry of the identity.
    Enum: "ACCOUNTING", "AUDIT", "FINANCE", "PUBLIC_SECTOR_ADMINISTRATION", "ART_ENTERTAINMENT", "AUTO_AVIATION", "BANKING_LENDING", "BUSINESS_CONSULTANCY_LEGAL", "CONSTRUCTION_REPAIR", "EDUCATION_PROFESSIONAL_SERVICES", "INFORMATIONAL_TECHNOLOGIES", "TOBACCO_ALCOHOL", "GAMING_GAMBLING", "MEDICAL_SERVICES", "MANUFACTURING", "PR_MARKETING", "PRECIOUS_GOODS_JEWELRY", "NON_GOVERNMENTAL_ORGANIZATION", "INSURANCE_SECURITY", "RETAIL_WHOLESALE", "TRAVEL_TOURISM", "FREELANCER"

  - `sourceOfFunds` (string)
    The corporate's source of funds.
    Enum: "LABOUR_CONTRACT", "CIVIL_CONTRACT", "RENT", "FUNDS_FROM_OTHER_AUXILIARY_SOURCES", "SALE_OF_MOVABLE_ASSETS", "SALE_OF_REAL_ESTATE", "ORDINARY_BUSINESS_ACTIVITY", "DIVIDENDS", "LOAN_FROM_FINANCIAL_INSTITUTIONS_CREDIT_UNIONS", "LOAN_FROM_THIRD_PARTIES", "SALE_OF_COMPANY_SHARES_BUSINESS", "OTHER", "DONATION", "INHERITANCE", "ORIGIN_OF_FUNDS_UNKNOWN"

  - `sourceOfFundsOther` (string)
    Description of source of funds in case OTHER was chosen.

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

## Response 200 fields (application/json):

  - `id` (object, required)
    The unique identifier of the Corporate Identity.

  - `id.type` (string, required)
    Indicates the identity type.
    Enum: "CONSUMER", "CORPORATE"

  - `id.id` (string, required)
    The identifier for the identity.

  - `profileId` (string, required)
    The profile Id which a specific identity, instrument or transaction type is linked to.

Profiles contain configuration and determine behavioral aspects of the newly created transaction, for example, fees that may apply.

You can have one or more profiles linked to your application, and these can be used to drive different behaviors according to your product's needs.

Profile Ids can be found in the Multi Portal, in the API Credentials page.

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

  - `rootUser` (object, required)
    The root user of the Corporate Identity.

  - `rootUser.id` (object, required)

  - `rootUser.id.type` (string, required)
    Indicates the identity type.
    Enum: "CONSUMER", "CORPORATE"

  - `rootUser.id.id` (string, required)
    The identifier for the identity.

  - `rootUser.name` (string, required)
    First name of the root user.

  - `rootUser.surname` (string, required)
    Last name of the root user.

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

  - `rootUser.mobile` (object, required)

  - `rootUser.mobile.countryCode` (string, required)
    The country code of the user mobile number (e.g. +44).

  - `rootUser.mobile.number` (string, required)
    The mobile number of the user - excluding country code.

  - `rootUser.companyPosition` (string, required)
    The company position of the Corporate Root User.
    Enum: "DIRECTOR", "AUTHORISED_REPRESENTATIVE"

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

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

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

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

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

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

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

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

  - `rootUser.locale` (string)
    BCP47 locale code (e.g. en, en-US). The locale determines which email and SMS user notification templates are used.
    Example: "en-GB"

  - `rootUser.brand` (string)
    Brand identifier used to determine the set of email and SMS user notification templates. Must be alphanumeric, up to 25 characters, and contain no spaces.

  - `rootUser.passwordAlreadySet` (boolean, required)
    When the corporate root user is a single email multiple identities user, this field returns true, indicating that there is no need to call the passwordCreate operation for this user.

  - `company` (object, required)

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

  - `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: "SOLE_TRADER", "LLC", "PUBLIC_LIMITED_COMPANY", "LIMITED_LIABILITY_PARTNERSHIP", "NON_PROFIT_ORGANISATION"

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

  - `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.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 code 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.

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

  - `company.incorporatedOn.year` (integer, required)

  - `company.incorporatedOn.month` (integer, required)

  - `company.incorporatedOn.day` (integer, required)

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

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

  - `baseCurrency` (string, required)
    The currency expressed in ISO-4217 code. Example: GBP, EUR, USD.

  - `feeGroup` (string)
    Fee groups allow the possibility to charge different fees to users under the same profile. If fee groups are not required, ignore this field.

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

  - `retailQualifier` (string)
    Indicates the type of corporate entity based on its retail status.
    Enum: "RETAIL", "NON_RETAIL", "UNKNOWN"

  - `industry` (string)
    The industry of the identity.
    Enum: "ACCOUNTING", "AUDIT", "FINANCE", "PUBLIC_SECTOR_ADMINISTRATION", "ART_ENTERTAINMENT", "AUTO_AVIATION", "BANKING_LENDING", "BUSINESS_CONSULTANCY_LEGAL", "CONSTRUCTION_REPAIR", "EDUCATION_PROFESSIONAL_SERVICES", "INFORMATIONAL_TECHNOLOGIES", "TOBACCO_ALCOHOL", "GAMING_GAMBLING", "MEDICAL_SERVICES", "MANUFACTURING", "PR_MARKETING", "PRECIOUS_GOODS_JEWELRY", "NON_GOVERNMENTAL_ORGANIZATION", "INSURANCE_SECURITY", "RETAIL_WHOLESALE", "TRAVEL_TOURISM", "FREELANCER"

  - `sourceOfFunds` (string)
    The corporate's source of funds.
    Enum: "LABOUR_CONTRACT", "CIVIL_CONTRACT", "RENT", "FUNDS_FROM_OTHER_AUXILIARY_SOURCES", "SALE_OF_MOVABLE_ASSETS", "SALE_OF_REAL_ESTATE", "ORDINARY_BUSINESS_ACTIVITY", "DIVIDENDS", "LOAN_FROM_FINANCIAL_INSTITUTIONS_CREDIT_UNIONS", "LOAN_FROM_THIRD_PARTIES", "SALE_OF_COMPANY_SHARES_BUSINESS", "OTHER", "DONATION", "INHERITANCE", "ORIGIN_OF_FUNDS_UNKNOWN"

  - `sourceOfFundsOther` (string)
    Description of source of funds in case OTHER was chosen.

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

  - `errorCode` (string)
    Enum: "PAYMENT_MODEL_CONSTRAINTS_VIOLATED", "PROFILE_NOT_FOUND", "PROFILE_INACTIVE", "ROOT_EMAIL_NOT_UNIQUE", "CURRENCY_UNSUPPORTED", "FEE_GROUP_INVALID", "COUNTRY_INVALID", "MOBILE_OR_COUNTRY_CODE_INVALID", "COUNTRY_UNSUPPORTED", "ROOT_USER_INACTIVE", "ROOT_EMAIL_NOT_VERIFIED", "KYC_APPROVAL_MISSING", "PROFILE_MISMATCH", "COMPANY_TYPE_UNSUPPORTED", "EMAIL_DOMAIN_NOT_ALLOWED"

## Response default fields (application/json):

  - `code` (string)

  - `message` (string)


## Response 401 fields

## Response 403 fields

## Response 429 fields

## Response 500 fields

## Response 503 fields