Captain.AI API Documentation

website·Indexed 33 days ago

https://developers.captain.ai/

API reference for Captain.AI, featuring endpoints for managing orders, accounts, and drivers. Includes detailed documentation on order creation, status updates, driver clock-in/out, and a webhook system for events such as order status updates, preparation updates, and KDS print requests.

Tokens: 25.6K
Snippets: 93
Records: 134
Agent score: 49%

What's inside Captain.AI

Introduction to Captain.AI API
The Captain.AI API is a REST-based service used to manage stores, delivery drivers, and orders. It uses standard HTTP methods (GET, POST, PATCH, DELETE) and transmits all data in JSON format. Key capabilities include creating and retrieving orders and delivery jobs, retrieving account drivers, canceling orders, and automating order preparation.
https://developers.captain.ai/docs/

Order Model Assigned Driver data schema

The Assigned Driver object provides details about the driver assigned to an order, including personal identification, contact information, status, and real-time tracking data such as GPS coordinates and ETA timestamps.

{
  "first_name": "string",
  "last_name": "string",
  "email": "string",
  "phone_number": "string",
  "profile_picture_url": "string",
  "active": "boolean",
  "agent_uuid": "string",
  "eta_calculated_at": "number",
  "eta_till_available": "number",
  "eta_till_arrive_at_home_hub": "number",
  "last_location": {
    "latitude": "number",
    "longitude": "number",
    "recorded_at": "string"
  }
}

Handle job delivery status updates via webhooks

The job_delivery_status_updated webhook event is triggered whenever a job's status changes (e.g., accepted by driver, picked up, or completed). This event provides detailed information about the job, the driver (agent), and the order, including FleetShare provider details if applicable.

{
  "data": {
    "job_uuid": "a41d767aac70",
    "job_delivery_status": "assigned_to_driver",
    "job_delivery_status_agent_uuid": "2933a9574fa0",
    "job_delivery_status_agent_location": {
      "latitude": "13.715925",
      "longitude": "100.585788",
      "recorded_at": "2025-03-13T08:14:47.267+00:00"
    },
    "order_description": "1506-177",
    "account_uuid": "a9c7b6a24e67",
    "published_at": 1741853746.4946675,
    "order_account_business_partners_external_identifier": "",
    "order_account_partners_external_identifier": "",
    "order_uuid": "a41d767aac70",
    "partners_unique_internal_order_id": "cf22a4c0-0e6a-41cc-a0fe-96a76f5085e4",
    "order_custom_fields": null,
    "fleetshare": {
      "provider_name": "DoorDash",
      "driver_name": "John Smith",
      "driver_phone_number": "+1234567890",
      "driver_email": "john.smith@example.com",
      "placeholder": false
    }
  },
  "event_name": "job_delivery_status_updated",
  "environment": "production",
  "created_at": "2025-03-13T08:15:46.503+00:00",
  "event_uuid": "ae9b6746-48ca-40db-9058-f74ab6b25c05",
  "metadata": {
    "sent_at": "2025-03-13T08:15:46.513+00:00",
    "delivery_attempt": 1
  }
}

Understand the item_status_updated webhook payload

The item_status_updated webhook is triggered whenever an order status changes. The payload contains detailed information about the item, the order, and the recipient. Key fields include item_status (the new status), item_uuid and order_uuid for identification, and recipient details for delivery.

{
  "item_status": "string", // e.g., being_prepared or prepared
  "quantity": "integer",
  "sequence": "string", // Used for printing labels
  "channel_slug": "string",
  "account_uuid": "string", // Store UUID
  "published_at": "integer", // Unix timestamp
  "payment_gateway_id": "string",
  "payment_status": "string",
  "grand_total_including_tax": "decimal",
  "item_account_partners_external_identifier": "string", // Store's unique ID in your system
  "item_account_business_partners_external_identifier": "string", // Business's unique ID in your system
  "kind": "string", // delivery, collection, walk_in, third_party_delivery, or drive_thru
  "order_description": "string", // Internal friendly order ID
  "tracking_link": "string", // URL to Captain.AI Tracking Page
  "item_uuid": "string",
  "item_name": "string",
  "item_addons": "array",
  "order_uuid": "string",
  "partners_unique_internal_order_id": "string", // Your internal order UUID
  "order_custom_fields": "object or null", // Custom fields passed during order creation
  "recipient": {
    "name": "string",
    "phone_number": "string",
    "address": {
      "name": "string",
      "line_1": "string",
      "line_2": "string",
      "city": "string",
      "postcode": "string",
      "country": "string",
      "state": "string",
      "apartment_number": "string",
      "latitude": "string",
      "longitude": "string",
      "address_specific_instructions_to_driver": "string"
    }
  },
  "printer": "string"
}

Handle the order_assigned webhook event

The order_assigned webhook event is triggered every time an order is assigned to a driver. It provides details about the order, the assigned driver (agent), the store (account), and optional FleetShare provider information if the delivery is handled via FleetShare.

{
  "data": {
    "order_uuid": "6992dc85d681",
    "partners_unique_internal_order_id": "ac730930-a545-4a54-8ad9-5f60737d8a1c",
    "account_uuid": "73f4c9af9f79",
    "agent_uuid": "7183bb9f1a65",
    "agent_partners_external_identifier": "webhook-driver-1-partners-external-identifier",
    "agent_partner_data": {
      "example": 456
    },
    "order_account_partners_external_identifier": "partners-external-identifier-account",
    "order_account_business_partners_external_identifier": "",
    "order_custom_fields": {
      "example": 123,
      "sms_opt_in": true,
      "anything_else_that": "was_passed_through_when_creating_an_order"
    },
    "fleetshare": {
      "provider_name": "DoorDash",
      "driver_name": "John Smith",
      "driver_phone_number": "+1234567890",
      "driver_email": "john.smith@example.com",
      "placeholder": false
    },
    "published_at": 1651157722.2628822
  },
  "environment": "production",
  "event_name": "order_assigned",
  "created_at": "2022-04-28T14:55:22.333+00:00",
  "event_uuid": "a18a4c70-e1e0-4024-a44f-b189835eb970",
  "metadata": {
    "sent_at": "2022-04-28T14:55:22.350+00:00",
    "delivery_attempt": 1
  }
}

Handle the `order_unassigned` webhook event

The order_unassigned event is triggered every time an order is unassigned from an agent. This webhook provides details about the order, the store (account), the driver (agent), and optional FleetShare provider information if applicable.

{
  "data": {
    "order_uuid": "1bbccbfff496",
    "partners_unique_internal_order_id": "ac730930-a545-4a54-8ad9-5f60737d8a1c",
    "account_uuid": "1234c9999f79",
    "agent_uuid": "1133bb999a45",
    "agent_partners_external_identifier": "webhook-driver-1-partners-external-identifier",
    "agent_partner_data": {},
    "order_account_partners_external_identifier": "partners-external-identifier-account",
    "order_account_business_partners_external_identifier": "",
    "order_custom_fields": null,
    "fleetshare": {
      "provider_name": "DoorDash",
      "driver_name": "John Smith",
      "driver_phone_number": "+1234567890",
      "driver_email": "john.smith@example.com",
      "placeholder": false
    },
    "published_at": 1651156220.3478127
  },
  "environment": "production",
  "event_name": "order_unassigned",
  "created_at": "2022-04-28T14:30:20.483+00:00",
  "event_uuid": "b3df4834-328b-4d54-a871-91b17aa52ca4",
  "metadata": {
    "sent_at": "2022-04-28T14:30:20.500+00:00",
    "delivery_attempt": 1
  }
}

Retrieve account information using the Accounts API
Use the GET /v1/accounts/{account_uuid} endpoint to retrieve detailed information about a specific account, including its unique identifier, friendly name, account type (fleet or store), and webhook configurations.
```
GET /v1/accounts/3584a197b5a9
```
https://developers.captain.ai/docs/accounts_show
Retrieve information about a specific webhook
Use the GET /v1/accounts/{account_uuid}/webhooks/{webhook_uuid} endpoint to list the configuration and status of a specific webhook. The response includes the webhook's URL, secret token, enabled status, a detailed map of subscribed events, and specific configuration options.
```
GET /v1/accounts/3584a197b5a9/webhooks/DPTCye18PXXAG2gv
```
https://developers.captain.ai/docs/api/accounts/webhooks/webhooks_show
Retrieve a single order
Use the GET /v1/accounts/{account_uuid}/orders/{order_uuid} endpoint to retrieve detailed information about a specific order. The response includes order status, financial records, recipient details, delivery job information, item lists, and timing milestones.
```
GET /v1/accounts/3584a197b5a9/orders/46edc8e3
```
https://developers.captain.ai/docs/orders_show

Handle the order_status_updated webhook event

The order_status_updated event is triggered every time the status of an order changes. This webhook provides details about the order, the new status, and, in cases of failure or cancellation, the reason for that change.

{
  "data": {
    "order_uuid": "string",
    "order_description": "string",
    "order_custom_fields": "array or null",
    "order_status": "string",
    "account_uuid": "string",
    "partners_unique_internal_order_id": "string",
    "order_account_partners_external_identifier": "string",
    "order_account_business_partners_external_identifier": "string",
    "published_at": "integer (unix timestamp)",
    "items": "array (contact support to enable)",
    "reason": "string or null (only present if status is cancelled or failed"
  },
  "event_name": "order_status_updated",
  "environment": "production",
  "created_at": "ISO8601 timestamp",
  "event_uuid": "string",
  "metadata": {
    "sent_at": "ISO8601 timestamp",
    "delivery_attempt": "integer"
  }
}

Understand the item_status_updated webhook trigger
The item_status_updated webhook event is triggered whenever the status of an order changes. For this event to fire, the system must receive order preparation data, which occurs either via the Captain.ai Kitchen App or through a third-party system integration that provides kitchen updates to the store.
https://developers.captain.ai/docs/webhooks_item_status_updated
Set up Captain.AI Webhooks
To enable webhooks, you must contact your account manager.
Requirements:
- Your system must provide an HTTPS/SSL endpoint capable of receiving external messages.
- Captain.AI supports one primary URL for all webhooks, with the exception of the item_status_updated event, which requires its own dedicated endpoint.
https://developers.captain.ai/docs/webhooks_overview/