Update Citation Schema

Update an existing citation schema’s name, description, or schema configuration.

PATCH /v1/citation_schemas

Update Citation Schema

cURL

curl --request PATCH \
  --url https://api.bland.ai/v1/citation_schemas/ \
  --header 'Content-Type: application/json' \
  --header 'authorization: <authorization>' \
  --data '
{
  "name": "<string>",
  "description": "<string>",
  "schema": {}
}
'

Response

{
  "status": 200,
  "data": {
    "id": "3f4a2b1c-8e9d-4c7f-b2a1-5e8d9c7f6a2b",
    "name": "Enhanced Customer Information Extraction",
    "description": "Extracts comprehensive customer demographics, contact information, and lead qualification data from call transcripts",
    "org_id": "7c8b9a2d-3e4f-5c6b-8a9d-2e3f4c5b6a7c",
    "schema": {
      "variables": [
        {
          "name": "Customer Name",
          "description": "The full name of the customer",
          "type": "string"
        },
        {
          "name": "Customer Email",
          "description": "The email address provided by the customer",
          "type": "string"
        },
        {
          "name": "Phone Number",
          "description": "The customer's phone number",
          "type": "string"
        },
        {
          "name": "Lead Score",
          "description": "Numeric score indicating lead quality (1-10)",
          "type": "number"
        },
        {
          "name": "Interested in Demo",
          "description": "Whether the customer wants to schedule a demo",
          "type": "boolean"
        }
      ],
      "groupings": [
        {
          "name": "Contact Information",
          "variables": ["Customer Name", "Customer Email", "Phone Number"]
        },
        {
          "name": "Lead Qualification",
          "variables": ["Lead Score", "Interested in Demo"]
        }
      ],
      "conditions": [
        {
          "condition": {
            "value": "5",
            "operator": ">=",
            "variable": "Lead Score"
          },
          "variables": [
            {
              "name": "Follow-up Priority",
              "type": "string",
              "description": "Priority level for follow-up (high, medium, low)"
            }
          ]
        }
      ]
    },
    "created_at": "2023-12-15T14:30:00.000Z"
  },
  "errors": null
}

Headers

authorization · string · required

Your API key for authentication.

Query Parameters

id · string · required

The unique identifier of the citation schema to update.

Body Parameters

name · string

The updated name for the citation schema.

description · string

The updated description for the citation schema.

schema · object

The updated JSON schema configuration for citation extraction. This completely replaces the existing schema configuration.

The schema object can contain:

• variables: Array of variable definitions for data extraction
• groupings: Array of related variable collections
• conditions: Array of conditional logic rules

Example structure:

{
  "variables": [
    {
      "name": "Customer Name",
      "description": "The full name of the customer",
      "type": "string"
    },
    {
      "name": "Lead Score",
      "description": "Numeric score indicating lead quality (1-10)",
      "type": "number"
    }
  ],
  "groupings": [
    {
      "name": "Lead Information",
      "variables": ["Customer Name", "Lead Score"]
    }
  ],
  "conditions": []
}

At least one field (name, description, or schema) must be provided in the request body.

Response

status · integer

HTTP status code (200 for success).

data · object

The updated citation schema object.

id · string

The unique identifier for the citation schema (UUID format).

name · string

The updated name of the citation schema.

description · string

The updated description of the citation schema.

org_id · string

The organization ID that owns this schema.

schema · object

The updated JSON schema configuration for citation extraction.

created_at · string

The timestamp when the citation schema was originally created (ISO 8601 format).

errors · null

Will be null for successful requests.

Error Responses

400 Bad Request

Returned when:

• The schema ID parameter is missing
• No update fields are provided in the request body

404 Not Found

Returned when the specified citation schema is not found or doesn’t belong to your organization.

Response

{
  "status": 200,
  "data": {
    "id": "3f4a2b1c-8e9d-4c7f-b2a1-5e8d9c7f6a2b",
    "name": "Enhanced Customer Information Extraction",
    "description": "Extracts comprehensive customer demographics, contact information, and lead qualification data from call transcripts",
    "org_id": "7c8b9a2d-3e4f-5c6b-8a9d-2e3f4c5b6a7c",
    "schema": {
      "variables": [
        {
          "name": "Customer Name",
          "description": "The full name of the customer",
          "type": "string"
        },
        {
          "name": "Customer Email",
          "description": "The email address provided by the customer",
          "type": "string"
        },
        {
          "name": "Phone Number",
          "description": "The customer's phone number",
          "type": "string"
        },
        {
          "name": "Lead Score",
          "description": "Numeric score indicating lead quality (1-10)",
          "type": "number"
        },
        {
          "name": "Interested in Demo",
          "description": "Whether the customer wants to schedule a demo",
          "type": "boolean"
        }
      ],
      "groupings": [
        {
          "name": "Contact Information",
          "variables": ["Customer Name", "Customer Email", "Phone Number"]
        },
        {
          "name": "Lead Qualification",
          "variables": ["Lead Score", "Interested in Demo"]
        }
      ],
      "conditions": [
        {
          "condition": {
            "value": "5",
            "operator": ">=",
            "variable": "Lead Score"
          },
          "variables": [
            {
              "name": "Follow-up Priority",
              "type": "string",
              "description": "Priority level for follow-up (high, medium, low)"
            }
          ]
        }
      ]
    },
    "created_at": "2023-12-15T14:30:00.000Z"
  },
  "errors": null
}

---

Docs for agents: llms.txt