Entities API

Create and manage corporate entities

Entities represent corporate structures like companies, foundations, and trusts. Use these endpoints to create new entities, retrieve their details, and update their information.

API flow

API key auth always creates a draft entity — no invoice until you explicitly request one. This keeps the entity fully editable while you gather information, and lets you control exactly when billing happens.

Step	What happens
`POST /entities`	Creates a `draft` entity. No invoice, fully editable.
Configure	Add parties, share classes, documents, addons, and CSP data across as many calls as needed.
`POST /entities/{id}/invoice`	Issues the incorporation invoice. Pass `payment_method: "card"` + URLs to also create a hosted checkout session in the same call. Entity stays `draft`.
Payment	Customer pays via the hosted checkout URL. You receive a `payment.received` webhook.
`POST /entities/{id}/submit`	Validates all requirements and transitions to `submitted_for_review`.

Entity Object

{
  "id": "ent_abc123",
  "name": "Acme Holdings LLC",
  "status": "pre_incorporation",
  "jurisdiction_product_id": "jp_xyz789",
  "jurisdiction": {
    "id": "jur_uae",
    "name": "UAE",
    "slug": "uae"
  },
  "product": {
    "id": "prod_freezone",
    "name": "Freezone Company",
    "slug": "freezone-company"
  },
  "metadata": {
    "source": "api",
    "api_key_id": "key_abc123"
  },
  "created_at": "2024-01-15T10:30:00Z",
  "updated_at": "2024-01-15T10:30:00Z"
}

Entity Statuses

Status	Description
`draft`	Created via API key auth (`POST /entities`). No invoice yet, fully editable. Issue an invoice via `POST /entities/{id}/invoice` and submit via `POST /entities/{id}/submit`.
`pre_incorporation`	Created via dashboard session auth. Invoice exists, entity is editable, awaiting documents and payment.
`awaiting_payment`	Legacy status from the deprecated `/checkout` endpoint. Not used in the current API flow — `draft` entities stay in `draft` throughout billing.
`submitted_for_review`	Submitted to the EntityEngine team for review.
`submitted_to_csp`	Approved by EntityEngine and forwarded to the Corporate Service Provider.
`returned_for_changes`	More information needed from the client (entity is editable again).
`incorporated`	Successfully incorporated. Use Change Requests for modifications.
`dissolved`	Entity has been dissolved.

API flow

Entity Object

Entity Statuses

Endpoints