Quickstart Guide

Create your first entity in minutes

This guide walks you through the complete workflow for creating an entity via the API, from browsing available products to adding directors and uploading documents.

Workflow Overview

Browse the catalog

Discover available jurisdictions and products with their requirements.

Review requirements

Check party_requirements to understand what directors, shareholders, and UBOs are needed.

Create entity

Use the jurisdiction_product_id to create your entity.

Add persons

Add directors, shareholders, and UBOs with all required fields.

Upload documents

Upload required documents for each person and the entity.

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.com/api/v1/catalog?jurisdiction=cayman-islands" \
  -H "X-API-Key: sk_live_your_api_key"

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

Step 2: Review Requirements

Each catalog item includes detailed requirements. Here's what to look for:

Example party_requirements

{
  "party_requirements": {
    "applicable_roles": ["directors", "shareholders", "ubos"],
    "directors": {
      "minimum": 1,
      "minimum_natural_person": 1,
      "fields_required": ["address", "date_of_birth", "nationality"],
      "explanation": "At least one natural person director required"
    },
    "shareholders": {
      "minimum": 1,
      "fields_required": ["address", "date_of_birth", "nationality"]
    },
    "ubos": {
      "minimum": 1,
      "fields_required": ["address", "date_of_birth", "nationality"],
      "explanation": "UBOs with 25%+ ownership must be disclosed"
    }
  }
}

Corporation vs Foundation

Different entity types have different applicable roles:

Corporation

• directors - Company officers
• shareholders - Equity owners
• ubos - Ultimate beneficial owners

Foundation

• directors - Foundation council
• members - Foundation members
• supervisors - Oversight role
• beneficiaries - Benefit recipients
• ubos - Ultimate beneficial owners

Required Fields

The fields_required array tells you which fields must be provided for each role:

Field	Description
`address`	Residential address with street, city, country, postcode
`date_of_birth`	Date of birth in YYYY-MM-DD format
`nationality`	ISO 3166-1 alpha-2 country code (e.g., "US", "GB")

Step 3: Create Entity

Use the jurisdiction_product_id from the catalog to create your entity.

Create an entity

curl -X POST "https://app.entityengine.com/api/v1/entities" \
  -H "X-API-Key: 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 the next steps.

Step 4: Add Persons

Add directors, shareholders, and UBOs with all required fields based on the party_requirements.

Add a director/shareholder/UBO

curl -X POST "https://app.entityengine.com/api/v1/entities/{entity_id}/persons" \
  -H "X-API-Key: sk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "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"
    }
  }'

A single person can hold multiple roles. The response includes a party_id which you'll need if creating shareholdings.

Step 5: Upload Documents

Check document_requirements from the catalog to see what documents are needed.

Upload a document

curl -X POST "https://app.entityengine.com/api/v1/entities/{entity_id}/documents" \
  -H "X-API-Key: sk_live_your_api_key" \
  -F "file=@passport.pdf" \
  -F "document_type=passport" \
  -F "person_id={person_id}"

Complete Example

Here's the full workflow in JavaScript:

Complete workflow example

const API_KEY = 'sk_live_your_api_key';
const BASE_URL = 'https://app.entityengine.com/api/v1';

async function createCompany() {
  // 1. Browse catalog for Cayman products
  const catalog = await fetch(`${BASE_URL}/catalog?jurisdiction=cayman-islands`, {
    headers: { 'X-API-Key': API_KEY }
  }).then(r => r.json());

  // 2. Find the exempt company product
  const exemptCo = catalog.data.find(item => item.product.slug === 'exempt-company');
  console.log('Requirements:', exemptCo.party_requirements);

  // 3. Create the entity
  const entity = await fetch(`${BASE_URL}/entities`, {
    method: 'POST',
    headers: {
      'X-API-Key': API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      jurisdiction_product_id: exemptCo.jurisdiction_product_id,
      name: 'Acme Holdings Ltd'
    })
  }).then(r => r.json());

  console.log('Entity created:', entity.data.id);

  // 4. Add a director (with all required fields)
  const director = await fetch(`${BASE_URL}/entities/${entity.data.id}/persons`, {
    method: 'POST',
    headers: {
      'X-API-Key': API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      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'
      }
    })
  }).then(r => r.json());

  console.log('Director added:', director.data.id);
  
  return { entity: entity.data, director: director.data };
}

createCompany();

What's Next

• Share Classes - Create share classes and allocate shares to shareholders
• Webhooks - Set up real-time notifications for entity status changes
• Requirements API - Check what's missing before submitting for incorporation