---
title: "Create Entity"
method: POST
path: "/v3/entity"
---

# Create Entity

`POST /v3/entity`

Create a sub-entity for your account

## Request body

- object
  - `name` string, required — Name of the entity
  - `type` 'sole_proprietorship' | 'company' | 'non_profit' | 'government_entity' | 'individual', required — Type of the entity
  - `email` string — Email of the entity
  - `description` string — A short description of the business
  - `registration_address` Address — Address details
    - `line1` string — Address Line 1
    - `line2` string — Address Line 2
    - `city` string — Address city
    - `state` string — Address state
    - `country` string — Address country (ISO 3166-1 alpha-2 country code)
    - `postal_code` string — Postal Code
  - `operating_address` Address — Address details
    - `line1` string — Address Line 1
    - `line2` string — Address Line 2
    - `city` string — Address city
    - `state` string — Address state
    - `country` string — Address country (ISO 3166-1 alpha-2 country code)
    - `postal_code` string — Postal Code
  - `phone` Phone — Phone contact details
    - `calling_code` string — Calling country code (for example, '1' for United States, '91' for India)
    - `number` string — Phone Number
  - `tax_id` string — Tax ID of the entity
  - `vertical` string — Industry Vertical
  - `website` string — Entity website
  - `registration_number` string — Business Registration Number
  - `registration_date` string — Business Registration Date, Format DD-MM-YYYY
  - `submit` boolean — true or false, default is false
  - `statement_descriptor` string — Statement Descriptor for the entity
  - `representatives` object[] — Representative Details
    - `first_name` string, required — Representative first name
    - `last_name` string — Representative last name
    - `date_of_birth` string, required — Date of birth of the representative, in format "DD-MM-YYYY"
    - `address` Address — Address details
      - `line1` string — Address Line 1
      - `line2` string — Address Line 2
      - `city` string — Address city
      - `state` string — Address state
      - `country` string — Address country (ISO 3166-1 alpha-2 country code)
      - `postal_code` string — Postal Code
    - `nationality` string, required — Two-letter country code, in ISO format
    - `phone` Phone — Phone contact details
      - `calling_code` string — Calling country code (for example, '1' for United States, '91' for India)
      - `number` string — Phone Number
    - `ownership_percentage` number, double, required — Ownership percent, two digits after decimal is allowed
    - `roles` string[], required — Representative's role. Can be one or more than one of these: 'director', 'shareholder', 'beneficial_owner', 'authorised_signatory', 'authorised_representative', or 'other'
    - `documents` object[] — Documents for the representatives
      - `type` 'proof_of_identity' | 'proof_of_address' | 'registration_documents' | 'article_of_incorporation' | 'shareholder_registry' | 'identity' | 'address' | 'other', required — Type of document
      - `sub_type` 'drivers_license' | 'national_id' | 'passport' | 'other' | 'driving_license', required — Sub Type of the document
      - `tag` 'AddressProofDoc' | 'identityProofTypeFrontDoc' | 'identityProofTypeBackDoc' | 'additionalDocs', required — Document type characteristics
      - `description` string, required — A short description of the document submitted
      - `file_name` string, required — Name of the file uploaded
      - `url` string, required — Dynamically downloadable URL
  - `individual` object — Individual Details
    - `national_identification_number` object — National identification details
      - `type` 'passport' | 'driving_license' | 'national_id' | 'tax_id' | 'residence_permit' | 'other' | 'asylum_registration_card' | 'consular_id' | 'immigration_status_document' | 'indigenous_card' | 'insurance_card' | 'international_driving_license' | 'municipal_identity_card' | 'national_health_id' | 'postal_identity_card' | 'private_operators_card' | 'professional_qualification_card' | 'proof_of_citizenship' | 'residence_status_document' | 'service_id_card' | 'social_security_card' | 'visa' | 'voter_id' | 'work_permit' — Type of identification document
      - `number` string — Identification document number
      - `issuer` object — Issuing authority details
        - `country` string — ISO 3166-1 alpha-2 country code of the issuing country
        - `state` string — State of the issuing authority (if applicable)
      - `expiration` string — Expiration date of the identification document (YYYY-MM-DD)
      - `country_of_citizenship` string — ISO 3166-1 alpha-2 country code of the individual's citizenship
    - `date_of_birth` string — Date of Birth in ISO format (YYYY-MM-DD)
    - `nationality` string — Two-letter country code (ISO 3166-1 alpha-2)
    - `profession` object — Occupation details of the individual
      - `occupation` string — Occupation title. Required if isco_code is not provided. Max 100 characters.
      - `isco_code` string — 4-digit ISCO occupation code. Required if occupation is not provided.
      - `industry` string — Industry sector. Max 100 characters.
      - `employment_status` 'employed' | 'self_employed' | 'unemployed' | 'student' | 'retired' | 'homemaker' | 'other' — Employment status of the individual
    - `source_of_funds` object — Source of funds information
      - `primary_source` 'salary' | 'business_income' | 'investment_income' | 'inheritance' | 'savings' | 'gift' | 'pension' | 'rental_income' | 'sale_of_assets' | 'loan' | 'scholarship' | 'commission' | 'royalty' | 'other' — Primary source of funds
      - `description` string — Description of source of funds. Required when primary_source is "other". Max 500 characters.
    - `employment_details` object — Employment details of the individual
      - `employer_name` string, required — Name of the employer. Max 200 characters.
      - `designation` string, required — Job title or designation. Max 100 characters.
  - `transaction_profile` object — Expected transaction profile of the entity
    - `monthly_expected_transactions_value` integer — Expected total value of transactions per month (in smallest currency unit)
    - `monthly_expected_transaction_volume` integer — Expected number of transactions per month
    - `expected_transaction_countries` string[] — List of ISO 3166-1 alpha-2 country codes for expected transaction countries
    - `expected_transaction_currencies` string[] — List of ISO 4217 currency codes for expected transaction currencies
    - `customer_risk` 'low' | 'medium' | 'high' — Risk classification of the customer
  - `documents` object[] — Documents for the entity
    - `type` 'proof_of_identity' | 'proof_of_address' | 'registration_documents' | 'article_of_incorporation' | 'shareholder_registry' | 'identity' | 'business' | 'other' | 'address' | 'source_of_wealth' | 'person', required — Type of the document
    - `sub_type` 'drivers_license' | 'national_id' | 'passport' | 'other' | 'driving_license', required — Subtype of the document
    - `tag` 'registrationProofDoc' | 'AddressProofDoc' | 'beneficialOwnershipDoc' | 'bankStatementProofDoc' | 'previousCardStatementProofDoc' | 'sampleInvoicesDoc' | 'additionalDocs', required — Additonal description about the type
    - `file_name` string, required — Name of the file
    - `description` string, required — A short description about the document uploaded
    - `url` string, required — Dynamically downloadable URL
  - `reference_id` string — Merchant's internal reference ID for the entity
  - `metadata` string, json — Set of key-value pairs to attach to the entity
  - `relationship` 'customer' | 'vendor' | 'fourth_party' | 'other' — The entity's relationship with you
  - `purpose_of_use` string[] — The capabilities the entity intends to use. Possible values - `collect`, `payout`. In case you only want to add global collection account on behalf of the entity, pass collect. If you want to only make payouts on behalf of the entity, use `payout`. In case you want to do both, pass `["collect","payout"]`
  - `onboarding_package_url` string — Link to the complete onboarding package for the entity
  - `on_behalf_of` string — ID of the entity this entity is created on behalf of

## Response `200`

200

- object
  - `status` string — Indicates the result of the API call.
  - `message` string — Optional message providing context or additional information about the response. Can be empty.
  - `data` object — Details of the entity or KYB record returned in the response.
    - `approval_status` string — Current approval status of the entity record.
    - `approval_status_description` string — Additional description or remarks regarding the approval status.
    - `approved_at` string — Timestamp when the entity was approved (ISO 8601 format). Can be null if not yet approved.
    - `created_at` string — Timestamp when the entity record was created (ISO 8601 format).
    - `description` string — Description or additional information about the entity.
    - `documents` object[] — List of documents associated with this entity, such as proof of address or identity.
      - `description` string
      - `document_id` string
      - `file_name` string
      - `sub_type` string
      - `tag` string
      - `type` string
      - `updated_at` string
      - `url` string
    - `email` string — Email address associated with the entity. May be empty.
    - `id` string — Unique identifier for the entity record.
    - `metadata` Metadata, nullable — Custom metadata key-value pairs attached to the object
    - `name` string — Name of the entity or individual.
    - `object` string
    - `on_behalf_of` string — Identifier of another entity on whose behalf this record is created, if applicable.
    - `onboarding_package_url` string — Link to the onboarding package for this entity. May be empty.
    - `operating_address` string — Operating address details for the entity. May be null or empty if not provided.
    - `pending_documents` object[] — List of documents pending submission or verification.
    - `phone` Phone — Phone contact details
      - `calling_code` string — Calling country code (for example, '1' for United States, '91' for India)
      - `number` string — Phone Number
    - `purpose_of_use` string[] — List of purposes for which the entity account is used.
    - `reference_id` string — External reference identifier linked to this entity.
    - `registration_address` Address — Address details
      - `line1` string — Address Line 1
      - `line2` string — Address Line 2
      - `city` string — Address city
      - `state` string — Address state
      - `country` string — Address country (ISO 3166-1 alpha-2 country code)
      - `postal_code` string — Postal Code
    - `registration_date` string — Date of business registration or incorporation. May be empty.
    - `registration_number` string — Official registration number of the entity.
    - `rejected_at` string — Timestamp when the entity was rejected, if applicable. May be null or empty.
    - `relationship` string — Defines the relationship type of this entity (e.g., customer, partner).
    - `representatives` object[] — List of authorized representatives associated with the entity, such as directors, beneficial owners, or shareholders.
      - `person_id` string — Unique identifier for the representative.
      - `first_name` string — The first name of the representative.
      - `last_name` string — The last name of the representative.
      - `date_of_birth` string — Date of birth of the representative (ISO 8601).
      - `address` Address — Address details
        - `line1` string — Address Line 1
        - `line2` string — Address Line 2
        - `city` string — Address city
        - `state` string — Address state
        - `country` string — Address country (ISO 3166-1 alpha-2 country code)
        - `postal_code` string — Postal Code
      - `nationality` string — Two-letter ISO country code for nationality.
      - `phone` Phone — Phone contact details
        - `calling_code` string — Calling country code (for example, '1' for United States, '91' for India)
        - `number` string — Phone Number
      - `ownership_percentage` number — The ownership percentage held by this representative in the entity.
      - `roles` string[] — Roles or designations of the representative within the entity.
      - `documents` object[] — List of documents submitted for this representative.
        - `description` string
        - `document_id` string
        - `file_name` string
        - `sub_type` string
        - `tag` string
        - `type` string
        - `updated_at` string
        - `url` string
    - `source_of_wealth` string — Details of the entity’s source of wealth, if applicable. May be empty.
    - `statement_descriptor` string — Custom statement descriptor for this entity’s transactions.
    - `submit` boolean — Indicates whether the KYB submission has been completed.
    - `submitted_at` string — Timestamp when the entity submission was made.
    - `tax_id` string — Tax identification number of the entity.
    - `type` string — Type of entity (e.g., individual, business).
    - `vertical` string — Industry vertical of the entity, if specified.
    - `website` string — Website URL of the entity.

## Other responses

- `400` — Bad Request

---

[API](https://skmtc.net/tazapay/apis/sandbox.md) · [All operations](https://skmtc.net/tazapay/apis/sandbox/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/tazapay/sandbox/versions/bf5f4b8f6f5d/schema)