> ## Documentation Index > Fetch the complete documentation index at: https://docs.clemta.com/llms.txt > Use this file to discover all available pages before exploring further. # Retrieve Formation > Retrieve the current status of a company formation process. # 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 ```json theme={null} { "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": "john@example.com", "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) ```json theme={null} { "success": false, "message": "Invalid request data", "data": null, "error": { "code": "INVALID_REQUEST", "details": "Invalid company ID format" } } ``` ### Unauthorized - Invalid API Key (401) ```json theme={null} { "success": false, "message": "API key is required", "data": null, "error": { "code": "API_KEY_REQUIRED" } } ``` ### Access Denied (403) ```json theme={null} { "success": false, "message": "Access denied", "data": null, "error": { "code": "ACCESS_DENIED" } } ``` ### Company Not Found (404) ```json theme={null} { "success": false, "message": "Company not found", "data": null, "error": { "code": "COMPANY_NOT_FOUND" } } ``` ### Internal Server Error (500) ```json theme={null} { "success": false, "message": "Internal server error", "data": null, "error": { "code": "INTERNAL_ERROR" } } ``` ## OpenAPI ````yaml GET /formations/{id} openapi: 3.0.3 info: title: Clemta Formation API description: >- API for company formation services. This API allows partners to create, retrieve, and manage company formations programmatically. version: '2025-06-24' contact: name: Clemta API Support email: tech@clemta.com license: name: Proprietary url: https://clemta.com/terms servers: - url: https://api.clemta.com description: Production server - url: https://sandbox.clemta.com description: Sandbox server security: - ApiKeyAuth: [] paths: /formations/{id}: get: tags: - Formation summary: Get Formation Status description: >- Retrieves the current status and details of a company formation. The ID can be either the company ID or the external ID provided during creation. operationId: getFormation parameters: - name: id in: path required: true description: Company ID (ObjectID) or External ID schema: type: string maxLength: 64 example: 64b8f1a2e4b0c8d9f0123456 - name: If-Modified-Since in: header required: false description: HTTP conditional request header for caching schema: type: string format: http-date example: Wed, 21 Oct 2015 07:28:00 GMT responses: '200': description: Formation details retrieved successfully headers: Last-Modified: description: Last modification time of the formation schema: type: string format: http-date content: application/json: schema: $ref: '#/components/schemas/FormationStatusResponse' '304': description: >- Not Modified - Formation has not been updated since the time specified in If-Modified-Since header '400': description: Invalid request content: application/json: schema: $ref: '#/components/schemas/BadRequestError' '401': description: Unauthorized - Invalid or missing API key content: application/json: schema: $ref: '#/components/schemas/UnauthorizedError' '403': description: Forbidden - Access denied to this formation content: application/json: schema: $ref: '#/components/schemas/ForbiddenError' '404': description: Formation not found content: application/json: schema: $ref: '#/components/schemas/NotFoundError' '429': description: Rate limit exceeded headers: Retry-After: description: Number of seconds to wait before retrying schema: type: integer X-RateLimit-Remaining: description: Number of requests remaining in the current window schema: type: integer X-RateLimit-Reset: description: Unix timestamp when the rate limit resets schema: type: integer content: application/json: schema: $ref: '#/components/schemas/RateLimitError' components: schemas: FormationStatusResponse: type: object required: - success - company_id - company_name - status properties: success: type: boolean description: Indicates if the request was successful company_id: type: string description: Company ID company_name: type: string description: Company name status: type: string description: Formation status enum: - shareholder_verification - in_progress - active - refunded - name_change - signature_requested - submitted_to_state - cancelled formation_date: type: string description: Company formation date nullable: true ein: type: string description: Employer Identification Number nullable: true external_id: type: string description: Partner's external ID nullable: true custom_data: type: object description: Partner's custom data for this company nullable: true type: type: string description: Company type enum: - LLC - C-CORP nullable: true state: type: string description: State abbreviation enum: - 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 nullable: true country: type: string description: Country code nullable: true ending: type: string description: Company ending enum: - LLC - Inc. - Corporation - Corp. nullable: true industry: type: string description: Industry type nullable: true number_of_shares: type: number description: Number of shares nullable: true par_value: type: number description: Par value per share nullable: true is_company_private: type: boolean description: Whether the company is private address: $ref: '#/components/schemas/Address' description: Company address nullable: true timezone: type: string description: Company timezone nullable: true shareholders: type: array description: List of shareholders items: $ref: '#/components/schemas/ShareholderResponse' nullable: true directors: type: array description: List of directors (C-CORP only) items: $ref: '#/components/schemas/PersonResponse' nullable: true officers: type: array description: List of officers (C-CORP only) items: $ref: '#/components/schemas/PersonResponse' nullable: true created_at: type: integer description: Creation timestamp nullable: true updated_at: type: integer description: Last update timestamp nullable: true federal_tax_filing: type: integer description: Federal tax filing timestamp nullable: true state_tax_filing: type: integer description: State tax filing timestamp nullable: true foreign_qualification_addresses: type: array description: Foreign qualification addresses items: $ref: '#/components/schemas/Address' nullable: true BadRequestError: type: object properties: success: type: boolean example: false message: type: string example: Invalid request data data: type: object nullable: true example: null error: type: object properties: code: type: string example: INVALID_REQUEST details: type: string example: Field 'name' is required UnauthorizedError: type: object properties: success: type: boolean example: false message: type: string example: API key is required data: type: object nullable: true example: null error: type: object properties: code: type: string example: API_KEY_REQUIRED details: type: string example: '' ForbiddenError: type: object properties: success: type: boolean example: false message: type: string example: Access denied data: type: object nullable: true example: null error: type: object properties: code: type: string example: ACCESS_DENIED details: type: string example: '' NotFoundError: type: object properties: success: type: boolean example: false message: type: string example: Company not found data: type: object nullable: true example: null error: type: object properties: code: type: string example: COMPANY_NOT_FOUND details: type: string example: '' RateLimitError: type: object properties: success: type: boolean example: false message: type: string example: Rate limit exceeded data: type: object nullable: true example: null error: type: object properties: code: type: string example: RATE_LIMIT_EXCEEDED details: type: string example: Too many requests. Please try again later. Address: type: object required: - address1 - city - state - zip - country properties: address1: type: string description: Address line 1 address2: type: string description: Address line 2 city: type: string description: City state: type: string description: State zip: type: string description: ZIP code country: type: string description: Country code ShareholderResponse: type: object properties: first_name: type: string description: First name last_name: type: string description: Last name title: type: string description: Position/title number_of_shares: type: number description: Number of shares email: type: string description: Email address phone: type: string description: Phone number iso_code: type: string description: Country ISO code address: $ref: '#/components/schemas/Address' is_director: type: boolean description: Whether shareholder is also a director is_main_incorporator: type: boolean description: Whether shareholder is the main incorporator type: type: string enum: - individual - organization description: Shareholder type legal_entity_name: type: string description: Legal entity name (for organization shareholders) representative_name: type: string description: Representative name (for organization shareholders) PersonResponse: type: object properties: first_name: type: string description: First name last_name: type: string description: Last name title: type: string description: Position/title email: type: string description: Email address phone: type: string description: Phone number iso_code: type: string description: Country ISO code address: $ref: '#/components/schemas/Address' securitySchemes: ApiKeyAuth: type: apiKey in: header name: X-API-Key description: Formation API key for authentication. ````