Pinkbot Delivery API
Last updated

Pinkbot logo

Pinkbot Delivery API

Getting Started

This documentation describes how to integrate with Pinkbot's production delivery API, covering authentication, endpoints, and operational best practices.

🧑‍💻 API

Our platform exposes RESTful endpoints secured with bearer tokens so you can create, manage, and monitor Pinkbot deliveries directly from your systems.

📲 Customer UX

To provide the end customer (eater) with the necessary UX to unlock the robot and receive their food, Pinkbot will provide their standard SMS/Tracking interface.

đź”’ Robot lid access

Refer to the POST /drive/v2/deliveries/{external_delivery_id}/open-lid operation in the OpenAPI reference for unlock flow details.

Base API Endpoint

Use the following endpoint when creating deliveries:

https://api.pink.bot/v2/deliveries

2. Authentication

For authentication please request a security token from your Pinkbot contact, it will be provided over email.

Every HTTP request must contain Authorization header with the provided security token:

Authorization: 'Bearer ' + token

Notice that you don’t need to generate a JWT token, instead use the provided security token as is.

3. Create Delivery openapi

Use this API to create a new delivery.

Use this endpoint to create a delivery request for Pinkbot to fulfill.

The subset of request fields supported (fields outside of this list will be ignored):

  • external_delivery_id (required)
  • pickup_address (required)
  • dropoff_address (required)
  • dropoff_location
  • dropoff_phone_number (required)
  • dropoff_instructions
  • dropoff_contact_given_name (required)
  • dropoff_contact_family_name
  • pickup_time (if omitted, we assume pickup_time = now + merchant prep time)
  • dropoff_time
  • order_value
  • tip

The successful response (HTTP 200) will contain the following fields:

  • external_delivery_id
  • currency (always “USD”)
  • delivery_status (always “created”)
  • fee
  • tracking_url
  • dasher_vehicle_make (always “Pinkbot”)
  • dasher_vehicle_model (always “Geoffrey”)
  • dasher_vehicle_year (always current year)

If Pinkbot cannot accept the delivery, we return HTTP 422 with a JSON payload describing the reason.

{

    "code": "invalid_delivery_parameters",
    "message": "Requested delivery is not valid",
    "reason": "distance_too_long"

}

See API usage example here.

4. Receive Delivery Status Updates Using Webhook

To receive delivery status updates, you must register a webhook where Pinkbot will submit updates. Simply send your webhook URL to your Pinkbot contact.

Pinkbot sends webhooks for the following events, as soon as the event takes place:

  • DASHER_CONFIRMED: Pinkbot has accepted your delivery and is on the way to the pickup location.
  • DASHER_CONFIRMED_PICKUP_ARRIVAL: Pinkbot has confirmed that they arrived at the pickup location and are attempting to pick up the delivery.
  • DASHER_PICKED_UP: Pinkbot has picked up the delivery.
  • DASHER_CONFIRMED_DROPOFF_ARRIVAL: Pinkbot has confirmed that they arrived at the dropoff location.
  • DASHER_DROPPED_OFF: Pinkbot has dropped off the delivery at the dropoff location and the delivery is complete.

Supported subset of JSON payload fields:

  • external_delivery_id
  • pickup_address
  • dropoff_address
  • dropoff_location
  • dropoff_phone_number
  • dropoff_instructions
  • dropoff_contact_given_name
  • dropoff_contact_family_name
  • tip
  • fee
  • currency (always “USD”)
  • tracking_url
  • dropoff_verification_image_url
  • dasher_vehicle_make (always “Pinkbot”)
  • dasher_vehicle_model (always “Geoffrey”)
  • dasher_vehicle_year (always current year)
  • dasher_name
  • dasher_id
  • event_name (one from the list above)
  • pickup_time_actual
  • dropoff_time_actual
  • updated_at
  • support_reference

Pinkbot will make 3 retries if webhook call is not successful (HTTP status other than 200 OK).

5. Get Delivery openapi

Use this API to get current delivery status.

Use this endpoint to retrieve the latest status and details for a delivery.

Retruns JSON object with the same subset of fields that are supported by the Webhook.

6. Update Delivery openapi

Use this API to update the delivery information.

Use this endpoint to update mutable delivery fields such as dropoff instructions or contact details.

It is impossible to update the delivery after it was picked up by a courier (HTTP 409 will be returned).

Accepts JSON object with the same subset of fields that are supported by Create Delivery method.

Retruns JSON object with the same subset of fields that are supported by the Webhook.

7. Cancel Delivery openapi

Use this API to cancel the delivery.

Use this endpoint to cancel a delivery when permissible (for example, before pickup).

It is impossible to cancel the delivery after it was picked up by a courier (HTTP 409 will be returned).

Retruns JSON object with the same subset of fields that are supported by the Webhook.

 
Next page