Update numbering scheme – ConversionLab Docs

PUT /numbering-schemes/{numberingScheme}

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

{
  "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."
}

Parameters

Name	Location	Required	Description
`numberingScheme`	path	Yes	The numbering scheme ID

numberingScheme

{
  "type": "integer",
  "minimum": 1
}

Request body

The request body is optional.

application/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"
      }
    ]
  }
}

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

Example request

curl --request PUT 'https://api.example.test/api/numbering-schemes/1' \
  --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

200

Successful response.

Content type: application/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"
  ]
}

{
  "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.

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

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

402

The Team is in read-only billing mode.

Content type: application/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"
  ]
}

{
  "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.

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

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

404

Not found

Content type: application/json.

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

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

422

Validation error

Content type: application/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"
  ]
}

{
  "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:

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

Content type: application/json.

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

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

See API conventions for error handling, rate limits, pagination, and uploads.

On this page