Submit Application via Payload

Submits a KYB application using complete structured parameters. This endpoint supports complex nested objects and strict data models, making it suitable for service-to-service calls or scenarios requiring full business models.

Request

https://openapi.advance.ai/v1/business/applications/structured
POST (application/json)

Request Header Parameters

Parameter	Description
Authorization	`string` Please use Token Authentication API to get your access token. Format: `Bearer {token}`

Request Parameters

Parameter	Required	Description
externalCompanyId	False	`string` The company ID defined by the user, used to link the company information in the user system.
kybLevel	True	`string` Indicating the specific KYB level that this request goes through. If empty, it goes by the default kybLevel (settings).
applicantEmail	False	`string` Email of the applicant who submitted the application. Must be a valid email format.
qnreIdentifierVersion	False	`string` The questionnaire identifier and version.
companyInfo	True	`object` Company information provided by the applicant. See CompanyInfo object below.
declaredCompanies	False	`array` Company structure information provided by the applicant. List of declared company entities.
declaredIndividuals	False	`array` Individual structure information provided by the applicant. List of declared individual entities.

CompanyInfo Object

Field	Required	Description
companyName	True	`string` Name of the company.
registrationNumber	True	`string` Registration number of the company.
registeredCountry	True	`String` Country where the company is registered. ISO 3166-1 alpha-3 code (e.g., "SGP", "USA").
registeredState	False	`string` State where the company is registered (for US companies).
legalAddress	False	`object` Address where the company is registered. See AddressInfo object.
registrationDate	False	`string` Date when the company was registered (yyyy-MM-dd format).
legalType	False	`enum` Type of legal person for the company. See CompanyLegalTypeEnum.
email	False	`string` Email of the company.
phoneNumber	False	`object` Contact phone number of the company. See PhoneNumber object.
taxId	False	`string` Taxpayer registration number/code.
leiCode	False	`string` Legal Entity Identifier code from the financial entities registry.
websiteUrl	False	`string` Website of the company.
merchantCategoryCode	False	`string` Merchant Category Code (MCC) for card network checks.
dbaName	False	`string` Doing Business As name.
customFields	False	`array` Custom fields provided by the applicant.
documentIds	False	`array` Company document IDs provided by the applicant.
mode	False	`[enum]()` Invocation Business Verification Mode (LIVE, CACHE, HYBRID).

AddressInfo Object

Field	Required	Description
street	False	`string` Street address.
city	False	`string` City name.
state	False	`string` State or province.
postalCode	False	`string` Postal or ZIP code.
country	False	`string` Country code.

PhoneNumber Object

Field	Required	Description
countryCode	False	`string` Country calling code (e.g., "+65").
number	False	`string` Phone number.

DeclaredCompanyInfo Object

Field	Required	Description
referencedExternalId	False	`string` Referenced external ID.
referencedProfileId	False	`string` Referenced profile ID.
shareRatio	False	`number` Share ratio of the company (0-1). Each company ownership share cannot exceed 100%.
roleType	True	`enum` Shareholder type. See CompanyRoleTypeEnum.
companyInfo	True	`object` Company information. See CompanyInfo object.

DeclaredIndividualInfo Object

Field	Required	Description
referencedExternalId	False	`string` Referenced external ID.
referencedProfileId	False	`string` Referenced profile ID.
shareRatio	False	`number` Share ratio (0-1).
roleType	True	`enum` Role type. See CompanyRoleTypeEnum.
individualInfo	True	`object` Individual information. See CompanyRelatedIndividual object.

CompanyRelatedIndividual Object

Field	Required	Description
firstName	True	`string` First name of the individual.
middleName	False	`string` Middle name of the individual.
lastName	True	`string` Last name of the individual.
legalName	False	`string` Legal name of the individual.
aliasName	False	`string` Alias name of the individual.
gender	False	`enum` Gender of the individual (MALE, FEMALE, OTHER).
dob	False	`string` Date of birth (yyyy-MM-dd format).
placeOfBirth	False	`object` Place of birth. See AddressInfo object.
countryOfResidence	False	`string` Country of residence.
placeOfResidence	False	`object` Place of residence. See AddressInfo object.
nationality	False	`string` Nationality of the individual.
tin	False	`string` Tax identification number.
taxResidenceCountry	False	`string` Country of tax residence.
email	False	`string` Email of the individual.
phoneNumber	False	`object` Phone number. See PhoneNumber object.
nationalId	False	`string` National ID number.
customFields	False	`array` Custom fields.
documentIds	False	`array` Document IDs.

Enumerations

CompanyRoleTypeEnum

Value	Description
UBO	Ultimate Beneficial Owner
SHAREHOLDER	Shareholder
REPRESENTATIVE	Representative
DIRECTOR	Director
AUTHORIZED_PERSON	Authorized Person
OTHER	Other
ACCOUNTANT	Accountant
COMMISSIONER	Commissioner
AUDITOR	Auditor
SECRETARY	Secretary

CompanyLegalTypeEnum

Value	Description
PRIVATE_LIMITED_LIABILITY_COMPANY	Private Limited Liability Company
PUBLIC_LIMITED_LIABILITY_COMPANY	Public Limited Liability Company
LIMITED_LIABILITY_COMPANY	Limited Liability Company
FOUNDATION	Foundation
ASSOCIATION	Association
COOPERATIVE	Cooperative
LIMITED_PARTNERSHIP	Limited Partnership
SOLE_PROPRIETORSHIP	Sole Proprietorship
FEDERATION_OF_FIRMS	Federation of Firms
CIVIL_PARTNERSHIP	Civil Partnership
GENERAL_PARTNERSHIP	General Partnership
PUBLIC_UTILITY_COMPANY	Public Utility Company
STATE_OWNED_COMPANY	State-owned Company
COMPANY_LIMITED_BY_GUARANTEE	Company Limited by Guarantee
SOCIETY	Society
NON_PROFIT_ORGANIZATION	Non-Profit Organization
BRANCH_OFFICE	Branch Office
LIMITED_LIABILITY_PARTNERSHIP	Limited Liability Partnership
TRUST	Trust
GOVERNMENT_ENTITY	Government Entity
OTHERS	Others

InvocationModeEnum

Value	Description
LIVE	Retrieves the latest records directly from primary official sources.
CACHE	Leverages global databases for maximized search depth and global reach.
HYBRID	Combines LIVE and CACHE modes for optimal results.

Request Examples

curl -X POST "https://openapi.advance.ai/v1/business/applications/structured" \
-H "Authorization: Bearer {Your Access Token}" \
-H "Content-Type: application/json" \
-d '{
  "externalCompanyId": "EXT-12345",
  "kybLevel": "STANDARD",
  "applicantEmail": "[email protected]",
  "companyInfo": {
    "companyName": "Example Corp Ltd",
    "registrationNumber": "123456789",
    "registeredCountry": "SGP",
    "registrationDate": "2020-01-15",
    "legalType": "PRIVATE_LIMITED_LIABILITY_COMPANY",
    "legalAddress": {
      "street": "123 Business Street",
      "city": "Singapore",
      "postalCode": "123456",
      "country": "SGP"
    },
    "email": "[email protected]",
    "phoneNumber": {
      "countryCode": "+65",
      "number": "12345678"
    },
    "websiteUrl": "https://example.com",
    "mode": "LIVE"
  },
  "declaredIndividuals": [
    {
      "roleType": "SHAREHOLDER",
      "shareRatio": 0.255,
      "individualInfo": {
        "firstName": "John",
        "lastName": "Smith",
        "gender": "MALE",
        "dob": "1985-03-20",
        "nationality": "SGP",
        "email": "[email protected]"
      }
    }
  ]
}'

Success Response

Response Description

Field	Description
applicationId	`string` The unique identifier of the created KYB application.
status	`enum` The current status of the application.
subjectCompany	`object` The subject company information.
declaredCompanies	`array` List of declared company entities.
declaredIndividuals	`array` List of declared individual entities.

Response.status

Value	Description
PENDING_REVIEW	Application requires manual review.
PENDING_RESUBMISSION	Application requires resubmission with corrections.
APPROVED	Application has been approved.
REJECTED	Application has been rejected.

Response Examples

{
  "applicationId": "APP-2026052200001",
  "status": "PENDING_REVIEW",
  "subjectCompany": {
    "companyId": "COM-2026052200001",
    "externalId": "EXT-12345",
    "companyName": "Example Corp Ltd",
    "registrationNumber": "123456789",
    "registeredCountry": "SGP",
    "registrationDate": "2020-01-15",
    "legalType": "PRIVATE_LIMITED_LIABILITY_COMPANY",
    "legalAddress": "123 Business Street, Singapore 123456",
    "email": "[email protected]",
    "phone": "+65 12345678",
    "taxId": null,
    "leiCode": null,
    "websiteUrl": "https://example.com",
    "confirmed": false,
    "customFields": [],
    "attachedDocs": [],
    "createdAt": "2026-05-22T10:30:00Z",
    "updatedAt": "2026-05-22T10:30:00Z"
  },
  "declaredCompanies": [],
  "declaredIndividuals": [
    {
      "individualId": "IND-2026052200001",
      "externalId": null,
      "firstName": "John",
      "middleName": null,
      "lastName": "Smith",
      "legalName": "John Smith",
      "aliasName": null,
      "roleType": "SHAREHOLDER",
      "individualType": "SHAREHOLDER",
      "shareRatio": 25.5,
      "companyId": "COM-2026052200001",
      "gender": "MALE",
      "dob": "1985-03-20",
      "placeOfBirth": null,
      "countryOfResidence": null,
      "nationality": "SGP",
      "tin": null,
      "taxResidenceCountry": null,
      "email": "[email protected]",
      "confirmed": false,
      "customFields": [],
      "attachedDocs": [],
      "createdAt": "2026-05-22T10:30:00Z",
      "updatedAt": "2026-05-22T10:30:00Z"
    }
  ]
}

Error Response

Response Description

Parameter	Description
error	`object` The error details.

ResponseError.error

Field	Description
type	`string` Error code or type.
message	`string` Human-readable error message.

ResponseError.error.type

Value	Description	HTTP Status Code
parameter_error	Parameter validation failed (e.g., missing or invalid parameter).	400 Bad Request
iam_failed	Authentication or authorization failed.	401 Unauthorized
error	Internal server error or unknown error.	500 Internal Server Error
not_found	Requested resource not found.	404 Not Found
service_busy	The service is busy or rate limited.	429 Too Many Requests

Response Examples

{
  "error": {
    "type": "parameter_error",
    "message": "companyInfo cannot be null"
  }
}

Updated about 11 hours ago