Incorporating an Entity via API

This guide walks you through the complete process of incorporating a legal entity (LLC) in Próspera using the e-Próspera API.

Prerequisites

• You must have an active e-Próspera API key (get one here)
• You must be an active resident (e-Resident or Resident) of Próspera
• You must have purchased e-Próspera coupon codes for payment

Overview

The entity incorporation process involves these steps:

1. Create Application - Submit legal entity application data
2. Process Payment - Pay using coupon codes
3. Collect Signature - Sign Agreement of Coexistence, and submit application
4. Poll for Approval - Wait for application approval
5. Retrieve Entity Details - Get final entity information and RPN

Step 1: Create Legal Entity Application

Submit a POST request to create a new legal entity application:

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,
      "analytics": {
        "industry": "Technology",
        "whatIsYourBusinessIntendingToDo": "Software development services",
        "howDidYouHearAboutProspera": "Online research",
        "whyChooseProspera": "Regulatory innovation",
        "website": "https://mycompany.com"
      }
    },
    "redirectUrl": "https://myapp.com/success"
  }'

See API reference for more details about the POST legal_entity_applications endpoint.

Response

{
  "data": {
    "id": "215ea307-980e-46cb-9463-3e82d03dd08e",
    "statusId": "Draft",
    "applicationData": { ... },
    "createdAt": "2024-01-15T10:30:00Z",
    "submittedAt": null,
    "approvedAt": null
  },
  "nextSteps": {
    "signature": "https://portal.eprospera.com/en/application/api-terms/215ea307-980e-46cb-9463-3e82d03dd08e?token=abc123..."
  }
}

Step 2: Process Payment with Coupon

Once the user has completed the signature process, pay for the application using a coupon code:

curl -X POST https://portal.eprospera.com/api/v1/legal_entity_applications/<uuid of application>/pay/coupon \
  -H "Authorization: Bearer <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "couponCode": "<your coupon code>"
  }'

Typically, you'd get a single code corresponding to many coupons, so that you can just store a single code as your secret. You can read more about free coupon codes in staging.

Response

{
  "success": true,
  "data": {
    "id": "215ea307-980e-46cb-9463-3e82d03dd08e",
    "statusId": "Submitted",
    "submittedAt": "2024-01-15T11:00:00Z",
    "applicationData": { ... }
  },
  "message": "Application paid, but not signed yet - please sign the application to complete the process."
}

Step 3: Collect Signature

Direct the person who will be signing the Agreement of Coexistence for this new entity to the signature URL returned in the first response (Step 1). On this URL they can read the agreement, sign it, and (providing you've already completed step 2), submit the application.

The user will be redirected to the redirectUrl (if provided in Step 1) upon completion.

Step 4: Poll for Application Approval

Monitor the application status by polling the GET endpoint:

curl -X GET https://portal.eprospera.com/api/v1/legal_entity_applications \
  -H "Authorization: Bearer <your-api-key>"

Response

{
  "data": [
    {
      "id": "215ea307-980e-46cb-9463-3e82d03dd08e",
      "statusId": "Approved",
      "applicationData": { ... },
      "submittedAt": "2024-01-15T11:00:00Z",
      "approvedAt": "2024-01-16T09:30:00Z",
      "legalEntityId": "2a4408c5-291e-4442-ba63-ac78f3f6eff7"
    }
  ]
}

Application Status Values

• Draft - Application created but not yet submitted
• Submitted - Application submitted and under review
• Approved - Application approved, legal entity created
• Rejected - Application rejected

Continue polling until statusId is "Approved" and legalEntityId is present.

Step 5: Retrieve Final Entity Details

Once approved, fetch the complete legal entity information:

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

Response

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

The residentPermitNumber is the entity's official RPN that can be used for verification and other API operations.

Error Handling

Common Error Responses

Status	Error	Description
400	Invalid request body	Check your JSON structure and required fields
400	Only LLCs are supported in the API	Use the web app for other entity types
400	Either registeredAgentProvider or registeredAgentDetails must be provided	Cannot provide both or neither
400	Signature is required before payment	User must complete signature step first
401	Unauthorized	Invalid or missing API key
403	You must be an active resident	API user must have active residency
404	Legal entity application not found	Invalid application ID or no access