Get Formation Status

curl --request GET \
  --url https://api.clemta.com/formations/{id} \
  --header 'X-API-Key: <api-key>'

{
  "success": true,
  "company_id": "<string>",
  "company_name": "<string>",
  "formation_date": "<string>",
  "ein": "<string>",
  "external_id": "<string>",
  "custom_data": {},
  "country": "<string>",
  "industry": "<string>",
  "number_of_shares": 123,
  "par_value": 123,
  "is_company_private": true,
  "address": {
    "address1": "<string>",
    "city": "<string>",
    "state": "<string>",
    "zip": "<string>",
    "country": "<string>",
    "address2": "<string>"
  },
  "timezone": "<string>",
  "shareholders": [
    {
      "first_name": "<string>",
      "last_name": "<string>",
      "title": "<string>",
      "number_of_shares": 123,
      "email": "<string>",
      "phone": "<string>",
      "iso_code": "<string>",
      "address": {
        "address1": "<string>",
        "city": "<string>",
        "state": "<string>",
        "zip": "<string>",
        "country": "<string>",
        "address2": "<string>"
      },
      "is_director": true,
      "is_main_incorporator": true,
      "legal_entity_name": "<string>",
      "representative_name": "<string>"
    }
  ],
  "directors": [
    {
      "first_name": "<string>",
      "last_name": "<string>",
      "title": "<string>",
      "email": "<string>",
      "phone": "<string>",
      "iso_code": "<string>",
      "address": {
        "address1": "<string>",
        "city": "<string>",
        "state": "<string>",
        "zip": "<string>",
        "country": "<string>",
        "address2": "<string>"
      }
    }
  ],
  "officers": [
    {
      "first_name": "<string>",
      "last_name": "<string>",
      "title": "<string>",
      "email": "<string>",
      "phone": "<string>",
      "iso_code": "<string>",
      "address": {
        "address1": "<string>",
        "city": "<string>",
        "state": "<string>",
        "zip": "<string>",
        "country": "<string>",
        "address2": "<string>"
      }
    }
  ],
  "created_at": 123,
  "updated_at": 123,
  "federal_tax_filing": 123,
  "state_tax_filing": 123,
  "foreign_qualification_addresses": [
    {
      "address1": "<string>",
      "city": "<string>",
      "state": "<string>",
      "zip": "<string>",
      "country": "<string>",
      "address2": "<string>"
    }
  ]
}

GET

formations

{id}

Get Formation Status

curl --request GET \
  --url https://api.clemta.com/formations/{id} \
  --header 'X-API-Key: <api-key>'

{
  "success": true,
  "company_id": "<string>",
  "company_name": "<string>",
  "formation_date": "<string>",
  "ein": "<string>",
  "external_id": "<string>",
  "custom_data": {},
  "country": "<string>",
  "industry": "<string>",
  "number_of_shares": 123,
  "par_value": 123,
  "is_company_private": true,
  "address": {
    "address1": "<string>",
    "city": "<string>",
    "state": "<string>",
    "zip": "<string>",
    "country": "<string>",
    "address2": "<string>"
  },
  "timezone": "<string>",
  "shareholders": [
    {
      "first_name": "<string>",
      "last_name": "<string>",
      "title": "<string>",
      "number_of_shares": 123,
      "email": "<string>",
      "phone": "<string>",
      "iso_code": "<string>",
      "address": {
        "address1": "<string>",
        "city": "<string>",
        "state": "<string>",
        "zip": "<string>",
        "country": "<string>",
        "address2": "<string>"
      },
      "is_director": true,
      "is_main_incorporator": true,
      "legal_entity_name": "<string>",
      "representative_name": "<string>"
    }
  ],
  "directors": [
    {
      "first_name": "<string>",
      "last_name": "<string>",
      "title": "<string>",
      "email": "<string>",
      "phone": "<string>",
      "iso_code": "<string>",
      "address": {
        "address1": "<string>",
        "city": "<string>",
        "state": "<string>",
        "zip": "<string>",
        "country": "<string>",
        "address2": "<string>"
      }
    }
  ],
  "officers": [
    {
      "first_name": "<string>",
      "last_name": "<string>",
      "title": "<string>",
      "email": "<string>",
      "phone": "<string>",
      "iso_code": "<string>",
      "address": {
        "address1": "<string>",
        "city": "<string>",
        "state": "<string>",
        "zip": "<string>",
        "country": "<string>",
        "address2": "<string>"
      }
    }
  ],
  "created_at": 123,
  "updated_at": 123,
  "federal_tax_filing": 123,
  "state_tax_filing": 123,
  "foreign_qualification_addresses": [
    {
      "address1": "<string>",
      "city": "<string>",
      "state": "<string>",
      "zip": "<string>",
      "country": "<string>",
      "address2": "<string>"
    }
  ]
}

Get Company Formation Status

This endpoint allows partners to retrieve the current status of a company formation process. It supports conditional requests using the If-Modified-Since header for efficient polling.

Headers

Parameter	Type	Description
X-API-KEY	string	Formation API Key (required)
If-Modified-Since	string	RFC 7232 formatted date to check if the resource has been modified (optional)

Path Parameters

Parameter	Type	Description
company_id	string	Company ID (required)

Response

{
  "success": true,
  "data": {
    "company_id": "60d21b4667d0d8992e610c85",
    "company_name": "Acme Corporation LLC",
    "status": "active",
    "formation_date": "2023-06-15",
    "ein": "12-3456789",
    "external_id": "your-unique-id-123",
    "custom_data": {
      "your_field": "your_value"
    },
    "type": "LLC",
    "state": "DE",
    "country": "US",
    "ending": "LLC",
    "industry": "Technology",
    "number_of_shares": 100,
    "par_value": 0.01,
    "is_company_private": false,
    "address": {
      "address1": "123 Main St",
      "city": "Wilmington",
      "state": "DE",
      "zip": "19801",
      "country": "US"
    },
    "timezone": "America/New_York",
    "shareholders": [
      {
        "first_name": "John",
        "last_name": "Doe",
        "title": "CEO",
        "number_of_shares": 100,
        "email": "[email protected]",
        "phone": "+1234567890",
        "iso_code": "US",
        "address": {
          "address1": "123 Main St",
          "city": "Wilmington",
          "state": "DE",
          "zip": "19801",
          "country": "US"
        },
        "is_director": true,
        "is_main_incorporator": true,
        "type": "individual"
      }
    ],
    "directors": [],
    "officers": [],
    "created_at": 1686787200,
    "updated_at": 1686787200,
    "federal_tax_filing": 1686787200,
    "state_tax_filing": 1686787200,
    "foreign_qualification_addresses": []
  }
}

Response Parameters

Parameter	Type	Description
success	boolean	Indicates if the operation was successful
company_id	string	Unique identifier for the company
company_name	string	Name of the company
status	string	Current status of the company formation (possible values: “shareholder_verification”, “in_progress”, “active”, “refunded”, “name_change”, “signature_requested”, “submitted_to_state”, “cancelled”)
formation_date	string	Date when the company was formed (if completed)
ein	string	Employer Identification Number (if assigned)
external_id	string	Partner’s external ID (if provided during creation)
custom_data	object	Partner’s custom data for this company
type	string	Company type (“LLC” or “C-CORP”)
state	string	State abbreviation
country	string	Country code
ending	string	Company ending (“LLC”, “Inc.”, “Corporation”, “Corp.”)
industry	string	Industry type
number_of_shares	number	Number of shares
par_value	number	Par value per share
is_company_private	boolean	Whether the company is private
address	object	Company address
timezone	string	Company timezone
shareholders	array	List of shareholders
directors	array	List of directors (C-CORP only)
officers	array	List of officers (C-CORP only)
created_at	integer	Creation timestamp
updated_at	integer	Last update timestamp
federal_tax_filing	integer	Federal tax filing timestamp
state_tax_filing	integer	State tax filing timestamp
foreign_qualification_addresses	array	Foreign qualification addresses

Response Headers

Header	Description
Last-Modified	RFC 7232 formatted date indicating when the resource was last modified

Status Codes

Status Code	Description
200	Success - Returns the company formation status
304	Not Modified - No changes since the If-Modified-Since date
400	Bad Request - Invalid company ID format
401	Unauthorized - Invalid API key
403	Forbidden - Company doesn’t belong to the partner
404	Not Found - Company not found
500	Internal Server Error

Error Responses

Invalid Company ID (400)

{
  "success": false,
  "message": "Invalid request data",
  "data": null,
  "error": {
    "code": "INVALID_REQUEST",
    "details": "Invalid company ID format"
  }
}

Unauthorized - Invalid API Key (401)

{
  "success": false,
  "message": "API key is required",
  "data": null,
  "error": {
    "code": "API_KEY_REQUIRED"
  }
}

Access Denied (403)

{
  "success": false,
  "message": "Access denied",
  "data": null,
  "error": {
    "code": "ACCESS_DENIED"
  }
}

Company Not Found (404)

{
  "success": false,
  "message": "Company not found",
  "data": null,
  "error": {
    "code": "COMPANY_NOT_FOUND"
  }
}

Internal Server Error (500)

{
  "success": false,
  "message": "Internal server error",
  "data": null,
  "error": {
    "code": "INTERNAL_ERROR"
  }
}

Authorizations

X-API-Key

string

header

required

Formation API key for authentication.

Headers

If-Modified-Since

string<http-date>

HTTP conditional request header for caching

Example:

"Wed, 21 Oct 2015 07:28:00 GMT"

Path Parameters

string

required

Company ID (ObjectID) or External ID

Maximum string length: 64

Example:

"64b8f1a2e4b0c8d9f0123456"

Response

Formation details retrieved successfully

success

boolean

required

Indicates if the request was successful

company_id

string

required

Company ID

company_name

string

required

Company name

status

enum<string>

required

Formation status

Available options:

shareholder_verification,

in_progress,

active,

refunded,

name_change,

signature_requested,

submitted_to_state,

cancelled

formation_date

string | null

Company formation date

ein

string | null

Employer Identification Number

external_id

string | null

Partner's external ID

custom_data

object | null

Partner's custom data for this company

type

enum<string> | null

Company type

Available options:

LLC,

C-CORP

state

enum<string> | null

State abbreviation

Available options:

AL,

AK,

AZ,

AR,

CA,

CO,

CT,

DE,

FL,

GA,

HI,

ID,

IL,

IN,

IA,

KS,

KY,

LA,

ME,

MD,

MA,

MI,

MN,

MS,

MO,

MT,

NE,

NV,

NH,

NJ,

NM,

NY,

NC,

ND,

OH,

OK,

OR,

PA,

RI,

SC,

SD,

TN,

TX,

UT,

VT,

VA,

WA,

WV,

WI,

WY

country

string | null

Country code

ending

enum<string> | null

Company ending

Available options:

LLC,

Inc.,

Corporation,

Corp.

industry

string | null

Industry type

number_of_shares

number | null

Number of shares

par_value

number | null

Par value per share

is_company_private

boolean

Whether the company is private

address

object | null

Company address

Show child attributes

timezone

string | null

Company timezone

shareholders

object[] | null

List of shareholders

Show child attributes

directors

object[] | null

List of directors (C-CORP only)

Show child attributes

officers

object[] | null

List of officers (C-CORP only)

Show child attributes

created_at

integer | null

Creation timestamp

updated_at

integer | null

Last update timestamp

federal_tax_filing

integer | null

Federal tax filing timestamp

state_tax_filing

integer | null

State tax filing timestamp

foreign_qualification_addresses

object[] | null

Foreign qualification addresses

Show child attributes

Initiate Formation

Cancel Formation

​Get Company Formation Status

​Headers

​Path Parameters

​Response

​Response Parameters

​Response Headers

​Status Codes

​Error Responses

​Invalid Company ID (400)

​Unauthorized - Invalid API Key (401)

​Access Denied (403)

​Company Not Found (404)

​Internal Server Error (500)

Authorizations

Headers

Path Parameters

Response

Get Company Formation Status

Headers

Path Parameters

Response

Response Parameters

Response Headers

Status Codes

Error Responses

Invalid Company ID (400)

Unauthorized - Invalid API Key (401)

Access Denied (403)

Company Not Found (404)

Internal Server Error (500)