Dockets V2

When you trigger the below endpoint, it creates a docket.

Create Docket

Creates a docket record in the DB only; does not place a call

POST https://api.dialflo.ai/api/v2/dockets

auth_token: Bearer <auth_token>
Content-Type: application/json

{
  
	"agent_id": 280,
	"to_phone_number": "917504429196", // 12 Digit Phone Number with Country Code
    "external_id": "12345", // internal CRM id
     "extra_config": {
     	"call_context": { // context or attributes for the AI agent to use 
	      "crm_id": "12345",         // internal CRM id
	      "name": "",
	      "email": "",          // if email is present
		}
    }
}

Response:

Success Response Status: 200 with body

{
  "docket_id": "3f2b9c1a-7d4e-4a10-9b2c-8e5f1a6d4c22",
  "status": "OPEN",
  "created": true
}

The docket uuid is unique identifier for this docket which can be used to get status of this and associated calls with this docket.

Webhook Delivery

On Completion of docket ( i.e no more further calls to be made), we will send docket details to the webhook. Important Fields -

docket_id → can be use to map to original docket created

call_insights.call_disposition → final outcome of calls made in the docket

call_insights.call_metadata → extracted call details map based on the agent (if configured).

call_context → contains the context variables sent originally.

attempts → contains the details of call attempts made in this docket.

dashboard_url → url of last answered call if any (can be null if no calls were answered)

**Note: call_insights would be null if user did not pick call in any call attempt.**

Retry

We recommend to track status code of APIs at your end as well and to have a exponential backoff based retry for 5xx statuses so that any brief downtime does not affect the API.

Fetch Docket Details

This can be used to fetch the current state of docket using the docket ID. status: COMPLETED → the docket is completed status: IN_PROGRESS → the docket is still pending to be completed.

GET https://api.dialflo.ai/api/v1/dockets/{docket_id}

curl 'https://api.dialflo.ai/api/v1/dockets/{docket_id}' \
--header 'Accept: application/json' \
--header 'auth_token: Bearer <auth_token>' \
--header 'Content-Type: application/json'

Sample response -

 {
    "docket_id": "81664fe3-cabf-4720-8cda-8a3a1a1d6a46",
    "agent_name": "Wroots Outgoing",
    "status": "COMPLETED",
    "call_type": "DIALFLO_INTERNAL_TEST",
    "from_number": "918071583200",
    "to_phone_number": "917504429196",
    "call_context": {
    		"crm_id": "xxxx",
			"name": "",
			"email": "",          // if email is present
    },
    "external_id": "crm_id",
    "closed_call_id": "f632b050-4f3a-47d0-a914-04e73a98b8d1",
    "latest_call_id": "f632b050-4f3a-47d0-a914-04e73a98b8d1",
    "closure_reason": "DISPOSITION",
    "outbound_call_count": 1,
    "notification_status": "SKIPPED",
    "first_called_at": "2026-08-11T12:31:17.889766",
    "closed_at": "2026-08-11T12:32:33.333911",
    "created_at": "2026-08-11T12:31:14.989407",
    "updated_at": "2026-08-11T12:32:33.351692"
}

Trigger Call for a docket

Triggers the outbound call for an already-created docket.

POST /api/v2/dockets/{docket_id}/trigger

auth_token: Bearer <auth_token>
Content-Type: application/json

Response Status: 200 with body

{
  "task_uuid": "9f8c2b7e-1a34-4d6f-b0e2-7c5a1d9e4f30"
}

Create docket and trigger call

Creates a docket and immediately triggers the outbound call.

POST /api/v2/dockets/create-and-trigger

auth_token: Bearer <auth_token>
Content-Type: application/json

{
  
	"agent_id": 280,
	"to_phone_number": "917504429196", // 12 Digit Phone Number with Country Code
    "external_id": "12345", // internal CRM id
     "extra_config": {
     	"call_context": { // context or attributes for the AI agent to use 
	      "crm_id": "12345",         // internal CRM id
	      "name": "",
	      "email": "",          // if email is present
		}
    }
}

Response:

{
  "docket_id": "dkt_a1b2c3d4e5",
  "created": true,
  "task_uuid": "9f8c2b7e-1a34-4d6f-b0e2-7c5a1d9e4f30"
}

Bulk Create Dockets

Creates multiple dockets in one request (create-only, per-item success/error); does not place calls.

POST /api/v2/dockets/bulk

auth_token: Bearer <auth_token>
Content-Type: application/json

{
  "agent_id": 123,
  "dockets": [
    {
      "to_phone_number": "919876543210",
      "external_id": "cust-4567",
      "extra_config": {
        "call_context": {
          "CAMPAIGN_ID": "camp-001",
          "customer_name": "Ravi"
        }
      }
    },
    {
      "to_phone_number": "918123456789",
      "external_id": "cust-4568"
    },
    {
      "to_phone_number": "12345"
    }
  ]
}

curl -X POST 'https://<host>/api/v2/dockets/bulk' \
  -H 'Content-Type: application/json' \
  -H 'auth_token: Bearer dfl_your_org_api_key' \
  -d '{
    "agent_id": 123,
    "dockets": [
      {"to_phone_number": "919876543210", "external_id": "cust-4567"},
      {"to_phone_number": "918123456789", "external_id": "cust-4568"}
    ]
  }'

Response:

{
  "total": 3,
  "succeeded": 2,
  "failed": 1,
  "results": [
    {
      "success": true,
      "docket_id": "dkt_a1b2c3d4e5",
      "status": "IN_PROGRESS",
      "created": true,
      "error": null
    },
    {
      "success": true,
      "docket_id": "dkt_f6g7h8i9j0",
      "status": "IN_PROGRESS",
      "created": false,
      "error": null
    },
    {
      "success": false,
      "docket_id": null,
      "status": null,
      "created": null,
      "error": "to_phone_number must be 12 digits"
    }
  ]
}

Notes:

Per-item failures don’t fail the whole request — each is reported individually in results (created: false means an existing open docket was reused).
If the top-level agent_id resolves to no agent, the whole request fails with 404.
The to_phone_number 12-digit check is enforced at the schema level here; an invalid one within a batch item surfaces as a Pydantic 422 for the whole request (not a per-item error), while other errors like agent-access are per-item. So validate numbers client-side before sending.

Common Failures

Status	When	Body / Notes
`422`	Any item’s `to_phone_number` is not exactly 12 digits, or `dockets` is empty (`min_length=1`)	Pydantic validation — fails the whole request before any docket is created
`401`	Missing/invalid `auth_token`	`{"detail": {"message": "User is unauthorised"}}`
`404`	Top-level `agent_id` resolves to no OUTGOING agent	`{"detail": {"message": "No agent found for id <id>"}}` — fails the whole request
`403`	Agent not accessible to your org	`{"detail": {"message": "Agent <name> is not accessible to your account"}}` — fails the whole request
`500`	Unexpected failure at the batch level	`{"detail": "Failed to bulk create dockets"}`
Per-item	A single docket fails during DB creation	Request still returns `201`; that item appears in `results` with `success: false` and an `error` string, `failed` count incremented

Overview

Customization

Webhooks

Create Docket

Response:

Webhook Delivery

Retry

Fetch Docket Details

Trigger Call for a docket

Create docket and trigger call

Bulk Create Dockets

Common Failures

​Create Docket

​Response:

​Webhook Delivery

​Retry

​Fetch Docket Details

​Trigger Call for a docket

​Create docket and trigger call

​Bulk Create Dockets

​Common Failures

Create Docket

Response:

Webhook Delivery

Retry

Fetch Docket Details

Trigger Call for a docket

Create docket and trigger call

Bulk Create Dockets

Common Failures