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>",
    "address2": "<string>",
    "city": "<string>",
    "state": "<string>",
    "zip": "<string>",
    "country": "<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>",
        "address2": "<string>",
        "city": "<string>",
        "state": "<string>",
        "zip": "<string>",
        "country": "<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>",
        "address2": "<string>",
        "city": "<string>",
        "state": "<string>",
        "zip": "<string>",
        "country": "<string>"
      }
    }
  ],
  "officers": [
    {
      "first_name": "<string>",
      "last_name": "<string>",
      "title": "<string>",
      "email": "<string>",
      "phone": "<string>",
      "iso_code": "<string>",
      "address": {
        "address1": "<string>",
        "address2": "<string>",
        "city": "<string>",
        "state": "<string>",
        "zip": "<string>",
        "country": "<string>"
      }
    }
  ],
  "created_at": 123,
  "updated_at": 123,
  "federal_tax_filing": 123,
  "state_tax_filing": 123,
  "foreign_qualification_addresses": [
    {
      "address1": "<string>",
      "address2": "<string>",
      "city": "<string>",
      "state": "<string>",
      "zip": "<string>",
      "country": "<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

ParameterTypeDescription
X-API-KEYstringFormation API Key (required)
If-Modified-SincestringRFC 7232 formatted date to check if the resource has been modified (optional)

​
Path Parameters

ParameterTypeDescription
company_idstringCompany 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

ParameterTypeDescription
successbooleanIndicates if the operation was successful
company_idstringUnique identifier for the company
company_namestringName of the company
statusstringCurrent status of the company formation (possible values: “shareholder_verification”, “in_progress”, “active”, “refunded”, “name_change”, “signature_requested”, “submitted_to_state”, “cancelled”)
formation_datestringDate when the company was formed (if completed)
einstringEmployer Identification Number (if assigned)
external_idstringPartner’s external ID (if provided during creation)
custom_dataobjectPartner’s custom data for this company
typestringCompany type (“LLC” or “C-CORP”)
statestringState abbreviation
countrystringCountry code
endingstringCompany ending (“LLC”, “Inc.”, “Corporation”, “Corp.”)
industrystringIndustry type
number_of_sharesnumberNumber of shares
par_valuenumberPar value per share
is_company_privatebooleanWhether the company is private
addressobjectCompany address
timezonestringCompany timezone
shareholdersarrayList of shareholders
directorsarrayList of directors (C-CORP only)
officersarrayList of officers (C-CORP only)
created_atintegerCreation timestamp
updated_atintegerLast update timestamp
federal_tax_filingintegerFederal tax filing timestamp
state_tax_filingintegerState tax filing timestamp
foreign_qualification_addressesarrayForeign qualification addresses

​
Response Headers

HeaderDescription
Last-ModifiedRFC 7232 formatted date indicating when the resource was last modified

​
Status Codes

Status CodeDescription
200Success - Returns the company formation status
304Not Modified - No changes since the If-Modified-Since date
400Bad Request - Invalid company ID format
401Unauthorized - Invalid API key
403Forbidden - Company doesn’t belong to the partner
404Not Found - Company not found
500Internal 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

​
id
string
required

Company ID (ObjectID) or External ID

Maximum length: 64
Example:

"64b8f1a2e4b0c8d9f0123456"

Response

200
application/json

Formation details retrieved successfully

The response is of type object.