getstarted.ae

Core concepts

The objects in the GetStarted API and how they relate to each other.

Everything in the API hangs off a customer. A customer owns incorporations, people and companies. An incorporation links people and companies to itself as participants, and each participant carries the documents its roles need. IDs are prefixed with the object type, so you can tell what an ID refers to by reading it.

Customer

The account on your platform that a company is being formed for. Usually one per end user or organisation you serve. Store your own account ID in externalReference; it must be unique per environment and is returned on every read.

  • Prefix: cus_
  • Owns: incorporations, persons, business entities.
  • Created with POST/customers.

Incorporation

One application to form one company, in one jurisdiction, as one type, for example SG and PRIVATE_LIMITED_COMPANY. It starts as a DRAFT you fill in, is locked when you submit it, and ends COMPLETED or CANCELLED.

It holds the company-level answers under requirements (name options, business activity, registered office) and records the requirementsVersion of the schema it was created against. When the company exists, businessEntityId points at the business entity that was formed.

  • Prefix: inc_
  • Belongs to: a customer.
  • Has: participants, issues, a status history.

Participant

A person or company taking part in an incorporation, with one or more roles: DIRECTOR, SHAREHOLDER, SECRETARY, MANAGER, UBO or AUTHORISED_SIGNATORY. Shareholder and UBO roles carry an ownershipPercentage.

A participant is a link, not a record of the person. It points at a person (participantType: "INDIVIDUAL", resourceType: "PERSON") or a business entity (participantType: "CORPORATE", resourceType: "BUSINESS_ENTITY"), and holds the document slots for that incorporation. Removing a participant keeps the person or entity.

  • Prefix: par_
  • Belongs to: an incorporation.
  • References: one person or one business entity.

Person

A natural person: name, date of birth, nationality, contact details, residential address. Persons belong to the customer, not to an incorporation, so the same director can be reused across several incorporations without re-entering their details.

Business entity

A company. There are two sources:

  • Companies you create, such as a holding company that will be a corporate shareholder. Created with POST/customers/{customerId}/business-entities.
  • Companies formed through GetStarted. The entity is created for you when the incorporation completes.

A business entity carries its locations, its registrations (reg_, one per jurisdiction it is registered in), its corporate documents (doc_, such as the certificate of incorporation) and its government identifiers (such as a company number).

  • Prefix: ent_
  • Belongs to: a customer.

Location

An address belonging to a business entity, with a type of REGISTERED_OFFICE, OPERATING_ADDRESS or MAILING_ADDRESS. A location can also be the value of an intake field that asks for an address, such as a registered office. See Requirements.

File

An uploaded PDF, JPEG or PNG, up to 20 MB. A file is not tied to anything when uploaded; you attach it to document slots afterwards. One file can fill slots on several participants, so a passport uploaded once can serve every incorporation that person joins.

Document slot

A named place on a participant that a file fills, identified by its documentKind: PASSPORT_SCAN, PROOF_OF_ADDRESS, CERTIFICATE_OF_INCORPORATION and so on. Which slots a participant needs depends on its roles and type, and is listed in documentRequirements of the requirements schema.

A slot has no ID of its own. You address it by participant and kind, and fill it with PUT/incorporations/{incorporationId}/participants/{participantId}/documents/{documentKind}. Putting a different file replaces what was there.

Validation

A check of a draft against its requirements schema, computed on request. It returns isComplete and two lists, missingRequirements and invalidRequirements, each item carrying a path that points at what to fix. Submission is only accepted when isComplete is true.

Issue

A problem raised while a submitted incorporation is being processed, such as a cropped passport scan. An open issue moves the incorporation to ACTION_REQUIRED and pauses it. Issues are read-only: fix the data or document at the issue's path and it resolves on its own.

Status workflow

The ordered stages an incorporation of a given jurisdiction and type moves through. Every incorporation has two fields that describe where it is:

  • status, the same small set everywhere: DRAFT, SUBMITTED, IN_PROGRESS, ACTION_REQUIRED, COMPLETED, CANCELLED. Branch your logic on this.
  • stage, a jurisdiction-specific step such as compliance_review or name_reservation. Show this to users.

GET/incorporations/status-workflow returns the stages with titles and descriptions, so you can draw a progress tracker without hard-coding each country.

How they fit together

Text
Customer  cus_
├── Person  per_
├── Business entity  ent_
│   ├── Location  loc_
│   ├── Registration  reg_
│   ├── Entity document  doc_
│   └── Government identifier
└── Incorporation  inc_
    ├── requirements            company-level intake values
    ├── Participant  par_       → Person or Business entity, with roles
    │   └── Document slot       documentKind → File  file_
    ├── Issue  iss_
    └── businessEntityId        → the Business entity formed, once completed

Requirements schema    per jurisdiction + type: what the draft must contain
Validation             per incorporation: what the draft is still missing
Status workflow        per jurisdiction + type: the stages it moves through