Amendments and certificates

Use this guide to take an existing entity from a proposed change through signing, payment, review, and document retrieval. For personal or applicant agreements, use the separate Personal and applicant documents guide.

Choose a workflow

Credentials and boundaries

OAuth entity consent currently supports entity and document reads. It does not authorize these filing writes. Partner Keys are for natural-person onboarding; they do not authorize entity filings. Removing representation or revoking a credential removes access on subsequent requests. A valid credential and its scopes alone are insufficient.

Amendments cover legal names, extensions, and principal office addresses. Corporate board/officer appointments, share issuances, and option-pool changes are separate workflows. Staff review and approval remain internal. Use REST for this guide; it does not assume new filing commands exist in the released CLI.

Set up access before building the workflow

For your own organization, create a standard key in the key owner's Developer → API keys. The owner must actively represent the entity. Do not ask clients to share their personal standard keys with your service.

For delegated service access, the represented account owner creates an Agent Key under Developer → Agents and grants these scopes for the complete filing workflow:

agent:entity.filing.read
agent:entity.filing.create
agent:entity.filing.pay
agent:entity.documents.read

Also request agent:registry.search if your integration needs to find entity IDs, and agent:entity.read if it displays current entity details. Read permission does not imply write or payment permission. The owner must sign an active Manifestation of Will for Agent Key writes; this delegation does not replace the amendment's own representative signature.

Agent Keys cannot amend portal-incorporated entities in this release, even when the owner represents them. Finding an entity in the public registry or selecting it during OAuth consent does not remove that restriction. OAuth filing writes and a general delegated-write flow for those existing entities are not provided by these endpoints.

Endpoint map

All paths below follow /api/v1/legal_entities/{id}. {id} is the legal-entity UUID, not its RPN, original application ID, invoice ID, or filing ID.

The OpenAPI amendment reference and certificate reference contain the field-level contracts. These filing routes have no cancellation, deletion, signature-upload, standalone invoice-preparation, or public approval endpoint.

Prepare a staging client

All names and IDs below are fictional. Substitute your own authorized staging entity, credential, and returned filing IDs. For production, change BASE_URL and use production credentials. Accounts and keys are separate between environments.

export BASE_URL='https://stg.portal.eprospera.com'
export API_KEY='<your-staging-standard-or-agent-key>'
export ENTITY_ID='11111111-1111-4111-8111-111111111111'

See Testing in staging for the legacy hostname transition and test vouchers. Never put a key in browser code. These examples use backend cURL calls.

You can obtain the entity UUID from a previously approved incorporation, or search the registry using a name or the entity's 14-digit RPN:

curl -sS -X POST "$BASE_URL/api/v1/registries/legal_entities/search" \
  -H "Authorization: Bearer $API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"query":"Example Harbor"}'

Read the matching entry's id in results, verify its RPN, and replace ENTITY_ID above. A search match does not grant access. Use GET /api/v1/legal_entities/{id} to confirm visibility if you have the entity-read scope. There is no general entity-list route at GET /api/v1/legal_entities.

The examples use fictional IDs to show the request structure. Always save and reuse the IDs returned by your own requests. Check the HTTP status before consuming a response; a JSON body alone does not mean success. Add --fail-with-body to cURL when you need a nonzero exit code on HTTP errors, while retaining the error body for the recovery steps.

Amend an entity

The lifecycle is Draft → Pending Payment → Pending Review → Approved or Rejected. The filing can be signed while still Draft; preparing its invoice moves it to Pending Payment. After that, its proposed changes are read-only.

1. Create or revise a draft

curl -sS -X POST "$BASE_URL/api/v1/legal_entities/$ENTITY_ID/amendments" \
  -H "Authorization: Bearer $API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"updatedName":"Example Harbor","updatedExtension":"LLC"}'

The response is 200. This is a complete illustrative create response; see also the field reference.

{
  "data": {
    "id": "22222222-2222-4222-8222-222222222222",
    "legalEntityId": "11111111-1111-4111-8111-111111111111",
    "statusId": "Draft",
    "proposedChanges": {
      "name": "Example Harbor",
      "extension": "LLC",
      "nameStartsWithExtension": null,
      "principalOfficeAddress": null
    },
    "signed": false,
    "signedAt": null,
    "invoice": null,
    "submittedAt": null,
    "approvedAt": null,
    "rejectedAt": null,
    "rejectedReason": null,
    "createdAt": "2026-09-17T14:00:00.000Z",
    "updatedAt": "2026-09-17T14:00:00.000Z",
    "nextSteps": {
      "changesRequired": false,
      "signatureUrl": "https://stg.portal.eprospera.com/en/business/11111111-1111-4111-8111-111111111111/amendment/22222222-2222-4222-8222-222222222222",
      "paymentRequired": true,
      "submitReady": false,
      "reviewDispatchPending": false
    }
  },
  "nextSteps": {
    "changesRequired": false,
    "signatureUrl": "https://stg.portal.eprospera.com/en/business/11111111-1111-4111-8111-111111111111/amendment/22222222-2222-4222-8222-222222222222",
    "paymentRequired": true,
    "submitReady": false,
    "reviewDispatchPending": false
  }
}

There is one open draft per entity. POST reuses an existing Draft and replaces its proposed changes; omitted fields are cleared. A pending-review filing or an existing invoiced filing causes 409; complete that filing first.

Input rules and PATCH behavior

An address requires line1 (1–200 characters), city (1–100), postalCode (1–20), and country (1–100). line2 (up to 200) and state (up to 100) are optional and nullable. Strings are trimmed. The address country is a text field here, for example Honduras; do not infer a two-letter country requirement from other API workflows.

POST needs at least one non-null proposal. PATCH needs at least one supplied field and can clear the last proposal. Top-level unknown properties and empty string names are rejected. updatedAddress replaces the whole proposed address; a city-only nested patch is not supported. Explicit null removes a proposed change, not the entity's current registered value. Null response proposals mean that field will remain unchanged.

For example, after POST proposes both a new name and extension, PATCH with only updatedName keeps the extension proposal. A second POST with only updatedName clears the extension proposal. Prefer PATCH after receiving a filing ID. There is no version or ETag precondition: coordinate concurrent edits in your own application.

PATCH preserves omitted fields, and explicit null clears a proposed change:

export FILING_ID='22222222-2222-4222-8222-222222222222'
curl -sS -X PATCH "$BASE_URL/api/v1/legal_entities/$ENTITY_ID/amendments/$FILING_ID" \
  -H "Authorization: Bearer $API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"updatedExtension":null,"updatedAddress":{"line1":"45 Example Street","city":"Roatan","postalCode":"34101","country":"Honduras"}}'

Every draft revision invalidates its earlier signature. Fetch the updated filing and use its new signing step before paying. A draft with all changes cleared cannot be invoiced.

POST/PATCH return { "data": { ... }, "nextSteps": { ... } }; the top-level nextSteps duplicates data.nextSteps. GET detail returns only { "data": { ... } }. List returns { "data": [ ... ] }. Read data.nextSteps in a shared detail-response handler.

Other useful fields are legalEntityId, proposedChanges, signed, signedAt, invoice (null or { "id", "statusId" }), submittedAt, approvedAt, rejectedAt, rejectedReason, createdAt, and updatedAt. Dates are UTC strings or null. The proposal fields are not a copy of the current entity record.

2. Complete hosted representative signing

Send the active representative to the returned nextSteps.signatureUrl. They sign in, review the exact proposed changes, and sign. Neither uploaded signatures nor a reused Manifestation of Will satisfy this step. The API never returns signature images.

curl -sS "$BASE_URL/api/v1/legal_entities/$ENTITY_ID/amendments/$FILING_ID" \
  -H "Authorization: Bearer $API_KEY"

Wait for data.signed: true. The signature URL becomes null. Review remains a separate step after payment.

Use the returned URL rather than constructing one. It is a portal navigation link, not an API callback or a substitute for login. Your frontend should offer an Open signing page action and a way to resume the flow. Poll GET after the representative returns; there is no signing-completion webhook in this release. A null signing URL can also mean the filing is no longer open, so check statusId and signed together.

3. Pay and submit

A full-coverage voucher prepares the invoice, applies payment, and submits:

curl -sS -X POST "$BASE_URL/api/v1/legal_entities/$ENTITY_ID/amendments/$FILING_ID/pay/voucher" \
  -H "Authorization: Bearer $API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"voucherCode":"API1234"}'

API1234 is a staging voucher. On success, the response includes success: true, data.invoice.statusId: "paid", and data.statusId: "Pending Review". Payment and event delivery are separate operations; see the recovery table below if the response fails after settlement.

The pay route can create and link the invoice before rejecting an invalid, expired, inapplicable, or insufficient voucher. A failed payment can therefore leave the filing in Pending Payment, with locked proposals and an unpaid invoice. Read the existing filing and correct the payment; do not create another draft to work around it.

The voucher must cover the full invoice. Partial-voucher-plus-card payment is not a workflow provided here. These filing responses expose invoice ID and status, not amount, currency, line items, or a checkout URL. Review pricing/payment in the portal; do not hard-code a fee or assume the API has quoted one. General billing APIs are separate work.

If the representative pays through the portal, fetch the filing and make its first submission only when data.nextSteps.submitReady is true. This means the filing is signed, paid, and unsubmitted in Pending Payment; a paid invoice alone is insufficient. Then submit it explicitly:

curl -sS -X POST "$BASE_URL/api/v1/legal_entities/$ENTITY_ID/amendments/$FILING_ID/submit" \
  -H "Authorization: Bearer $API_KEY"

Submitting again preserves the first submission time and returns the current state. A pending review-dispatch event is retried. Repeating voucher payment after a submitted, paid filing returns its state without another redemption.

Pay and submit success responses use { "success": true, "data": { ... } }. A replay can return an already Approved or Rejected filing; always read the returned status. nextSteps.paymentRequired: false means no payment step is offered in the current state; use invoice.statusId === "paid" to establish recorded settlement.

4. Poll review and retrieve documents

Continue GET requests to the filing URL with a delay between polls. Approved means the registry changes were applied; document generation is asynchronous. Rejected includes rejectedReason. No approval deadline is guaranteed by the API.

curl -sS "$BASE_URL/api/v1/legal_entities/$ENTITY_ID/documents" \
  -H "Authorization: Bearer $API_KEY"

Use agent:entity.documents.read for an Agent Key. Wait for the Certificate of Amendment to appear; an LLC name amendment also regenerates its Certificate of Organization. Responses include document IDs, slugs, versions, and fileUrl. Do not treat a successful payment or submission as evidence that the document exists.

There is no public amendment-to-document ID field. Take a snapshot of existing document IDs/versions before submission and refresh the list after approval. Do not assume the first document is this filing's result or that Approved contains a PDF URL. If you cannot identify the expected document, report the filing ID rather than submitting another filing.

Request a Certificate of Good Standing

LLCs and for-profit corporations need active residency and no dissolution on record. Start by reading current eligibility:

curl -sS "$BASE_URL/api/v1/legal_entities/$ENTITY_ID/certificate_requests" \
  -H "Authorization: Bearer $API_KEY"

The GET response includes both history and a current eligibility check, for example:

{
  "data": [],
  "eligibility": {
    "eligible": true,
    "reason": null,
    "taxCompliant": true
  }
}

eligible: true covers entity type/residency/dissolution checks; it does not mean tax compliance is clear. taxCompliant: false requires resolving the overdue obligations or submitting a supported contest. Null means the tax result is unavailable or not evaluated; do not treat it as true. eligible: false includes reason: "not_eligible_entity_type" or "not_in_good_standing". An inaccessible entity returns HTTP 404 instead of eligibility.

When eligible with no tax contest required, create the request:

curl -sS -X POST "$BASE_URL/api/v1/legal_entities/$ENTITY_ID/certificate_requests" \
  -H "Authorization: Bearer $API_KEY" \
  -H 'Content-Type: application/json' -d '{}'

The POST response contains data.id, data.statusId: "Pending Payment", and an open data.invoice. POST returns an existing open or issued request instead of charging again. Reusing an issued request does not make a new assertion about current eligibility. There is no force-reissue option on this endpoint.

Certificate creation accepts {} (or an empty body); it returns HTTP 200 for both creation and reuse. Save data.id as REQUEST_ID and data.invoice.id separately. There is no separate certificate /submit call and no additional certificate-signature API step.

If creation returns certificate.tax_overdue, provide a contest note and an allowed proof-of-payment upload URL. The URL must come from an approved portal upload; arbitrary external URLs are rejected. This release does not add a public certificate-proof upload API.

curl -sS -X POST "$BASE_URL/api/v1/legal_entities/$ENTITY_ID/certificate_requests" \
  -H "Authorization: Bearer $API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"contest":{"note":"Please review the attached payment confirmation.","proofUrl":"<URL returned by the portal upload>"}}'

An already-contested unpaid request can be retried without resupplying its evidence. Use the returned request ID to pay:

export REQUEST_ID='33333333-3333-4333-8333-333333333333'
curl -sS -X POST "$BASE_URL/api/v1/legal_entities/$ENTITY_ID/certificate_requests/$REQUEST_ID/pay/voucher" \
  -H "Authorization: Bearer $API_KEY" \
  -H 'Content-Type: application/json' -d '{"voucherCode":"API1234"}'
curl -sS "$BASE_URL/api/v1/legal_entities/$ENTITY_ID/certificate_requests/$REQUEST_ID" \
  -H "Authorization: Bearer $API_KEY"

Tax-current requests proceed through Approved to Issued; contested requests enter Pending Review for a registrar. Completion means statusId: "Issued" and a non-null documentUrl. Rejected requests include rejectionReason. The certificate also appears in the entity's document list.

Stop polling when the request reaches Issued, Rejected, or Cancelled. Only Issued delivers a certificate at documentUrl. For Rejected, show rejectionReason; for Cancelled, show the cancellation state. Neither state should trigger automatic repayment or a replacement request. Contact support if the request needs intervention.

After successful payment, invoice.statusId may already be paid while the request still says Pending Payment. This is an intermediate asynchronous state, not an instruction to pay again. Poll the same request. A contested request goes to review; a change in tax compliance or an unavailable compliance result can also route a request to review.

An issued GET response looks like this (URLs and IDs are fictional):

{
  "data": {
    "id": "33333333-3333-4333-8333-333333333333",
    "legalEntityId": "11111111-1111-4111-8111-111111111111",
    "type": "certificate_of_good_standing",
    "statusId": "Issued",
    "contested": false,
    "taxContestNote": null,
    "taxPaymentProofUrl": null,
    "contestedAt": null,
    "rejectionReason": null,
    "reviewedAt": "2026-09-17T14:02:00.000Z",
    "issuedAt": "2026-09-17T14:03:00.000Z",
    "documentId": "55555555-5555-4555-8555-555555555555",
    "documentUrl": "https://documents.example.test/good-standing.pdf",
    "invoice": {
      "id": "66666666-6666-4666-8666-666666666666",
      "statusId": "paid"
    },
    "createdAt": "2026-09-17T14:00:00.000Z",
    "updatedAt": "2026-09-17T14:03:00.000Z",
    "nextSteps": {
      "paymentRequired": false,
      "awaitingReview": false,
      "issued": true
    }
  }
}

The create response adds a top-level copy of nextSteps; the payment response adds success and message. List responses include all requests, including historical rejections, while POST reuses the latest open or fulfilled request. A rejection is not reopened by retrying payment. There is no public cancel/refund or forced-reissue operation; contact support if the existing request needs intervention.

Certificate errors you can handle directly

These are certificate creation responses; payment has its own voucher errors below. Use the HTTP status and code together.

A contest note must contain 1–2,000 characters after trimming, and proofUrl must be a valid URL no longer than 2,048 characters. Once a contest is recorded, retrying does not replace its note/proof. Use the portal/support for an evidence correction. Do not attach arbitrary proof when no tax obligation is disputed.

Recover from failures

Not every failure includes code. Some return just { "error": "..." }; validation may also return details, and a state conflict can include data or nextSteps. Handle the status first, use code when present, and retain the message for the user.

These filing endpoints use resource-level duplicate protection and settlement checks. They do not implement an Idempotency-Key response cache. Store returned IDs and use PATCH for draft revisions. The Partner API has a separate durable idempotency contract; do not assume it applies to these endpoints.

Filing and certificate list endpoints return complete arrays, newest first; they have no pagination parameters. Use bounded polling and observe rate limits.

Voucher failures versus submission failures

Both filing voucher endpoints return 400 with one of these error messages for expected voucher failures. They do not guarantee a machine-readable voucher code in the body:

For amendments, a failure after successful payment can instead return 409 or 503 and include invoiceId, filingId, and code. For example:

{
  "error": "Voucher payment was applied. Fetch the filing and retry submission; do not create a replacement filing.",
  "code": "submission_not_queued",
  "invoiceId": "66666666-6666-4666-8666-666666666666",
  "filingId": "22222222-2222-4222-8222-222222222222"
}

On this 503, GET the same filing. Its recorded submission remains pending review and the invoice remains paid. Retry /submit, not a new POST /amendments. A 503 from /submit itself can contain only error and code; retain your existing IDs. If it is already Approved or Rejected, show that state instead of continuing submission retries.

For an unrecognized 500 or network timeout, the outcome is unknown. Read state first. If you cannot read it yet, wait and retry the read; do not switch to a new resource or invoice.

Polling and support

As a client recommendation, poll every 5–30 seconds while the user is actively completing signing/payment, with jitter. Back off for background review and document generation; there is no guaranteed processing time. Honor Retry-After when supplied, and use exponential backoff when it is absent. Stop polling terminal rejected or cancelled states. For approval, stop only after your required document is available. There are no outbound filing webhooks.

If a paid filing remains stuck, contact the Help Center with the environment, HTTP method/path/status, UTC timestamps, entity ID, filing/request ID, invoice ID, and a redacted response. Never include raw API keys, vouchers, signatures, personal documents, or document download URLs in a support transcript.

Frequently asked integration questions

Integration acceptance checklist

Before enabling production writes, exercise this sequence with authorized staging records:

1. Confirm access with the intended key type; verify missing scopes and unrelated entities fail.
2. Create a draft, PATCH one field, and verify omitted proposals remain. Clear a proposal with null.
3. Sign in the portal, edit the Draft, and verify it needs a new signature before payment.
4. Pay with a staging voucher, record the invoice and filing IDs, and retry the same resource.
5. Poll review and retrieve the resulting document; handle rejection and delayed PDF generation separately.
6. Read certificate eligibility, create/pay a request, and wait for both Issued and documentUrl; also verify that Rejected and Cancelled stop polling without another payment.
7. Retry the completed certificate request and verify it returns the existing certificate.
8. Test timeout/503 handling against a mocked response so your client reads and resumes the same filing.

Treat the steps requiring review/issuance as complete only after the deployed staging flow has produced the expected records and PDFs. Successful schema validation alone does not establish end-to-end availability.

Personal and applicant documents

The dedicated document guide provides full response examples, active-residency matching rules, empty-result troubleshooting, and download handling.

For a person's own documents, use an OAuth token consented for eprospera:person.documents.read or an Agent Key with agent:person.documents.read:

curl -sS "$BASE_URL/api/v1/me/natural-person/documents" \
  -H 'Authorization: Bearer <personal-oauth-token-or-agent-key>'

The response contains data document records and agreementOfCoexistence. Standard API keys are not accepted on this endpoint. For consented entity reads, use the existing OAuth /api/v1/me/legal-entities/{id}/documents with eprospera:entity.documents.read; unselected entities remain unavailable.

A partner can read only agreements and policy documents for its own applicant:

curl -sS "$BASE_URL/api/v1/partner/residency_applications/44444444-4444-4444-8444-444444444444/documents" \
  -H 'Authorization: Bearer <partner-key>'

This returns the accepted agreement version and, after approval and generation, signed agreement/policy documents. Identity documents, tax records, and admin-only documents are excluded. Document URLs in this release have no advertised expiry guarantee; handle them as sensitive links. See the applicant document reference.