# Create reference
URL: https://docs.fluenta.io/docs/reference/program/create-reference
Operation: `createReference`
Required permission: `program`

`POST /v1/external/organizations/{organizationId}/references`

Create an OC (a referencia, a cut of a garment) at the end of a módulo’s «Programa», as «Nueva referencia» does.

### Authorization

- `apiToken` — Bearer token. An API token created in Configuración › Tokens de API, or a connected app’s access token

Send it as `Authorization: Bearer <your API token>`.

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `Idempotency-Key` | header | string | no | A fresh unique string per intended write (1 to 255 visible ASCII characters). Sent again unchanged only to retry THAT write after a timeout or a 409 `IDEMPOTENCY_IN_PROGRESS`: the stored answer comes back (`Idempotency-Replayed: true`) and nothing is written twice. The same key with another request is a 422 `IDEMPOTENCY_KEY_REUSED`. |
| `organizationId` | path | integer | yes | The organization, from `getMe` or `listOrganizations`. |

### Request body

`application/json`

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `moduleId` | integer, 1–2147483647 | yes | The módulo whose «Programa» the OC joins, at the end of its queue (an id from `listModules`). |
| `name` | string | yes | «Referencia»: the garment style’s name. |
| `orderNumber` | string | no | «Corte (OC)», the cut’s order number. Omitted or blank, the OC takes its name, as the dashboard’s form does. |
| `garment` | string | no | «Categoría»: one of the organization’s categories when it keeps a list (`getOrganization`). |
| `goal` | integer, 1–100000 | yes | «Meta por hora»: units per hour. |
| `total` | integer, 1–1000000 | no | «Total de unidades». Required unless the plant has «El operario escoge la referencia» on: 400 `TOTAL_REQUIRED`. |
| `price` | number, 0–1000000000 | no | «Precio por unidad», in the organization’s currency (`getOrganization`). |
| `color` | string | no | The OC’s colour, `#RRGGBB`. Omitted, Fluenta picks one, as on the dashboard. |
| `dueDate` | string (date-time) | no | «Fecha de compromiso»: promised to the client. ISO 8601 with its offset (the plant’s), e.g. `2026-11-28T00:00:00-05:00`. |
| `spliceDate` | string (date-time) | no | «F. Empalme»: when it starts on its módulo. ISO 8601 with its offset. |
| `priority` | boolean | no | «OC prioritaria». |
| `continuity` | boolean | no | «Continuidad»: the same garment as the cut before it. |
| `step1Name` | string | no | «Subproceso 1»: needs `step1Goal`. |
| `step1Goal` | integer | no | «Meta subproceso 1», units per hour. |
| `step2Name` | string | no | «Subproceso 2»: needs step 1 and `step2Goal`. |
| `step2Goal` | integer | no | «Meta subproceso 2». |
| `saveToCatalog` | boolean | no | Also add the OC’s name, category, goal, price and colour to the «Catálogo de referencias» when it lacks the name (the dashboard’s «Guardar en el catálogo»). Never fails the OC. |

### Responses

| Status | Description |
| --- | --- |
| `201` | `ExternalReferenceDto` |
| `400` | `INVALID_REQUEST`: a body or a parameter the route cannot take, as `{statusCode, code: 'INVALID_REQUEST', message, details}`, with one `{field, message}` in `details` per failure (`field` the body field as a path, such as `items.0.name`; null when the failure names none). Or a value the dashboard refuses (its own `code`), or `INVALID_IDEMPOTENCY_KEY`. Nothing changed. |
| `401` | Missing, malformed, unknown, expired or revoked credential: `INVALID_API_TOKEN`. |
| `402` | The organization is blocked: `ORG_BLOCKED`. |
| `403` | `ROLE_NOT_ALLOWED`: the usuario’s role does not make this change in the dashboard (it needs ADMIN or MODERATOR, or an account with platform-wide access);`INSUFFICIENT_SCOPE`: the credential lacks «Gestionar el Programa»; `PLAN_LIMIT`: the organization’s plan does not answer this credential (a connected app needs «Conectar con IA», Plan Pro). Nothing changed. |
| `404` | The organization does not exist or is out of the credential’s reach: `ORGANIZATION_NOT_FOUND`. One body for both. |
| `409` | `IDEMPOTENCY_IN_PROGRESS` (with `Retry-After`): the same `Idempotency-Key` is still being answered; retry it unchanged. Or the dashboard’s own conflict. |
| `422` | `IDEMPOTENCY_KEY_REUSED`: the `Idempotency-Key` answered another request. Nothing changed. |
| `429` | The credential is over its rate limit: `RATE_LIMITED`. Per credential, in fixed windows of 60 seconds: 60 requests in one organization on Light and 120 on Pro; 20 on the heavy reads (the range figures, the whole floor, the month and the pauses); 300 across every organization; 60 on the routes that name no organization. Wait `Retry-After` seconds; a refused request counts against nothing. |

### Example

```bash
curl -X POST 'https://api.fluenta.io/v1/external/organizations/{organizationId}/references' \
  -H 'Authorization: Bearer <your API token>' \
  -H 'Content-Type: application/json' \
  -d @body.json
```