ZoneJump's shipper API is a REST-based API for creating and tracking shipments. Only API clients that (1) are associated with a customer account and (2) have been pre-authorized with an assigned API key may access the API.
ZoneJump's REST API
provides a means of creating new shipments and tracking existing shipments. Shipments are
created by issuing an HTTP POST method with a valid JSON body containing shipment information and are assigned a
trackingNumber that can be used for subsequent monitoring of shipment status.
The API supports several means of tracking shipments.
- Using the assigned tracking number, a list of tracking events can be requested via an HTTP GET method for an existing shipment.
- Alternatively, an API client may register a webhook to provide a callback URL and a list of tracking events that are of interest. The ZoneJump platform will push events to the client's registered callback as they occur, foregoing the need for the client to periodically poll for shipment status.
Here are the steps to successfully implement and integrate an API client with the ZoneJump platform:
- For access to ZoneJump's API development environment:
- Gain understanding to the API and its terms of use by reading this document.
- Use this API Access Request link to obtain an API key for the ZoneJump development environment.
-
Exercise the API to ensure the client software is able to obtain responses for basic operations. See the
section on API Testing that describes available testing methods such as
cURL,Swagger UI, andPostman. - Print off one of each sample shipping label on a printer that will be used for production shipping operations and provide a scanned image or photo of the printed labels to API Support for ZoneJump's validation.
- In addition, for access to the Production API:
- Complete a service agreement with ZoneJump, which contains information needed to properly configure service operations.
- Complete testing and validation in the Development environment as described above;
-
Contact API
Support to obtain:
- the API key for the Production environment;
-
the values needed to populate parameters for
pickupAddressIdandaccountNumberin a shipment request.
By creating API shipments within the ZoneJump system, the account holder agrees to ZoneJump’s service terms and conditions for API use that are listed here.
Only authorized ZoneJump account holders may invoke this API to create and track shipments for their business use. Customers' API clients are not to exceed a reasonable amount of method invocations, as outlined below. When developing software to access ZoneJump's platform you agree to the terms listed below:
Application restrictions:
-
Customers are not to disclose their API credentials to any external parties, including third-party auditors or shipment
tracking services without ZoneJump's prior permission. Best practices for securing API keys include:
- Do not embed API keys directly in application code. This could lead to accidental public exposure.
- Do not store API keys in source files that could be committed to a publicly accessible source code management system - e.g., GitHub.
- Notify ZoneJump immediately if you suspect your API keys have been compromised. ZoneJump will invalidate your current keys and issue replacements.
- Only packages tendered to ZoneJump should be tracked; do not attempt to track (1) shipments tendered to other carriers (e.g., FedEx, UPS, etc.) or (2) shipments that have not yet been tendered to ZoneJump.
-
Once delivered, shipments should not be tracked again. Use the ZoneJump dashboard to obtain additional
service metrics and historical shipment data. No attempt to retrieve historical data via the API should ever be
made. Special requests for this data should be sent to
system.support@zonejump.com. - Tracking requests may be issued several times a day but should be limited to less than 10 invocations per package per day. Excessive use of the API may result in throttling of tracking requests to an acceptable rate.
-
Shipments older than two weeks, regardless of status, should not be tracked. Contact
system.support@zonejump.comfor problem package resolution. -
ZoneJump has been contracted to offer delivery services to a fixed list of ZIP codes. Shipments will only be
successfully created when they contain ZIP codes that are serviced by ZoneJump. To facilitate API use, ZoneJump
maintains a file of
available ZIP codes and services for each.
- API client software should validate destination addresses before creating shipments via the API to ensure shipments are handled properly within the ZoneJump system. Any attempt to create a shipment for an unavailable destination or for a service that is unavailable for a given destination will be rejected. Delivery to a PO box address is supported for ZoneJump Flats service.
- Users in violation of Terms of Use will be contacted by ZoneJump and will be expected to take immediate action to rectify identified issues. If full compliance with the Terms of Use is not achieved, ZoneJump reserves the right to restrict or terminate access to the API and its services.
Contact ZoneJump in order to:
- Obtain an API key for use with ZoneJump's API development environment. API keys will be issued within 1 business day of receiving a request, excluding weekends and holidays.
- Submit questions or issues regarding API operation or to ask for support in client development. Please indicate the severity of the issue in the subject of the email and provide as much detail as possible in the body.
- Submit a request for custom data exports. Describe the nature of the data you wish to obtain, the time period of interest, and any perceived need for ongoing data exports.
Send an email to system.support@zonejump.com and include the customer account number, if assigned,
in the subject line.
This section describes the details of the method invocations available to clients to create and track shipments. All methods are available in both the development and production API environments.
Electronic billing and invoicing functions are currently performed off-line and not available via the API, though these functions may be implemented in a future version of the API.
This section is meant to be an overview of the API. Please refer to the formal specification for an in-depth definition of the API methods and schema. Where the overview may differ, the formal specification has precedence.
API access is achieved by targeting a base URL with an HTTP method invocation (POST, GET) for a specific resource (e.g., shipment or tracker). The base URLs for API access are:
-
Development API:
https://api-dev.zonejump.com -
Production API:
https://api.zonejump.com
Customers developing API client software will be given keyed access to ZoneJump's Development environment. Access to the Production environment will be granted after successful exercise and validation of the customer's client in the Development environment.
Shipments are created in the ZoneJump platform by issuing an HTTP POST method with a JSON payload that describes
the shipment. The client provides its API key in the X-Api-Key request header.
POST /shipments
Content-Type: application/json
X-Api-Key: <CLIENT_API_KEY>
cache-control: no-cache
{
"testFlag": true,
"requestId": "1564602222443",
"accountNumber": "1",
"serviceCode": "ZJG",
"pickupAddressId": 1,
"deliveryAddress": {
"name": "Dean A Meyer",
"street": "219 Via Fortuna",
"city": "Henderson",
"state": "NV",
"zip": "89011",
"phone": "7020001111",
"residence": true,
"phone": "9871236540",
"email": "a.person@somewhere.com"
},
"package": {
"weight": 0.75,
"length": 4,
"width": 6,
"height": 8,
"signatureRequired": false,
"saturdayDelivery": true,
"declaredValue": 0,
"shipDate": 2025-07-31T12:43:42-07:00",
"isIataDangerousGoods": false,
"labelType": "ZPL"
}
}
Each API request parameter is listed in the table below and is either a required (R) or optional (O) parameter.
Unused/empty optional (O) parameters should be omitted from the request.
| Request Parameter | Required | Type | Description |
|---|---|---|---|
testFlag
| O | boolean |
true - Indicates a test requestfalse - Indicates a normal shipmentTest requests will provide an API response that includes a printable label and an accurate estimate of transit time, delivery date and shipping charges; however, no shipment will be recorded for subsequent processing. |
requestId
| R | string | A client-supplied unique ID to associate a request with its subsequent response |
accountNumber
| R | string | A ZoneJump customer's pre-assigned account number |
serviceCode
| R | string | Use one of the following codes to indicate the choice of service:
ZJG - ZoneJump® Ground Service for Parcels
FTF - ZoneJump FlatTrack Express® Service for USPS First-Class Flats
FTL - ZoneJump FlatTrack Express® Service for USPS First-Class Letters
DDG - DoorDash Ground Service for Parcels
Note: ZoneJump FlatTrack Express® Service shipments are rated on actual weight;
|
pickupAddressId
| R | integer | An origination address identifier assigned by ZoneJump at service configuration time; typically indicating a customer's warehouse location or shipping center |
deliveryAddress
| R | object | The destination's address must be validated by address validation software prior to issuing the request. An address contains the following parameters: |
name
| R | string | Length: 35 The name of the person to receive the shipment |
company
| O | string | Length: 35 This field may be used to further specify the recipient's delivery address - e.g., a work address |
street
| R | string | Length: 35 Street number and name Note: Only ZoneJump® Flats Service permit a post office (PO) box in lieu of a street address; Ground service will not accept a PO box as a street address. |
street2
| O | string | Length: 35 Additional address information |
city
| R | string | Length: 30 |
state
| R | string | Length: 2 The 2-letter state abbreviation (e.g., AZ) |
zip
| R | string | A 5-digit (99999) or 9-digit zip code (99999-0000) |
residence
| R | boolean | true - Address is a residencefalse - Address is a business or
non-residential
location |
phone
| R | string | Length: 10 - Digits 0-9 only. The recipient's phone number |
email
| O | string | A well-formed email address for the recipient of the shipment; if provided, the recipient will receive notifications for certain tracking event types. |
validateAddress
| O | boolean | TRUE - Validate the delivery address and fail the shipment if invalid.
When address validation fails, detailed results will be provided in the returned error response. If the address validation is successful, the API response will include a success indicator. Note: There may be an additional charge for this option. |
specialInstructions
| O | string | Maximum length: 100 Special delivery instructions for the driver ‐ e.g., gate code, etc. ‐ that will be provided to the carrier to assist delivery.
Note: This attribute is only applicable for |
package
| R | object | The item to be shipped, defined by the following attributes: |
shipperName
| O | string | The name of the shipper; 3PL customers may indicate their customer's name in this field which will be displayed on the shipping label as part of the return address. | shipDate
| R | string |
A timestamp expressed in RFC3339 date-time format
- e.g., 2019-07-04T11:00:00-07:00. This timestamp is the basis for calculating the
daysInTransit and expectedDeliveryDate fields in the API response.
Note: For the most accurate results for |
type
| R | string | The type of shipment
|
weight
| R | number | A decimal representation of weight in pounds
Note: Ounce weights should be specified as fractional pounds; i.e. 1 ounce = 0.0625 pounds; intermediate ounce values will be rounded to the next whole ounce. Weights greater than 1 pound will be rounded up the next whole pound. Rounded weights will be recorded and used for billing calculations. Please ensure accurate measurements to avoid billing corrections as billing is based on these measurements. Follow best practices for scale calibration at regular intervals. |
length
| R | number | A decimal representation of the dimension in inches. Standard rounding will apply to this value for rate
calculations using dimensional weight.
Note: Dimension values will be rounded to the nearest whole inch. Values with a fraction < 0.5 will be rounded down while fractions ≥ 0.5 will be rounded up; e.g., 11.49in rounds to 11in while 11.5in rounds to 12in. Rounded dimension values will be used to calculate dimensional weight. |
width
| R | number | A decimal representation of the dimension in inches. Standard rounding will apply to this value for rate calculations using dimensional weight. |
height
| R | number | A decimal representation of the dimension in inches. Standard rounding will apply to this value for rate calculations using dimensional weight. |
isIataDangerousGoods
| O | boolean | true - Explicityly indicates the item is a dangerous item per IATA guidelines
false - indicates the classification does not apply
Note: This field is an explicit indication that the shipped item is not subject to the IATA classification for dangerous goods. ZoneJump does not accept dangerous goods for shipment. |
signatureRequired
| O | boolean | true - Signature requiredfalse - No signature required
currently a placeholder for future use.
Note: There is an additional charge for this option. |
increaseLiabilityLimit
| O | boolean |
true - In case of damaged or missing package, ZoneJump will be liable for the declared value.
false - ZoneJump is liable for up to $100 per package even if actual value of the shipment is
greater than $100.
Note: There is an additional charge for this option. The limit is capped at $999.99.
|
declaredValue
| O | number | The dollar value of the shipped item. Required if increaseLiabilityLimit is specified.
Note: Omit if your service contract does not have insurance or liability terms. |
saturdayDelivery
| O | boolean |
true - Request a Saturday delivery.
If the destination supports this option, the package will be marked for Saturday delivery. Note: There may be an additional charge for this option. |
reference1
| O | string | Maximum length: 50 A customer-supplied field that will be rendered on the shipping label Note: Shippers should consider populating the reference1 field with an order number for the shipment. |
reference2
| O | string | Maximum length: 50 A customer-supplied field that will be rendered on the shipping label Note: Shippers should consider populating the reference2 field with a product SKU, especially in the case where the SKU indicates standard packaging. This permits automated resolution of carrier disputes where scanned package dimensions may differ from past shipments of the same SKU. See the ZoneJump Support Guide for Finance — ZoneJump’s process to reduce billing exceptions — for more information about billing auditing and disputes. |
labelType
| O | string | The image encoding for 4-by-6 inch label to be provided in the response
PDF - a Portable Document Format label; Base64 encoded
PNG - a Portable Network Graphic image; Base64 encoded
ZPL - a Zebra Printer Language text string
Note: PDF and PNG labels must be Base64 decoded to binary to render the image for printing.
Only PNG format is available for FTF and FTL shipments. ZPL label strings are UTF-8 text strings. |
A shipment response is returned synchronously by the API. The response content is a JSON payload:
{
"requestId": "1564602222443",
"accountNumber": "1",
"serviceCode": "ZJG",
"trackingNumber": "92748902069736000099996666",
"shippingLabel": "^XA^LH0,10
^FS^FO040,010^AQN,20,30^FDABC RETAIL
^FS^FO040,035^AQN,20,30^FD21 MAIN ST # 552
^FS^FO040,085^AQN,20,30^FDMORRIS, NJ 07962
^FS^FO500,010^GB250,150,5
^FS^FO535,030^AQN,20,30^FDPS LIGHTWEIGHT
^FS^FO530,060^AQN,20,30^FDUS POSTAGE PAID
^FS^FO585,090^AQN,20,30^FDOnTrac
^FS^FO600,120^AQN,20,30^FDeVS
^FS^FO040,155^ARN,20,30^FDNO ENDORSEMENTS REQUIRED
^FS^FO040,225^ARN,20,30^FDSHIP
^FS^FO040,255^ARN,20,30^FDTO:
^FS^FO150,225^ATN,30,50^FD
^FS^FO150,265^ATN,30,50^FDDEAN A SMITH
^FS^FO150,305^ATN,30,50^FD219 VIA FORTUNA
^FS^FO150,385^ATN,30,50^FDHENDERSON, NV 89011
^FS^FO020,460^GB775,1,12,B,0
^FS^FO240,500^ASN,20,30^FDUSPS TRACKING # eVS
^FS^FO055,560^BY3^BCN,160,N,N,N,D^FD4208901192748902069736000099996666
^FS^FO170,740^ASN,20,30^FD9274 8902 0697 3600 0099 9966 66
^FS^FO020,800^GB775,1,12,B,0
^FS^FO040,875^AVN,10,20^FDDDU
^FS^FO190,880^ARN,20,30^FD404 S BOULDER HWY
^FS^FO190,910^ARN,20,30^FDHENDERSON, NV 89015
^FS^FO540,840^AVN,10,20^FDVEG-B
^FS^FO540,910^AVN,10,20^FDB11^XZ",
"daysInTransit": 3,
"expectedDeliveryDate": 2025-08-03",
"deliveryCharge": "12.00",
"totalCharge": "12.00"
}
All string representations are UTF-8 encoded.
| Response Parameter | Type | Description |
|---|---|---|
requestId
| string | Echoed from the request body |
accountNumber
| string | Echoed from the request body |
serviceCode
| string | Echoed from the request body |
trackingNumber
| string | A unique identifier assigned by ZoneJump and associated to the shipment for subsequent tracking purposes |
shippingLabel
| string |
A pre-formatted shipping label. For the ZPL label type, the label string may be
printed directly on any ZPL or EPL2 label printer. For PNG or PDF label types,
the label string as a base64-encoded string representation of a .png or .pdf file that must be decoded
before printing.
Note:
|
daysInTransit
| integer | The number of calendar days the shipment will be in transit |
expectedDeliveryDate
| string | YYYY-MM-DD - The expected date of delivery
Note: This date is the date of shipment creation plus the number of days in transit and assumes the package will be tendered to ZoneJump prior to shipment cut-off time. The client is responsible for managing shipments and recipient expectations accordingly. The ZoneJump platform will adjust the expected delivery date in the case that the shipment is tendered to ZoneJump after the cut-off time; i.e., is tendered the "next day". |
deliveryCharge
| number | Delivery charge is the base charge exclusive of add-ons, in US dollars |
deliveryAreaSurcharge
| number | Per shipper agreement, if delivery area surcharges apply |
peakSurcharge
| number | Per shipper agreement, if peak season surcharges apply |
declaredValueSurcharge
| number | Per shipper agreement, if declared value surcharges apply |
signatureRequiredCharge
| number | Per shipper agreement, if signature required surcharges apply |
residentialSurcharge
| number | Per shipper agreement, if residential delivery surcharges apply |
fuelSurcharge
| number | Per shipper agreement, if fuel surcharges apply |
totalCharge
| number | The total charge is the base charge with add-ons (e.g., declared value, etc.), in US dollars |
deliveryAddressValid
| boolean |
If validateAddress was present in the request and the address was validated successfully, this attribute
will be present in the response and set to true. Validation errors will be presented and described in a
returned error response.
|
The shippingLabel string in the response message should render on a compatible label printer.
Shipping labels are formatted for compatibility with ZoneJump's last mile delivery partners. The currently supported 4x6 shipping label formats are:
The ZoneJump platform provides several options for tracking shipments once they are in the ZoneJump system.
- Tracking via API. The API can support dynamic queries of shipment status for individual shipments.
- Tracking via Webhook. A tracking webhook can be configured via the API to report incremental status updates for all outstanding shipments.
- Tracking via File Export. A status file export can be configured at the time of initial account establishment to provide incremental status updates, similar to the webhook option.
The following table list the tracking event codes, their meaning, and the action taken by the ZoneJump platform on detection of the associated event.
| Code | Description | Action |
|---|---|---|
ACN
| Access code needed. Carrier requires access or gate code to deliver package. | Email sent to the shipper's email address that is provided at account creation. |
ADC
| Delivery address changed by shipper or package recipient. | Email sent to the shipper's email address that is provided at account creation. Address correction fee may apply. |
AIC
| Address incorrect. Carrier requires updated information to deliver package. | Email sent to the deliveryAddress.email provided in the shipment request. Address correction fee may apply. |
AII
| Address incomplete. Carrier requires updated information to deliver package. | Email sent to the shipper's email address that is provided at account creation. Address correction fee may apply. |
AIR
| Undeliverable address. Package returned to sender. | Email sent to the shipper's email address that is provided at account creation. |
CLP
| The shipment information has been provided to the carrier. | No action taken. |
DAC
| Delivery attempted. Carrier reported company closed. | Email sent to the shipper's email address that is provided at account creation. Expected delivery date may be extended 1 day. |
DAN
| Delivery attempted. Carrier reported customer not home. Package not left for security reasons. | Email sent to the shipper's email address that is provided at account creation. Expected delivery date may be extended 1 day. |
DAP
| Delivery attempted. Recipient no longer at the address. | Email sent to the shipper's email address that is provided at account creation. |
DAR
| Delivery attempted. Package was refused. | Email sent to the shipper's email address that is provided at account creation. |
DDC
| Package en route delayed before reaching the delivery hub; possible one day delay. | Expected delivery date may be extended 1-2 days. |
DDW
| Delayed due to weather or inaccessible delivery location. | Expected delivery date may be extended 1 day. |
HFP
| Held for customer pickup at carrier facility. | No action taken. |
HIW
| Package will not be delivered until the problem is resolved at the carrier. Call carrier. | Email sent to the shipper's email address that is provided at account creation. |
MRC
| There was an issue with package routing by the carrier; possible one day delay. | Email sent to the shipper's email address that is provided at account creation. Expected delivery date may be extended 1-2 days. |
OFD
| Out for delivery today until 9pm. | No action taken. |
ODP
| Out for delivery by postal carrier. | No action taken. |
PDC
| Delivered. | Email sent to the deliveryAddress.email provided in the shipment request. |
PDD
| Carrier reported that the package was damaged and was delivered to the recipient. | Email sent to the shipper's email address that is provided at account creation. |
PDF
| Package delivered to local postal carrier. | No action taken. |
PDN
| Carrier reported package delivered to neighbor. No action needed. | Email sent to the deliveryAddress.email provided in the shipment request. |
PMA
| Package not delivered. Damaged. Notification sent to shipper. | Email sent to the shipper's email address that is provided at account creation. |
PMS
| Package has been accepted by USPS and is on its way to you.. | Email sent to the shipper's email address that is provided at account creation. |
PND
| Pick up at shipper completed. Pending acceptance scan.. | Email sent to the shipper's email address that is provided at account creation. |
PNL
| Package not delivered. Lost. Notification sent to shipper. | Email sent to the shipper's email address that is provided at account creation. |
PSH
| Package scanned at carrier facility that will deliver package. | No action taken. |
PUS
| Package has been scanned by the carrier and is on its way to you. | Email sent to the deliveryAddress.email provided in the shipment request. |
RRS
| Package return received by shipper. | No action taken. |
RTS
| Package returned to shipper. | No action taken. |
SLP
| Shipping label printed. Package at shipper facility until pickup. | No action taken. |
UPD
| Updated package delivery date. | No action taken. |
UPL
| Updated package location. | No action taken. |
XXX
| Package not able to be delivered. Notification sent to shipper. | Email sent to the shipper's email address that is provided at account creation. |
Note: The events that result in email to the shipperNotification
recipients will also result in a bcc email to the ZoneJump
customer account email addresses established at the time of account configuration.
An API client may track shipment status via a tracking request API call. A tracking request is created by invoking an HTTP GET method on a specific shipment:
GET /shipments/<TRACKING_NUMBER>
Content-Type: application/json
X-Api-Key: <CLIENT_API_KEY>
cache-control: no-cache
The TRACKING_NUMBER is provided as a path parameter in the request. The client provides its API key
in the X-Api-Key header.
A tracking response is returned synchronously by the API. The response content is a JSON payload consisting of an array of tracking events:
{
"trackingNumber": "TRACKING_NUMBER",
"expectedDeliveryDate": "2025-08-03",
"notice": "NOTICE_MESSAGE",
"trackingEvents": [
{
"eventCode": "PUS",
"description": "Package has been scanned by the carrier and is on its way to you",
"occurredAt": 2025-01-19 18:43:21",
"city": "Henderson",
"state": "NV",
"zip": "89011"
},{
:
}
]
}
A tracking response is represented in JSON format as shown below. All string representations are UTF-8 encoded.
| Response Parameter | Type | Description |
|---|---|---|
trackingNumber
| string | Echoed from the request path |
expectedDeliveryDate
| string | The date the package is expected to be delivered, in YYYY-MM-DD format |
notice
| string | An optional response element, a notification is included in the tracking response to indicate there is a condition (e.g., weather delays, equipment failure, etc) in effect that may affect package delivery or extend the expected delivery date |
progressState
| string | The current progress state of the shipment;
Possible values: READY - The package is ready for pickup by the carrier.
TRANSITING - The package is in transit to the delivery address.
DELIVERED - The package has been delivered to the delivery address.
EXCEPTION - There is an exception that may affect the delivery of the package.
|
carrier
| array | Carrier information for the shipment, described by the following parameters: |
company
| string | The name of the carrier company. |
phone
| string | The phone number of the carrier company. |
email
| string | The email address of the carrier company. |
csHours
| string | The customer service hours of the carrier company. |
url
| string | The URL of the carrier company's website. |
trackingEvents
| array | A list of all events for the shipment, described by the following parameters: |
eventCode
| string | The type of the event; see the table above |
description
| string | Additional information about the event; see the table above |
occurredAt
| datetime | The event timestamp expressed in 24-hour local time at the event location Format: YYYY-MM-DD HH:mm:ss
|
city
| string | The city where the event occurred |
state
| string | The state where the event occurred |
zip
| string | The ZIP code where the event occurred |
In lieu of an API client issuing periodic tracking requests to poll the ZoneJump platform for shipment status, an API client may register a webhook target (i.e., "consumer"). The ZoneJump platform will individually post the current and historical status for each package that is currently being tracked by the system when new events are detected for those packages.
A webhook is created with an HTTP POST request and may be subsequently updated with an HTTP PUT request; for example:
POST /shipments/webhook/<ACCOUNT_NUMBER>/<WEBHOOK_ID>
Content-Type: application/json
X-Api-Key: <CLIENT_API_KEY>
cache-control: no-cache
...
{
"url": "https://your-webhook-host.com",
"headers": {
"header_name_1": "header_value_1",
"header_name_2": "header_value_2"
}
}
Once created, a webhook can be removed by an HTTP DELETE request:
DELETE /shipments/webhook/<ACCOUNT_NUMBER>/<WEBHOOK_ID>
Content-Type: application/json
X-Api-Key: <CLIENT_API_KEY>
cache-control: no-cache
A simple message is returned to indicate successful deletion:
{
"message": "Webhook deleted"
}
Note: Currently, only one webhook can be registered per customer account; multiple requests to create or update a webhook will result in establishment of the webhook specified in the lastest POST or PUT request.
A webhook creation request is represented in JSON format as shown below. All string representations are UTF-8 encoded.
Note: Unused optional parameters should be omitted from the request.
| Request Parameter | Required | Type | Description |
|---|---|---|---|
ACCOUNT_NUMBER
| R | string | A path parameter that specifies the customer's pre-assigned account number |
WEBHOOK_ID
| R | string | A path parameter that specifies a unique identifier for the webhook |
url
| R | string | The URL of the webhook consumer; subsequent event updates are posted to this URL |
headers
| O | object | An optional list of key-value pairs that define the HTTP headers that are required by the webhook consumer to be included in the POST operation for event notifications |
The JSON response to a webhook request simply echoes the request parameters:
{
"accountNumber": "ACCOUNT_NUMBER",
"webhookId": "WEBHOOK_ID",
"url": "https://webhook-consumer-host.com",
"headers": {
"header_name_1": "header_value_1",
"header_name_2": "header_value_2"
}
}
After the webhook has been registered, the ZoneJump platform will execute an HTTP POST with a content body that is the list of all events for all shipments that have occurred since the last webhook execution:
POST /webhook-consumer-host.com
Content-Type: application/json
X-ZoneJump-Webhook-Id: <WEBHOOK_ID>
header_key1: header_value1
header_key2: header_value2
...
{
"expectedDeliveryDate": 2025-08-03T00:00:00+00:00",
"trackingNumber": "TRACKING_NUMBER",
"notice": "NOTICE_MESSAGE",
"trackingEvents": [
{
"eventCode": "PUS",
"description": "Package has been scanned by the carrier and is on its way to you",
"occurredAt": "2025-01-19 18:43:21",
"city": "Henderson",
"state": "NV",
"zip": "89011"
},{
:
}
]
}
The POST method will include an X-ZoneJump-Webhook-Id header with the webhook identifier.
The expected response to the POST is a simple HTTP 200 status; no body content is required.
Note: The webhook consumer should be provisioned so that it is in a ready state to accept event posting requests.
If the webhook consumer is unable to respond successfully to an event posting (i.e., an HTTP response status of 200)
after 3 consecutive attempts, the webhook will be disabled and no further event postings will occur. Should this
occur, the webhook consumer can check the status of the webhook and, if necessary, re-create it via the API.
Also, regardless of the event reporting options described above, ZoneJump relies on its carrier partners for timely
upstream reporting of events for downstream aggregation and reporting to its customers. As a result, individual event
timestamps may differ from the actual time the event was made available for reporting.
The API development environment offers the ability to exercise API in a low-risk setting. The environment provides a "mock" implementation of the API that is fully validated, but no data is persisted in the system. Mock shipments are created with simulated tracking events to support a subsequent tracking operation.
The API can be exercised in several ways:
- cURL can be used to send both raw POST and GET requests to the API.
- Swagger UI can be used to send both POST and GET requests to the API. Swagger also offers the ability to create a client SDK in a variety of languages.
- Postman can be used to import the OAS 3.0 API definition to create both POST and GET method calls.
To test with cURL, simply copy the text below and paste into a command line. Replace <CLIENT_API_KEY> in these requests with a valid API key, the <ACCOUNT_NUMBER> with a valid account number, and <PICKUP_ADDRESS_ID> with the appropriate value.
curl -X POST https://api-dev.zonejump.com/shipments \
-H 'Content-Type: application/json' \
-H 'X-Api-Key: <CLIENT_API_KEY>' \
-H 'cache-control: no-cache' \
-d '{
"requestId": "1564602222443",
"accountNumber": "ACCOUNT_NUMBER",
"serviceCode": "ZJG",
"pickupAddressId": "PICKUP_ADDRESS_ID",
"deliveryAddress": {
"name": "Dean A Meyer",
"street": "219 Via Fortuna",
"city": "Henderson",
"state": "NV",
"zip": "89011",
"phone": "7020001111",
"residence": true
},
"package": {
"shipperName": "ABC Retail",
"weight": 0.75,
"length": 4,
"width": 6,
"height": 8,
"type": "PACKAGE",
"isIataDangerousGoods": false,
"signatureRequired": false,
"saturdayDelivery": true,
"declaredValue": 0,
"increaseLiabilityLimit": false,
"shipDate": 2025-07-31T12:43:42-07:00"
}
}'
Using the tracking number from a prior shipment request, a tracker test request can be issued with a GET method.
curl -X GET https://api-dev.zonejump.com/shipments/<TRACKING_NUMBER> \
-H 'x-api-key: <CLIENT_API_KEY>' \
-H 'Accept: */*'
You can test the API with a valid API key using Swagger UI
or, alternatively, download the Open API Specification (OAS) 3.0
file
and import it into Postman or other tooling. Refer to the respective user guides for these
tools regarding their proper use to exercise the API.