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>",
  "status": "shareholder_verification",
  "formation_date": "<string>",
  "ein": "<string>",
  "external_id": "<string>",
  "custom_data": {},
  "type": "LLC",
  "state": "AL",
  "country": "<string>",
  "ending": "LLC",
  "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,
      "type": "individual",
      "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>",
  "status": "shareholder_verification",
  "formation_date": "<string>",
  "ein": "<string>",
  "external_id": "<string>",
  "custom_data": {},
  "type": "LLC",
  "state": "AL",
  "country": "<string>",
  "ending": "LLC",
  "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,
      "type": "individual",
      "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

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

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

⌘I

Formation API Endpoints

Contacts API

Fixed Assets API

API Documentation

Retrieve 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

Formation API Endpoints

Contacts API

Fixed Assets API

API Documentation

​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)