> For the complete documentation index, see [llms.txt](https://docs.cuoral.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.cuoral.com/api-reference/customers/company/create-company.md).

# Create Company

**POST** `/external/v1/external/v1/customers/companies`

### Request

#### Parameters

* None

#### Request Body

The request body is a JSON object containing the new company's details.

**Content Type:** `application/json`

| Field               | Type     | Description                                         | Example                        | Required |
| ------------------- | -------- | --------------------------------------------------- | ------------------------------ | -------- |
| **company\_name**   | `string` | The official name of the company.                   | `"Acme Corp Ltd"`              | **Yes**  |
| **company\_email**  | `string` | A primary email address for the company.            | `"info@acmecorp.com"`          | **Yes**  |
| **company\_status** | `string` | The operational status of the company.              | `"active"`                     | No       |
| **description**     | `string` | A brief description of the company or its business. | `"Software development firm."` | No       |
| **industry**        | `string` | The industry the company operates in.               | `"Technology"`                 | No       |
| **website**         | `string` | The company's main website URL.                     | `"https://www.acmecorp.com"`   | No       |
| **phone**           | `string` | The company's primary phone number.                 | `"1-555-123-4567"`             | No       |
| **address**         | `string` | The company's physical street address.              | `"123 Corporate Ave"`          | No       |

**Example Request Body:**

```json
{
  "company_name": "Acme Corp Ltd",
  "company_email": "info@acmecorp.com",
  "company_status": "active",
  "description": "Software development firm.",
  "industry": "Technology",
  "website": "[https://www.acmecorp.com](https://www.acmecorp.com)",
  "phone": "1-555-123-4567",
  "address": "123 Corporate Ave, City, Country"
}
```

### Responses

#### 201 Successful Response (Created)

Returns the newly created company object, including system-generated IDs and timestamps.

Content Type: `application/json`

| **Field**          | **Type**            | **Description**                                         |
| ------------------ | ------------------- | ------------------------------------------------------- |
| id                 | `integer`           | The internal database ID of the company.                |
| company\_id        | `string`            | The unique external ID assigned to the company.         |
| time\_created      | `string` (datetime) | The timestamp when the company record was created.      |
| time\_updated      | `string` (datetime) | The timestamp when the company record was last updated. |
| organization\_id   | `integer`           | The organization ID this company belongs to.            |
| *... other fields* | *...*               | *All fields from the request body are also returned.*   |

Example Response Body (201):

```json
{
  "company_name": "Acme Corp Ltd",
  "company_email": "info@acmecorp.com",
  "company_status": "active",
  "description": "Software development firm.",
  "industry": "Technology",
  "website": "[https://www.acmecorp.com](https://www.acmecorp.com)",
  "phone": "1-555-123-4567",
  "address": "123 Corporate Ave, City, Country",
  "id": 501,
  "company_id": "COMP-XZY-789",
  "time_created": "2025-11-27T09:44:56.631Z",
  "time_updated": "2025-11-27T09:44:56.631Z",
  "organization_id": 42
}
```

#### 422 Validation Error

Returned if the request body is malformed or contains invalid data (e.g., missing required fields).

Content Type: `application/json`

| **Field** | **Type**         | **Description**                     |
| --------- | ---------------- | ----------------------------------- |
| detail    | Array of Objects | A list of validation error objects. |

Example Response Body (422):

```json
{
  "detail": [
    {
      "loc": [
        "body",
        "company_name"
      ],
      "msg": "Field required",
      "type": "value_error.missing"
    }
  ]
}
```