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>"
  ],
  "conversation_id": "<string>",
  "conversation_ids": [
    "<string>"
  ]
}
'
{
  "status": "<string>",
  "workflow_id": "<string>",
  "call_count": 123,
  "conversation_count": 123,
  "schema_count": 123,
  "total_combinations": 123,
  "conversations": [
    {}
  ],
  "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 and SMS conversations that have already been completed. This is useful when you:
  • Create a new schema and want to extract data from historical calls or conversations
  • Need to re-analyze calls or conversations with updated schemas
  • Want to extract data from multiple calls or conversations at scale
Call backfill operations are asynchronous — you’ll receive a workflow_id immediately and can poll the status endpoint to check progress. SMS conversation backfill is synchronous — results are returned directly in the response.
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. Not supported for SMS conversation backfill.

​
Call Parameters

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

​
SMS Conversation Parameters

​
conversation_id
string
A single SMS conversation ID to analyze with the specified schema(s). Processed synchronously.
​
conversation_ids
string[]
An array of SMS conversation IDs to analyze. Maximum 50 conversations per request. All schemas will be applied to each conversation. Processed synchronously.

​
Response

Returns 202 Accepted when calls are included (async processing), or 200 OK when only SMS conversations are included (sync processing).
​
status
string
"processing" when calls are being processed asynchronously, or "complete" when only SMS conversations were processed.
​
workflow_id
string
Unique identifier for the call backfill workflow. Only present when calls are included. Use this to check status and retrieve results.
​
call_count
integer
Number of calls being processed.
​
conversation_count
integer
Number of SMS conversations processed.
​
schema_count
integer
Number of schemas being applied.
​
total_combinations
integer
Total number of call+schema extractions that will be performed (call_count × schema_count). Only present when calls are included.
​
conversations
array
Results for SMS conversation backfill. Only present when conversations are included. Each entry contains:
  • conversation_id — the conversation that was analyzed
  • status — "success", "skipped", or "error"
  • variables_extracted — number of citation variables extracted
  • error — error message if the extraction failed
​
message
string
Instructions on how to check the status of the call 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)..."
}

​
SMS Conversations

Request
curl -X POST https://api.bland.ai/v1/citation_schemas/backfill \
  -H "authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "conversation_ids": ["conv-123", "conv-456"],
    "schema_id": "schema-abc"
  }'
Response (200 OK)
{
  "status": "complete",
  "call_count": 0,
  "conversation_count": 2,
  "schema_count": 1,
  "conversations": [
    {
      "conversation_id": "conv-123",
      "status": "success",
      "variables_extracted": 3
    },
    {
      "conversation_id": "conv-456",
      "status": "success",
      "variables_extracted": 2
    }
  ]
}

​
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 identifier parameter provided (call_id, call_ids, conversation_id, conversation_ids, or recording_url required)
  • Invalid parameter combinations (e.g., schema_ids with inline schema)
  • Empty arrays provided
  • More than 50 SMS conversations in a single request

​
403 Forbidden

Returned when:
  • Account does not have enterprise features enabled
  • Attempting to access another organization’s calls, conversations, 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