Incorporating an entity

Prerequisites

• An API key from Settings > Developer
• The API-key owner is an active e-Resident or Resident
• Either a voucher code that covers the application invoice, or a standard API key for hosted checkout
• Optional but recommended for automation: the e-Próspera CLI

This flow can be driven either by a standard API key or by an Agent Key with the required write scopes. Agent Keys currently support voucher payments only. If you are delegating this flow to an AI agent, CLI workflow, or external service, read the Agent Keys guide first.

Overview

The flow has five stages:

1. Create the application.
2. Pay the application invoice (voucher or checkout session).
3. Collect the Agreement of Coexistence signature.
4. Wait until the application moves to Pending Review, then poll for approval.
5. Fetch the resulting legal-entity record.

Payment and signature can happen in either order. The application moves out of Draft only after both are complete.

Required Agent scopes for delegated incorporation

If you are using an Agent Key instead of a standard API key, the key needs:

• agent:entity.application.create
• agent:entity.application.read
• agent:entity.read
• agent:entity.application.pay for voucher payments

Write-capable Agent Keys require a signed Manifestation of Will. If the Manifestation of Will also includes acceptance of the relevant Agreement of Coexistence (AOC), the signature step is skipped entirely and the application can proceed directly to payment and submission — enabling fully automated entity incorporation.

The agent:entity.application.read scope only returns applications created through this API.

Step 1: Create the legal-entity application

With the CLI, put the request body in application.json, validate it locally, then create the application:

eprospera --json --dry-run application create --file application.json
eprospera --json --yes application create --file application.json

The direct HTTP request is:

curl -X POST https://portal.eprospera.com/api/v1/legal_entity_applications \
  -H "Authorization: Bearer <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "applicationData": {
      "residencyType": "e-Resident",
      "entityType": "llc",
      "name": "My Company",
      "extension": "LLC",
      "principalOffice": {
        "line1": "123 Main Street",
        "city": "Roatan",
        "postalCode": "34101",
        "country": "Honduras"
      },
      "contactEmail": "contact@mycompany.com",
      "registeredAgentProvider": "prospera_employment_solutions",
      "registeredAgentDetails": null
    },
    "redirectUrl": "https://example.com/success"
  }'

Example response:

{
  "data": {
    "id": "215ea307-980e-46cb-9463-3e82d03dd08e",
    "statusId": "Draft",
    "applicationVersion": "1.0.0",
    "createdViaAPI": true,
    "submittedAt": null
  },
  "nextSteps": {
    "signature": "https://portal.eprospera.com/en/application/api-terms/215ea307-980e-46cb-9463-3e82d03dd08e?token=abc123..."
  }
}

The nextSteps.signature URL is the portal page where the signer reviews and signs the Agreement of Coexistence.

If the Agent Key's Manifestation of Will includes acceptance of the relevant Agreement of Coexistence, nextSteps.signature will be null and the AOC is auto-applied from the stored acceptance. In this case, you can skip Step 3 entirely — just complete payment and the application auto-submits.

Step 2: Pay the application invoice

Complete payment before final submission. Agent Keys can apply a voucher code directly. Standard API keys can also create a checkout session and send the user through a payment flow. If the Agreement of Coexistence has already been signed, the application may submit immediately after payment. Otherwise it remains paid and in draft until signature is completed.

Option A: Apply a voucher

CLI:

eprospera --json --yes application pay 215ea307-980e-46cb-9463-3e82d03dd08e --voucher STARTUP100

Direct HTTP:

curl -X POST https://portal.eprospera.com/api/v1/legal_entity_applications/215ea307-980e-46cb-9463-3e82d03dd08e/pay/voucher \
  -H "Authorization: Bearer <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "voucherCode": "STARTUP100"
  }'

If the application is already signed, payment also submits it. If it is not signed yet, the endpoint still succeeds and returns a reminder message.

Example response before signature:

{
  "success": true,
  "data": {
    "id": "215ea307-980e-46cb-9463-3e82d03dd08e",
    "statusId": "Draft",
    "submittedAt": null
  },
  "message": "Application paid, but not signed yet - please sign the application to complete the process."
}

In this unsigned-but-paid case, statusId remains Draft until the Agreement of Coexistence is signed.

Option B: Create a checkout session

Hosted checkout is currently standard-API-key only. Agent Key checkout-session creation is temporarily disabled.

curl -X POST https://portal.eprospera.com/api/v1/legal_entity_applications/<uuid of application>/checkout_session \
  -H "Authorization: Bearer <your-standard-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "paymentProvider": "stripe",
    "redirectUrl": "https://example.com/payment-complete",
    "email": "contact@mycompany.com"
  }'

This returns a provider-specific checkout payload and the associated invoice ID. See the POST legal_entity_applications/[id]/checkout_session reference.

Step 3: Collect the signature

Send the signer to the nextSteps.signature URL returned by step 1.

On that page, the signer can:

• review the Agreement of Coexistence
• sign it
• finish submission immediately if payment is already complete

If you supplied redirectUrl when creating the application, the signer is redirected there after completion.

Step 4: Poll the application

Use the CLI watcher, GET /api/v1/legal_entity_applications, or GET /api/v1/legal_entity_applications/{id} to monitor status.

eprospera --json application watch 215ea307-980e-46cb-9463-3e82d03dd08e --timeout 30m

Direct HTTP:

curl -X GET https://portal.eprospera.com/api/v1/legal_entity_applications/215ea307-980e-46cb-9463-3e82d03dd08e \
  -H "Authorization: Bearer <your-api-key>"

Example response after submission:

{
  "data": {
    "id": "215ea307-980e-46cb-9463-3e82d03dd08e",
    "statusId": "Pending Review",
    "submittedAt": "2024-01-15T11:00:00.000Z",
    "approvedAt": null,
    "rejectedAt": null,
    "legalEntityId": null
  }
}

Possible statuses:

• Draft: waiting on payment and/or signature
• Pending Review: submitted and awaiting review
• Approved: approved and converted into a legal entity
• Rejected: rejected by the review team

Continue polling until the response contains both:

• statusId: "Approved"
• legalEntityId

Step 5: Fetch the created legal entity

CLI:

eprospera --json entity get 2a4408c5-291e-4442-ba63-ac78f3f6eff7

Direct HTTP:

curl -X GET https://portal.eprospera.com/api/v1/legal_entities/2a4408c5-291e-4442-ba63-ac78f3f6eff7 \
  -H "Authorization: Bearer <your-api-key>"

Example response:

{
  "data": {
    "id": "2a4408c5-291e-4442-ba63-ac78f3f6eff7",
    "optionId": "llc",
    "type": "Limited Liability Company",
    "name": "My Company",
    "extension": "LLC",
    "nameStartsWithExtension": false,
    "formationDate": "2024-01-16T00:00:00.000Z",
    "registrationDate": "2024-01-16T09:30:00.000Z",
    "createdAt": "2024-01-16T09:30:00.000Z",
    "principalOfficeAddress": {
      "line1": "123 Main Street",
      "line2": null,
      "city": "Roatan",
      "state": null,
      "postalCode": "34101",
      "country": "Honduras"
    },
    "residentPermitNumber": "80000000000123",
    "dissolutionDate": null
  }
}

Common errors

See the endpoint references for full request/response details:

• POST legal_entity_applications
• POST legal_entity_applications/[id]/pay/voucher
• POST legal_entity_applications/[id]/checkout_session
• GET legal_entity_applications/[id]