Quickstart Guide

Create and incorporate your first entity via the API

This guide walks you through the complete workflow for incorporating an entity via the API, from browsing available products to receiving incorporation documents.

Workflow Overview

Browse the catalog

Discover available jurisdictions and products with their requirements.

Create entity

Use the jurisdiction_product_id to create a draft entity (no invoice yet).

Check requirements

Get detailed requirements for parties, documents, and entity-specific fields.

Add required information

Add parties, fill jurisdiction-specific CSP fields, set up share classes, and upload the documents listed by GET /incorporationdocuments.

Issue invoice

Call POST /entities/{id}/invoice to create the incorporation invoice. Pass payment_method: "card" or "crypto" to also receive a hosted checkout URL.

Submit for review

Call POST /entities/{id}/submit once the invoice is paid. Or call it early — it queues auto-submit and fires entity.status_changed when payment lands.

Handle feedback

Respond to any admin feedback and resubmit if needed.

Receive documents

Get notified when incorporation is complete with documents and dates.

Step 1: Browse the Catalog

Start by calling the catalog endpoint to see what products are available. You can filter by jurisdiction or product type.

Get products in Cayman Islands

curl -X GET "https://app.entityengine.io/api/v1/catalog?jurisdiction=cayman-islands" \
  -H "Authorization: Bearer sk_live_your_api_key"

The response includes party_requirements showing what roles are needed and which fields are required for each.

Step 2: Create Entity

Use the jurisdiction_product_id from the catalog to create your entity.

Create an entity

curl -X POST "https://app.entityengine.io/api/v1/entities" \
  -H "Authorization: Bearer sk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "jurisdiction_product_id": "jp_abc123",
    "name": "Acme Holdings Ltd"
  }'

Save the returned entity.id - you'll need it for all subsequent steps.

Step 3: Check Requirements

Get detailed requirements for your specific entity, including what's already completed and what's still needed.

Get entity requirements

curl -X GET "https://app.entityengine.io/api/v1/entities/{entity_id}/requirements" \
  -H "Authorization: Bearer sk_live_your_api_key"

The response includes completion_status.ready_for_submission which tells you if all requirements are met.

Step 4: Add Required Information

4a. Check which documents are needed

Before adding anything, call GET /incorporationdocuments to get the full list of required documents with their current status (missing, uploaded, approved, or rejected). The response includes a summary.complete boolean and scoped requirements per party and at the entity level.

Get required documents

curl -X GET "https://app.entityengine.io/api/v1/entities/{entity_id}/incorporationdocuments" \
  -H "Authorization: Bearer sk_live_your_api_key"

4b. Add parties

Add directors, shareholders, UBOs, and corporate parties. Use party_type to distinguish persons ("person"), companies ("corporate"), or foundations ("foundation").

Add a party (person, corporate, or foundation)

curl -X POST "https://app.entityengine.io/api/v1/entities/{entity_id}/parties" \
  -H "Authorization: Bearer sk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "party_type": "person",
    "first_name": "John",
    "last_name": "Smith",
    "roles": ["director", "shareholder", "ubo"],
    "date_of_birth": "1985-03-15",
    "nationality": "US",
    "address": {
      "street1": "123 Main Street",
      "city": "New York",
      "country": "US",
      "postcode": "10001"
    }
  }'

4c. Submit CSP fields

Some jurisdictions require additional fields collected via a CSP form. Use the schema.id from the catalog response and post each field as a key–value pair. For party-scoped fields, include party_id in the request body.

Submit CSP form fields

curl -X POST "https://app.entityengine.io/api/v1/entities/{entity_id}/csp-data" \
  -H "Authorization: Bearer sk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "csp_form_schema_id": "schema_abc123",
    "fields": [
      { "field_key": "business_activity", "value": "Software development" },
      { "field_key": "source_of_funds", "value": "Business revenue" }
    ]
  }'

4d. Set up share classes and shareholdings

If the entity type requires it, define share classes first, then assign shareholdings to each party using their party_id.

Create share class and assign shareholding

# Create a share class
curl -X POST "https://app.entityengine.io/api/v1/entities/{entity_id}/share-classes" \
  -H "Authorization: Bearer sk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Ordinary",
    "total_shares": 1000,
    "par_value": 1,
    "currency": "USD"
  }'

# Assign shares to a party
curl -X POST "https://app.entityengine.io/api/v1/entities/{entity_id}/shareholdings" \
  -H "Authorization: Bearer sk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "party_id": "pty_abc123",
    "share_class_id": "sc_xyz789",
    "shares_held": 500
  }'

4e. Upload documents

Upload each required document identified in step 4a. Use the document_type_id and party_id from the incorporationdocuments response to target each upload correctly.

Upload a document

curl -X POST "https://app.entityengine.io/api/v1/entities/{entity_id}/documents" \
  -H "Authorization: Bearer sk_live_your_api_key" \
  -F "file=@passport.pdf" \
  -F "document_type_id=dt_passport" \
  -F "party_id=pty_abc123"

Step 5: Issue Invoice

Call POST /entities/{entity_id}/invoice to create the incorporation invoice. Pass payment_method: "card" or "crypto" to also receive a hosted checkout URL in the same response.

Issue the incorporation invoice

curl -X POST "https://app.entityengine.io/api/v1/entities/{entity_id}/invoice" \
  -H "Authorization: Bearer sk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "payment_method": "card",
    "success_url": "https://your-app.com/checkout/done",
    "cancel_url": "https://your-app.com/checkout/cancelled",
    "customer_email": "founder@example.com"
  }'

The response includes invoice.id and, when using hosted checkout, checkout_session.checkout_url to forward to the customer. For bank transfer, omit payment_method — the customer receives an invoice email. Use sandbox endpoints to simulate payment during testing.

Step 6: Submit for Review

Once all requirements are met and the invoice is paid, submit the entity for review.

Submit for review

curl -X POST "https://app.entityengine.io/api/v1/entities/{entity_id}/submit" \
  -H "Authorization: Bearer sk_live_your_api_key"

You can also call /submit before payment completes — it returns 402 but queues the entity for automatic submission. When payment lands, the entity submits automatically and you receive an entity.status_changed webhook with no further API call needed.

Step 7: Handle Feedback

If the admin returns the entity for changes, you'll receive an entity.feedback_created webhook. Fetch the feedback, respond to each item, then resubmit.

Get Feedback

Get feedback items

curl -X GET "https://app.entityengine.io/api/v1/entities/{entity_id}/feedback" \
  -H "Authorization: Bearer sk_live_your_api_key"

Respond to Feedback

Respond to a feedback item

curl -X POST "https://app.entityengine.io/api/v1/entities/{entity_id}/feedback/{feedback_id}/responses" \
  -H "Authorization: Bearer sk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "I have uploaded the corrected document."
  }'

Resubmit

Once you've responded to all feedback items, resubmit the entity:

Resubmit after addressing feedback

curl -X POST "https://app.entityengine.io/api/v1/entities/{entity_id}/submit" \
  -H "Authorization: Bearer sk_live_your_api_key"

Step 8: Receive Documents

When incorporation is complete, you'll receive an entity.status_changed webhook with the new status incorporated.

Incorporation complete webhook

{
  "id": "evt_abc123",
  "type": "entity.status_changed",
  "created_at": "2024-01-25T10:00:00Z",
  "data": {
    "entity_id": "ent_xyz789",
    "name": "Acme Holdings Ltd",
    "old_status": "submitted_to_csp",
    "new_status": "incorporated",
    "company_number": "12345678",
    "incorp_date": "2024-01-25"
  }
}

Fetch the entity details to get incorporation documents, company number, and key dates.

Entity Status Lifecycle

Status	Description
`draft`	Initial state for API key callers — no invoice yet, fully editable
`submitted_for_review`	Submitted and awaiting admin review
`returned_for_changes`	Returned with feedback - action required
`submitted_to_csp`	Sent to Corporate Service Provider
`incorporated`	Successfully incorporated

What's Next

• Sandbox Testing - Test the full flow without real payments
• Webhooks - Set up real-time notifications for status changes and feedback
• Entities API - Full API reference for entity operations