# List numbering schemes

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

`GET /numbering-schemes`

List numbering schemes. Requires the REST `read` 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. 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": "read",
  "team": "Token-bound Team",
  "authorization": "Additional role, entity-policy and plan requirements vary by operation."
}
```

## Example request

```bash
curl --request GET 'https://api.example.test/api/numbering-schemes' \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Accept: application/json'
```

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

## Responses

### 200

Successful response.

Content type: `application/json`.

```json
{
  "type": "object",
  "properties": {
    "data": {
      "type": "array",
      "items": {
        "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."
}
```

### 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."
}
```

### 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.