POST
/
v1
/
citation_schemas
/
Create Citation Schema
curl --request POST \
  --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": "6ba7b812-9dad-11d1-80b4-00c04fd430c8",
    "name": "Customer Information Extraction",
    "description": "Extracts customer demographics and contact information from call transcripts",
    "org_id": "9b59f853-c2c7-4e3a-b5d6-8f7e9a1b2c3d",
    "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": "Interested in Demo",
          "description": "Whether the customer wants to schedule a demo",
          "type": "boolean"
        }
      ],
      "groupings": [
        {
          "name": "Contact Information",
          "variables": ["Customer Name", "Customer Email"]
        }
      ],
      "conditions": [
        {
          "condition": {
            "value": "true",
            "operator": "===",
            "variable": "Interested in Demo"
          },
          "variables": [
            {
              "name": "Demo Preference",
              "type": "string",
              "description": "Type of demo the customer prefers (in-person, virtual, etc.)"
            }
          ]
        }
      ]
    },
    "created_at": "2023-12-15T14:30:00.000Z"
  },
  "errors": null
}

​
Overview

Create a citation schema to define what data should be extracted from call transcripts. Citation schemas allow you to automatically capture structured information like customer details, call outcomes, or any custom variables relevant to your use case.

​
Headers

​
authorization
string
required

Your API key for authentication.

​
Body Parameters

​
name
string
required

The name of the citation schema. This should be descriptive and help you identify the schema’s purpose.

​
description
string

An optional description explaining what this schema extracts and its intended use case.

​
schema
object

The JSON schema configuration that defines variables, groupings, and conditions for citation extraction. If not provided, an empty schema will be created that can be configured later.

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 that trigger additional variable extraction

Example structure:

{
  "variables": [
    {
      "name": "Customer Name",
      "description": "The full name of the customer",
      "type": "string"
    },
    {
      "name": "Customer Email",
      "description": "The customer's email address",
      "type": "string"
    },
    {
      "name": "Customer Age",
      "description": "The customer's age in years",
      "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"
      ],
      "description": "The customer's contact details"
    },
    {
      "name": "Demographics",
      "variables": [
        "Customer Age"
      ],
      "description": "The customer's demographic information"
    }
  ],
  "conditions": [
    {
      "condition": {
        "value": "true",
        "operator": "===",
        "variable": "Interested in Demo"
      },
      "variables": [
        {
          "name": "Demo Preference",
          "type": "string",
          "description": "Type of demo preferred (in-person, virtual, etc.)"
        }
      ]
    }
  ]
}

​
Response

​
status
integer

HTTP status code (200 for success).

​
data
object

The created citation schema object.

​
id
string

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

​
name
string

The name of the citation schema.

​
description
string

The description of the citation schema.

​
org_id
string

The organization ID that owns this schema.

​
schema
object

The JSON schema configuration for citation extraction.

​
created_at
string

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

​
errors
null

Will be null for successful requests.

​
Error Responses

​
400 Bad Request

Returned when the required name parameter is missing.

{
  "status": 200,
  "data": {
    "id": "6ba7b812-9dad-11d1-80b4-00c04fd430c8",
    "name": "Customer Information Extraction",
    "description": "Extracts customer demographics and contact information from call transcripts",
    "org_id": "9b59f853-c2c7-4e3a-b5d6-8f7e9a1b2c3d",
    "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": "Interested in Demo",
          "description": "Whether the customer wants to schedule a demo",
          "type": "boolean"
        }
      ],
      "groupings": [
        {
          "name": "Contact Information",
          "variables": ["Customer Name", "Customer Email"]
        }
      ],
      "conditions": [
        {
          "condition": {
            "value": "true",
            "operator": "===",
            "variable": "Interested in Demo"
          },
          "variables": [
            {
              "name": "Demo Preference",
              "type": "string",
              "description": "Type of demo the customer prefers (in-person, virtual, etc.)"
            }
          ]
        }
      ]
    },
    "created_at": "2023-12-15T14:30:00.000Z"
  },
  "errors": null
}