Zippykind API Documentation

Our API

Welcome to Zippykind's API documentation. Browse through our API documentation to see examples and explanations of our API. The Zippykind API is a RESTful web service for developers to programmatically interact with Zippykind's data.

Every POST or GET request to the Zippykind API is handled over HTTPS and is secure. We recommend using Postman for testing your API calls. Please direct any questions or concerns about the Zippykind API to our contact page.

The base URL for the Zippykind API is https://zippykind.com/api/v2.

Getting an API key

In order to get an API key, you must sign up for an account by going to https://zippykind.com. Once you have created an account, you will need to click on the API Connect menu item and then the Keys sub-menu, where you can generate an API key. API access requires a paid account. If your account is not on a paid plan, email contact@zippykind.com for approval. You will be asked to re-enter your account password to generate the key. The API key you create will allow you to make API calls to our API and will authenticate you as a user. Please keep your API key private. In order to make our API more secure, we only show you your API key once. If you lost your API key, you can generate a new one which will replace your old key.

Your API key should look similar to this 2wUizN2ghJYGQddGkMx2cx0LhorGWCq8Hupe5b0D, we will use this API key throughout the Zippykind API documentation as an example.

Authentication

You can test the authorization of your API call by using the endpoint

GET

https://zippykind.com/api/test/

Quickstart

You can use our quickstart example code to quickly test our API. If your API request was successful, you should see an example similar to the example response we provided.

curl -X GET \
  https://zippykind.com/api/test/ \
  -H 'apikey: 2wUizN2ghJYGQddGkMx2cx0LhorGWCq8Hupe5b0D'

Example response

{
  "code": 200,
  "msg": "Success: API key is valid.",
  "status": "The property you are requesting has been found.",
  "details": ""
}

Create A Customer

Creates a new customer account that delivery tickets can be assigned to. When you create a new delivery ticket a new customer account is created so that customer account delivery history can be viewed later. You can create a customer account without creating a delivery ticket. So lets say you create a customer's account during the first step of your website checkout process, if the customer abandons the cart, you will still have the customer's contact information. You can then finish the delivery request through our dispatch software without needing to ask the customer for their basic information like name, email, phone etc. If an account already exists for this customer (matched on your account's customer lookup key, which is the email address by default), no new account is created and the response returns an empty details value with HTTP 200. Creating a customer is not subject to a credit check. Only Create A Delivery checks your account credit and can return HTTP 402.

Property	Description
`scope`	(required) Must be `newCustomer`
`customer_name`	(required) The customer's name
`ext_customer_number`	(optional) Link the customer's account to a different platform
`contact_number`	(optional) Phone number of customer, stored as the account's `phone`
`email_address`	(required) Email address of customer, stored as the account's `email`. Zippykind uses this as the duplicate detection key by default, so a request without it creates a new account on every call
`delivery_address`	(optional) Address of the customer, stored as the account's `address`. Zippykind geocodes it into `account_lat` / `account_lng`
`date_created`	(optional) Date the account was created in `YYYY-MM-DD HH:MM:SS` format, it will default to today's date
`rewards_level`	(optional) The Zippykind rewards level (Bronze, Silver or Gold). The value is stored as sent but is recalculated by Zippykind from the customer's 30 day spend, which overwrites whatever you send
`spent_this_month`	(optional) Total amount of money the customer has spent in the last 30 days

This endpoint accepts multipart/form-data or application/x-www-form-urlencoded only; a JSON request body is ignored.

scope=newCustomer
customer_name=John Doe
ext_customer_number=A-10045
contact_number=480-123-4567
email_address=johndoe@gmail.com
delivery_address=12345 broadway st. Phoenix, AZ 85251
date_created=2017-05-02 14:15:51

POST

https://zippykind.com/api/v2/

Example request

curl -X POST \
  https://zippykind.com/api/v2/ \
  -H 'apikey: 2wUizN2ghJYGQddGkMx2cx0LhorGWCq8Hupe5b0D' \
  -F scope=newCustomer \
  -F 'customer_name=John Doe' \
  -F contact_number=480-123-4567 \
  -F email_address=johndoe@gmail.com \
  -F 'delivery_address=12345 broadway st. Phoenix, AZ 85251' \
  -F ext_customer_number=A-10045

Example request fields

Example response

{
  "code": 200,
  "msg": "Success: API key is valid.",
  "status": "The property you are requesting has been found.",
  "details": {
    "account_id": "48213",
    "customer_name": "John Doe",
    "ext_customer_number": "A-10045",
    "phone": "4801234567",
    "email": "johndoe@gmail.com",
    "account_lat": "33.4483771",
    "account_lng": "-112.0740373",
    "address": "12345 broadway st. Phoenix, AZ 85251",
    "date_created": "2017-05-02 14:15:51",
    "rewards_level": "",
    "spent_this_month": ""
  }
}

Create A Delivery

Fields marked (required) are the ones a usable delivery needs. V2 does not reject a request that omits them: only scope is validated, so a request missing them is accepted and creates an incomplete ticket. Validate before you send.

Deliveries in Zippykind are referred to as tickets. Create a delivery ticket that can be automatically pushed to one of your delivery drivers. If a driver is not specified, the ticket will be marked as unassigned and will follow the settings in your account. If your Zippykind account settings are set to automatically assign the ticket to a driver, our system will attempt to assign the ticket. Once a delivery ticket has been created, it can be canceled by sending a cancelTicket request.

Property	Type	Description
`scope`	String	(required) Dictates the type of request
`order_source`	String	(optional) Source of the request
`trans_type`	String	(required) Options are delivery or pickup
`status`	String	(optional) Starting status. If you send one it overrides the status Zippykind would otherwise derive from `driver_id`
`ticket_description`	String	(optional) Notes for the driver
`team_id`	Number	(optional) ID of the team the driver is assigned to
`driver_id`	Number	(optional) ID of the driver the ticket is assigned to
`contact_number`	String	(optional) Phone number of the customer
`email_address`	String	(optional) Email address of the customer
`customer_name`	String	(required) The customer's name
`delivery_address`	String	(required) The destination address of either the pickup or delivery
`delivery_address_unit`	String	(optional, max 10 characters) Apartment/suite/unit number for the delivery address, stored in its own column and never appended into `delivery_address`
`ticket_lat`	String	(optional) The latitude of the delivery destination
`ticket_lng`	String	(optional) The longitude of the delivery destination
`product_pickup_name`	String	(optional) The name of the location where the product is being picked up
`product_pickup_contact_number`	String	(optional) Phone number of the location where the product is being picked up
`product_pickup_address`	String	(optional) Address to where the product will be picked up
`product_pickup_address_unit`	String	(optional, max 10 characters) Apartment/suite/unit number for the product pickup address, stored in its own column and never appended into `product_pickup_address`
`product_pickup_location_id`	Number	(optional) ID of the Zippykind location the product is picked up from. Also stored on each order item
`product_pickup_lat`	String	(optional) The latitude of the product pickup location
`product_pickup_lng`	String	(optional) The longitude of the product pickup location
`delivery_date_start`	String	(optional) Start of the delivery window. Any format PHP's strtotime() accepts; stored as `Y-m-d H:i`
`delivery_date`	String	(optional) Date and time of the delivery. Any format PHP's strtotime() accepts (e.g. `03/15/2017` or `2017-03-15 14:30`); stored as `Y-m-d H:i`
`total_tax`	Number	(optional) The total tax
`promo_code`	String	(optional) The promo code applied to the order
`tax_percent`	Number	(optional) The percent of the total amount that should be taxed
`total`	Number	(optional) Total amount owed
`leave_it`	Number	(optional, 0 or 1) Value 1 indicates driver should leave package at destination
`delivery_fee`	Number	(optional) The delivery fee
`processing_fee`	Number	(optional) The processing fee stored on the order
`ext_order_id`	String	(optional) Reference an order ID from a different platform
`ext_customer_number`	String	(optional) Reference a customer ID from a different platform
`ext_invoice_number`	String	(optional) Reference an invoice ID from a different platform
`ext_product_id`	String	(optional) Reference the product to an external platform prodoct's ID
`order_items`	Array	(optional) JSON encoded array of items included with the order. Only saved when an order record is created, which requires at least one of `order_source`, `ext_order_id`, `ext_customer_number`, `promo_code`, `total`, `delivery_fee` or `processing_fee` to also be sent
`product_name`	String	(optional) Name of the product
`product_id`	String	(optional) Product ID of the order item managed with Zippykind. When it matches a Zippykind catalogue product, the catalogue's name and price take priority over the `product_name` and `sub_total` sent in the request
`quantity`	String	(optional) Quantity of the order item
`sub_total`	String	(optional) Sub total of the order item. Ignored when a matching `product_id` is supplied, the Zippykind catalogue price is used instead
`tax`	String	(optional) Tax of the order item
`weight`	String	(optional) Weight of the order item

The v2 endpoint does not accept a JSON request body. Send every parameter as a POST form field (multipart/form-data or application/x-www-form-urlencoded), as in the examples above. The object below is the ticket Zippykind creates and returns in the response details object, it is not a payload you send.

POST

https://zippykind.com/api/v2/

Example request

curl -X POST \
  https://zippykind.com/api/v2/ \
  -H 'apikey: 2wUizN2ghJYGQddGkMx2cx0LhorGWCq8Hupe5b0D' \
  -F scope=newTicket \
  -F order_source=ecommerce_website \
  -F trans_type=delivery \
  -F 'ticket_description=The gate code is 8228.  There is a big dog in the yard, be careful.' \
  -F team_id=1025 \
  -F driver_id=63526 \
  -F contact_number=480-123-4567 \
  -F email_address=johndoe@gmail.com \
  -F 'customer_name=John Doe' \
  -F 'delivery_address=12345 broadway st. Phoenix, AZ 85251' \
  -F delivery_date=03/15/2017 \
  -F total_tax=3.81 \
  -F tax_percent=8.5 \
  -F total=48.97 \
  -F delivery_fee=20 \
  -F 'order_items=[{ "ext_product_id" : "4567", "product_name" : "Donzen Red Roses", "product_id" : "8566", "quantity" : "1", "sub_total" : "29.99", "tax" : "2.54", "weight" : "1 pound"},{"ext_product_id" : "4568", "product_name" : "Kettle Korn", "product_id" : "8567", "quantity" : "3", "sub_total" : "14.99", "tax" : "1.27", "weight" : "3 pounds"}]'

Example created ticket

{
    "ticket_details": {
      "ticket_id": "101441",
      "ext_order_id": "12345",
      "ext_customer_number": "9876",
      "ext_invoice_number": "INV5263",
      "account_id": "100328",
      "customer_id": "36",
      "ticket_description": "The gate code is 8228.  There is a big dog in the yard, be careful.",
      "trans_type": "delivery",
      "contact_number": "480-123-4567",
      "email_address": "johndoe@gmail.com",
      "customer_name": "John Doe",
      "delivery_date_start": "03/15/2017",
      "delivery_date": "03/15/2017",
      "delivery_address": "12345 broadway st. Phoenix, AZ 85251",
      "delivery_address_unit": "Apt 4B",
      "team_id": "1025",
      "driver_id": "63526",
      "ticket_lat": "33.4084199",
      "ticket_lng": "-112.2041058",
      "status": "assigned",
      "date_created": "2017-05-02T23:44:25-05:00",
      "ip_address": "111.22.333.44",
      "product_pickup_location_id": "482",
      "product_pickup_name": "2nd Store Location",
      "product_pickup_contact_number": "480-555-6688",
      "product_pickup_address": "653 Shea blvd Scottsdale, AZ 85265",
      "product_pickup_address_unit": "Suite 200",
      "product_pickup_lat": "33.4084199",
      "product_pickup_lng": "-112.2041058",
      "order_id": "3090",
      "promo_code": "NEWYRS17",
      "total": "48.97",
      "ticket_token": "9f3c1a7e42b8",
      "leave_it": "1"
    },
    "order_details": {
      "order_id": "3090",
      "order_source": "ecommerce_website",
      "ext_order_id": "12345",
      "ext_customer_number": "9876",
      "account_id": "100328",
      "tax": "3.81",
      "promo_code": "NEWYRS17",
      "tax_percent": "8.5",
      "delivery_fee": "20",
      "total": "48.97"
    },
    "order_items": [{ "order_id" : "3090", "account_id" : "100328", "ext_product_id" : "4567", "product_name" : "Donzen Red Roses", "product_id" : "8566", "quantity" : "1", "sub_total" : "29.99", "tax" : "2.54", "weight" : "1 pound"},{"order_id" : "3090", "account_id" : "100328", "ext_product_id" : "4568", "product_name" : "Kettle Korn", "product_id" : "8567", "quantity" : "3", "sub_total" : "14.99", "tax" : "1.27", "weight" : "3 pounds"}]
}

Example response

{
  "code": 200,
  "msg": "Success: API key is valid.",
  "status": "The property you are requesting has been found.",
  "details": {
      "ticket_details": {
        "ticket_id": "101441",
        "ext_order_id": "12345",
        "ext_customer_number": "9876",
        "ext_invoice_number": "INV5263",
        "account_id": "100328",
        "customer_id": "36",
        "ticket_description": "The gate code is 8228.  There is a big dog in the yard, be careful.",
        "trans_type": "delivery",
        "contact_number": "480-123-4567",
        "email_address": "johndoe@gmail.com",
        "customer_name": "John Doe",
        "delivery_date_start": "03/15/2017",
        "delivery_date": "03/15/2017",
        "delivery_address": "12345 broadway st. Phoenix, AZ 85251",
        "delivery_address_unit": "Apt 4B",
        "team_id": "1025",
        "driver_id": "63526",
        "ticket_lat": "33.4084199",
        "ticket_lng": "-112.2041058",
        "status": "assigned",
        "date_created": "2017-05-02T23:44:25-05:00",
        "ip_address": "111.22.333.44",
        "product_pickup_location_id": "482",
        "product_pickup_name": "2nd Store Location",
        "product_pickup_contact_number": "480-555-6688",
        "product_pickup_address": "653 Shea blvd Scottsdale, AZ 85265",
        "product_pickup_address_unit": "Suite 200",
        "product_pickup_lat": "33.4084199",
        "product_pickup_lng": "-112.2041058",
        "order_id": "3090",
        "promo_code": "NEWYRS17",
        "total": "48.97",
        "ticket_token": "9f3c1a7e42b8",
        "leave_it": "1"
      },
      "order_details": {
        "order_id": "3090",
        "order_source": "ecommerce_website",
        "ext_order_id": "12345",
        "ext_customer_number": "9876",
        "account_id": "100328",
        "tax": "3.81",
        "promo_code": "NEWYRS17",
        "tax_percent": "8.5",
        "delivery_fee": "20",
        "total": "48.97"
      },
      "order_items": [{ "order_id" : "3090", "account_id" : "100328", "ext_product_id" : "4567", "product_name" : "Donzen Red Roses", "product_id" : "8566", "quantity" : "1", "sub_total" : "29.99", "tax" : "2.54", "weight" : "1 pound"},{"order_id" : "3090", "account_id" : "100328", "ext_product_id" : "4568", "product_name" : "Kettle Korn", "product_id" : "8567", "quantity" : "3", "sub_total" : "14.99", "tax" : "1.27", "weight" : "3 pounds"}]
  }
}

Update A Delivery

Update a delivery using the ticket_id and scope updateTicket parameters. Updates will happen in real time and will notify the driver assigned to the ticket of the change.

An omitted ticket_id returns HTTP 400 with the status MissingParameters naming ticket_id. A ticket_id that belongs to another account returns HTTP 403 Unauthorized.

Property	Type	Description
`ticket_id`	Number	(required) ID of the ticket that you want to update
`scope`	String	(required) Dictates the type of request
`status`	String	(optional) Dictates the status of the delivery (accepted, started, arrived etc). Ignored when `driver_id` is also sent: a `driver_id` greater than 0 forces the status to `assigned`
`trans_type`	String	(optional) Options are delivery or pickup
`ticket_description`	String	(optional) Notes for the driver
`team_id`	Number	(optional) ID of the team the driver is assigned to
`driver_id`	Number	(optional) ID of the driver the ticket is assigned to
`contact_number`	String	(optional) Phone number of the customer
`email_address`	String	(optional) Email address of the customer
`customer_name`	String	(optional) The customer's name
`delivery_address`	String	(optional) The destination address of either the pickup or delivery. Addresses are not re-geocoded on update, send `ticket_lat` and `ticket_lng` as well, otherwise the ticket keeps its previous coordinates
`delivery_address_unit`	String	(optional, max 10 characters) Apartment/suite/unit number for the delivery address, stored in its own column and never appended into `delivery_address`
`ticket_lat`	String	(optional) The latitude of the delivery destination. Required alongside `delivery_address` if you want the map/route to move
`ticket_lng`	String	(optional) The longitude of the delivery destination
`product_pickup_name`	String	(optional) The name of the location where the product is being picked up
`product_pickup_contact_number`	String	(optional) Phone number of the location where the product is being picked up
`product_pickup_address`	String	(optional) Address to where the product will be picked up
`product_pickup_address_unit`	String	(optional, max 10 characters) Apartment/suite/unit number for the product pickup address, stored in its own column and never appended into `product_pickup_address`
`product_pickup_lat`	String	(optional) The latitude of the product pickup location
`product_pickup_lng`	String	(optional) The longitude of the product pickup location
`delivery_date_start`	String("YYYY-MM-DD HH:MM:SS")	(optional) Start of the delivery time window
`delivery_date`	String("YYYY-MM-DD HH:MM:SS")	(optional) Date and time of the delivery
`leave_it`	Number	(optional, 0 or 1) Value 1 indicates driver should leave package at destination
`ext_order_id`	String	(optional) Reference an order ID from a different platform
`ext_customer_number`	String	(optional) Reference a customer ID from a different platform
`ext_invoice_number`	String	(optional) Reference an invoice ID from a different platform

POST

https://zippykind.com/api/v2/

Example request

curl -X POST \
  https://zippykind.com/api/v2 \
  -H 'apikey: 2wUizN2ghJYGQddGkMx2cx0LhorGWCq8Hupe5b0D' \
  -F scope=updateTicket \
  -F status=arrived \
  -F ticket_id=107632 \
  -F ext_order_id=222222 \
  -F ext_invoice_number=333333 \
  -F ext_customer_number=444444 \
  -F 'ticket_description=The gate code is 2929.' \
  -F trans_type=delivery \
  -F contact_number=14804777931 \
  -F email_address=john@zippykind.com \
  -F 'customer_name=John Doe' \
  -F 'delivery_date=2017-08-11 00:00:02' \
  -F 'delivery_address=1200 Broadway st. Scottsdale AZ 85251' \
  -F team_id=6001 \
  -F driver_id=6002 \
  -F ticket_lat=33.1111 \
  -F ticket_lng=-112.0000 \
  -F 'product_pickup_name=2nd Store' \
  -F product_pickup_contact_number=14805556666 \
  -F 'product_pickup_address=1300 Broadway st. SCottsdale AZ 85251' \
  -F product_pickup_lat=32.22222 \
  -F product_pickup_lng=-111.0555 \
  -F leave_it=1

Example request body (field names and values only, send them as form fields, e.g. multipart/form-data or application/x-www-form-urlencoded; a raw JSON body is not parsed)

{
    "scope": "updateTicket",
    "ticket_id": "101441",
    "ext_order_id": "12345",
    "ext_customer_number": "9876",
    "ext_invoice_number": "INV5263",
    "ticket_description": "The gate code is 2929.",
    "trans_type": "delivery",
    "contact_number": "14801234567",
    "email_address": "johndoe@gmail.com",
    "customer_name": "John Doe",
    "delivery_date": "2017-08-11 00:00:02",
    "delivery_address": "12345 broadway st. Phoenix, AZ 85251",
    "delivery_address_unit": "Apt 4B",
    "team_id": "1025",
    "driver_id": "63526",
    "ticket_lat": "33.4084199",
    "ticket_lng": "-112.2041058",
    "product_pickup_name": "2nd Store Location",
    "product_pickup_contact_number": "14805556688",
    "product_pickup_address": "653 Shea blvd Scottsdale, AZ 85265",
    "product_pickup_address_unit": "Suite 200",
    "product_pickup_lat": "33.4084199",
    "product_pickup_lng": "-112.2041058",
    "leave_it": "1"
}

Example response

{
    "code": 200,
    "msg": "Success: API key is valid.",
    "status": "The property you are requesting has been found.",
    "details": {
        "ext_order_id": "12345",
        "ext_invoice_number": "INV5263",
        "ext_customer_number": "9876",
        "ticket_description": "The gate code is 2929.",
        "trans_type": "delivery",
        "phone_number": "14801234567",
        "email_address": "johndoe@gmail.com",
        "customer_name": "John Doe",
        "delivery_date": "2017-08-11 00:00:02",
        "delivery_address": "12345 broadway st. Phoenix, AZ 85251",
        "delivery_address_unit": "Apt 4B",
        "team_id": "1025",
        "driver_id": "63526",
        "ticket_lat": "33.4084199",
        "ticket_lng": "-112.2041058",
        "pickup_name": "2nd Store Location",
        "pickup_phone_number": "14805556688",
        "pickup_address": "653 Shea blvd Scottsdale, AZ 85265",
        "pickup_address_unit": "Suite 200",
        "pickup_lat": "33.4084199",
        "pickup_lng": "-112.2041058",
        "leave_it": "1",
        "status": "assigned"
    }
}

Track A Delivery

When the delivery has no order items, order_items is returned as null rather than an empty array. Check for null before looping.

Pass any delivery ID to this endpoint to get the details of the delivery. For the example request we will use ticket ID 101417. We will use demo data in the request response. The most common reason for tracking a single delivery is to determine the status. The status property options are: unassigned, assigned, accepted, declined, started, arrived, failed, successful, cancelled.

When a ticket is assigned to a driver, the driver can deny or accept the ticket. If the ticket is denied, the ticket status will change to declined; if the "declined to unassigned" setting is enabled on your account, the status changes to unassigned instead so Zippykind can keep trying to assign it.

If a ticket is created and is not assigned, the status will be considered unassigned and will follow the settings in your account. If the ticket is assigned, the ticket has been assigned to a team and a driver, you can't assign a ticket to a driver without first assigning it to a team. If the ticket status is accepted, the driver has accepted the ticket but has not yet started the delivery. If the ticket status is started, the driver has begun the delivery run but has not yet arrived. If the ticket status is failed, the driver arrived to the destination but was unable to deliver the package. If the ticket status has a status of arrived, the driver has arrived to the delivery destination and usually means the driver is in the process of getting a signature, taking a photo or handing off the delivery package. If the ticket status is successful, the driver has completed all steps in the delivery process and has successfully delivered the package.

Property	Type	Description
`scope`	String	(required) Dictates the type of request
`ticket_id`	String	(required) The ID of the ticket you want to request data for. If the ticket ID does not exist on your account, the endpoint still returns a 200 response; `details.ticket_details` comes back with the ticket_id you sent and every other property empty

Note: this scope is not available while API testing mode (enable_api_testing) is turned on for your account, the response returns a 200 with an empty details value.

POST

https://zippykind.com/api/v2/

Example request

curl -X POST \
  https://zippykind.com/api/v2/ \
  -H 'apikey: 2wUizN2ghJYGQddGkMx2cx0LhorGWCq8Hupe5b0D' \
  -F scope=trackTicket \
  -F ticket_id=101417

Example response

{
  "code": 200,
  "msg": "Success: API key is valid.",
  "status": "The property you are requesting has been found.",
  "details": {
    "ticket_details": {
      "ticket_id": "101417",
      "ext_order_id": "12345",
      "ext_customer_number": "6958",
      "ext_invoice_number": "5263",
      "account_id": "100292",
      "ticket_description": "Gate code is 9292.",
      "trans_type": "delivery",
      "phone_number": "+14804777931",
      "email_address": "johndoe@gmail.com",
      "customer_name": "John Doe",
      "delivery_date_start": "2017-05-02 15:00:00",
      "delivery_date": "2017-05-02 16:00:00",
      "delivery_address": "658 West Camelback Road, Phoenix, AZ, United States",
      "delivery_address_unit": "Apt 4B",
      "team_id": "1052",
      "driver_id": "17653",
      "ticket_lat": "33.509636",
      "ticket_lng": "-112.081177",
      "status": "assigned",
      "date_created": "2017-05-02 14:12:54",
      "ip_address": "11.111.11.111",
      "product_pickup_name": "2nd Store",
      "product_pickup_contact_number": "+14804777931",
      "product_pickup_address": "9301 East Shea Boulevard, Scottsdale, AZ, United States",
      "product_pickup_address_unit": "Suite 200",
      "product_pickup_lat": "33.5809114",
      "product_pickup_lng": "-111.8811427",
      "leave_it": "1"
    },
    "order_details": {
      "order_id": "285",
      "order_source": "zippykind_dispatch",
      "ext_order_id": "",
      "ext_customer_number": "",
      "account_id": "100292",
      "tax": "5.52",
      "promo_code": "PROMO",
      "tax_percent": "8.5",
      "delivery_fee": "20.00",
      "total": "90.50"
    },
    "order_items": [
      {
        "order_item_id": "342",
        "ext_product_id": "",
        "order_id": "285",
        "account_id": "100292",
        "product_id": "36",
        "quantity": "1",
        "weight": "2 pounds",
        "product_name": "Kettle Korn",
        "tax": "0.00",
        "sub_total": "5.00",
        "date_created": "2017-05-02 16:12:54"
      },
      {
        "order_item_id": "343",
        "ext_product_id": "",
        "order_id": "285",
        "account_id": "100292",
        "product_id": "35",
        "quantity": "2",
        "weight": "1 pound",
        "product_name": "Roses",
        "tax": "0.00",
        "sub_total": "29.99",
        "date_created": "2017-05-02 16:12:54"
      }
    ]
  }
}

View Delivery History

When there is no history for the ticket, ticket_history is returned as null rather than an empty array. Check for null before looping.

Pass any delivery ID to this endpoint to get the history details of the delivery. For the example request we will use ticket ID 101148. We will use demo data in the request response. Most of the actions fetched from the delivery history are usually submitted by the driver and are referred to in this documentation as milestons; however, dispatch operators do have the ability to update the delivery history. Note: this scope is not available while API testing mode (enable_api_testing) is turned on for your account, the response will omit the ticket_history array.

Property	Type	Description
`scope`	String	(required) Dictates the type of request
`ticket_id`	String	(required) The ID of the ticket you are requesting data for
`status`	String	(response) The type of action submitted by the delivery driver
`remarks`	String	(response) The action described and formatted by Zippykind
`driver_id`	String	(response) The ID of the driver assigned to the delivery
`account_id`	String	(response) The account ID of the customer the delivery is assigned to
`driver_location_lat`	String	(response) The latitude of the driver's location when the mileston was submitted
`driver_location_lng`	String	(response) The longitude of the driver's location when the mileston was submitted
`date_created`	String("YYYY-MM-DD HH:MM:SS")	(response) The date and time the milestone was submitted
`ip_address`	String	(response) The IP address the milestone was submitted from
`notes`	String	(response) The notes submitted by the driver
`received_by`	String	(response) The person who signed for the package
`customer_signature`	String	(response, only present on `sign` entries) The URL of the signature image of the delivery recipient
`photo_url`	String	(response, only present on `photo` entries) The URL of the a photo that has been submitted with the delivery ticket

POST

https://zippykind.com/api/v2/

Example request

curl -X POST \
  https://zippykind.com/api/v2/ \
  -H 'apikey: 2wUizN2ghJYGQddGkMx2cx0LhorGWCq8Hupe5b0D' \
  -F scope=ticketHistory \
  -F ticket_id=101148

Example response

{
  "code": 200,
  "msg": "Success: API key is valid.",
  "status": "The property you are requesting has been found.",
  "details": {
    "ticket_history": [
      {
        "status": "accepted",
        "remarks": "John Jones accepted the ticket",
        "driver_id": "15635",
        "account_id": "2365",
        "driver_location_lat": "32.4836882",
        "driver_location_lng": "-116.9206706",
        "date_created": "2017-04-24 21:34:12",
        "ip_address": "11.111.1.11",
        "notes": "",
        "received_by": ""
      },
      {
        "status": "started",
        "remarks": "John Jones started the ticket",
        "driver_id": "15635",
        "account_id": "2365",
        "driver_location_lat": "32.8545863",
        "driver_location_lng": "-116.2456",
        "date_created": "2017-04-24 21:34:20",
        "ip_address": "11.111.1.11",
        "notes": "",
        "received_by": ""
      },
      {
        "status": "arrived",
        "remarks": "John Jones reached the destination",
        "driver_id": "15635",
        "account_id": "2365",
        "driver_location_lat": "32.4579993",
        "driver_location_lng": "-116.2365",
        "date_created": "2017-04-24 21:34:42",
        "ip_address": "11.111.1.11",
        "notes": "",
        "received_by": ""
      },
      {
        "status": "sign",
        "remarks": "John Jones added a signature",
        "driver_id": "15635",
        "account_id": "2365",
        "driver_location_lat": "32.7456",
        "driver_location_lng": "-116.126",
        "date_created": "2017-04-24 21:35:03",
        "ip_address": "11.111.1.11",
        "notes": "",
        "received_by": "Charles Jennings",
        "customer_signature": "https://zippykind.com/upload/signature_101148-17080643690.png"
      },
      {
        "status": "notes",
        "remarks": "John Jones added a note",
        "driver_id": "15635",
        "account_id": "2365",
        "driver_location_lat": "32.9856",
        "driver_location_lng": "-116.563215",
        "date_created": "2017-04-24 21:35:20",
        "ip_address": "11.111.1.11",
        "notes": "Left package at door",
        "received_by": ""
      },
      {
        "status": "photo",
        "remarks": "John Jones added a photo",
        "driver_id": "15635",
        "account_id": "2365",
        "driver_location_lat": "32.0126",
        "driver_location_lng": "-116.7456",
        "date_created": "2017-04-24 21:35:37",
        "ip_address": "11.111.1.11",
        "notes": "",
        "received_by": "",
        "photo_url": "https://zippykind.com/upload/photo/1493094937198833.jpg"
      },
      {
        "status": "successful",
        "remarks": "John Jones completed the ticket successfully",
        "driver_id": "15635",
        "account_id": "2365",
        "driver_location_lat": "33.4859",
        "driver_location_lng": "-111.2635",
        "date_created": "2017-04-24 21:35:45",
        "ip_address": "11.111.1.11",
        "notes": "",
        "received_by": ""
      }
    ]
  }
}

Get Driver Details

Pass the ID of one of your drivers to this endpoint to get that driver's full details including current latitude and longitude position. Only drivers belonging to the account that owns the API key can be requested; an unknown or foreign driver_id returns HTTP 403 with the status DriverNotOnAccount and the message "The driver_id you supplied is not on your account."

scope and driver_id are the request parameters. Every property marked (response) below is returned by Zippykind and has no effect if you send it in the request.

Property	Type	Description
`scope`	String	(required) Dictates the type of request
`driver_id`	String	(required) The ID of the driver
`team_id`	String	(response) The ID of the team the driver is assigned to
`on_duty`	String	(response, 1 or 2) Value 1 indicates the driver is on duty, value 2 indicates the driver is off duty
`first_name`	String	(response) First name of the driver
`last_name`	String	(response) Last name of the driver
`email`	String	(response) Email of the driver
`phone`	String	(response) Phone number of the driver
`username`	String	(response) Username of the driver
`transport_type`	String	(response) Transportation type of the driver
`transport_description`	String	(response) Description of the driver's transportation
`license_plate`	String	(response) License plate of the driver
`driver_color`	Hex Code	(response) The color associated with the driver's dashboard markers
`color`	String	(response) Color of the driver's transportation vehicle
`status`	String	(response) Options are pending, active, blocked, suspended
`date_created`	String("YYYY-MM-DD HH:MM:SS")	(response) Date the driver's account was created
`last_login`	String("YYYY-MM-DD HH:MM:SS")	(response) Date the driver last logged into the Zippykind app. Returns 0000-00-00 00:00:00 if the driver has never logged in
`location_lat`	String	(response) The latitude of the driver's current location
`location_lng`	String	(response) The longitude of the driver's current location
`ip_address`	String	(response) The IP address of the driver's device
`device_id`	String	(response) The push notification device token of the driver's device
`device_platform`	String	(response) Options are IOS and Android
`app_version`	String	(response) The version of the app the driver is using

Note: driverDetails does not currently return a value for transport_type. Use List Drivers, which returns the driver's transport type correctly.

POST

https://zippykind.com/api/v2/

Example request

curl -X POST \
  https://zippykind.com/api/v2/ \
  -H 'apikey: 2wUizN2ghJYGQddGkMx2cx0LhorGWCq8Hupe5b0D' \
  -F scope=driverDetails \
  -F driver_id=18256

Example request body

{
  "scope": "driverDetails",
  "driver_id": "18256"
}

Example response

{
  "code": 200,
  "msg": "Success: API key is valid.",
  "status": "The property you are requesting has been found.",
  "details": {
    "driver_details": {
      "driver_id": "18256",
      "team_id": "8635",
      "on_duty": "1",
      "first_name": "John",
      "last_name": "Doe",
      "email": "johndoe@gmail.com",
      "phone": "+14804777931",
      "username": "johndoe",
      "transport_type": null,
      "transport_description": "Ford F-150",
      "license_plate": "TAD-582",
      "driver_color": "FF2B75",
      "color": "White",
      "status": "active",
      "date_created": "2017-04-29 18:11:01",
      "last_login": "2017-05-3 14:10:23",
      "location_lat": "33.856982",
      "location_lng": "-112.674596",
      "ip_address": "11.111.1.11",
      "device_id": "782sdf5as6sfd23ad3ds2dsf3dsfd2ad0gjtfgs2",
      "device_platform": "Android",
      "app_version": "1.1.6"
    }
  }
}

List Drivers

When the account has no active drivers, drivers_list is returned as null rather than an empty array. Check for null before looping.

Retrieves a list all active driver's along with each driver's profile information. The list will be displayed in ascending order based on each driver's first name and will be displayed in a json array. The property keys and types are the same as the driver details table above.

POST

https://zippykind.com/api/v2/

Example request

curl -X POST \
  https://zippykind.com/api/v2/ \
  -H 'apikey: 2wUizN2ghJYGQddGkMx2cx0LhorGWCq8Hupe5b0D' \
  -F scope=listDrivers

Example response

{
  "code": 200,
  "msg": "Success: API key is valid.",
  "status": "The property you are requesting has been found.",
  "details": {
    "drivers_list": [
      {
        "driver_id": "175632",
        "team_id": "10245",
        "on_duty": "1",
        "first_name": "John",
        "last_name": "Doe",
        "email": "johndoe@gmail.com",
        "phone": "+14804777931",
        "username": "donald",
        "transport_type": "Truck",
        "transport_description": "Ford F-150",
        "license_plate": "DKSID",
        "driver_color": "4DFFC6",
        "color": "black",
        "status": "active",
        "date_created": "2017-04-29 17:57:17",
        "last_login": "2017-05-02 13:19:35",
        "location_lat": "30.596623",
        "location_lng": "-116.42635",
        "ip_address": "111.1.11.1",
        "device_id": "akdlsldkskd82kls8dsd9f9ssdksldf82ll82633523adksld36942125829310safievamzl",
        "device_platform": "Android",
        "app_version": "1.1.7"
      },
      {
        "driver_id": "1489632",
        "team_id": "56326",
        "on_duty": "2",
        "first_name": "Jane",
        "last_name": "Doe",
        "email": "janedoe@gmail.com",
        "phone": "+14804777931",
        "username": "mikeh",
        "transport_type": "bicycle",
        "transport_description": "Beach cruiser",
        "license_plate": "",
        "driver_color": "FF2B75",
        "color": "Green",
        "status": "active",
        "date_created": "2017-04-29 18:11:01",
        "last_login": "0000-00-00 00:00:00",
        "location_lat": "29.26354",
        "location_lng": "-107.2335",
        "ip_address": "111.22.333.44",
        "device_id": "adklsdf8292lalda;fkanz.cdfqoadlsaf81012ad6fa3z2xv56afd5saf901kss",
        "device_platform": "IOS",
        "app_version": "1.1.6"
      }
    ]
  }
}

Driver Proximity

Not available. Driver proximity is not exposed through the public API. The driverProximity scope is not implemented and will return "details": "Scope has not been provided or is incorrect". Use driverDetails to read the driver's current location_lat / location_lng and compute proximity on your side.

Webhooks

Http WebHooks make it possible for your application to be notified when various events happen in Zippykind.

Let's say you want your application to receive a notification when a driver arrives to the delivery destination, this is possible using WebHooks. All WebHooks can be registered through the API Connect page in your Zippykind account.

The JSON data that will POST to your WebHook URL will have the following parameters along with the data relative to the event type:

Property	Description
`event_name`	The name of the event (i.e. ticket_started)
`date_stamp`	Server local time, format YYYY-MM-DD H:MM:SS. The hour is 24 hour and is not zero padded, so times before 10am appear as `2017-07-29 9:52:03`
`hand_shake_key`	Handshake key to authenticate the POST call to your WebHook

Validation
Before a WebHook is created we verify that you own the URL. Zippykind makes a POST call to your WebHook URL with the handshake in the parameters, and your endpoint proves ownership in any one of four ways. You only need one, and you only need to do this once.

1. Return a JSON body containing the zippy_token nested inside a details object (the original method).
2. Return any response header whose value is the token, for example X-Zippy-Token: u5X3wkVB4OergZwAgISR. The header name does not matter.
3. Return the token anywhere in the response body, plain text, HTML, or JSON of any shape.
4. If none of the above match, we send a GET to your WebHook URL with a zippy_token query parameter. Reply with the token and nothing else: the whole response body must be exactly the token.

Example response

{
  "details": {
    "zippy_token": "u5X3wkVB4OergZwAgISR"
  }
}

Simply add the generated zippy_token to your JSON response nested inside the details object. You only need to do this once. When you click on the green Add Webhook button, Zippykind will compare the generated zippy_token shown to you on the WebHooks page with the zippy_token provided by your JSON response, if the zippy_token matches, the WebHook is created. After the WebHook is created, you can remove the zippy_token from your JSON response, it will no longer be needed during future calls to your WebHook URL. If you are using Zapier, you don't need to add WebHooks through Zippykind. WebHooks through Zapier are handled through Zapier.

Handshake
You can provide a unique handshake key with your WebHook to authenticate the request to your application.

Testing
We recommend you use requestinspector.com to test your WebHooks. The following webhook testing services are whitelisted through Zippykind, including any of their subdomains, so you don't need to verify the server's identity using the zippy_token: requestinspector.com, requestb.in, webhook.site, requestcatcher.com, beeceptor.com, pipedream.net, typedwebhook.tools and postb.in.

Events are triggered when a driver or dispatch operator changes the status of a ticket

Event	Description
`ticket_cancelled`	Ticket was cancelled while en route.
`ticket_failed`	Package was not able to be delivered after the driver arrived.
`ticket_declined`	Driver declined to accept the ticket.
`ticket_assigned`	Ticket has been assigned to a driver.
`ticket_unassigned`	Ticket's driver assignment was removed.
`ticket_accepted`	Driver accepted the ticket.
`ticket_started`	Driver is now en route and has started to deliver the package.
`ticket_arrived`	Driver has arrived to the destination.
`ticket_successful`	Driver successfully delivered the package.
`added_photo`	Photo has been added to the ticket.
`added_signature`	Signature has been added to the ticket.
`added_note`	Driver has added a note to the ticket.
`updated_note`	Driver has edited an existing note on the ticket.
`on_duty_status`	Driver went on or off duty. The `data` object for this event contains `driver_id`, `on_duty` and `last_online` instead of the ticket fields.

Example response

{
  "event_name":"ticket_started",
  "date_stamp":"2017-07-29 13:52:03",
  "data": {
      "ticket_id":"1042",
      "ext_order_id":"",
      "ext_customer_number":"",
      "ext_invoice_number":"",
      "status":"started",
      "team_id":"1",
      "driver_id":"1",
      "ticket_lat":"38.5269665",
      "ticket_lng":"-110.625446",
      "product_pickup_lat":"",
      "product_pickup_lng":"",
      "driver_location_lat":"37.378596",
      "driver_location_lng":"-111.245695"
    },
  "hand_shake_key":"KLDSK8292kYsll02"
}

API Endpoints

Below you will find technical information related to the Zippykind API.

Endpoint	Description
`https://zippykind.com/api/v2/`	Used for all API requests.
`https://zippykind.com/api/v1/`	Legacy endpoint, kept available for the Zapier integration and existing direct callers. See the Zapier (V1) section.
`https://zippykind.com/api/test/`	Test your API key

Throttling

We ask that you keep your request rate reasonable. Continued overuse of your API key may result in a temporary ban. Please contact us before running a high volume integration so we can plan for it.

Definitions

Property	Description
`Team`	Drivers are assigned to teams in an effort to organize drivers
`Driver`	The person who is actually delivering the package
`Ticket`	Each time you create a new pickup or dropoff delivery, you are creating what we call a delivery ticket
`Map Zones`	Maps zones are organized into two categories, delivery and driver. When you create a map zone, you must assign it to a driver or to a delivery territory on the map. You can use map zones to determine driver territories, delivery travel fees and driver geofencing,

HTTP Error Codes

Error Code	Description
`200`	Success: API key is valid.
`400`	Error: API key has been provided but is not formatted correctly or is incorrect.
`401`	Error: API key is missing.
`402`	Error: Payment required. You have run out of credit or have an outstanding invoice due.
`403`	Error: Forbidden request.
`429`	Error: Too many requests. You have exceeded your API request limit.
`500`	Error: Something went wrong, please contact contact@zippykind.com.

Zippykind Status

Status	Description
`ok`	The property you are requesting has been found.
`AccountSuspended`	The account your are requesting is currently suspended.
`DeliveryNotFound`	We can't find the delivery you are looking for.
`Unauthorized`	You are not authorized to request details about the delivery.
`noCredit`	You have run out of credit or have an outstanding invoice due.
`DeletedTicket`	The delivery ticket you requested has been deleted.
`Failed`	Failed.
`MissingParameters`	Missing Parameters, followed by the names of the parameters that were absent.
`DriverNotOnAccount`	The driver_id you supplied is not on your account.

The V1 endpoint is the API behind the Zippykind Zapier integration. It is kept available for Zapier and for any direct caller already built against it. If you are building a new integration from scratch, use the V2 endpoint documented above instead: it authenticates with a header, returns richer responses, and has more scopes.

Only three scopes live here: new_ticket, new_customer, cancel_ticket. Two read-only list scopes, list_teams and list_drivers, were added to V1 briefly and then moved out to Zapier (V3) on 08.08.26 so this endpoint's contract stays fixed for the installed Zapier app and its existing users. If you need a team or driver dropdown, use V3 — everything else below is unchanged.

POST

https://zippykind.com/api/v1/

Authentication

V1 takes the API key and the scope as query string parameters, and every other field as form-encoded POST data.

Parameter	Where	Required	Description
`api_key`	query string	yes	Your API key. Generate it under API Connect, then the Keys tab.
`scope`	query string	yes, except on a credentials check	One of `new_ticket`, `new_customer`, `cancel_ticket`. Omit it to check the key instead of doing work. See below.

Because the key travels in the URL on this endpoint, it can appear in server and proxy logs. Treat a V1 key as lower-trust than a V2 key, rotate it if it is ever exposed, and prefer V2 for new work.

Checking your credentials

A GET carrying only api_key, with no scope at all, is a credentials check. It writes nothing and returns 200 with the account the key belongs to. This is the call the Zapier connection test makes, so it stays 200 even for an account that is out of credit. Anything other than a 200 here means the key itself is not usable.

Add &json=true to get that body on its own. Without it the response is wrapped in parentheses for the legacy JSONP callers, which is the shape the Zapier app has always received.

scope is read from the QUERY STRING only. Sending it as a POST field is not an error: the request is treated as a credentials check, returns HTTP 200 with "API key is valid." and creates nothing. Every other field is form-encoded POST data as usual.

A scope that is present but misspelled is still rejected with a 403. Only an omitted scope is treated as a credentials check, because a typo is what silently writes bad data and an omission never does.

GET

https://zippykind.com/api/v1/?api_key=YOUR_API_KEY

{
  "code": 1,
  "msg": "API key is valid.",
  "details": {
    "customer_id": "20",
    "company_name": "Your Company",
    "api_testing": "0"
  }
}

Response codes

Code	Meaning
`200`	The request succeeded.
`400`	The API key was provided but is not valid, or the write failed.
`401`	The API key is missing.
`402`	Payment required. The account is out of credit or has an outstanding invoice.
`403`	Forbidden. A required parameter is missing or invalid, or the record was not found.
`500`	Something went wrong on our side. Contact contact@zippykind.com.

A failed request always returns a non-200 status. The status field in the body names the reason, and for a missing parameter it names the offending field.

Create a ticket

POST

https://zippykind.com/api/v1/?api_key=YOUR_API_KEY&scope=new_ticket

Required fields

Field	Description
`customer_name`	Name of the person receiving the delivery.
`delivery_address`	Full destination address. Coordinates are not an accepted substitute.
`trans_type`	Either `delivery` or `pickup`. Any other value is rejected with a 403.

Optional fields

Field	Description
`delivery_date`	When the delivery is due. If omitted, we use the current date and time in your company's timezone, as set on your Zippykind account.
`ext_order_id`	Your own order number. Free text, so `ORD-1024` is fine.
`ext_customer_number`	Your own customer number.
`order_source`	Where the order came from, for example `shopify_draft_order`.
`ticket_description`	Notes for the driver.
`contact_number`	Recipient phone number.
`email_address`	Recipient email address.
`task_lat`, `task_lng`	Destination coordinates. If omitted we geocode `delivery_address`.
`status`	Starting status. `unassigned` is the usual choice. Accepted values: `unassigned`, `assigned`, `picked_up`, `accepted`, `acknowledged`, `started`, `arrived`, `successful`, `failed`, `declined`, `cancelled`. Any other value is silently dropped: the ticket is created as `unassigned` with no driver, and the response still reports success.
`team_id`	Team the ticket is assigned to.
`driver_id`	Driver the ticket is assigned to.
`weight`	Total weight of the delivery.
`quantity`	Number of items in the delivery.
`promo_code`	Promo code supplied by the customer.
`delivery_fee`, `processing_fee`, `tax`, `total`	Order money fields.
`line_items`	Array of items. Each item accepts `item_product_id`, `item_product_name`, `item_quantity`, `item_price`, `item_weight`. Send it as indexed form fields, for example `-d 'line_items[0][item_product_name]=Blue widget' -d 'line_items[0][item_quantity]=2'`. A JSON string is NOT decoded on V1 and is silently ignored, so the ticket is created without its items.
`product_pickup_name`	Name of the pickup location.
`product_pickup_contact_number`	Phone number of the pickup location.
`product_pickup_address`	Address of the pickup location.
`product_pickup_lat`, `product_pickup_lng`	Pickup coordinates. If omitted we geocode the pickup address.

Leaving out a required field returns a 403 naming it.

curl -X POST \
  'https://zippykind.com/api/v1/?api_key=2wUizN2ghJYGQddGkMx2cx0LhorGWCq8Hupe5b0D&scope=new_ticket&json=true' \
  -d 'customer_name=Jane Doe' \
  -d 'delivery_address=1600 Pennsylvania Ave NW, Washington DC' \
  -d 'trans_type=delivery' \
  -d 'delivery_date=2026-09-20 14:00' \
  -d 'ext_order_id=ORD-1024' \
  -d 'weight=12.5' \
  -d 'quantity=3' \
  -d 'total=48.97' \
  -d 'line_items[0][item_product_id]=SKU-1' \
  -d 'line_items[0][item_product_name]=Red Roses' \
  -d 'line_items[0][item_quantity]=1' \
  -d 'line_items[0][item_price]=29.99' \
  -d 'line_items[0][item_weight]=1 pound' \
  -d 'line_items[1][item_product_id]=SKU-2' \
  -d 'line_items[1][item_product_name]=Kettle Korn' \
  -d 'line_items[1][item_quantity]=3' \
  -d 'line_items[1][item_price]=14.99' \
  -d 'line_items[1][item_weight]=3 pounds'

Example response

{
  "code": 1,
  "msg": "Successfully created ticket",
  "details": {
    "ticket_id": 133105,
    "ext_order_id": "ORD-1024",
    "customer_name": "Jane Doe",
    "trans_type": "delivery",
    "delivery_address": "1600 Pennsylvania Ave NW, Washington DC",
    "delivery_date": "2026-08-02 14:00",
    "status": "unassigned"
  }
}

Example error

{
  "code": 403,
  "msg": "Error: Forbidden request.",
  "status": "Missing Parameters: customer_name, delivery_address",
  "details": ""
}

Create a customer

customer_name is required. email_address, contact_number, ext_customer_number and delivery_address are optional.

The call is safe to repeat. If a matching customer already exists we do not create a duplicate, and the response tells you which happened through the result field.

If the customer already existed, result is already_exists and account_id points at the existing record.

POST

https://zippykind.com/api/v1/?api_key=YOUR_API_KEY&scope=new_customer

curl -X POST \
  'https://zippykind.com/api/v1/?api_key=2wUizN2ghJYGQddGkMx2cx0LhorGWCq8Hupe5b0D&scope=new_customer&json=true' \
  -d 'customer_name=Jane Doe' \
  -d 'email_address=jane@example.com'

Example response

{
  "code": 1,
  "msg": "Successfully created customer",
  "details": {
    "customer_name": "Jane Doe",
    "email": "jane@example.com",
    "account_id": 110617,
    "result": "created"
  }
}

Cancel a ticket

ext_order_id is required and is the only accepted identifier. It is matched as text, so alphanumeric order numbers work.

Assigned drivers are notified only after the cancellation has been committed.

If no ticket on your account carries that ext_order_id, the response is a 403 with status We can't find the delivery you are looking for.

POST

https://zippykind.com/api/v1/?api_key=YOUR_API_KEY&scope=cancel_ticket

curl -X POST \
  'https://zippykind.com/api/v1/?api_key=2wUizN2ghJYGQddGkMx2cx0LhorGWCq8Hupe5b0D&scope=cancel_ticket&json=true' \
  -d 'ext_order_id=ORD-1024'

Example response

{
  "code": 1,
  "msg": "OK",
  "details": {
    "ticket_id": 133105,
    "ext_order_id": "ORD-1024",
    "result": "cancelled"
  }
}

Testing

Turn on API testing mode under API Connect to have tickets and customers written to separate testing tables instead of your live data. Everything else about the request and response is identical.

The V3 endpoint is a small, read-only endpoint built for the new Zippykind Zapier app. It answers exactly two dropdown-list scopes and a bare-key ping. It does not create, update or cancel anything — for that, use Zapier (V1) (legacy) or the Open API V2 endpoint.

Why a third endpoint. list_teams and list_drivers briefly lived inside the V1 endpoint. They were moved out to V3 on 08.08.26 so the live, installed Zapier (V1) app is never changed underneath its existing users, while the new Zapier app gets scopes that can keep evolving on their own. If you are building the new app: change the URL from /api/v1 to /api/v3 and nothing else — same api_key resolution, same scope names, same optional team_id.

GET

https://zippykind.com/api/v3/

Authentication

Same key resolution as V1 and V2, checked in this order:

Order	Where	Notes
1	`APIKEY` request header	Same header V2 reads.
2	`api_key` POST field
3	`api_key` query string parameter

A missing key returns 401. A key that does not resolve to an account returns 400.

Checking your credentials

A request carrying an API key but no scope at all is a ping. It writes nothing and returns 200 with the account the key belongs to.

Unlike V1's ping, this body is plain JSON — never wrapped in a JSONP callback. V1's parenthesized callback(...) envelope exists only to keep old installed Zaps working; V3 has no installed base to preserve.

A scope that is present but not one of the two below still returns 403, same rule as V1: an omitted scope is a connection test, a misspelled one is a mistake the caller needs to see.

GET

https://zippykind.com/api/v3/?api_key=YOUR_API_KEY

Example request

curl -X GET \
  'https://zippykind.com/api/v3/?api_key=2wUizN2ghJYGQddGkMx2cx0LhorGWCq8Hupe5b0D'

Example response

{
  "code": 1,
  "msg": "API key is valid.",
  "details": {
    "customer_id": 20,
    "company_name": "Your Company"
  },
  "request": "{...the request you sent, with the api_key masked...}"
}

List teams

Returns every published team on the authenticated account, sorted by name.

The response body for a successful scope call is a plain JSON array — not wrapped in the {code, msg, details} envelope the rest of the platform's API uses. Zapier's dynamic dropdown fields parse the array directly.

Property	Description
`id`	The team's `team_id`, as a number.
`name`	The team's name.

GET

https://zippykind.com/api/v3/?api_key=YOUR_API_KEY&scope=list_teams

Example request

curl -X GET \
  'https://zippykind.com/api/v3/?api_key=2wUizN2ghJYGQddGkMx2cx0LhorGWCq8Hupe5b0D&scope=list_teams'

Example response

[
  { "id": 1025, "name": "North Zone" },
  { "id": 1031, "name": "South Zone" }
]

List drivers

Returns every active driver on the account, sorted by first name then last name. Pass team_id to narrow the list to one team; omit it to get every active driver on the account.

Property	Description
`id`	The driver's `driver_id`, as a number.
`name`	The driver's first and last name, trimmed. Falls back to the driver's `username` when the driver has no first or last name on file, so a dropdown never shows a blank row.

team_id is optional and can only narrow the result — it is applied on top of the account's own customer_id, which comes from the API key itself and never from the request, so a team_id belonging to a different account simply matches nothing.

Note: only id and name are returned. This is deliberate — the underlying account and driver tables carry phone numbers, emails, GPS coordinates and device tokens, and this endpoint exists to populate a dropdown, not to hand a third party a driver roster.

GET

https://zippykind.com/api/v3/?api_key=YOUR_API_KEY&scope=list_drivers&team_id=1025

Example request

curl -X GET \
  'https://zippykind.com/api/v3/?api_key=2wUizN2ghJYGQddGkMx2cx0LhorGWCq8Hupe5b0D&scope=list_drivers&team_id=12342'

Example response

[
  { "id": 63526, "name": "John Doe" },
  { "id": 63530, "name": "Jane Smith" }
]

Response codes

Code	Meaning
`200`	The request succeeded.
`400`	The API key was provided but is not valid.
`401`	The API key is missing.
`403`	The `scope` parameter is present but is not `list_teams` or `list_drivers`.

There is no 402 on this endpoint: reading a list of team or driver names does not check account credit. On V1 only new_ticket checks credit; new_customer and cancel_ticket no longer do. A 403 error response still uses the same envelope as V1 and V2 ({code, msg, status, details}) — only the two successful list scopes and the ping return a bare body as shown above.

Migrating from Zapier (V1)

list_teams and list_drivers are not available on V1 as of 08.08.26. If your integration was built against an earlier version of V1 that had them, move it to V3:

Change the base URL from /api/v1 to /api/v3.
The api_key parameter and its resolution order are unchanged.
The scope names are unchanged.
The response is unchanged (a plain JSON array of {id, name}).

Ticket and customer scopes (new_ticket, new_customer, cancel_ticket) are not on V3 and are not moving — they remain on Zapier (V1) for existing integrations, or the Open API V2 endpoint for anything new.

Unit/apt/suite numbers. The new Zapier app's ticket-creation action is built against the Open API V2 Create A Delivery endpoint (see just above), which accepts delivery_address_unit and product_pickup_address_unit as optional fields and returns both on create, update and track. They are stored in their own columns and are never appended into delivery_address / product_pickup_address.

Show examples in:

cURL Python JS

Zippykind API Documentation