Addons API

Discover, purchase, and complete addon surveys for an entity

Add-ons extend entity functionality with services like registered office, nominee directors, annual maintenance, or corporate changes. The Addons API has two halves: (1) discovery and purchase, and (2) survey requirements and submission for add-ons that need extra customer input.

Two ways to attach add-ons

At entity creation: pass addon_ids: [] on POST /entities. All addons are bundled into the setup invoice and pricing rolls up.
After creation: call POST /entities/:id/addons for any addon the customer wants later. Whether this appends to the existing setup invoice or raises a new invoice depends on the entity's status — see the decision tree below.

Billing decision tree

When you call POST /entities/:id/addons:

Entity status is pre_incorporation or returned_for_changes AND the original setup invoice is unpaid → addon line items are appended to that invoice. Response carries invoice.action: "appended". Any prior Stripe / Radom session for that invoice is now stale; pass payment_provider to regenerate it automatically, or use POST /invoices/:id/checkout-session.
Entity is post-submission, OR setup invoice is already paid → a fresh api_topup invoice is created for the addon alone. Response carries invoice.action: "created".

Lifecycle availability matrix

Every addon entry returned by the catalog and entity-addons endpoints carries an availability object with eight booleans — one per stage of the entity lifecycle. Filter on the flag matching the current stage to decide whether to surface the addon to your end user.

initial_checkout — basket flow before an entity row exists
pre_incorporation, submitted_for_review, submitted_to_csp, returned_for_changes — pre-incorporation lifecycle states
incorporated, liquidation, after_dissolved — post-incorporation states

Addon Survey Flow

Purchase an add-on when creating an entity, via POST /entities/:id/addons, or via the dashboard.
If the addon's GET response shows requires_survey: true, call GET /entities/:id/addons/:slug/requirements to get the form schema.
Render the form and save progress with PATCH /entities/:id/addons/:slug/progress.
Submit the completed survey with POST /entities/:id/addons/:slug/submit.

Addon Survey Flow

Purchase an add-on when creating an entity or via the dashboard
Call GET /entities/:id/addons/:slug/requirements to get the survey form schema
Render the form and save progress with PATCH /entities/:id/addons/:slug/progress
Submit the completed survey with POST /entities/:id/addons/:slug/submit

Addon Survey Response

Addon Survey Requirements Response

{
  "success": true,
  "data": {
    "entity_id": "ent_abc123",
    "addon": {
      "id": "ea_xyz789",
      "slug": "change-directors",
      "name": "Change Directors",
      "description": "Add, remove, or update directors",
      "status": "active"
    },
    "survey": {
      "id": "srv_def456",
      "name": "Change Directors Survey"
    },
    "sections": [
      {
        "sectionType": "entity_details",
        "label": "Change Details",
        "fields": [
          {
            "fieldKey": "change_type",
            "label": "Type of Change",
            "type": "select",
            "required": true,
            "options": [
              { "value": "add_director", "label": "Add Director" },
              { "value": "remove_director", "label": "Remove Director" },
              { "value": "update_director", "label": "Update Director Details" }
            ]
          },
          {
            "fieldKey": "effective_date",
            "label": "Effective Date",
            "type": "date",
            "required": true
          }
        ]
      }
    ],
    "currentData": {
      "change-details": {
        "change_type": "add_director"
      }
    },
    "completionStatus": {
      "sectionsComplete": 0,
      "sectionsTotal": 2,
      "readyForSubmission": false
    }
  }
}

Common Add-on Types

Slug	Name	Has Survey
`change-directors`	Change Directors	Yes
`change-shareholders`	Change Shareholders	Yes
`change-officers`	Change Officers	Yes
`registered-agent`	Registered Agent	No
`annual-maintenance`	Annual Maintenance	No

Discovery & purchase

Survey requirements & submission

Webhooks

The following webhook events are fired for add-on surveys:

Event	Description
`addon.purchased`	When an add-on is purchased for an entity (both append and topup paths).
`addon.invoiced`	When an addon raises a new `api_topup` invoice (post-submission purchases).
`addon.status_changed`	When an add-on status changes (e.g., submitted for review, approved, completed).

Webhook Payload Example

addon.status_changed Webhook

{
  "id": "evt_abc123",
  "type": "addon.status_changed",
  "created_at": "2024-03-15T14:30:00Z",
  "data": {
    "entity_id": "ent_abc123",
    "addon_slug": "change-directors",
    "old_status": "draft",
    "new_status": "submitted_for_review"
  }
}