Skip to main content
POST
/
v1
/
citation_schemas
/
backfill
Backfill Citation Schema
curl --request POST \
  --url https://api.bland.ai/v1/citation_schemas/backfill \
  --header 'Content-Type: application/json' \
  --header 'authorization: <authorization>' \
  --data '{
  "schema_id": "<string>",
  "schema_ids": [
    "<string>"
  ],
  "schema": {},
  "call_id": "<string>",
  "call_ids": [
    "<string>"
  ]
}'
{
  "status": "<string>",
  "workflow_id": "<string>",
  "call_count": 123,
  "schema_count": 123,
  "total_combinations": 123,
  "message": "<string>",
  "result": {},
  "result.status": "<string>",
  "result.calls": [
    {}
  ],
  "result.calls[].call_id": "<string>",
  "result.calls[].status": "<string>",
  "result.calls[].schemas_processed": [
    {}
  ],
  "result.calls[].variables_extracted_count": 123,
  "result.calls[].previous_variables": {},
  "result.calls[].newly_extracted_variables": {},
  "result.calls[].final_variables": {},
  "result.summary": {}
}

​
Overview

The backfill endpoint allows you to apply citation schemas to calls that have already been completed. This is useful when you:
  • Create a new schema and want to extract data from historical calls
  • Need to re-analyze calls with updated schemas
  • Want to extract data from multiple calls at scale
Backfill operations are asynchronous - you’ll receive a workflow_id immediately and can poll the status endpoint to check progress and retrieve results.
This is an Enterprise-only feature. Contact your Bland representative or reach out to sales to enable this functionality.
Backfilling will update citation variables for the specified call(s) and schema(s). Variables are merged with existing data - only the variables defined in the schema being backfilled will be updated.

​
Request

​
Headers

​
authorization
string
required
Your API key for authentication.

​
Body Parameters

​
Schema Parameters (Choose One)

​
schema_id
string
A single citation schema ID from your organization to apply to the call(s).
​
schema_ids
string[]
An array of citation schema IDs to apply to the call(s). All schemas will be processed for each call.Note: Cannot be combined with schema (inline schema).
​
schema
object
An inline citation schema definition. Useful for one-time analysis without creating a schema in your account.Can be combined with call_id or call_ids for multi-call analysis.Note: Cannot be combined with schema_ids.

​
Call Parameters (Choose One)

​
call_id
string
A single call ID to analyze with the specified schema(s).
​
call_ids
string[]
An array of call IDs to analyze with the specified schema(s). All schemas will be applied to each call.

​
Response (202 Accepted)

The endpoint returns immediately with a workflow ID. Use the status endpoint to monitor progress.
​
status
string
Always "processing" - indicates the workflow has been started.
​
workflow_id
string
Unique identifier for this backfill operation. Use this to check status and retrieve results.
​
call_count
integer
Number of calls being processed.
​
schema_count
integer
Number of schemas being applied to each call.
​
total_combinations
integer
Total number of call+schema extractions that will be performed (call_count × schema_count).
​
message
string
Instructions on how to check the status of your workflow.

​
Checking Status

Use the workflow ID to poll the status endpoint: 
GET https://api.bland.ai/v1/citation_schemas/backfill/status/{workflow_id}

​
Status Response

​
workflow_id
string
The workflow ID you’re querying.
​
status
string
Current workflow status:
  • RUNNING: Still processing
  • COMPLETED: Finished successfully (may have partial failures)
  • FAILED: Workflow encountered an error
  • TERMINATED: Manually stopped
  • TIMED_OUT: Exceeded maximum execution time
​
result
object
Only present when status is COMPLETED. Contains the full backfill results.

​
Result Object (When Completed)

​
result.status
string
Overall result status:
  • success: All extractions succeeded
  • partial: Some extractions succeeded, some failed
  • failed: All extractions failed
​
result.calls
array
Array of results, one entry per call processed.
​
result.calls[].call_id
string
The call that was analyzed.
​
result.calls[].status
string
Status for this call: success, partial, or failed.
​
result.calls[].schemas_processed
array
Details about each schema extraction for this call.
​
result.calls[].variables_extracted_count
integer
Total number of unique variables extracted across all schemas for this call.
​
result.calls[].previous_variables
object
The call’s citation variables before this backfill operation.
​
result.calls[].newly_extracted_variables
object
Variables that were extracted or updated by this backfill operation.
​
result.calls[].final_variables
object
The call’s citation variables after this backfill operation (complete state).
​
result.summary
object
Aggregate statistics across all calls and schemas:
  • total_calls: Number of calls processed
  • successful_calls: Calls where all schemas succeeded
  • partial_calls: Calls where some schemas failed
  • failed_calls: Calls where all schemas failed
  • total_schemas_processed: Total schema extractions attempted
  • successful_schema_extractions: Schema extractions that succeeded
  • failed_schema_extractions: Schema extractions that failed

​
Usage Flow

  1. Send backfill request and receive workflow_id
  2. Poll the status endpoint periodically (every 5-10 seconds)
  3. When status is COMPLETED, retrieve results from result field
  4. Review the results to see what was extracted for each call

​
Examples

​
Single Call, Single Schema

Request
curl -X POST https://api.bland.ai/v1/citation_schemas/backfill \
  -H "authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "call_id": "call-123",
    "schema_id": "schema-abc"
  }'
Response (202 Accepted)
{
  "status": "processing",
  "workflow_id": "backfill:call-123:1760635265843",
  "call_count": 1,
  "schema_count": 1,
  "total_combinations": 1,
  "message": "Citation backfill workflow started for 1 call(s) with 1 schema(s)..."
}

​
Multiple Calls, Multiple Schemas

Request
curl -X POST https://api.bland.ai/v1/citation_schemas/backfill \
  -H "authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "call_ids": ["call-123", "call-456", "call-789"],
    "schema_ids": ["schema-abc", "schema-def"]
  }'
Response (202 Accepted)
{
  "status": "processing",
  "workflow_id": "backfill:batch:671b7623-f9ac-46db-95f1-9b504fe59a06:1760635265843",
  "call_count": 3,
  "schema_count": 2,
  "total_combinations": 6,
  "message": "Citation backfill workflow started for 3 call(s) with 2 schema(s)..."
}

​
Single Call with Inline Schema

Request
curl -X POST https://api.bland.ai/v1/citation_schemas/backfill \
  -H "authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "call_id": "call-123",
    "schema": {
      "name": "Customer Sentiment Analysis",
      "variables": [
        {
          "name": "customer_satisfied",
          "type": "boolean",
          "description": "Whether the customer expressed satisfaction"
        },
        {
          "name": "sentiment_score",
          "type": "number",
          "description": "Overall sentiment from -1 (negative) to 1 (positive)"
        }
      ]
    }
  }'

​
Checking Status

Request
curl https://api.bland.ai/v1/citation_schemas/backfill/status/backfill:call-123:1760635265843 \
  -H "authorization: YOUR_API_KEY"
Response (Status: RUNNING)
{
  "workflow_id": "backfill:call-123:1760635265843",
  "status": "RUNNING",
  "run_id": "0199ee0a-2343-7d98-8fbb-8d5c2d46ed4c",
  "start_time": "2025-10-16T17:21:05.859Z"
}
Response (Status: COMPLETED)
{
  "workflow_id": "backfill:call-123:1760635265843",
  "status": "COMPLETED",
  "run_id": "0199ee0a-2343-7d98-8fbb-8d5c2d46ed4c",
  "start_time": "2025-10-16T17:21:05.859Z",
  "close_time": "2025-10-16T17:21:39.019Z",
  "result": {
    "status": "success",
    "calls": [
      {
        "call_id": "call-123",
        "status": "success",
        "schemas_processed": [
          {
            "schema_id": "schema-abc",
            "status": "success",
            "variables_extracted": 5
          }
        ],
        "variables_extracted_count": 5,
        "previous_variables": {
          "customer_name": "John Doe"
        },
        "newly_extracted_variables": {
          "order_id": "ORD-789456",
          "issue_type": "shipping",
          "products": [
            {
              "name": "Wireless Headphones",
              "issue": "damaged packaging",
              "quantity": 1
            }
          ],
          "customer_satisfied": true,
          "resolution": "refund_issued"
        },
        "final_variables": {
          "customer_name": "John Doe",
          "order_id": "ORD-789456",
          "issue_type": "shipping",
          "products": [
            {
              "name": "Wireless Headphones",
              "issue": "damaged packaging",
              "quantity": 1
            }
          ],
          "customer_satisfied": true,
          "resolution": "refund_issued"
        }
      }
    ],
    "summary": {
      "total_calls": 1,
      "successful_calls": 1,
      "partial_calls": 0,
      "failed_calls": 0,
      "total_schemas_processed": 1,
      "successful_schema_extractions": 1,
      "failed_schema_extractions": 0
    }
  }
}

​
Error Responses

​
400 Bad Request

Returned when:
  • No schema parameter provided (schema_id, schema_ids, or schema required)
  • No call parameter provided (call_id or call_ids required)
  • Invalid parameter combinations (e.g., schema_ids with inline schema)
  • Empty arrays provided

​
403 Forbidden

Returned when:
  • Account does not have enterprise features enabled
  • Attempting to access another organization’s calls or schemas

​
404 Not Found

Returned when:
  • Specified call ID(s) not found
  • Specified schema ID(s) not found
  • Resources don’t belong to your organization

​
500 Internal Server Error

Returned when an unexpected error occurs starting the workflow.

​
Best Practices

​
Polling Strategy

  • Poll every 5-10 seconds for single-call operations
  • Poll every 10-30 seconds for batch operations
  • Implement exponential backoff if polling for extended periods
  • Stop polling once status is COMPLETED, FAILED, TERMINATED, or TIMED_OUT

​
Batch Processing

  • Process up to 100 calls at once for optimal performance
  • For larger batches, split into multiple backfill requests
  • Use multiple schemas in a single request rather than separate requests per schema

​
Error Handling

  • Check the result.calls[].status field for per-call results
  • Review schemas_processed array to see which schemas succeeded/failed
  • Use error_summary field for quick diagnosis of partial failures
  • Failed extractions don’t prevent successful ones from being stored

​
Variable Management

  • Newly extracted variables overwrite previous values with the same name
  • Variables from different schemas are merged together
  • Only variables defined in the backfilled schema are updated
  • Other existing variables remain unchanged
⌘I