---
title: "Create a new sub account"
method: POST
path: "/accounts"
tags: ["Accounts"]
---

# Create a new sub account

`POST /accounts`

This is for registering new users onto your platform that will act as one of your 'sub' accounts

## Request body

- CreateSubAccountRequestBody
  - `onboardingFlow` 'Hosted' | 'NonHosted', nullable — The flow that this account will use to be onboarded. `Hosted` accounts will be onboarded via the Ryft portal and cannot be updated via the API. `NonHosted` accounts will be onboarded via the API and will not have access to the Ryft portal. Once defined this value cannot be changed. Defaults to `Hosted` if not provided.
  - `email` string, email, nullable — The main email address for the sub account. Required if `onboardingFlow` is `Hosted` and you are not supplying the 'entityType', otherwise you can supply this in the 'business'/'individual' block. Not required if `onboardingFlow` is `NonHosted` - any value supplied will be ignored.
  - `entityType` 'Business' | 'Individual', nullable — The type of entity that this account is - either a registered business or an individual person (sole trader). Optional if `onboardingFlow` is `Hosted`, though certain actions will be restricted until this is provided (creating persons, payout methods and therefore payouts). Optional if `onboardingFlow` is `NonHosted`, any values supplied can be updated by the account via the Ryft portal.
  - `business` object, nullable — The details of the business. Required if `entityType` is `Business`
    - `name` string — The legal name of the business (not the operating/trade name).
    - `type` 'Corporation' | 'GovernmentEntity' | 'Charity' | 'LimitedPartnership' | 'PrivateCompany' | 'PublicCompany'
    - `registrationNumber` string — The registration number of the business, assigned by a government body. If the business is not registered then they should be created with `entityType` set to `Individual`
    - `registrationDate` string, nullable — The date when the business was registered
    - `registeredAddress` object — The address where the business is registered
      - `lineOne` string — First line of the address. It must satisfy the following regex pattern: ^[A-Za-z0-9 !&'()+,-./:;]*$
      - `lineTwo` string, nullable — Second line of the address. It must satisfy the following regex pattern: ^[A-Za-z0-9 !&'()+,-./:;]*$
      - `city` string — The address city/town It must satisfy the following regex pattern: ^[A-Za-z0-9 !&'()+,-./:;]*$
      - `country` string — The two-character ISO country code
      - `postalCode` string — The postal/zip code of the address. It must satisfy the following regex pattern: ^[A-Za-z0-9 -]*$
      - `region` string, nullable — The state/county/province/region Required if the address is in the US/Canada and must be a 2-character ISO state/province code Otherwise it must satisfy the following regex pattern: ^[A-Za-z0-9 !&'()+,-./:;]*$
    - `contactEmail` string, email — An email address used in case we need to contact you. This takes precedence over the 'email' on the account itself.
    - `phoneNumber` string, nullable — The phone number of the business, in E.164 format
    - `tradingName` string, nullable — The trading/operating name of the business
    - `tradingAddress` object, nullable — The address where the business trades/operates
      - `lineOne` string — First line of the address. It must satisfy the following regex pattern: ^[A-Za-z0-9 !&'()+,-./:;]*$
      - `lineTwo` string, nullable — Second line of the address. It must satisfy the following regex pattern: ^[A-Za-z0-9 !&'()+,-./:;]*$
      - `city` string — The address city/town It must satisfy the following regex pattern: ^[A-Za-z0-9 !&'()+,-./:;]*$
      - `country` string — The two-character ISO country code
      - `postalCode` string — The postal/zip code of the address. It must satisfy the following regex pattern: ^[A-Za-z0-9 -]*$
      - `region` string, nullable — The state/county/province/region Required if the address is in the US/Canada and must be a 2-character ISO state/province code Otherwise it must satisfy the following regex pattern: ^[A-Za-z0-9 !&'()+,-./:;]*$
    - `tradingCountries` string[], nullable — The countries where the business trades/operates
    - `websiteUrl` string, nullable — The website url of the business
  - `individual` object, nullable — The details of the person. Required if `entityType` is `Individual`
    - `firstName` string — The first name of the individual
    - `middleNames` string, nullable — The middle names of the individual
    - `lastName` string — The last name / surname of the individual
    - `email` string, email — The email address of the individual. This takes precedence over the 'email' on the account itself.
    - `dateOfBirth` string — The date of birth of the individual, in format YYYY-MM-DD
    - `countryOfBirth` string, nullable — The two-character ISO 3166 country code of birth of the individual
    - `gender` 'Female' | 'Male' — The gender of the individual. International regulations require either `Female` or `Male`
    - `nationalities` string[] — The countries of citizenship or nationality of the individual
    - `address` object — The address of the individual
      - `lineOne` string — First line of the address. It must satisfy the following regex pattern: ^[A-Za-z0-9 !&'()+,-./:;]*$
      - `lineTwo` string, nullable — Second line of the address. It must satisfy the following regex pattern: ^[A-Za-z0-9 !&'()+,-./:;]*$
      - `city` string — The address city/town It must satisfy the following regex pattern: ^[A-Za-z0-9 !&'()+,-./:;]*$
      - `country` string — The two-character ISO country code
      - `postalCode` string — The postal/zip code of the address. It must satisfy the following regex pattern: ^[A-Za-z0-9 -]*$
      - `region` string, nullable — The state/county/province/region Required if the address is in the US/Canada and must be a 2-character ISO state/province code Otherwise it must satisfy the following regex pattern: ^[A-Za-z0-9 !&'()+,-./:;]*$
    - `phoneNumber` string, nullable — The phone number of the individual, in E.164 format
  - `metadata` object, nullable — use this parameter to attach key-value data to the account. These will be sent with any associated account events on your webhooks. You can have a maximum of 5 pieces of metadata.
  - `settings` object, nullable — Settings for the account.
    - `payouts` object — Customise how payouts function for the account
      - `schedule` object
        - `type` 'Automatic' | 'Manual' — `Automatic` - funds will be paid out by Ryft on the agreed basis (e.g. daily) `Manual` - funds will be paid out via explicit requests to our /payouts API By default all accounts are configured to `Automatic`. **Note:** that you can only update this setting for accounts onboarded through the `NonHosted` flow.
  - `termsOfService` object, nullable — Use this parameter to indicate acceptance of our terms & conditions by the sub account.
    - `acceptance` object
      - `ipAddress` string — The IP address of the user who has accepted the terms & conditions
      - `userAgent` string, nullable — The User Agent of the user's browser who has accepted the terms & conditions
      - `when` number, nullable — The time (in epoch seconds) when the terms & conditions were accepted. If omitted, we will set this to the time the request was received.

## Response `200`

The account was created successfully

- AccountResponse
  - `id` string — The ID of the account
  - `type` 'Standard' | 'Sub' — The type of account
  - `status` 'ActionRequired' | 'Unverified' | 'VerificationPending' | 'Verified', nullable — The overall status of the account
  - `actionsRequired` object[], nullable — A list of actions required by the user when the status is 'ActionRequired', each accompanied by a description. DEPRECATED - if you wish to determine if actions are required before payouts can be sent out, check: - if `verification.status` is `Required` on this response - if `status` is `Invalid` on any payout methods under /v1/accounts/{id}/payout-methods
    - `action` 'PayoutDetailsRequired' | 'PayoutMethodRequired' | 'PayoutMethodInvalid' | 'VerificationRequired' | 'AccountLocked' — The possible actions required to take if an account is in the 'ActionRequired' status
    - `description` string — The description of the action that is required by the user
  - `frozen` boolean — A flag to determine whether or not the account is frozen. We may temporarily mark an account as frozen if we detect any potential fraudulent activity. Payments can still be taken however payouts will be disabled, contact us to resolve the issue. DEPRECATED - this flag is no longer in use and will always return false, though payouts may still be disabled if we detect fraudulent activity.
  - `email` string, email, nullable — The account's email address
  - `onboardingFlow` 'Hosted' | 'NonHosted'
  - `entityType` 'Business' | 'Individual', nullable
  - `business` object, nullable — The details of the business
    - `name` string — The legal name of the business (not the operating/trade name).
    - `type` 'Corporation' | 'GovernmentEntity' | 'Charity' | 'LimitedPartnership' | 'PrivateCompany' | 'PublicCompany'
    - `registrationNumber` string, nullable — The registration number of the business, assigned by a government body.
    - `registrationDate` string, nullable — The date when the business was registered
    - `registeredAddress` object — The address where the business is registered
      - `lineOne` string, nullable — First line of the address. It must satisfy the following regex pattern: ^[A-Za-z0-9 !&'()+,-./:;]*$
      - `lineTwo` string, nullable — Second line of the address. It must satisfy the following regex pattern: ^[A-Za-z0-9 !&'()+,-./:;]*$
      - `city` string, nullable — The address city/town It must satisfy the following regex pattern: ^[A-Za-z0-9 !&'()+,-./:;]*$
      - `country` string — The two-character ISO country code
      - `postalCode` string, nullable — The postal/zip code of the address. It must satisfy the following regex pattern: ^[A-Za-z0-9 -]*$
      - `region` string, nullable — The state/county/province/region Required if the address is in the US/Canada and must be a 2-character ISO state/province code Otherwise it must satisfy the following regex pattern: ^[A-Za-z0-9 !&'()+,-./:;]*$
    - `contactEmail` string, email — The email address used in case we need to contact you. This takes precedence over the 'email' on the account itself.
    - `phoneNumber` string, nullable — The phone number of the business, in E.164 format
    - `tradingName` string, nullable — The trading/operating name of the business
    - `tradingAddress` object, nullable — The address where the business trades/operates
      - `lineOne` string, nullable — First line of the address. It must satisfy the following regex pattern: ^[A-Za-z0-9 !&'()+,-./:;]*$
      - `lineTwo` string, nullable — Second line of the address. It must satisfy the following regex pattern: ^[A-Za-z0-9 !&'()+,-./:;]*$
      - `city` string, nullable — The address city/town It must satisfy the following regex pattern: ^[A-Za-z0-9 !&'()+,-./:;]*$
      - `country` string — The two-character ISO country code
      - `postalCode` string, nullable — The postal/zip code of the address. It must satisfy the following regex pattern: ^[A-Za-z0-9 -]*$
      - `region` string, nullable — The state/county/province/region Required if the address is in the US/Canada and must be a 2-character ISO state/province code Otherwise it must satisfy the following regex pattern: ^[A-Za-z0-9 !&'()+,-./:;]*$
    - `tradingCountries` string[], nullable — The countries where the business trades/operates
    - `websiteUrl` string, nullable — The website url of the business
    - `documents` AccountDocumentResponse[], nullable — The KYB documents
      - `type` 'BankStatement' | 'BusinessRegistration' | 'CreditCardStatement' | 'DriversLicense' | 'LetterOfAuthorization' | 'NationalId' | 'OfficialGovernmentLetter' | 'Passport' | 'PropertyTaxAssessment' | 'TaxReturn' | 'UtilityBill' — The type of document, these are only applicable for certain entities: - 'LetterOfAuthorization' is only applicable for Persons, when the 'Authorization' category is required - 'BankStatement', 'CreditCardStatement', 'OfficialGovernmentLetter', 'PropertyTaxAssessment', 'TaxReturn', 'UtilityBill' are only applicable for Individuals or Persons, when the 'ProofOfAddress' category is required - 'BusinessRegistration' is only applicable for Businesses, when the 'ProofOfBusiness' category is required - 'DriversLicense', 'NationalId', 'Passport' are only applicable for Individuals or Persons, when the 'ProofOfIdentity' category is required
      - `category` 'Authorization' | 'ProofOfAddress' | 'ProofOfBusiness' | 'ProofOfIdentity' — The category of document, these are only applicable for certain entities: - `Authorization` is only applicable for Persons - `ProofOfAddress` is only applicable for Individuals or Persons - `ProofOfBusiness` is only applicable for Businesses - `ProofOfIdentity` is only applicable for Individuals or Persons
      - `front` string — The ID of the uploaded file that shows the front of the document.
      - `back` string, nullable — The ID of the uploaded file that shows the back of the document. Required if uploading a `DriversLicense` or `NationalId`.
      - `status` 'Invalid' | 'Pending' | 'Valid'
      - `invalidReason` string, nullable — The reason for the document being invalid
      - `country` string, nullable — The two-character ISO 3166 country code of the document. Only present historically on documents with `type`: `Passport`, `DriversLicense`, `NationalId`
      - `assignedTimestamp` integer — The epoch timestamp (seconds) when the document was first assigned to the account
      - `lastUpdatedTimestamp` integer — The epoch timestamp (seconds) when the document was last updated
  - `individual` object, nullable — The details of the individual
    - `firstName` string — The first name of the individual
    - `middleNames` string, nullable — The middle names of the individual
    - `lastName` string — The last name / surname of the individual
    - `email` string, email — The email address of the individual. This takes precedence over the 'email' on the account itself.
    - `dateOfBirth` string — The date of birth of the individual, in format YYYY-MM-DD
    - `countryOfBirth` string, nullable — The two-character ISO 3166 country code of birth of the individual
    - `gender` 'Female' | 'Male', nullable — The gender of the individual. International regulations require either `Female` or `Male`
    - `nationalities` string[], nullable — The countries of citizenship or nationality of the individual
    - `address` object, nullable — The address of the individual
      - `lineOne` string, nullable — First line of the address. It must satisfy the following regex pattern: ^[A-Za-z0-9 !&'()+,-./:;]*$
      - `lineTwo` string, nullable — Second line of the address. It must satisfy the following regex pattern: ^[A-Za-z0-9 !&'()+,-./:;]*$
      - `city` string, nullable — The address city/town It must satisfy the following regex pattern: ^[A-Za-z0-9 !&'()+,-./:;]*$
      - `country` string — The two-character ISO country code
      - `postalCode` string, nullable — The postal/zip code of the address. It must satisfy the following regex pattern: ^[A-Za-z0-9 -]*$
      - `region` string, nullable — The state/county/province/region Required if the address is in the US/Canada and must be a 2-character ISO state/province code Otherwise it must satisfy the following regex pattern: ^[A-Za-z0-9 !&'()+,-./:;]*$
    - `phoneNumber` string, nullable — The phone number of the individual, in E.164 format
    - `documents` AccountDocumentResponse[], nullable — The KYC documents
      - `type` 'BankStatement' | 'BusinessRegistration' | 'CreditCardStatement' | 'DriversLicense' | 'LetterOfAuthorization' | 'NationalId' | 'OfficialGovernmentLetter' | 'Passport' | 'PropertyTaxAssessment' | 'TaxReturn' | 'UtilityBill' — The type of document, these are only applicable for certain entities: - 'LetterOfAuthorization' is only applicable for Persons, when the 'Authorization' category is required - 'BankStatement', 'CreditCardStatement', 'OfficialGovernmentLetter', 'PropertyTaxAssessment', 'TaxReturn', 'UtilityBill' are only applicable for Individuals or Persons, when the 'ProofOfAddress' category is required - 'BusinessRegistration' is only applicable for Businesses, when the 'ProofOfBusiness' category is required - 'DriversLicense', 'NationalId', 'Passport' are only applicable for Individuals or Persons, when the 'ProofOfIdentity' category is required
      - `category` 'Authorization' | 'ProofOfAddress' | 'ProofOfBusiness' | 'ProofOfIdentity' — The category of document, these are only applicable for certain entities: - `Authorization` is only applicable for Persons - `ProofOfAddress` is only applicable for Individuals or Persons - `ProofOfBusiness` is only applicable for Businesses - `ProofOfIdentity` is only applicable for Individuals or Persons
      - `front` string — The ID of the uploaded file that shows the front of the document.
      - `back` string, nullable — The ID of the uploaded file that shows the back of the document. Required if uploading a `DriversLicense` or `NationalId`.
      - `status` 'Invalid' | 'Pending' | 'Valid'
      - `invalidReason` string, nullable — The reason for the document being invalid
      - `country` string, nullable — The two-character ISO 3166 country code of the document. Only present historically on documents with `type`: `Passport`, `DriversLicense`, `NationalId`
      - `assignedTimestamp` integer — The epoch timestamp (seconds) when the document was first assigned to the account
      - `lastUpdatedTimestamp` integer — The epoch timestamp (seconds) when the document was last updated
  - `verification` AccountVerification
    - `status` 'NotRequired' | 'Required' | 'PendingVerification' | 'Verified'
    - `requiredFields` object[], nullable — A list of fields that must be provided for verification. For `Business` entities this will detail the fields required for the business only, it will not list requirements for persons.
      - `name` string — The name of the field
    - `requiredDocuments` object[], nullable — A list of documents that must be provided for verification. For `Business` entities this will detail the documents required for the business only, it will not list requirements for persons.
      - `category` 'Authorization' | 'ProofOfAddress' | 'ProofOfBusiness' | 'ProofOfIdentity' — The category of document, these are only applicable for certain entities: - `Authorization` is only applicable for Persons - `ProofOfAddress` is only applicable for Individuals or Persons - `ProofOfBusiness` is only applicable for Businesses - `ProofOfIdentity` is only applicable for Individuals or Persons
      - `types` AccountDocumentType[] — The types of document available to upload in this category. The types will be as follows for each category: - `Authorization`: - `LetterOfAuthorization` - `ProofOfAddress`: - `BankStatement` - `CreditCardStatement` - `OfficialGovernmentLetter` - `PropertyTaxAssessment` - `TaxReturn` - `UtilityBill` - `ProofOfBusiness`: - `BusinessRegistration` - `ProofOfIdentity`: - `DriversLicense` - `NationalId` - `Passport`
      - `quantity` integer — The minimum number of documents required of this category
    - `errors` object[], nullable — Details the errors returned if verification was unsuccessful. This could contain documents and/or fields.
      - `code` 'InvalidDocument' | 'InvalidField'
      - `id` string — For `InvalidDocument` this will be the file id of the document that is invalid For `InvalidField` this will be the name of the field that is invalid
      - `description` string — A description of why this document/field was invalid
    - `persons` object, nullable — Details of the overall requirements for persons in the business. Only present if `entityType` is `Business`
      - `status` 'NotRequired' | 'Required' | 'PendingVerification' | 'Verified'
      - `required` object[] — The minimum required persons that must be created for verification. Use the Persons API to create the person and provide the relevant details so we can verify them.
        - `role` 'BusinessContact' | 'Director' | 'UltimateBeneficialOwner' — The role that a person has in the business: `BusinessContact`: An individual designated as the main contact for the business. When verifying, a letter of authorization may be required if this person is not also a director. `Director`: An individual who is listed as one of the company's directors. `UltimateBeneficialOwner`: An individual who owns at least 25% of the shares, voting rights or other interests.
        - `quantity` integer — The minimum number of persons of this role that are required to be created
  - `metadata` object, nullable — use this parameter to attach key-value data to the account. These will be sent with any associated account events on your webhooks. You can have a maximum of 5 pieces of metadata.
  - `settings` object — Settings for the account
    - `payouts` object
      - `schedule` object
        - `type` 'Automatic' | 'Manual' — The basis on which funds are paid out to the account
  - `capabilities` AccountCapabilities
    - `visaPayments` AccountCapability
      - `status` 'NotRequested' | 'Pending' | 'Disabled' | 'Enabled'
      - `requested` boolean
      - `requiredFields` object[], nullable — A list of fields that must be provided prior to requesting the capability.
        - `name` string — The name of the field
      - `disabledReason` string, nullable — If the capability is `Disabled`, this may contain an optional description explaining why.
      - `requestedTimestamp` integer — The epoch timestamp (seconds) when the capability was requested
      - `lastUpdatedTimestamp` integer — The epoch timestamp (seconds) when the capability was last updated
    - `mastercardPayments` AccountCapability
      - `status` 'NotRequested' | 'Pending' | 'Disabled' | 'Enabled'
      - `requested` boolean
      - `requiredFields` object[], nullable — A list of fields that must be provided prior to requesting the capability.
        - `name` string — The name of the field
      - `disabledReason` string, nullable — If the capability is `Disabled`, this may contain an optional description explaining why.
      - `requestedTimestamp` integer — The epoch timestamp (seconds) when the capability was requested
      - `lastUpdatedTimestamp` integer — The epoch timestamp (seconds) when the capability was last updated
    - `amexPayments` AccountCapability
      - `status` 'NotRequested' | 'Pending' | 'Disabled' | 'Enabled'
      - `requested` boolean
      - `requiredFields` object[], nullable — A list of fields that must be provided prior to requesting the capability.
        - `name` string — The name of the field
      - `disabledReason` string, nullable — If the capability is `Disabled`, this may contain an optional description explaining why.
      - `requestedTimestamp` integer — The epoch timestamp (seconds) when the capability was requested
      - `lastUpdatedTimestamp` integer — The epoch timestamp (seconds) when the capability was last updated
    - `inPersonPayments` AccountCapability
      - `status` 'NotRequested' | 'Pending' | 'Disabled' | 'Enabled'
      - `requested` boolean
      - `requiredFields` object[], nullable — A list of fields that must be provided prior to requesting the capability.
        - `name` string — The name of the field
      - `disabledReason` string, nullable — If the capability is `Disabled`, this may contain an optional description explaining why.
      - `requestedTimestamp` integer — The epoch timestamp (seconds) when the capability was requested
      - `lastUpdatedTimestamp` integer — The epoch timestamp (seconds) when the capability was last updated
  - `termsOfService` object, nullable
    - `acceptance` TermsOfServiceAcceptance
      - `ipAddress` string — The IP address of the user who accepted the terms & conditions
      - `userAgent` string, nullable — The User Agent of the user's browser who has accepted the terms & conditions
      - `when` number — The time (in epoch seconds) when the terms & conditions were accepted.
  - `createdTimestamp` integer — The epoch timestamp (seconds) when the account was created

## Other responses

- `400` — One or more inputs are invalid
- `409` — This operation has already been performed
- `500` — An unexpected error occurred when executing this request

---

[API](https://skmtc.net/ryftpay/apis/ryft-payment-api.md) · [All operations](https://skmtc.net/ryftpay/apis/ryft-payment-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/ryftpay/ryft-payment-api/versions/a042f64d4305/schema)