> For the complete documentation index, see [llms.txt](https://docs.facephi.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.facephi.com/docs.facephi-en/rest-api/midapi-v2/operations/create-operation.md).

# Create Operation

Service that creates an operation and returns its identifier together with its expiration.

The `operationId` returned is the one sent to the [store an asset](/docs.facephi-en/rest-api/midapi-v2/storage/save-asset.md) and the first segment of every asset key.

### Endpoint

```
POST /operation
```

### Headers

| Name              | Type   | Required | Description                                                                                                                |
| ----------------- | ------ | -------- | -------------------------------------------------------------------------------------------------------------------------- |
| **Authorization** | string | **Yes**  | consumer Token in the format `Bearer <token>`. See [Authentication](/docs.facephi-en/rest-api/midapi-v2/autenticacion.md). |
| **consumer-id**   | string | **Yes**  | Consumer identifier.                                                                                                       |

### Request body

The body is optional: a request without a body also creates the operation.

#### Parameters

| Parameter           | Type   | Required | Description                                                                                           |
| ------------------- | ------ | -------- | ----------------------------------------------------------------------------------------------------- |
| `merchantReference` | string | No       | Own reference for this operation: the order, case, or cart it corresponds to. Maximum 128 characters. |

#### Request example

```json
{
  "merchantReference": "ORD-4417"
}
```

{% hint style="info" %}
`merchantReference` is a reference **informational**. The service stores it and returns it, but it cannot be queried or operated on by it: the operation is always identified by its `operationId`. It is not unique, so two operations can have the same one without that relating them.
{% endhint %}

It is stored without leading or trailing spaces, and a blank reference is equivalent to sending none.

### Responses

#### `201` Created

#### Response parameters

| Parameter           | Type   | Description                                                              |
| ------------------- | ------ | ------------------------------------------------------------------------ |
| `operationId`       | string | Operation identifier (UUID).                                             |
| `timestamp`         | string | Creation time in format **ISO 8601** (UTC).                              |
| `expiresAt`         | string | Expiration time in format **ISO 8601** (UTC).                            |
| `merchantReference` | string | The reference sent, returned as-is. It does not appear if none was sent. |

#### Response example

```json
{
  "operationId": "0192a3f4-7b21-7c44-9e1a-3f5b8c2d1e04",
  "timestamp": "2026-06-26T12:00:00Z",
  "expiresAt": "2026-06-26T12:15:00Z",
  "merchantReference": "ORD-4417"
}
```

#### Other responses

| Code  | Description                                                                                                                                                                               |
| ----- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `400` | `merchantReference` more than 128 characters, or malformed body.                                                                                                                          |
| `401` | Missing, invalid, or expired Token.                                                                                                                                                       |
| `403` | The consumer is not provisioned with the service `OPERATION`.                                                                                                                             |
| `429` | The consumer has exceeded its request rate limit. The response includes `Retry-After` with the wait seconds, and `X-RateLimit-Limit` and `X-RateLimit-Burst` with the current thresholds. |
| `503` | The service is temporarily unavailable.                                                                                                                                                   |

The body of an error response has the form described in [MIDAPI v2](/docs.facephi-en/rest-api/midapi-v2.md#respuestas-de-error).