Government identifiers API

Overview

The Government Identifiers API manages official identification numbers issued by government authorities, such as EINs, VAT numbers, tax IDs, and company registration numbers across 50+ countries.

Core endpoints

List government identifiers

Get all government identifiers for a business entity.

GET /business-entities/:businessEntityId/government-identifiers

Path parameters

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

Query parameters

Parameter	Type	Description
`extend`	string[]	Optional fields to include: `SUPPORTING_DOCUMENT` fills in the file name and URL of each identifier’s uploaded evidence

Response The list also includes the identifiers the entity is expected to hold but has not recorded yet. Those entries have id: null and value: null. The example below is trimmed.

{
  "governmentIdentifiers": [
    {
      "id": "cm3g1b2c30002l508h7j9k1mn",
      "identifierTypeId": "GID:US:EIN",
      "displayName": "Employer Identification Number",
      "shortName": "EIN",
      "value": "12-3456789",
      "example": "12-3456789",
      "country": "US",
          "jurisdictionId": "ADM0_US",
      "corporationId": 123,
      "purposes": ["TAXATION"],
      "isFunctionCritical": true,
      "isCustom": false,
      "regexString": null,
      "supportingDocuments": [
        { "id": 456, "fileName": "EIN_Letter.pdf", "fileUrl": "https://files.example.com/ein-letter.pdf" }
      ],
      "acceptedDocuments": [
        { "documentTypeId": "DOC:US:CP575", "displayName": "Employer Identification Number Verification Notice" }
      ],
      "linkedRegistrations": [
        { "registrationIdentifier": "REG:US:EIN_APPLICATION", "displayName": "Employer Identification Number Application", "purpose": "INCOME_TAX" }
      ],
      "createdAt": 1579082400000,
      "lastUpdatedAt": 1579082400000
    },
    {
      "id": null,
      "identifierTypeId": "GID:US_DE:FILE_NUMBER",
      "displayName": "Delaware Entity File Number",
      "value": null,
      "country": "US"
    }
  ],
  "count": 2
}

createdAt and lastUpdatedAt are Unix timestamps in milliseconds.

Get government identifier

Retrieve a single government identifier by ID.

GET /business-entities/:businessEntityId/government-identifiers/:governmentIdentifierId

Path parameters

Parameter	Type	Description
`businessEntityId`	integer	Business entity ID
`governmentIdentifierId`	string	Government identifier ID

Response Returns one identifier, in the same shape as an entry of List government identifiers. The example below is trimmed.

{
  "id": "cm3g1b2c30002l508h7j9k1mn",
  "identifierTypeId": "GID:US:EIN",
  "displayName": "Employer Identification Number",
  "value": "12-3456789",
  "country": "US",
  "jurisdictionId": "ADM0_US",
  "purposes": ["TAXATION"],
  "supportingDocuments": [
    { "id": 456, "fileName": "EIN_Letter.pdf", "fileUrl": "https://files.example.com/ein-letter.pdf" }
  ]
}

Create government identifier

Add a new government identifier to a business entity.

POST /business-entities/:businessEntityId/government-identifiers

Path parameters

Parameter	Type	Description
`businessEntityId`	integer	Business entity ID

Request body

{
  "identifierTypeId": "GID:US:EIN",
  "value": "12-3456789",
  "supportingDocuments": [
    {
      "fileUrl": "https://files.example.com/ein-letter.pdf",
      "fileName": "EIN_Letter.pdf"
    }
  ]
}

Field	Type	Required	Description
`identifierTypeId`	string	Yes	The identifier type, as returned in `identifierTypeId` by List government identifiers (for example `GID:US:EIN`)
`value`	string	Yes	The identifier value
`country`	string	No	Issuing country (ISO 3166-1 alpha-2). Defaults to the entity’s incorporation country.
`registrationIdentifier`	string	No	The registration the identifier came from (for example `REG:US:EIN_APPLICATION`). Required when more than one of the entity’s registrations produces this identifier type.
`supportingDocuments`	object[]	No	Evidence for the identifier. See Supporting documents.

An entity holds one identifier of each type; creating a second one returns 400 Bad Request. Response Returns 201 Created.

{
  "governmentIdentifier": {
    "id": "cm3g1b2c30002l508h7j9k1mn"
  }
}

Update government identifier

Update an existing government identifier.

PATCH /business-entities/:businessEntityId/government-identifiers/:governmentIdentifierId

Path parameters

Parameter	Type	Description
`businessEntityId`	integer	Business entity ID
`governmentIdentifierId`	string	Government identifier ID

Request body

{
  "value": "12-3456789",
  "supportingDocuments": [
    {
      "fileUrl": "https://files.example.com/ein-letter-2024.pdf",
      "fileName": "EIN_Letter_2024.pdf"
    }
  ]
}

Field	Type	Description
`value`	string	The new identifier value
`supportingDocuments`	object[]	The identifier’s whole evidence: it replaces what the identifier holds. An empty list removes it; leaving the field out changes nothing.

Response Returns 200 OK with no body.

Supported identifier types

The type codes below name each identifier informally. To create one, send its identifierTypeId (for example GID:US:EIN), as returned by List government identifiers.

United States

Type	Description	Format	Jurisdiction
`EIN`	Employer Identification Number	`XX-XXXXXXX`	Federal
`STATE_ENTITY_NUMBER`	State entity registration number	Varies by state	State-level

India

Type	Description	Format
`PAN`	Permanent Account Number	`[A-Z]{5}[0-9]{4}[A-Z]`
`TAN`	Tax Deduction Account Number	`[A-Z]{4}[0-9]{5}[A-Z]`
`GSTIN`	Goods and Services Tax ID	`[0-9]{2}[A-Z]{5}[0-9]{4}[A-Z][0-9][Z][0-9A-Z]`
`CIN`	Corporate Identity Number	`[LU][0-9]{5}[A-Z]{2}[0-9]{4}[A-Z]{3}[0-9]{6}`
`LLPIN`	Limited Liability Partnership ID	`[A-Z]{3}-[0-9]{4}`

United Kingdom

Type	Description	Format
`COMPANY_REGISTRATION_NUMBER`	Companies House number	`[A-Z0-9]{8}`
`UTR`	Unique Taxpayer Reference	`[0-9]{10}`
`VAT_NUMBER`	VAT registration number	`GB[0-9]{9}`
`PAYE_NUMBER`	Pay As You Earn reference	`[0-9]{3}/[A-Z0-9]+`

Canada

Type	Description	Format
`BUSINESS_NUMBER`	CRA Business Number	`[0-9]{9}`
`CORPORATION_NUMBER`	Federal corporation number	`[0-9]{7}`
`COMPANY_KEY`	Provincial company key	Varies by province

Singapore

Type	Description	Format
`UEN`	Unique Entity Number	`[0-9]{9}[A-Z]` or `[0-9]{10}[A-Z]`
`GST_NUMBER`	GST registration number	`M[0-9]{8}[A-Z]`
`CPF_SUBMISSION_NUMBER`	CPF submission number	`[0-9]{8}[A-Z]`

United Arab Emirates

Type	Description
`LICENSE_NUMBER`	Trade license number
`TRN`	Tax Registration Number

Australia

Type	Description	Format
`ACN`	Australian Company Number	`[0-9]{9}`
`ABN`	Australian Business Number	`[0-9]{11}`
`TFN`	Tax File Number	`[0-9]{9}`
`GST_NUMBER`	GST registration number	`[0-9]{11}`

Germany

Type	Description	Format
`HRB_NUMBER`	Commercial register number	`HRB [0-9]+`
`STEUERNUMMER`	Tax number	Varies by state
`VAT_NUMBER`	VAT identification number	`DE[0-9]{9}`

France

Type	Description	Format
`SIREN`	Business identification number	`[0-9]{9}`
`CORPORATE_TAX_NUMBER`	Corporate tax number	`[0-9]{13}`
`TVA_NUMBER`	VAT number	`FR[0-9A-Z]{2}[0-9]{9}`

Validation rules

Government identifier values are validated against the identifier type’s format pattern, where one is defined (returned as regexString). Invalid formats will return a 400 Bad Request error.

Supporting documents

A government identifier can carry supporting documents (e.g., EIN letter, tax registration certificate). Upload each file first, then list them in supportingDocuments when creating or updating the identifier. Each entry takes:

Field	Type	Required	Description
`fileUrl`	string	Yes	Hosted URL of the file
`fileName`	string	Yes	File name
`fileId`	integer	No	ID of a file already stored in Commenda. That file is used, updated with `fileUrl` and `fileName`, instead of a new file being created.

The accepted document types for an identifier are listed in its acceptedDocuments.

Business Entity API - Manage parent business entities
Registrations API - Link identifiers to 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 government identifiers

Get government identifier

Create government identifier

Update government identifier

Supported identifier types

United States

India

United Kingdom

Canada

Singapore

United Arab Emirates

Australia

Germany

France

Validation rules

Supporting documents

​Overview

​Core endpoints

​List government identifiers

​Get government identifier

​Create government identifier

​Update government identifier

​Supported identifier types

​United States

​India

​United Kingdom

​Canada

​Singapore

​United Arab Emirates

​Australia

​Germany

​France

​Validation rules

​Supporting documents

​Related resources

Overview

Core endpoints

List government identifiers

Get government identifier

Create government identifier

Update government identifier

Supported identifier types

United States

India

United Kingdom

Canada

Singapore

United Arab Emirates

Australia

Germany

France

Validation rules

Supporting documents

Related resources