> ## Documentation Index
> Fetch the complete documentation index at: https://docs.burki.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Update Call Metadata

> Update the metadata for a specific call.

This allows you to store custom information against a call record.
The new metadata will be merged with any existing metadata.

Update the custom metadata associated with a call. This allows you to attach arbitrary data to call records for tracking, analytics, or integration with your systems.

<Info>
  **Merge Behavior**: New metadata is merged with existing metadata. To remove a field, set its value to `null`.
</Info>

## Use Cases

* **CRM Integration**: Link calls to customer records, tickets, or opportunities
* **Campaign Tracking**: Tag calls with campaign IDs for attribution
* **Custom Analytics**: Add business-specific data for reporting
* **Outcome Tracking**: Record call outcomes like "appointment\_booked" or "sale\_completed"

## Path Parameters

| Parameter | Type    | Required | Description                             |
| --------- | ------- | -------- | --------------------------------------- |
| `call_id` | integer | Yes      | The internal call ID (not the call SID) |

## Request Body

| Field      | Type   | Required | Description                            |
| ---------- | ------ | -------- | -------------------------------------- |
| `metadata` | object | Yes      | Key-value pairs to store with the call |

```json theme={null}
{
  "metadata": {
    "customer_id": "cust_abc123",
    "ticket_id": "TICKET-456",
    "campaign": "spring_outreach_2024",
    "outcome": "appointment_scheduled",
    "custom_field": "any_value"
  }
}
```

## Request Example

```bash theme={null}
curl -X PATCH "https://api.burki.dev/api/v1/calls/101/metadata" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "metadata": {
      "customer_id": "cust_abc123",
      "outcome": "appointment_scheduled"
    }
  }'
```

## Response

Returns the updated call object with the merged metadata.

```json theme={null}
{
  "id": 101,
  "call_sid": "CAxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "assistant_id": 123,
  "assistant_name": "ServiceBot",
  "to_phone_number": "+15551234567",
  "customer_phone_number": "+15559876543",
  "status": "completed",
  "duration": 180,
  "started_at": "2024-01-15T10:00:00Z",
  "ended_at": "2024-01-15T10:03:00Z",
  "call_meta": {
    "customer_id": "cust_abc123",
    "outcome": "appointment_scheduled"
  },
  "total_cost": 0.05,
  "llm_cost": 0.02,
  "tts_cost": 0.01,
  "stt_cost": 0.01,
  "telephony_cost": 0.01,
  "cost_currency": "USD"
}
```

## Error Responses

### 404 Not Found

```json theme={null}
{
  "detail": "Call with ID 101 not found in your organization"
}
```

### 422 Unprocessable Entity

```json theme={null}
{
  "detail": [
    {
      "loc": ["body", "metadata"],
      "msg": "field required",
      "type": "value_error.missing"
    }
  ]
}
```

## Examples

### Python - Add Customer Info

```python theme={null}
import requests

def tag_call_with_customer(call_id, customer_id, customer_name):
    response = requests.patch(
        f"https://api.burki.dev/api/v1/calls/{call_id}/metadata",
        headers={"Authorization": "Bearer YOUR_API_KEY"},
        json={
            "metadata": {
                "customer_id": customer_id,
                "customer_name": customer_name,
                "tagged_at": "2024-01-15T10:00:00Z"
            }
        }
    )
    
    return response.json()
```

### Python - Record Call Outcome

```python theme={null}
def record_call_outcome(call_id, outcome, notes=None):
    metadata = {
        "outcome": outcome,  # e.g., "sale", "no_answer", "callback_requested"
        "outcome_recorded_at": "2024-01-15T10:00:00Z"
    }
    
    if notes:
        metadata["outcome_notes"] = notes
    
    response = requests.patch(
        f"https://api.burki.dev/api/v1/calls/{call_id}/metadata",
        headers={"Authorization": "Bearer YOUR_API_KEY"},
        json={"metadata": metadata}
    )
    
    return response.json()
```

### Node.js - Campaign Attribution

```javascript theme={null}
const axios = require('axios');

async function attributeCallToCampaign(callId, campaignId, source) {
  const response = await axios.patch(
    `https://api.burki.dev/api/v1/calls/${callId}/metadata`,
    {
      metadata: {
        campaign_id: campaignId,
        traffic_source: source,
        attributed_at: new Date().toISOString()
      }
    },
    {
      headers: { 'Authorization': 'Bearer YOUR_API_KEY' }
    }
  );
  
  return response.data;
}
```

### Webhook Integration

A common pattern is to update call metadata from your webhook handler:

```python theme={null}
from flask import Flask, request
import requests

app = Flask(__name__)

@app.route('/webhooks/burki', methods=['POST'])
def handle_webhook():
    event = request.json
    
    if event['event'] == 'call_ended':
        call_id = event['call_id']
        
        # Look up the customer in your CRM
        customer = lookup_customer_by_phone(event['customer_phone_number'])
        
        if customer:
            # Tag the call with customer info
            requests.patch(
                f"https://api.burki.dev/api/v1/calls/{call_id}/metadata",
                headers={"Authorization": "Bearer YOUR_API_KEY"},
                json={
                    "metadata": {
                        "crm_customer_id": customer['id'],
                        "account_type": customer['type'],
                        "lifetime_value": customer['ltv']
                    }
                }
            )
    
    return {'received': True}
```

## Best Practices

1. **Use Consistent Keys**: Establish naming conventions for your metadata fields (e.g., `customer_id` vs `customerId`)

2. **Keep Values Simple**: Store IDs and references rather than large objects. Use your own systems for detailed data.

3. **Timestamp Important Updates**: Include timestamps when recording outcomes or status changes.

4. **Don't Store Sensitive Data**: Avoid storing PII, credentials, or other sensitive information in call metadata.

## Notes

* Metadata is stored as JSON and supports nested objects
* There is no size limit enforced, but keep metadata concise
* Metadata is included in call exports and analytics
* Use the [List Calls](/api-reference/calls/list) endpoint to filter calls by supported top-level metadata fields such as customer phone, assistant, status, dates, and call SID.


## OpenAPI

````yaml PATCH /api/v1/calls/{call_id}/metadata
openapi: 3.1.0
info:
  title: Burki
  description: A system that uses AI to answer customer Calls.
  version: 0.1.0
servers: []
security: []
paths:
  /api/v1/calls/{call_id}/metadata:
    patch:
      tags:
        - calls
      summary: Update Call Metadata
      description: |-
        Update the metadata for a specific call.

        This allows you to store custom information against a call record.
        The new metadata will be merged with any existing metadata.
      operationId: update_call_metadata_api_v1_calls__call_id__metadata_patch
      parameters:
        - name: call_id
          in: path
          required: true
          schema:
            type: integer
            title: Call Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateCallMetadataRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CallResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
        - HTTPBearer: []
components:
  schemas:
    UpdateCallMetadataRequest:
      properties:
        metadata:
          additionalProperties: true
          type: object
          title: Metadata
      type: object
      required:
        - metadata
      title: UpdateCallMetadataRequest
      description: Request model for updating call metadata.
    CallResponse:
      properties:
        call_sid:
          type: string
          title: Call Sid
        to_phone_number:
          type: string
          title: To Phone Number
        customer_phone_number:
          type: string
          title: Customer Phone Number
        call_meta:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Call Meta
        id:
          type: integer
          title: Id
        assistant_id:
          type: integer
          title: Assistant Id
        assistant_name:
          anyOf:
            - type: string
            - type: 'null'
          title: Assistant Name
        flow_name:
          anyOf:
            - type: string
            - type: 'null'
          title: Flow Name
        status:
          type: string
          title: Status
        duration:
          anyOf:
            - type: integer
            - type: 'null'
          title: Duration
        started_at:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Started At
        ended_at:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Ended At
        total_cost:
          anyOf:
            - type: number
            - type: 'null'
          title: Total Cost
        llm_cost:
          anyOf:
            - type: number
            - type: 'null'
          title: Llm Cost
        tts_cost:
          anyOf:
            - type: number
            - type: 'null'
          title: Tts Cost
        stt_cost:
          anyOf:
            - type: number
            - type: 'null'
          title: Stt Cost
        telephony_cost:
          anyOf:
            - type: number
            - type: 'null'
          title: Telephony Cost
        cost_currency:
          anyOf:
            - type: string
            - type: 'null'
          title: Cost Currency
      type: object
      required:
        - call_sid
        - to_phone_number
        - customer_phone_number
        - id
        - assistant_id
        - status
      title: CallResponse
      description: Schema for call response.
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
              - type: string
              - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
      type: object
      required:
        - loc
        - msg
        - type
      title: ValidationError
  securitySchemes:
    HTTPBearer:
      type: http
      scheme: bearer

````