# Incorporating an entity (/incorporating-entity) This guide walks through the CLI and direct API flow for incorporating an LLC in Próspera. ## Prerequisites [#prerequisites] * An API key from [Settings > Developer](https://portal.eprospera.com/settings) * 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](/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](/agent-keys) first. ## Overview [#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 [#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 [#step-1-create-the-legal-entity-application] With the CLI, put the request body in `application.json`, validate it locally, then create the application: ```bash eprospera --json --dry-run application create --file application.json eprospera --json --yes application create --file application.json ``` The direct HTTP request is: ```bash curl -X POST https://portal.eprospera.com/api/v1/legal_entity_applications \ -H "Authorization: Bearer " \ -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: ```json { "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 [#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 [#option-a-apply-a-voucher] CLI: ```bash eprospera --json --yes application pay 215ea307-980e-46cb-9463-3e82d03dd08e --voucher STARTUP100 ``` Direct HTTP: ```bash curl -X POST https://portal.eprospera.com/api/v1/legal_entity_applications/215ea307-980e-46cb-9463-3e82d03dd08e/pay/voucher \ -H "Authorization: Bearer " \ -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: ```json { "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 [#option-b-create-a-checkout-session] Hosted checkout is currently standard-API-key only. Agent Key checkout-session creation is temporarily disabled. ```bash curl -X POST https://portal.eprospera.com/api/v1/legal_entity_applications//checkout_session \ -H "Authorization: Bearer " \ -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/post-legal-entity-applications-id-checkout-session) reference. ## Step 3: Collect the signature [#step-3-collect-the-signature] If you accepted the Agreement of Coexistence when signing your Manifestation of Will (in Developer Settings), `nextSteps.signature` will be `null` and this step is not needed. The application auto-submits after payment. 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 [#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. ```bash eprospera --json application watch 215ea307-980e-46cb-9463-3e82d03dd08e --timeout 30m ``` Direct HTTP: ```bash curl -X GET https://portal.eprospera.com/api/v1/legal_entity_applications/215ea307-980e-46cb-9463-3e82d03dd08e \ -H "Authorization: Bearer " ``` Example response after submission: ```json { "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 [#step-5-fetch-the-created-legal-entity] CLI: ```bash eprospera --json entity get 2a4408c5-291e-4442-ba63-ac78f3f6eff7 ``` Direct HTTP: ```bash curl -X GET https://portal.eprospera.com/api/v1/legal_entities/2a4408c5-291e-4442-ba63-ac78f3f6eff7 \ -H "Authorization: Bearer " ``` Example response: ```json { "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 [#common-errors] | Status | Response | Meaning | | ------ | ------------------------------------------------------------- | -------------------------------------------------------------- | | `400` | `Invalid request body` | Payload does not match the schema. | | `400` | `Either registeredAgentProvider or registeredAgentDetails...` | Provide exactly one registered-agent mode. | | `400` | `Legal entity application is not in draft status` | Voucher payment only works while the application is a draft. | | `400` | `This endpoint can only be used for API-created applications` | Voucher payment is limited to API-created applications. | | `403` | `You must be an active resident...` | The API-key owner is not an active `e-Resident` or `Resident`. | | `409` | `An LLC with the name ... already exists` | The LLC name is already taken. | See the endpoint references for full request/response details: * [`POST legal_entity_applications`](/reference/post-legal-entity-applications) * [`POST legal_entity_applications/[id]/pay/voucher`](/reference/post-legal-entity-applications-id-pay-voucher) * [`POST legal_entity_applications/[id]/checkout_session`](/reference/post-legal-entity-applications-id-checkout-session) * [`GET legal_entity_applications/[id]`](/reference/get-legal-entity-applications-id)