API Overview

The Dispatch API provides programmatic access to all platform features, enabling you to build integrations, automate workflows, and extend functionality.

Introduction

What is the Dispatch API?

The Dispatch API is a RESTful web service that allows you to:

• Create and manage orders programmatically
• Track shipments in real-time
• Manage customers and products
• Integrate with external systems
• Automate business processes

Base URL

All API requests are made to:

https://api.dispatch.example.com/api

Replace with your actual API endpoint.

Versioning

The API uses URL-based versioning:

• /api/v1/ - Version 1 endpoints
• /api/ - Default/current version

Getting Started

Prerequisites

To use the API, you need:

1. An active Dispatch account
2. API access enabled for your plan
3. An API token

Generating API Tokens

Create an API token:

1. Log into Dispatch
2. Go to Settings > API Access
3. Click "Generate New Token"
4. Copy and securely store the token

warning

API tokens are shown only once when created. Store them securely.

Making Requests

Request Format

API requests use standard HTTP methods:

Method	Purpose
GET	Retrieve data
POST	Create new resources
PUT	Update existing resources
PATCH	Partial updates
DELETE	Remove resources

Headers

Include these headers with requests:

Authorization: Bearer YOUR_API_TOKEN
Content-Type: application/json
Accept: application/json

Example Request

curl -X GET "https://api.dispatch.example.com/api/v1/Orders" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Accept: application/json"

Response Format

Success Responses

Successful requests return:

{
  "data": {
    // Requested data
  },
  "success": true
}

Paginated Responses

List endpoints return paginated results:

{
  "data": [
    // Array of items
  ],
  "page": 1,
  "pageSize": 50,
  "totalCount": 250,
  "totalPages": 5,
  "success": true
}

Error Responses

Errors return appropriate HTTP status codes:

{
  "success": false,
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable error message"
  }
}

Common Parameters

Pagination

Control pagination with query parameters:

Parameter	Description	Default
Page	Page number	1
PageSize	Items per page	50

Example:

GET /api/v1/Orders?Page=2&PageSize=25

Filtering

Use OData-style filtering:

Parameter	Description
$filter	Filter expression
$orderby	Sort order
$search	Search text

Example:

GET /api/v1/Orders?$filter=status eq 'pending'&$orderby=createdDate desc

Searching

Search across fields:

GET /api/v1/Customers?$search=john

HTTP Status Codes

Code	Meaning
200	Success
201	Created
400	Bad Request
401	Unauthorized
403	Forbidden
404	Not Found
409	Conflict
500	Server Error

Rate Limiting

Limits

API requests are rate limited:

• Limits vary by plan
• Check response headers for current status

Rate Limit Headers

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1234567890

Handling Limits

If rate limited:

1. Wait for reset time
2. Implement exponential backoff
3. Consider upgrading plan

API Resources

Core Resources

• Business - Business management
• Customers - Customer management
• Orders - Order management
• Shipments - Shipment management
• Products - Product management

Operations Resources

• Carriers - Carrier configuration
• Dispatch - Dispatch operations
• Vehicles - Vehicle tracking

Integration Resources

• Integrations - E-commerce and external integrations

Best Practices

Security

1. Keep tokens secret - Never expose in client-side code
2. Use HTTPS - All requests over secure connection
3. Rotate tokens - Periodically update tokens
4. Limit scope - Create tokens with minimal needed access

Performance

1. Paginate requests - Don't fetch all data at once
2. Cache responses - Reduce unnecessary requests
3. Use webhooks - For real-time updates instead of polling
4. Batch when possible - Reduce number of requests

Error Handling

1. Check status codes - Handle all response types
2. Parse error messages - Log for debugging
3. Implement retry - For transient failures
4. Monitor errors - Track API error rates

Support

Getting Help

If you need API assistance:

1. Review this documentation
2. Check endpoint-specific docs
3. Contact support with details

Reporting Issues

When reporting API issues, include:

• Request details (method, URL, headers)
• Response received
• Expected behavior
• Timestamp of request