Reports - Delivery Data

How does it work?

This report can generate a report of your delivery data in either CSV or JSON format. You can then use it to manipulate the data yourself using a spreadsheet app, import it into your BI tooling software, or import it into other third-party systems.

It allows you to specify the format you want the data to be in, the start and end dates, as well as the fields you'd like. You can request data for either a set of accounts, or an entire business, or company.

The report may take some time to complete, and this endpoint is only responsible for triggering the report. To get the actual data, you can either do it via our API or get a webhook from us when the report has finished processing.

Reports expire after 30 days.

---

Part 1. Triggering the request

- Request Values

Key	Type	Value
entity	string	One of: company, business, or account. Specifying either company or business will result in generating a report for accounts under that company or business.
uuids	array	Array of uuids.
kind	string	One of: delivery_data
file_format	string	One of: csv of json
date_start	string	Start date of the report
date_end	string	End date of the report
fields	array	Specify the fields to be included in the report. Please see available fields below.

POST /v1/analytics/reports

Example Request

POST /v1/analytics/reports

{
    "entity": "account",
    "uuids": [
        "83f8e61ca65f"
    ],
    "kind": "delivery_data",
    "file_format": "csv",
    "date_start": "2022-10-01",
    "date_end": "2022-11-01",
    "fields": [
        "account_uuid",
        "order_uuid",
        "order_recipient_email",
        "order_grand_total_including_tax",
        "order_description",
        "crowfly_distance_mi"
    ]
}

Example Response

{
    "uuid": "fYH8L5hXv9djr3tBgQVHxzcr",
    "kind": "delivery_data",
    "status": "created"
}

---

Part 2. Getting the report

There are two ways of getting the report output via our API:

• Continuously call our API to check if it has finished processing. When you create the report, you will get a unique ID (uuid) that you can then reference.
• Opt to receive a webhook instead.

Getting the report via API

Request

GET /v1/analytics/reports/:uuid

Example Request

GET /v1/analytics/reports/fYH8L5hXv9djr3tBgQVHxzcr

Response

Key	Type	Value
uuid	string	The UUID of the report. Use this to reference in further calls to actually get the data.
kind	string	The report type. The only report we currently have is delivery_data. Please ensure you add a check for this to ensure that new report types dont' break anything.
status	string	One of: created, processing, completed, failed, or expired.
url	string	The URL of the file containing the report.

Example Response

{
    "uuid": "fYH8L5hXv9djr3tBgQVHxzcr",
    "kind": "delivery_data",
    "status": "completed",
    "url": "https://cds-report-exports.s3.amazonaws.com/production/1546831361/fYH8L5hXv9djr3tBgQVHxzcr/delivery_data.csv?response-content-disposition=attachment%3B%20filename%3Ddelivery_data.csv&X-Amz-Algorithm=x&X-Amz-Credential=x&X-Amz-Date=x&X-Amz-Expires=x&X-Amz-SignedHeaders=host&X-Amz-Signature=x"
}

Getting the report via webhook

Please contact your account manager to get this setup. The URL has to be the same for all report types.

{
    "data": {
        "uuid": "fYH8L5hXv9djr3tBgQVHxzcr",
        "kind": "delivery_data",
        "status": "completed",
        "url": "https://cds-report-exports.s3.amazonaws.com/production/1546831361/fYH8L5hXv9djr3tBgQVHxzcr/delivery_data.csv?response-content-disposition=attachment%3B%20filename%3Ddelivery_data.csv&X-Amz-Algorithm=x&X-Amz-Credential=x&X-Amz-Date=x&X-Amz-Expires=x&X-Amz-SignedHeaders=host&X-Amz-Signature=x"
    },
    "event_name": "analytics_report_ready"
}

Available Fields

General

Key	Type	Value
uuid	string	Captain's unique order ID. This is generated at the point of the order being created.
order_uuid	string	Duplicate of the above.
status	string	One of: created, being_prepared, prepared, in_progress, completed, failed, cancelled, auto_closed, not_dispatched
delivery_status	string	One of: unassigned_to_driver, assigned_to_driver, assigned_and_accepted_by_driver, collected, dropped_off
special_instructions	string	Special instructions for the order, as passed in by you at the point of the order being created.
order_description	string	A friendly order ID, as passed in by you at the point of the order being created.
order_partners_unique_internal_order_id	string	A unique order ID, as passed in by you at the point of the order being created.

Delivery Information

Key	Type	Value
geo_verified	boolean or nil	Whether or not the delivery was performed correctly by the driver, i.e. whether or not the driver marked the order as picked up and delivered at the right physical places,. It will be set to true if both of these conditions are true, otherwise it will be set to false. It will be empty if geoverification was not performed on the delivery (e.g. if the delivery was cancelled)
dropoff_sequence_number	integer	If this delivery is part of a multi-drop delivery group, the sequence number of this delivery.
crowfly_distance_km	decimal	Crowfly distance between the store and the dropoff address, in kilometers.
crowfly_distance_mi	decimal	Crowfly distance between the store and the dropoff address, in miles.
bearing	decimal	Bearing from the store towards the dropoff location.

Timings

Key	Type	Value
created_at	datetime	The time that the order was received by Captain.
order_placed_at	datetime	The time that your system marked the order as created
collected_at	datetime	The time the order was marked as picked up by the driver.
delivered_at	datetime	The time the order was marked as delivered by the driver.
promised_delivery_time_at	datetime	The time that the customer was promised the delivery, as passed in by you at the point of the order being created.
promised_delivery_minutes	integer	The promised amount of minutes it will take to deliver the order to the customer, as passed in by you at the point of the order being created.

Store / Account

Key	Type	Value
account_uuid	string	The store's unique identifier on Captain.
store_name	string	The store's name.
store_partners_external_identifier	string	The store's unique identifier on your system.

Recipient & Address

Key	Type	Value
order_recipient_full_name	string	The recipient's full name
order_recipient_email	string	The recipient's email address
order_recipient_phone_number	string	The recipient's phone number
order_recipient_first_line_address	string	The first line of the receipient's address
order_recipient_zipcode	string	The recipient's zip code / postcode
order_recipient_city	string	The recipient's city
order_recipient_latitude	string	The recipient's latitude
order_recipient_longitude	string	The recipient's longitude

Financial Data

Key	Type	Value
order_grand_total_including_tax	decimal	The grand total of the order, as passed in by you at the point of the order being created.
order_total_tip_left_for_driver	decimal	The total tip

Driver Data

Key	Type	Value
assigned_driver_uuid	string	The driver's unique driver ID on the Captain.AI system, unique per store.
assigned_driver_user_uuid	string	The driver's unique user ID on the Captain.AI system. If you have the same driver working in multiple stores, you can use this field as a unique identifier.
assigned_driver_first_name	string	The driver's first name
assigned_driver_last_name	string	The driver's last name
assigned_driver_phone_number	string	The driver's phone number
assigned_driver_profile_picture_url	string	The driver's profile picture URL
odometer_at_collection	string	The driver's phone's odometer reading at the point of this order being picked up.
odometer_at_delivery	string	The driver's phone's odometer reading at the point of this order being delivered.
odometer_upon_return_to_base	string	The driver's phone's odometer reading at the point of the driver returning to the store for the first time after this delivery was completed.