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 contact@zippykind.com.
The base URL for the Zippykind API is https://zippykind.com/api/v2.
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 Keys menu item and from there you will be able to generate an API 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.
You can test the authorization of your API call by using the endpoint
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' \
{
"code": 200,
"msg": "Success: API is valid.",
"status": "The property you are requesting has been found.",
"details": ""
}
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.
| Property | Description |
|---|---|
customer_name |
(required) The customer's name |
ext_customer_number |
(optional) Link the customer's account to a different platform |
phone |
(optional) Phone number of customer |
email |
(required) Email address of customer |
address |
(optional) Address of the customer |
account_lat |
(optional) The latitude of the customer's address |
account_lng |
(optional) The longitude of the customer's address |
date_created |
(optional) Date the account was created, it will default to today's date |
rewards_level |
(optional) The Zippykind rewards level (Bronze, Silver, Gold) |
spent_this_month |
(optional) Total amount of money the customer has spent in the last 30 days |
curl -X POST \
https://zippykind.com/api/v2/ \
-H 'apikey: 2wUizN2ghJYGQddGkMx2cx0LhorGWCq8Hupe5b0D' \
-F scope=newTicket \
-F trans_type=delivery \
-F delivery_date=03/15/2017 \
-F 'customer_name=John Doe' \
-F contact_number=480-123-4567 \
-F email_address=johndoe@gmail.com \
-F 'ticket_description=The gate code is 8228. There is a big dog in the yard, be careful.' \
-F 'delivery_address=12345 broadway st. Phoenix, AZ 85251'
-F 'account_lat=38.2526'
-F 'account_lng=-115.5845652'
{
"customer_name": "John Doe",
"ext_customer_number": "",
"phone": "480-123-4567",
"email": "johndoe@gmail.com",
"address": "12345 broadway st. Phoenix, AZ 85251",
"date_created": "2017-05-02T14:15:51-05:00"
}
{
"code": 200,
"msg": "Success: API is valid.",
"status": "The property you are requesting has been found.",
"details": {
"customer_name": "John Doe",
"ext_customer_number": "",
"phone": "480-123-4567",
"email": "johndoe@gmail.com",
"address": "12345 broadway st. Phoenix, AZ 85251",
"date_created": "2017-05-02T14:15:51-05:00"
}
}
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 |
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 |
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_lat |
String | (optional) The latitude of the product pickup location |
product_pickup_lng |
String | (optional) The longitude of the product pickup location |
delivery_date |
String("hh:mm") | (optional) Date and time of the delivery |
total_tax |
Number | (optional) The total tax |
promo_code |
Number | (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 |
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 |
account_id |
String | (optional) The ID of a Zippykind account |
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) Items included with the order |
product_name |
String | (optional) Name of the product |
product_id |
String | (optional) Product ID of the order item managed with Zippykind |
quantity |
String | (optional) Quantity of the order item |
sub_total |
String | (optional) Sub total of the order item |
tax |
String | (optional) Tax of the order item |
weight |
String | (optional) Weight of the order item |
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"}]'
{
"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": "03/15/2017",
"delivery_address": "12345 broadway st. Phoenix, AZ 85251",
"team_id": "1025",
"driver_id": "63526",
"ticket_lat": "33.4084199",
"ticket_lng": "-112.2041058",
"date_created": "2017-05-02T23:44:25-05:00",
"ip_address": "111.22.333.44",
"product_pickup_name": "2nd Store Location",
"product_pickup_contact_number": "480-555-6688",
"product_pickup_address": "653 Shea blvd Scottsdale, AZ 85265",
"product_pickup_lat": "33.4084199",
"product_pickup_lng": "-112.2041058",
"order_id": "3090",
"promo_code": "NEWYRS17",
"total": "48.97",
"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",
"customer_id": "36"
},
"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"}]
}
{
"code": 200,
"msg": "Success: API 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": "03/15/2017",
"delivery_address": "12345 broadway st. Phoenix, AZ 85251",
"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_name": "2nd Store Location",
"product_pickup_contact_number": "480-555-6688",
"product_pickup_address": "653 Shea blvd Scottsdale, AZ 85265",
"product_pickup_lat": "33.4084199",
"product_pickup_lng": "-112.2041058",
"order_id": "3090",
"promo_code": "NEWYRS17",
"total": "48.97",
"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": [{ "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"}]
}
}
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.
| 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) |
trans_type |
String | (required) 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 | (required) The customer's name |
delivery_address |
String | (required) The destination address of either the pickup or delivery |
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_lat |
String | (optional) The latitude of the product pickup location |
product_pickup_lng |
String | (optional) The longitude of the product pickup location |
delivery_date |
String("hh:mm") | (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 |
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
{
"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",
"team_id": "1025",
"driver_id": "63526",
"ticket_lat": "33.4084199",
"ticket_lng": "-112.2041058",
"ip_address": "111.22.333.44",
"product_pickup_name": "2nd Store Location",
"product_pickup_contact_number": "14805556688",
"product_pickup_address": "653 Shea blvd Scottsdale, AZ 85265",
"product_pickup_lat": "33.4084199",
"product_pickup_lng": "-112.2041058",
"leave_it": "1"
}
{
"code": 200,
"msg": "Success: API is valid.",
"status": "The property you are requesting has been found.",
"details": ""
}
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, acknowledged, failed, arrived, successful.
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 unassigned.
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 acknoledged, the driver has accepted the ticket but has not yet started the delivery. 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 |
curl -X POST \
https://zippykind.com/api/v2/ \
-H 'apikey: 2wUizN2ghJYGQddGkMx2cx0LhorGWCq8Hupe5b0D' \
-F scope=trackTicket \
-F ticket_id=101417
{
"code": 200,
"msg": "Success: API 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",
"contact_number": "+14804777931",
"email_address": "johndoe@gmail.com",
"customer_name": "John Doe",
"delivery_date": "2017-05-02 16:00:00",
"delivery_address": "658 West Camelback Road, Phoenix, AZ, United States",
"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_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"
}
]
}
}
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.
| 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 | (optional) The type of action submitted by the delivery driver |
remarks |
String | (optional) The action described and formatted by Zippykind |
driver_id |
String | (optional) The ID of the driver assigned to the delivery |
account_id |
String | (optional) The account ID of the customer the delivery is assigned to |
driver_location_lat |
String | (optional) The latitude of the driver's location when the mileston was submitted |
driver_location_lng |
String | (optional) The longitude of the driver's location when the mileston was submitted |
date_created |
String("hh:mm") | (optional) The date the milestone was submitted |
notes |
String | (optional) The notes submitted by the driver |
received_by |
String | (optional) The person who signed for the package |
customer_signature |
String | (optional) The signature of the delivery recipient |
photo_url |
String | (optional) The URL of the a photo that has been submitted with the delivery ticket |
curl -X POST \
https://zippykind.com/api/v2/ \
-H 'apikey: 2wUizN2ghJYGQddGkMx2cx0LhorGWCq8Hupe5b0D' \
-F scope=ticketHistory \
-F ticket_id=101148
{
"code": 200,
"msg": "Success: API is valid.",
"status": "The property you are requesting has been found.",
"details": {
"ticket_history": [
{
"status": "acknowledged",
"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 this 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": ""
}
]
}
}
Pass any driver's ID to this endpoint to get the driver's full details including current latitude and longitude position.
| Property | Type | Description |
|---|---|---|
scope |
String | (required) Dictates the type of request |
driver_id |
String | (required) The ID of the driver |
team_id |
String | (optional) The ID of the team the driver is assigned to |
on_duty |
String | (optional, 0 or 1) Value 1 indicates the driver is on duty |
first_name |
String | (optional) First name of the driver |
last_name |
String | (optional) Last name of the driver |
email |
String | (optional) Email of the driver |
phone |
String | (optional) Phone number of the driver |
username |
String | (optional) Username of the driver |
transport_type |
String | (optional) Transportation type of the driver |
transport_description |
String | (optional) Description of the driver's transportation |
license_plate |
String | (optional) License plate of the driver |
driver_color |
Hex Code | (optional) The color associated with the driver's dashboard markers |
color |
String | (optional) Color of the driver's transportation vehicle |
status |
String | (optional) Options are pending, active, blocked, suspended |
username |
String | (optional) Username of the driver |
date_created |
String("hh:mm") | (optional) Date the driver's account was created |
last_login |
String("hh:mm") | (optional) Date the driver last logged into the Zippykind app |
location_lat |
Number | (optional) The latitude of the driver's current location |
location_lng |
Number | (optional) The longitude of the driver's current location |
ip_address |
Number | (optional) The IP address of the driver's device |
device_platform |
String | (optional) Options are IOS and Android |
app_version |
String | (optional) The version of the app the driver is using |
curl -X POST \
https://zippykind.com/api/v2/ \
-H 'apikey: 2wUizN2ghJYGQddGkMx2cx0LhorGWCq8Hupe5b0D' \
-F scope=driverDetails \
-F driver_id=18256
{
"scope": "driverDetails",
"driver_id": "18256"
}
{
"code": 200,
"msg": "Success: API 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": "truck",
"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"
}
}
}
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.
curl -X POST \
https://zippykind.com/api/v2/ \
-H 'apikey: 2wUizN2ghJYGQddGkMx2cx0LhorGWCq8Hupe5b0D' \
-F scope=listDrivers
{
"code": 200,
"msg": "Success: API 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": "0",
"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"
}
]
}
}
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 Keys 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 |
Format YYYY-MM-DD HH:MM:SS |
handshake |
Handshake key to authenticate the POST call to your WebHook |
Validation
All URLs are validated through a simple JSON response with the provided zippy_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 requestb.in to test your WebHooks. Requestb.in is whitelisted through Zippykind, so you don't need to verify the server's identity using the zippy_token.
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_acknowledged |
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. |
photo_added |
Photo has been added to the ticket. |
signature_added |
Signature has been added to the ticket. |
notes_added |
Driver has added a note to the ticket. |
{
"event_name":"ticket_started",
"date_stamp":"2017-07-29 13:52:03",
"data": {
"ticket_id":"100101",
"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"
}
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/test/ |
Test your API key |
We allow you to perform up to 5 API requests per second. Exceeding the request limit will result in a 429 error. Continued overuse of your API key may result in a temporary ban. Please contact us if you need your request rate to be increased.
| 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, |
| Error Code | Description |
|---|---|
200 |
Success: API is valid. |
400 |
Error: API has been provided but is not formatted correctly or is incorrect. |
401 |
Error: API key is missing. |
402 |
Error: You must make the request using a SSL. |
403 |
Error: Forbidden request. |
429 |
Error: Too many requests. You have exceeded your 5 requests per second limit. |
500 |
Error: Something went wrong, please send email to contact@zippykind.com. |
| 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. |
DeletedTicket |
The delivery ticket you requested has been deleted. |