> 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/metrics/create-metric-definition.md).

# Create Metric Definition

Create a new metric definition for the organization. This metric can then be assigned values for specific companies.

POST /external/v1/external/v1/customers/metrics 

### Request 

#### Parameters

* None

#### Request Body (application/json)

| **Field**   | **Type** | **Description**                                                         | **Example**                          | **Required** |
| ----------- | -------- | ----------------------------------------------------------------------- | ------------------------------------ | ------------ |
| name        | `string` | The unique, human-readable name of the metric (e.g., 'Annual Revenue'). | `"ARR"`                              | Yes          |
| description | `string` | A detailed description of what the metric tracks.                       | `"Annual Recurring Revenue in USD."` | No           |
| data\_type  | `string` | The expected data type for the values of this metric.                   | `"NUMBER"`                           | Yes          |

Example Request Body:

```json
{
  "name": "Customer Tier",
  "description": "The service level tier the customer is subscribed to.",
  "data_type": "STRING"
}
```

***

### Responses 

#### Successful Response (201) (application/json)

Returns the newly created metric definition object.

| **Field**        | **Type**            | **Description**                                |
| ---------------- | ------------------- | ---------------------------------------------- |
| id               | `integer`           | The internal database ID of the definition.    |
| metric\_id       | `string`            | The unique external ID assigned to the metric. |
| name             | `string`            | The name of the metric.                        |
| description      | `string`            | The metric description.                        |
| data\_type       | `string`            | The expected data type.                        |
| organization\_id | `integer`           | The organization ID this metric belongs to.    |
| time\_created    | `string` (datetime) | Creation timestamp.                            |
| time\_updated    | `string` (datetime) | Last update timestamp.                         |

Example Response Body (201):

```json
{
  "id": 5,
  "metric_id": "METRIC-005",
  "name": "Customer Tier",
  "description": "The service level tier the customer is subscribed to.",
  "data_type": "STRING",
  "organization_id": 42,
  "time_created": "2025-11-27T10:06:09.459Z",
  "time_updated": "2025-11-27T10:06:09.459Z"
}
```

#### Validation Error (422) (application/json)

```json
{
  "detail": [
    {
      "loc": [
        "string",
        0
      ],
      "msg": "string",
      "type": "string"
    }
  ]
}
```