Overview

Use this method to import an applicant profile into the Sumsub system when you already have the applicant’s data and review results. For example, when you already have a list of verified applicants and want to recheck them or to maintain data consistency.

Unlike the standard method of creating an applicant profile, this approach enables you to instantly submit the review result from your side and specify whether the applicant is approved or rejected.

Specifics of importing company applicants data

When making a request to import company applicant data, the fixedInfo object should include the companyInfo object. The companyInfo object attributes are required to properly validate the company data during verification. This information is not mandatory to be submitted at creating an applicant profile, but make sure to provide it before requesting a check.

`companyInfo` arguments

The following table explains the companyInfo object attributes representing general data about the company, such as the company name, location, and country of registration, legal entity type, contacts, and other details.

Field	Type	Required	Description
`companyName`	String	Yes	The name of the company. There is no length limit for this field.
`registrationNumber`	String	No	Unique number assigned to the company when it was registered as a legal entity.
`country`	String	Yes	ISO 3166-1 alpha-3 code of the country where the company is legally registered (for example, `DEU` or `GBR`).
`alternativeNames`	Array of strings	No	List of alternative names of the company: a brand name, business trademark, name in a local language, and so on. For example, "Megacorp" instead of "The Megacorp ABC Inc."
`legalAddress`	String	No	Address a legal entity uses to register with a legal authority.
`incorporatedOn`	Date	No	Date of company incorporation (ISO 8601 format `yyyy-MM-dd`, for example,`2001-09-25`).
`type`	String	No	Type of legal entity. For example, `Private Company Limited by Shares`, `Public Limited Company`, `Limited Partnership`, and so on.
`email`	String	No	Company email address (RFC 5321/5322 format).
`phone`	String	No	Company phone number (ITU-T E.164 format).
`controlScheme`	String	No	Description of the control scheme of the company ownership or a group of entities.
`taxId`	String	No	Taxpayer registration number/Code of taxpayer registration. ⚠️This field has a country-specific format.
`leiCode`	String	No	Legal Entity Identifier (LEI) code. Refers to the public identifier from the financial entities registry.
`registrationLocation`	String	No	City, town, or another location where the company was registered.
`website`	String	No	Website URL of the company.
`postalAddress`	String	No	Company postal address.
`address`	Object	No	Represents the company address.
`skippedTypes`	Array of strings	No	Includes the required values (`shareholder`, `ubo`, `representative`, `director`) to verify a company applicant without the corresponding entities specified in the company profile. ⚠️ Applicable to the `fixedInfo` object only.
`noDocs`	Boolean	No	Indicates whether company documents must be uploaded to proceed verification. `true` — uploading company documents is optional. `false` (default) — at least one document must be uploaded.

`address` arguments

The following table explains the available details of the company address.

Field	Type	Required	Description
`country`	String	No	ISO 3166-1 alpha-3 country code (for example, `DEU`, `GBR`, `ARG`, and so on).
`postCode`	String	No	Address postal code.
`state`	String	No	State, region, district, county, or another territorial entity inside a country.
`town`	String	No	City, town, or another settlement.
`street`	String	No	Street name.
`subStreet`	String	No	Additional information related to the street. This could be a house number or any other details.

Request examples

curl -X POST 'https://api.sumsub.com/resources/applicants/-/ingestCompleted?levelName=basic-kyc-level' \
  -H 'Content-Type: application/json' \
  -d '{
      "externalUserId": "someClientUserId",
      "info": {
        "firstName": "John",
        "lastName": "Snow",
        "country": "GBR"
      },
      "review": {
        "createDate": "2022-11-21 08:25:32+0000",
        "reviewDate": "2022-11-21 08:25:36+0000",
        "reviewResult": {
           "moderationComment": "",
           "clientComment": "",
           "reviewAnswer": "GREEN"
        },
        "reviewStatus": "completed"
      }
   }'

curl -X POST 'https://api.sumsub.com/resources/applicants/-/ingestCompleted?levelName=basic-kyb-level' \
  -H 'Content-Type: application/json' \
  -d '{
        "externalUserId": "someClientUserIdCompany",
        "fixedInfo": {
          "companyInfo": {
            "companyName": "COMPANY NAME LTD",
            "registrationNumber" : "09688671",
            "country" : "GBR",
            "incorporatedOn" : "2015-01-01",
            "type" : "Private Company Limited by Shares",
            "email" : "[email protected]",
            "phone" : "+12366020172",
            "website" : "example.com"
          }
        },
        "review": {
          "createDate": "2022-11-21 08:25:32+0000",
          "reviewDate": "2022-11-21 08:25:36+0000",
          "reviewResult": {
             "moderationComment": "",
             "clientComment": "",
             "reviewAnswer": "GREEN"
          },
          "reviewStatus": "completed"
        }
      }'

Response explained

The response is a JSON file representing the applicant profile with augmented and structured information created as a result of importing applicant data. The existence of some fields depends on the documents submitted for verification and verification regulations.

You can see the response structure and possible content with descriptions on the following page.

Response examples

If the request is successfully sent and processed, you will get a response like one of those below.

{
  "id": "5b594ade0a975a36c9349e66",
  "createdAt": "2020-06-24 05:05:14",
  "clientId": "your_cool_id",
  "inspectionId": "5b594ade0a975a36c9379e67",
  "externalUserId": "SomeExternalUserId",
  "info": {
    "firstName": "DANIEL",
    "firstNameEn": "DANIEL",
    "lastName": "BROOKS",
    "lastNameEn": "BROOKS",
    "aliasName": "DAN BROOKS",
    "dob": "1989-07-16",
    "country": "DEU",
    "idDocs": [
      {
        "idDocType": "ID_CARD",
        "country": "DEU",
        "firstName": "DANIEL",
        "firstNameEn": "DANIEL",
        "lastName": "BROOKS",
        "lastNameEn": "BROOKS",
        "aliasName": "DAN BROOKS",
        "validUntil": "2028-09-04",
        "number": "LGXX359T8",
        "dob": "1989-07-16",
        "mrzLine1": "IDD<<LGXX359T88<<<<<<<<<<<<<<<",
        "mrzLine2": "8907167<2809045D<<<<<<<<<<<<<8",
        "mrzLine3": "SMITH<<CHRISTIAN<<<<<<<<<<<<<<",
        "nfcInfo": {
          "fullMrz": "MRZ IS HERE",
          "imageId": "IMAGE ID IS HERE"
        }        
      }
    ]
  },
  "fixedInfo": {
    "firstName": "Daniel",
    "lastName": "Brooks",
    "aliasName": "Dan Brooks",
    "dob": "1989-07-16"
  },
  "agreement": { //present when SDK was initialized with Agreement screen enabled
    "items": [
      {
        "id": "aea6411c-4a34-4d16-9e2c-62bd2c850011",
        "acceptedAt": "2024-03-25 06:56:47",
        "source": "WebSDK",
        "type": "onboarding",
        "recordIds": [
          "6401202f39c56ebefd4497b9",
          "67f0c31bf26d8087f14d133d"
        ],
      }
    ],
  },  
  "email": "[email protected]",
  "applicantPlatform": "Android",
  "requiredIdDocs": {
    "docSets": [
      {
        "idDocSetType": "IDENTITY",
        "types": [
          "PASSPORT",
          "ID_CARD"
        ]
      },
      {
        "idDocSetType": "SELFIE",
        "types": [
          "SELFIE"
        ]
      }
    ]
  },
  "review": {
    "elapsedSincePendingMs": 115879,
    "elapsedSinceQueuedMs": 95785,
    "reprocessing": true,
    "levelName": "basic-kyc",
    "createDate": "2020-06-24 05:11:02+0000",
    "reviewDate": "2020-06-24 05:12:58+0000",
    "reviewResult": {
      "reviewAnswer": "GREEN"
    },
    "reviewStatus": "completed"
  },
  "lang": "de",
  "type": "individual"
}

{
  "id": "5ecfbe9ad5ea48743f8dd1b8",
  "createdAt": "2020-05-28 13:37:30",
  "clientId": "coolclientid",
  "inspectionId": "5ecfbe9ad5ea48743f8dd1b9",
  "externalUserId": "externalCompanyId",
  "info": {
    "companyInfo": {
      "companyName": "Cool_company_name",
      "registrationNumber": "5555555",
      "country": "GBR",
      "legalAddress": "Street 123, London, England",
      "incorporatedOn": "2018-02-28 00:00:00",
      "applicantPosition": "Secretary",
      "type": "ltd",
      "email": "[email protected]",
      "phone": "(020) 0000 3333",
      "taxId": "55555276F",
      "registrationLocation": "UK Company Registration",
      "website": "www.website_name.com",
      "postalAddress": "10 St John Axe, London DT7R 00F"
    }
  },
  "requiredIdDocs": {
    "docSets": [
      {
        "idDocSetType": "COMPANY",
        "types": [
          "COMPANY_DOC"
        ],
        "steps": [
          {
            "name": "company",
            "minDocsCnt": 1,
            "idDocTypes": [
              "COMPANY_DOC"
            ],
            "idDocSubTypes": null
          },
          {
            "name": "ubos",
            "minDocsCnt": null,
            "idDocTypes": null,
            "idDocSubTypes": null
          }
        ]
      }
    ]
  }
}

{
  "id": "679762d6f1dbd5610000000f",
  "createdAt": "2025-01-27 10:41:26",
  "clientId": "cool_client_id",
  "inspectionId": "679762d6f1dbd56171000000",
  "externalUserId": "level-a543e802-b156-4375-8b68-000000000000",
  "info": { // The results of verification are stored here.
    "idDocs": [
      {
        "idDocType": "COMPANY_DOC",
        "country": "DEU"
      }
    ],
    "companyInfo": {
      "companyName": "COMPANY LTD",
      "registrationNumber": "00000000",
      "country": "GBR",
      "legalAddress": "30 Street, London, England, 7DR",
      "incorporatedOn": "2015-07-16 00:00:00",
      "applicantPosition": "Secretary",
      "type": "limitedLiabilityCompany",
      "email": "[email protected]",
      "phone": "(020) 0000 0000",
      "taxId": "00000000F",
      "registrationLocation": "UK Company Registration",
      "website": "https://website.com/",
      "postalAddress": "30 Street, London 7DR",
      "beneficiaries": [
        {
          "id": "ba1ec4a0-6c39-47e0-b9a5-000000000000",
          "applicantId": "6797633958c30f00000000gf",
          "shareSize": 100,
          "types": [
            "ubo",
            "director"
          ],
          "beneficiaryInfo": {
            "email": "[email protected]",
            "firstName": "John",
            "lastName": "Doe",
            "taxResidenceCountry": "PRT",
            "shareSize": 100
          }
        }
      ]
    }
  },
  "fixedInfo": { // This is what is expected to get from the applicant input.
    "companyInfo": {
      "companyName": "COMPANY LTD",
      "registrationNumber": "00000000",
      "country": "GBR",
      "legalAddress": "30 Street, London, England",
      "incorporatedOn": "2015-07-16 00:00:00",
      "applicantPosition": "-",
      "type": "limitedLiabilityCompany",
      "email": "[email protected]",
      "phone": "020-0000-0000",
      "taxId": "00000000F",
      "registrationLocation": "-",
      "website": "https://website.com/",
      "postalAddress": "30 Street, London 7DR",
      "skippedTypes": [
        "director",
        "representative"
      ],      
    }
  },
  "applicantPlatform": "Web",
  "ipCountry": "DEU",
  "authCode": "dglkbnzd;fkjnLULHLugluhlUGlyuhgvlUH;ihj;IH;ughkuhg;0MTQzNiwic3ViIjoibGV2ZWwtYTU0M2U4MDItYjE1Ni00Mzc1LThiNjgtNWJhNzhkMzBiOGU1IiwiYXVkIjoic3KDjnfzvkdfnH:H>IHJ/lihfr/xfmQ2ZjFkYmQ1NjE3MWY4YTk2NiJ9._eRh4qLCRxJA6lk6hKJrt-H67X9fmggdFEMpxaAmn_Y",
  "agreement": {
    "createdAt": "2025-01-27 10:41:29",
    "acceptedAt": "2025-01-27 10:41:29",
    "source": "WebSDK"
  },
  "requiredIdDocs": {
    "docSets": [
      {
        "idDocSetType": "COMPANY_DATA",
        "fields": [
          {
            "name": "companyName",
            "required": true
          },
          {
            "name": "country",
            "required": true
          },
          {
            "name": "registrationNumber",
            "required": false
          },
          {
            "name": "incorporatedOn",
            "required": false
          },
          {
            "name": "website",
            "required": false
          },
          {
            "name": "legalAddress",
            "required": false
          },
          {
            "name": "state",
            "required": false
          }
        ]
      },
      {
        "idDocSetType": "COMPANY_BENEFICIARIES",
        "companyBeneficiaryDefinitions": [
          {
            "category": "ubos",
            "canSkip": true,
            "individual": {
              "enabled": true,
              "levelName": "basic-kyc-level",
              "fields": [
                {
                  "name": "firstName",
                  "required": true
                },
                {
                  "name": "lastName",
                  "required": true
                },
                {
                  "name": "middleName",
                  "required": false
                },
                {
                  "name": "dob",
                  "required": false
                },
                {
                  "name": "taxResidenceCountry",
                  "required": true
                },
                {
                  "name": "shareSize",
                  "required": true
                }
              ],
              "customFields": null
            }
          },
          {
            "category": "shareholders",
            "canSkip": true,
            "individual": {
              "enabled": true,
              "levelName": "basic-kyc-level",
              "fields": [
                {
                  "name": "firstName",
                  "required": true
                },
                {
                  "name": "lastName",
                  "required": true
                },
                {
                  "name": "middleName",
                  "required": false
                },
                {
                  "name": "dob",
                  "required": false
                },
                {
                  "name": "taxResidenceCountry",
                  "required": false
                },
                {
                  "name": "shareSize",
                  "required": true
                }
              ],
              "customFields": null
            },
            "company": {
              "enabled": true,
              "levelName": "Auto KYB demo",
              "fields": [
                {
                  "name": "companyName",
                  "required": true
                },
                {
                  "name": "country",
                  "required": true
                },
                {
                  "name": "registrationNumber",
                  "required": false
                }
              ],
              "customFields": null
            }
          },
          {
            "category": "directors",
            "individual": {
              "enabled": true,
              "levelName": "basic-kyc-level",
              "fields": [
                {
                  "name": "firstName",
                  "required": true
                },
                {
                  "name": "lastName",
                  "required": true
                },
                {
                  "name": "middleName",
                  "required": false
                },
                {
                  "name": "dob",
                  "required": false
                },
                {
                  "name": "email",
                  "required": true
                },
                {
                  "name": "phone",
                  "required": false
                }
              ],
              "customFields": null
            },
            "company": {
              "enabled": false,
              "levelName": "Auto KYB demo",
              "fields": [
                {
                  "name": "companyName",
                  "required": true
                },
                {
                  "name": "country",
                  "required": true
                },
                {
                  "name": "registrationNumber",
                  "required": true
                }
              ],
              "customFields": null
            }
          }
        ]
      },
      {
        "idDocSetType": "COMPANY_DOCUMENTS",
        "companyDocsGroupDefinitions": [
          {
            "label": "legalPresence",
            "subTypes": [
              "INCORPORATION_CERT",
              "INCORPORATION_ARTICLES",
              "STATE_REGISTRY"
            ],
            "required": true
          },
          {
            "label": "companyDetails",
            "subTypes": [
              "INFORMATION_STATEMENT",
              "PROOF_OF_ADDRESS",
              "STATE_REGISTRY",
              "INCORPORATION_ARTICLES",
              "INCORPORATION_CERT",
              "INCUMBENCY_CERT",
              "GOOD_STANDING_CERT"
            ],
            "required": true
          }
        ]
      }
    ],
    "kybSettings": {
      "shareholderThreshold": 5,
      "uboThreshold": 25
    }
  },
  "review": {
    "reviewId": "bUKIB",
    "attemptId": "OKxAF",
    "attemptCnt": 1,
    "elapsedSincePendingMs": 219,
    "levelName": "Auto KYB demo",
    "createDate": "2025-01-27 10:44:39+0000",
    "reviewDate": "2025-01-27 10:44:39+0000",
    "reviewResult": {
      "reviewAnswer": "GREEN"
    },
    "reviewStatus": "completed"
  },
  "lang": "en",
  "type": "company",
  "riskLabels": {
    "attemptId": "SLfbz",
    "createdAt": "2025-01-27 10:44:39",
    "device": [
      "vpnUsage"
    ],
    "crossCheck": [
      "manyAccountDuplicates"
    ]
  }
}

If the request fails, you will receive an HTTP response containing an error code along with a message explaining the error. For example:

{
   "code": 400,
   "correlationId": "78f4988e0d611cb0ba6fa52603f4b2b0",
   "description": "Review result cannot be both GREEN and contain a rejection type"
}

Errors list

The following table lists the most common error types that you may encounter.

Code	Description	Comment
`400`	“Existing level should be specified to create an applicant”	`levelName` was not provided in the request.
`400`	"Applicant 'review' must be completed and consistent"	Some required parameters were not provided or were provided incorrectly in the request body. For example: `reviewStatus` is not “completed”. `reviewAnswer` was not provided.
`400`	"Review result cannot be both GREEN and contain a rejection type"	`reviewRejectType` was provided in the request body when it should not have been.
`400`	"Review result RED must contain rejection type FINAL or RETRY"	The `reviewRejectType` field was not provided in the request body, though it is required.
`409`	"Applicant with external user id '' already exists: "	An applicant with the provided `externalUserId` already exists in the Sumsub system.

Import applicant

Table of contents

Overview

Specifics of importing company applicants data

`companyInfo` arguments

`address` arguments

Request examples

Response explained

Response examples

Errors list

Table of contents

Overview

Specifics of importing company applicants data

companyInfo arguments

address arguments

Request examples

Response explained

Response examples

Errors list

`companyInfo` arguments

`address` arguments