PATCH
/
v1
/
citation_schemas
/
Update Citation Schema
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": {}
}'
{
  "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.

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