# Create numbering scheme

POST /numbering-schemes. Parameters, permissions, request and response schemas.

`POST /numbering-schemes`

Create numbering scheme. Requires the REST `write` token ability. The bearer token selects the Team; a supplied team\_id cannot switch tenants. Additional role, entity-policy and plan requirements vary by operation. A Team in blocked billing mode cannot write and receives 402. Only Team owners and admins may manage numbering schemes. After IDs have been claimed, the scheme scope cannot change. Backfill assigns IDs to existing records using the scheme assignments.

## Authentication

Use a team API key as `Authorization: Bearer YOUR_API_KEY`. The token ability and the user’s role must both allow this operation. See [authentication](https://conversionlab.app/docs/developer/authentication).

```json
{
  "ability": "write",
  "team": "Token-bound Team",
  "authorization": "Additional role, entity-policy and plan requirements vary by operation.",
  "billing": "Blocked billing mode rejects writes with 402."
}
```

## Request body

A request body is required.

### application/json

```json
{
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "maxLength": 255
    },
    "scope": {
      "type": "string",
      "enum": [
        "team",
        "project"
      ]
    },
    "template": {
      "type": "string",
      "maxLength": 120,
      "description": "Identifier template, for example EXP-{number:000}. Project-scoped templates may include {project_code}."
    },
    "initial_number": {
      "type": "integer",
      "minimum": 1
    },
    "is_active": {
      "type": "boolean"
    },
    "assignments": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "entity_type": {
            "type": "string",
            "enum": [
              "experiments",
              "ideas",
              "insights"
            ]
          },
          "project_id": {
            "type": [
              "integer",
              "null"
            ]
          }
        },
        "required": [
          "entity_type"
        ]
      }
    }
  },
  "example": {
    "name": "Experiment IDs",
    "scope": "team",
    "template": "EXP-{number:000}",
    "initial_number": 1,
    "assignments": [
      {
        "entity_type": "experiments"
      }
    ]
  },
  "required": [
    "name",
    "scope",
    "template"
  ]
}
```

```json
{
  "name": "Experiment IDs",
  "scope": "team",
  "template": "EXP-{number:000}",
  "initial_number": 1,
  "assignments": [
    {
      "entity_type": "experiments"
    }
  ]
}
```

## Example request

```bash
curl --request POST 'https://api.example.test/api/numbering-schemes' \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{"name":"Experiment IDs","scope":"team","template":"EXP-{number:000}","initial_number":1,"assignments":[{"entity_type":"experiments"}]}'
```

Examples use fictional data. Replace resource IDs and the API host with your environment’s values.

## Responses

### 201

Successful response.

Content type: `application/json`.

```json
{
  "type": "object",
  "properties": {
    "data": {
      "type": "object",
      "properties": {
        "id": {
          "type": "integer"
        },
        "name": {
          "type": "string"
        },
        "scope": {
          "type": "string"
        },
        "template": {
          "type": "string"
        },
        "initial_number": {
          "type": "integer"
        },
        "is_active": {
          "type": "boolean"
        },
        "claims_count": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "integer",
              "minimum": 0
            }
          ]
        },
        "assignments": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "id": {
                "type": "integer"
              },
              "entity_type": {
                "type": "string"
              },
              "assignment_scope_key": {
                "type": "string"
              },
              "project_id": {
                "type": [
                  "integer",
                  "null"
                ]
              }
            },
            "required": [
              "id",
              "entity_type",
              "assignment_scope_key",
              "project_id"
            ]
          }
        },
        "sequence_states": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "id": {
                "type": "integer"
              },
              "scope_key": {
                "type": "string"
              },
              "project_id": {
                "type": [
                  "integer",
                  "null"
                ]
              },
              "project_code": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "next_number": {
                "type": "integer"
              }
            },
            "required": [
              "id",
              "scope_key",
              "project_id",
              "project_code",
              "next_number"
            ]
          }
        },
        "created_at": {
          "type": [
            "string",
            "null"
          ],
          "format": "date-time"
        },
        "updated_at": {
          "type": [
            "string",
            "null"
          ],
          "format": "date-time"
        }
      },
      "required": [
        "id",
        "name",
        "scope",
        "template",
        "initial_number",
        "is_active",
        "claims_count",
        "assignments",
        "sequence_states",
        "created_at",
        "updated_at"
      ]
    }
  },
  "required": [
    "data"
  ]
}
```

```json
{
  "data": {
    "id": 101,
    "name": "Checkout delivery estimate",
    "scope": "example",
    "template": "example",
    "initial_number": 1,
    "is_active": true,
    "claims_count": "example",
    "assignments": [
      {
        "id": 101,
        "entity_type": "example",
        "assignment_scope_key": "example",
        "project_id": null
      }
    ],
    "sequence_states": [
      {
        "id": 101,
        "scope_key": "example",
        "project_id": null,
        "project_code": null,
        "next_number": 1
      }
    ],
    "created_at": null,
    "updated_at": null
  }
}
```

### 401

Unauthenticated

Content type: `application/json`.

```json
{
  "type": "object",
  "properties": {
    "message": {
      "type": "string",
      "description": "Error overview."
    }
  },
  "required": [
    "message"
  ]
}
```

```json
{
  "message": "The request could not be completed."
}
```

### 402

The Team is in read-only billing mode.

Content type: `application/json`.

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "string",
      "const": "subscription_required"
    },
    "mode": {
      "type": "string",
      "const": "blocked"
    },
    "message": {
      "type": "string",
      "example": "Your team is in read-only mode. Update billing to make changes."
    },
    "grace_period_ends_at": {
      "type": [
        "string",
        "null"
      ],
      "format": "date-time"
    }
  },
  "required": [
    "error",
    "mode",
    "message",
    "grace_period_ends_at"
  ]
}
```

```json
{
  "error": "subscription_required",
  "mode": "blocked",
  "message": "Your team is in read-only mode. Update billing to make changes.",
  "grace_period_ends_at": null
}
```

### 403

Token ability, user permission, Team membership, plan, or billing mode does not allow this operation.

Content type: `application/json`.

```json
{
  "type": "object",
  "properties": {
    "message": {
      "type": "string",
      "example": "This action is unauthorized."
    }
  },
  "required": [
    "message"
  ]
}
```

```json
{
  "message": "This action is unauthorized."
}
```

### 422

Validation error

Content type: `application/json`.

```json
{
  "type": "object",
  "properties": {
    "message": {
      "type": "string",
      "description": "Errors overview."
    },
    "errors": {
      "type": "object",
      "description": "A detailed description of each field that failed validation.",
      "additionalProperties": {
        "type": "array",
        "items": {
          "type": "string"
        }
      }
    }
  },
  "required": [
    "message",
    "errors"
  ]
}
```

```json
{
  "message": "The request could not be completed.",
  "errors": {
    "name": [
      "The name field is required."
    ]
  }
}
```

### 429

Rate limit exceeded. Honor Retry-After before retrying.

Response headers:

```json
{
  "Retry-After": {
    "description": "Seconds before retrying.",
    "schema": {
      "type": "integer"
    }
  }
}
```

Content type: `application/json`.

```json
{
  "type": "object",
  "properties": {
    "message": {
      "type": "string",
      "example": "Too Many Attempts."
    }
  },
  "required": [
    "message"
  ]
}
```

```json
{
  "message": "Too Many Attempts."
}
```

See [API conventions](https://conversionlab.app/docs/developer/api-conventions) for error handling, rate limits, pagination, and uploads.