> ## 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.

# Initiate Formation

> Start the company formation process with provided details.

# Initiate Company Formation

The Formation API allows partners to initiate company formations programmatically. This endpoint starts the company formation process with the provided details.

## Headers

| Parameter    | Type   | Description                  |
| ------------ | ------ | ---------------------------- |
| X-API-KEY    | string | Formation API Key (required) |
| Content-Type | string | multipart/form-data          |

## Request Body (multipart/form-data)

The request must be sent as `multipart/form-data` with the following fields:

### Required Fields

| Field         | Type   | Description                                      |
| ------------- | ------ | ------------------------------------------------ |
| company\_data | string | JSON string containing company formation details |

### Optional Fields

| Field                    | Type | Description                                                               |
| ------------------------ | ---- | ------------------------------------------------------------------------- |
| shareholder\_passport\_0 | file | Passport file for individual shareholder at index 0 (PDF, JPG, JPEG, PNG) |
| shareholder\_passport\_1 | file | Passport file for individual shareholder at index 1 (PDF, JPG, JPEG, PNG) |
| shareholder\_passport\_N | file | Additional passport files as needed                                       |

### company\_data JSON Structure

The `company_data` field must contain a JSON string with the following structure:

```json theme={null}
{
  "name": "Example Corp",
  "type": "LLC",
  "state": "DE",
  "ending": "LLC",
  "industry": "Technology",
  "address": {
    "address1": "123 Main St",
    "city": "Wilmington",
    "state": "DE",
    "zip": "19801",
    "country": "US"
  },
  "shareholders": [
    {
      "type": "individual",
      "first_name": "John",
      "last_name": "Doe",
      "number_of_shares": 100,
      "email": "john@example.com",
      "phone": "+1234567890",
      "iso_code": "US",
      "title": "CEO",
      "address": {
        "address1": "123 Main St",
        "city": "Wilmington",
        "state": "DE",
        "zip": "19801",
        "country": "US"
      },
      "is_main_incorporator": true,
      "ssn": "123456789"
    }
  ],
  "timezone": "America/New_York",
  "account_holder": {
    "first_name": "John",
    "last_name": "Doe",
    "email": "john@example.com",
    "phone": "+1234567890"
  },
  "package": "essential",
  "external_id": "your-unique-id-123",
  "custom_data": {
    "your_field": "your_value"
  }
}
```

## Response

```json theme={null}
{
  "success": true,
  "message": "Formation created successfully",
  "data": {
    "formation_id": "64b8f1a2e4b0c8d9f0123456",
    "company_id": "64b8f1a2e4b0c8d9f0123456",
    "status": "shareholder_verification",
    "external_id": "your-unique-id-123"
  },
  "error": null
}
```

### Response Parameters

| Parameter          | Type    | Description                                |
| ------------------ | ------- | ------------------------------------------ |
| success            | boolean | Indicates if the operation was successful  |
| message            | string  | Additional information about the operation |
| data               | object  | Response data for successful requests      |
| data.formation\_id | string  | Unique formation process ID                |
| data.company\_id   | string  | Unique identifier for the created company  |
| data.status        | string  | Current status of the company formation    |
| data.external\_id  | string  | Your provided external ID (if any)         |

## Error Responses

### Invalid Request or Validation Failed (400)

```json theme={null}
{
  "success": false,
  "message": "Invalid request data",
  "data": null,
  "error": {
    "code": "VALIDATION_FAILED",
    "details": "Field 'name' is required"
  }
}
```

### Unauthorized - Invalid API Key (401)

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

### Conflict - External ID Already Exists (409)

```json theme={null}
{
  "success": false,
  "message": "External ID already exists for this partner",
  "data": null,
  "error": {
    "code": "DUPLICATE_EXTERNAL_ID"
  }
}
```

### Rate Limit Exceeded (429)

```json theme={null}
{
  "success": false,
  "message": "Rate limit exceeded",
  "data": null,
  "error": {
    "code": "RATE_LIMIT_EXCEEDED"
  }
}
```

### Internal Server Error (500)

```json theme={null}
{
  "success": false,
  "message": "Internal server error",
  "data": null,
  "error": {
    "code": "INTERNAL_ERROR"
  }
}
```


## OpenAPI

````yaml POST /formations
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:
    post:
      tags:
        - Formation
      summary: Create Company Formation
      description: >-
        Creates a new company formation with the provided details. Requires
        multipart/form-data with company_data JSON and optional shareholder
        passport files.
      operationId: createFormation
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required:
                - company_data
              properties:
                company_data:
                  type: string
                  description: JSON string containing company formation details
                  example: >-
                    {"name":"Example
                    Corp","type":"LLC","state":"DE","ending":"LLC","industry":"Technology","address":{"address1":"123
                    Main
                    St","city":"Wilmington","state":"DE","zip":"19801","country":"US"},"shareholders":[{"type":"individual","first_name":"John","last_name":"Doe","number_of_shares":100,"email":"john@example.com","phone":"+1234567890","iso_code":"US","title":"CEO","address":{"address1":"123
                    Main
                    St","city":"Wilmington","state":"DE","zip":"19801","country":"US"},"is_main_incorporator":true,"ssn":"123456789"}],"timezone":"America/New_York","account_holder":{"first_name":"John","last_name":"Doe","email":"john@example.com","phone":"+1234567890"},"package":"essential"}
                shareholder_passport_0:
                  type: string
                  format: binary
                  description: >-
                    Passport file for individual shareholder at index 0 (PDF,
                    JPG, JPEG, PNG)
              additionalProperties:
                oneOf:
                  - type: string
                    format: binary
                    description: >-
                      Additional shareholder passport files
                      (shareholder_passport_1, shareholder_passport_2, etc.)
            encoding:
              company_data:
                contentType: application/json
              shareholder_passport_0:
                contentType: application/pdf, image/jpeg, image/png
      responses:
        '200':
          description: Formation created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FormationResponse'
        '400':
          description: Invalid request data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequestError'
        '401':
          description: Unauthorized - Invalid or missing API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedError'
        '409':
          description: Conflict - External ID already exists
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConflictError'
        '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'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalServerError'
components:
  schemas:
    FormationResponse:
      type: object
      required:
        - success
        - message
      properties:
        success:
          type: boolean
          description: Indicates if the request was successful
        message:
          type: string
          description: Response message
        data:
          type: object
          nullable: true
          description: Response data for successful requests
          properties:
            formation_id:
              type: string
              description: Unique formation process ID
            company_id:
              type: string
              description: Created company ID
            status:
              type: string
              description: Formation status
              enum:
                - shareholder_verification
                - in_progress
                - active
                - refunded
                - name_change
                - signature_requested
                - submitted_to_state
                - cancelled
            external_id:
              type: string
              description: Partner's external ID for this formation
        error:
          type: object
          nullable: true
          description: Error details for failed requests
          properties:
            code:
              type: string
              description: Error code
              enum:
                - API_KEY_REQUIRED
                - INVALID_API_KEY
                - ACCESS_DENIED
                - RATE_LIMIT_EXCEEDED
                - INVALID_REQUEST
                - VALIDATION_FAILED
                - COMPANY_NOT_FOUND
                - PACKAGE_NOT_FOUND
                - DUPLICATE_EXTERNAL_ID
                - INTERNAL_ERROR
            details:
              type: string
              description: Additional error details
    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: ''
    ConflictError:
      type: object
      properties:
        success:
          type: boolean
          example: false
        message:
          type: string
          example: External ID already exists for this partner
        data:
          type: object
          nullable: true
          example: null
        error:
          type: object
          properties:
            code:
              type: string
              example: DUPLICATE_EXTERNAL_ID
            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.
    InternalServerError:
      type: object
      properties:
        success:
          type: boolean
          example: false
        message:
          type: string
          example: Internal server error
        data:
          type: object
          nullable: true
          example: null
        error:
          type: object
          properties:
            code:
              type: string
              example: INTERNAL_ERROR
            details:
              type: string
              example: An unexpected error occurred.
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
      description: Formation API key for authentication.

````