Registrations API

Overview

The Registrations API manages formal registrations with government agencies that enable business operations, including tax registrations, payroll accounts, corporate registry access, and trade licenses.

Core endpoints

List registrations

Get all registrations for a business entity.

GET /business-entities/:businessEntityId/registrations

Path parameters

Parameter	Type	Description
`businessEntityId`	integer	Unique identifier for the business entity

Query parameters

Parameter	Type	Description
`extends`	string[]	Optional fields to include: `CREDENTIALS` adds the credentials linked to each registration as `linkedCredential`
`applicability`	string	Only return registrations of one applicability: `DOMESTIC`, `FOREIGN`, `BOTH`, or `CUSTOM` for custom registrations

Response The example below is trimmed. governmentIdentifiers are the identifiers the registration produced that the entity holds; unheldGovernmentIdentifiers are the ones it produces that the entity has not recorded yet, in the same shape.

{
  "registrations": [
    {
      "id": "cm3h4d5e60003l508p2q4r6st",
      "registrationIdentifier": "REG:US:EIN_APPLICATION",
      "displayName": "Employer Identification Number Application",
      "description": "IRS process for obtaining a federal EIN through the online tool or by phone, fax, or mail.",
      "purpose": "INCOME_TAX",
      "country": "US",
      "jurisdiction": null,
      "jurisdictionId": "ADM0_US",
      "businessEntityId": 123,
      "corporationType": "CCorp",
      "applicability": "BOTH",
      "isCustom": false,
      "status": "ACTIVE",
      "registrationStatus": "REGISTERED",
      "registeredBy": "USER",
      "effectiveStartDate": "2020-01-15",
      "effectiveEndDate": null,
      "governmentIdentifiers": [
        { "id": "cm3g1b2c30002l508h7j9k1mn", "identifierTypeId": "GID:US:EIN", "displayName": "Employer Identification Number", "value": "12-3456789" }
      ],
      "unheldGovernmentIdentifiers": [],
      "documents": [],
      "hasLinkedCredential": true,
      "linkedCredential": [
        {
          "id": "0b6f3f4e-6a7d-4c1e-9d0a-2f5b8c9e1a23",
          "blocks": [
            { "id": "cm3j8k9l00005l508a1b2c3d4", "key": "User name", "mask": null, "type": "PlainText" },
            { "id": "cm3j8k9l00006l508e5f6g7h8", "key": "Password", "mask": "3!", "type": "SecureString" }
          ]
        }
      ],
      "createdAt": 1579082400000,
      "lastUpdatedAt": 1579082400000
    }
  ],
  "count": 1
}

linkedCredential and hasLinkedCredential only reflect the linked credentials when you request extends=CREDENTIALS. Without it, linkedCredential is left out and hasLinkedCredential is false. createdAt and lastUpdatedAt are Unix timestamps in milliseconds.

Get registration

Retrieve a single registration by ID.

GET /business-entities/:businessEntityId/registrations/:registrationId

Path parameters

Parameter	Type	Description
`businessEntityId`	integer	Business entity ID
`registrationId`	string	Registration ID

Query parameters

Parameter	Type	Description
`extends`	string[]	Optional fields to include: `CREDENTIALS`

Response The registration has the same shape as an entry of List registrations. The example below is trimmed.

{
  "registration": {
    "id": "cm3h4d5e60003l508p2q4r6st",
    "registrationIdentifier": "REG:US:EIN_APPLICATION",
    "displayName": "Employer Identification Number Application",
    "purpose": "INCOME_TAX",
    "country": "US",
    "jurisdictionId": "ADM0_US",
    "status": "ACTIVE",
    "effectiveStartDate": "2020-01-15",
    "effectiveEndDate": null
  }
}

Create registration

Add a new registration to a business entity. Either name a registration from the entity’s supported registrations with registrationIdentifier, or describe a custom one with name and registrationPurpose.

POST /business-entities/:businessEntityId/registrations

Path parameters

Parameter	Type	Description
`businessEntityId`	integer	Business entity ID

Request body

{
  "registrationIdentifier": "REG:US:EIN_APPLICATION",
  "status": "ACTIVE",
  "effectiveStartDate": "2020-01-15",
  "governmentIdentifiers": [
    { "identifierTypeId": "GID:US:EIN", "value": "12-3456789" }
  ]
}

A custom registration:

{
  "name": "San Francisco business registration",
  "registrationPurpose": "OTHER",
  "country": "US",
  "jurisdiction": "ADM1_US-CA",
  "status": "ACTIVE",
  "effectiveStartDate": "2021-03-01"
}

Field	Type	Required	Description
`registrationIdentifier`	string	Unless custom	The `registrationIdentifier` of a supported registration. Cannot be combined with `name` or `registrationPurpose`.
`name`	string	Custom only	Name of a custom registration
`registrationPurpose`	string	Custom only	`INCOME_TAX`, `INDIRECT_TAX`, `PAYROLL`, `CORPORATE_REGISTRY`, `SOCIAL_SECURITY`, `TRADE`, `FORMATION`, `REGULATORY_REPORTING`, `TAX_AND_COMPLIANCE_REPORTING` or `OTHER`
`country`	string	Custom only	Country of the registration (ISO 3166-1 alpha-2). For a supported registration, defaults to the entity’s incorporation country.
`jurisdiction`	string	No	Jurisdiction of a custom registration, for example `ADM1_US-CA`
`status`	string	Yes	Registration status
`effectiveStartDate`	string	Yes	ISO 8601 date the registration took effect
`effectiveEndDate`	string	No	ISO 8601 date the registration ended. Must be after `effectiveStartDate`.
`governmentIdentifiers`	object[]	No	Identifiers the registration produced: a `value`, the `identifierTypeId` it is for, and optional `supportingDocuments` as in the Government Identifiers API. `identifierTypeId` may be left out where the registration produces one identifier, and is left out for a custom registration, whose number is held under an id Commenda gives it.

A supported registration can be recorded once per entity; creating it again returns 409 Conflict. Response Returns 201 Created.

{
  "registration": {
    "id": "cm3h4d5e60003l508p2q4r6st"
  }
}

Update registration

Update an existing registration.

PATCH /business-entities/:businessEntityId/registrations/:registrationId

Path parameters

Parameter	Type	Description
`businessEntityId`	integer	Business entity ID
`registrationId`	string	Registration ID

Request body

{
  "status": "INACTIVE",
  "effectiveStartDate": "2020-01-15",
  "effectiveEndDate": "2025-12-31"
}

Field	Type	Required	Description
`effectiveStartDate`	string	Yes	ISO 8601 date the registration took effect
`effectiveEndDate`	string	No	ISO 8601 date the registration ended. Must be after `effectiveStartDate`.
`status`	string	No	Registration status
`registeredBy`	string	No	`COMMENDA` or `USER`
`governmentIdentifiers`	object[]	No	Updates to the registration’s identifiers: each takes the identifier’s `id`, and a new `value` and/or `supportingDocuments` (the identifier’s whole evidence; an empty list removes it)

Response Returns 200 OK with no body.

Delete registration

Remove a registration from a business entity.

DELETE /business-entities/:businessEntityId/registrations/:registrationId

Path parameters

Parameter	Type	Description
`businessEntityId`	integer	Business entity ID
`registrationId`	string	Registration ID

Response Returns 204 No Content on success.

Supported registrations

Get supported registrations

Get the registrations a business entity can record, in its incorporation country or in another country.

GET /business-entities/registrations/supportedRegistrations

Query parameters

Parameter	Type	Description
`businessEntityId`	integer	Business entity ID (required)
`country`	string	Country to register in (ISO 3166-1 alpha-2). Defaults to the entity’s incorporation country.

Response

{
  "supportedRegistrations": [
    {
      "registrationIdentifier": "REG:US:EIN_APPLICATION",
      "displayName": "Employer Identification Number Application",
      "description": "IRS process for obtaining a federal EIN through the online tool or by phone, fax, or mail.",
      "purpose": "INCOME_TAX",
      "country": "US",
      "jurisdictionId": "ADM0_US",
      "legacyJurisdiction": null,
      "corporationType": "CCorp",
      "applicability": "BOTH",
      "producedGovernmentIdentifiers": [
        { "identifierTypeId": "GID:US:EIN", "displayName": "Employer Identification Number", "example": "12-3456789", "regex": null }
      ]
    }
  ],
  "count": 1
}

Get supported registrations for entity

Get registration types available for a specific business entity.

GET /business-entities/:businessEntityId/registrations/supportedRegistrations

Path parameters

Parameter	Type	Description
`businessEntityId`	integer	Business entity ID

Response Same format as above, for the entity’s incorporation country.

Registration types

Formation

Company registration with corporate registry:

US: Secretary of State registration
UK: Companies House registration
India: ROC (Registrar of Companies) registration
Singapore: ACRA registration

Income tax

Federal/national tax identification:

US: IRS federal income tax
UK: HMRC Corporation Tax
India: Income Tax Department
Canada: CRA corporate income tax

Indirect tax

VAT/GST/sales tax registration:

US: State sales tax permits
UK: VAT registration
India: GST registration
Singapore: GST registration
UAE: VAT registration

Payroll

Employer withholding and unemployment insurance:

US: State withholding tax, unemployment insurance
UK: PAYE registration
India: Professional Tax, ESI, EPF
Singapore: CPF registration

Employee benefit programs:

US: Social Security Administration
India: ESIC, EPFO
Singapore: CPF Board

Trade

Import/export licenses:

US: Customs and Border Protection
India: Import Export Code (IEC)
UAE: Trade license

Corporate registry

Access credentials for filing systems:

US: State business portals
UK: Companies House WebFiling
India: MCA portal
Singapore: BizFile+

Registration status

The status field takes one of:

Status	Description
`ACTIVE`	Registration is current and valid
`INACTIVE`	Registration has been deactivated
`PENDING`	Registration application in progress
`INVALID`	Registration has been marked invalid

Domestic vs foreign registrations

Domestic: For entities formed in the jurisdiction (e.g., Delaware corporation registering in Delaware)
Foreign: For entities qualified to do business from another jurisdiction (e.g., Delaware corporation registering in California)

A registration’s applicability says which it is for: DOMESTIC, FOREIGN or BOTH. It is null for a custom registration.

Linking credentials

Associate portal access credentials with registrations:

POST /business-entities/:businessEntityId/registrations/:registrationId/credential/:credentialId

This links a credential to a specific registration, enabling automated filing and compliance workflows. Returns 200 OK:

{
  "credential": {
    "id": "0b6f3f4e-6a7d-4c1e-9d0a-2f5b8c9e1a23"
  }
}

Business Entity API - Manage parent business entities
Government Identifiers API - Required identifiers for registrations
Credentials API - Portal access for registrations

Get Started

Registrations

Registrations V2

Corporations

Tax Calculations

Transactions

Address Requirements

Registration Thresholds

Products

Customers

Exemption Certificates

Exemptions

Files

Credentials

Locations

Filings

Webhooks

Overview

Core endpoints

List registrations

Get registration

Create registration

Update registration

Delete registration

Supported registrations

Get supported registrations

Get supported registrations for entity

Registration types

Formation

Income tax

Indirect tax

Payroll

Trade

Corporate registry

Registration status

Domestic vs foreign registrations

Linking credentials

​Overview

​Core endpoints

​List registrations

​Get registration

​Create registration

​Update registration

​Delete registration

​Supported registrations

​Get supported registrations

​Get supported registrations for entity

​Registration types

​Formation

​Income tax

​Indirect tax

​Payroll

​Social security

​Trade

​Corporate registry

​Registration status

​Domestic vs foreign registrations

​Linking credentials

​Related resources

Overview

Core endpoints

List registrations

Get registration

Create registration

Update registration

Delete registration

Supported registrations

Get supported registrations

Get supported registrations for entity

Registration types

Formation

Income tax

Indirect tax

Payroll

Social security

Trade

Corporate registry

Registration status

Domestic vs foreign registrations

Linking credentials

Related resources