Platform Docs

The Sail API provides a comprehensive delivery platform that connects you to multiple providers through a single, unified interface. See our pricing for plan limits and rates.

• Multi-Provider Support: Connect to Bolt, Uber, and Yango through one API
• Unified Interface: Consistent request/response format across all providers
• Real-time Pricing: Get accurate quotes and delivery estimates
• Provider Management: Easily connect and disconnect provider accounts
• Status Tracking: Monitor delivery progress with comprehensive status updates

The Sail API acts as a unified layer on top of multiple delivery providers, abstracting away the differences between their individual APIs. This allows you to integrate once and get access to multiple providers seamlessly.

All API requests should be made to https://api.sailrides.co. All endpoints are versioned and prefixed with /v1.

https://api.sailrides.co/v1/deliveries/quotes
https://api.sailrides.co/v1/deliveries
https://api.sailrides.co/v1/deliveries/{'{deliveryId}'}

All API requests must be authenticated using your API key in the Authorization header:

Authorization: ApiKey sail_prod_compass_abc123...

To get your API key:

• Sign in to your Sail Platform account
• Click “Create API Key” in the Getting Started section
• Copy your key immediately - it won’t be shown again for security reasons
• Store it securely in your environment variables

API keys follow the format: sail_prod_{theme}_{random_string}

• sail_prod: Production key prefix
• {theme}: Nautical theme (anchor, voyage, compass, etc.)
• {random_string}: Cryptographically secure random string

• Store your API key in environment variables, not in code
• Never commit API keys to version control
• Rotate your API key if you suspect it’s been compromised
• Use HTTPS for all API requests

API requests are rate limited per API key to ensure fair usage:

• Quotes: 100 requests per minute
• Deliveries: 50 requests per minute
• Status Checks: 200 requests per minute

Rate limit headers are included in all responses:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 99
X-RateLimit-Reset: 1695123456

When you receive a 429 Too Many Requests response:

• Check the X-RateLimit-Reset header for when the limit resets
• Implement exponential backoff for retries
• Consider webhook notifications instead of polling for high-frequency updates

Get delivery quotes from all connected providers for a given pickup and destination.

{
	"pickup": {
		"lat": 5.6037,
		"lng": -0.1870,
		"address": "Optional pickup address"
	},
	"destination": {
		"lat": 5.5600,
		"lng": -0.2050,
		"address": "Optional destination address"
	}
}

• pickup.lat, pickup.lng: Pickup coordinates (decimal degrees)
• destination.lat, destination.lng: Destination coordinates (decimal degrees)
• pickup.address, destination.address: Human-readable addresses for reference

{
	"quotes": [
		{
			"id": "quote_abc123",
			"provider": "bolt",
			"service_name": "Send by Bike",
			"price": {
				"amount": 12.5,
				"currency": "GHS"
			},
			"eta_minutes": 5,
			"expires_at": "2024-01-15T14:10:00Z"
		},
		{
			"id": "quote_def456",
			"provider": "yango",
			"service_name": "Express Cargo",
			"price": {
				"amount": 45.0,
				"currency": "GHS"
			},
			"eta_minutes": 8,
			"expires_at": "2024-01-15T14:10:00Z",
			"configuration": {
				"options": [
					{
						"id": "vehicle_size",
						"label": "Vehicle size",
						"description": "Size of the delivery truck",
						"choices": [
							{ "id": "xs", "label": "Extra Small (Aboboyaa)", "isDefault": false },
							{ "id": "small", "label": "Small", "isDefault": true },
							{ "id": "medium", "label": "Medium", "isDefault": false }
						]
					},
					{
						"id": "assistance",
						"label": "Loading assistance",
						"choices": [
							{ "id": "none", "label": "No helpers", "isDefault": true },
							{ "id": "driver_help", "label": "1 helper", "isDefault": false }
						]
					}
				],
				"defaults": {
					"vehicle_size": "small",
					"assistance": "none"
				}
			}
		},
		{
			"id": "quote_ghi789",
			"provider": "yango",
			"service_name": "Express Small (Priority)",
			"base_service_name": "Express Small",
			"urgency": {
				"code": "priority",
				"label": "Priority",
				"provider_label": "Urgent"
			},
			"price": {
				"amount": 15.0,
				"currency": "GHS"
			},
			"eta_minutes": 9,
			"expires_at": "2024-01-15T14:10:00Z"
		}
	],
	"meta": {
		"total_providers": 3,
		"successful_providers": 2,
		"delivery_options_count": 3,
		"warnings": []
	}
}

• quotes.id: Unique quote identifier for booking
• quotes.provider: Provider name (bolt, uber, yango)
• quotes.service_name: Display name of the service
• quotes.price.amount: Total price in local currency
• quotes.price.currency: 3-letter currency code
• quotes.eta_minutes: Estimated time to pickup in minutes
• quotes.expires_at: Quote expiration time (ISO 8601)
• quotes.configuration: (optional) Available delivery options for this service — only present on courier/cargo services. Pass selected options when booking.
• meta.delivery_options_count: Total number of delivery quotes returned
• quotes.base_service_name: (optional) Base service name without urgency modifier — only present on urgency tier quotes
• quotes.urgency: (optional) Urgency tier details — only present when the quote is a speed/price variant of a base service
• quotes.urgency.code: Stable identifier (priority, standard, scheduled) for programmatic use
• quotes.urgency.label: Display-friendly tier name
• quotes.urgency.provider_label: Original provider wording (e.g. “Urgent”, “A bit longer”, “In 2 hours”)
• quotes.urgency.description: (optional) Additional context about the tier

Common Error Responses:

{
	"error": {
		"code": "invalid_location",
		"message": "Pickup or destination location is invalid",
		"details": {
			"field": "pickup",
			"reason": "coordinates_outside_service_area"
		}
	}
}

• invalid_location: Coordinates outside service area
• no_providers_available: No providers servicing the route
• rate_limited: Too many quote requests
• invalid_coordinates: Malformed coordinate data

Manage delivery lifecycle from booking to completion.

Book a delivery using a previously obtained quote ID.

{
	"quoteId": "quote_1234567890",
	"webhookUrl": "https://your-app.com/webhooks/sail",
	"customerInfo": {
		"name": "John Doe",
		"phone": "+233123456789"
	},
	"options": {
		"vehicle_size": "small",
		"assistance": "none"
	}
}

• quoteId: Valid quote ID (must not be expired)
• webhookUrl: URL to receive status updates
• customerInfo: Customer contact information
• options: (optional) Delivery configuration overrides — use option IDs from the quote’s configuration.options (e.g. vehicle_size, assistance). If omitted, provider defaults apply.

Note: Pickup and destination must be at least 100 meters apart. Requests with locations closer than this will be rejected with a distance_too_short error.

{
	"delivery_id": "delivery_1234567890",
	"provider_booking_id": "9f3b4f36-d3ae-4716-a7f3-ccdfc8fdaf70"
}

Retrieve delivery status and details.

{
	"id": "delivery_1234567890",
	"provider": "yango",
	"status": "accepted",
	"created_at": "2024-01-15T14:05:00Z",
	"updated_at": "2024-01-15T14:06:30Z",
	"pickup": {
		"lat": 5.6764,
		"lng": -0.1443
	},
	"destination": {
		"lat": 5.6536,
		"lng": -0.1304
	},
	"estimated_fare": {
		"amount": 15,
		"currency": "GHS"
	},
	"tracking": {
		"driver": {
			"name": "Oko Enoch Boadu",
			"picture_url": "https://example.com/driver-photo.jpg",
			"rating": 4.9,
			"phone": "+233201234567"
		},
		"vehicle": {
			"make": "Honda",
			"model": "Bike Courier",
			"license_plate": "GR-1764"
		},
		"eta": "13 min",
		"pin": null,
		"live_position": {
			"lat": 5.6750,
			"lng": -0.1450,
			"direction": 180
		},
		"waiting_info": null,
		"sharing_url": "https://yango.com/track/abc123"
	}
}

• id: Delivery identifier
• provider: Provider handling the delivery (bolt, yango, uber)
• status: Current delivery status
• pickup, destination: Coordinates for each location
• estimated_fare: Price and currency
• tracking: (present while delivery is active) Real-time tracking details
• tracking.driver: Driver name, photo URL, rating, and phone number (when available)
• tracking.vehicle: Vehicle make, model, and license plate
• tracking.eta: Estimated time of arrival
• tracking.pin: Verification PIN (if required by provider)
• tracking.live_position: Driver’s current lat/lng and bearing
• tracking.sharing_url: (optional) Provider’s live tracking link — shareable with recipients

Deliveries progress through these statuses:

• booking - Order placed, searching for a driver
• accepted - Driver assigned to your delivery
• arriving - Driver is heading to or at the pickup location
• picked_up - Package collected by driver
• in_transit - Driver en route to destination
• delivered - Delivery completed successfully
• cancelled - Delivery cancelled by user or driver
• failed - Delivery failed (no drivers available, expired, payment issue)

Cancel an active delivery.

Note: Only deliveries in booking, accepted, or arriving status can be cancelled.

No request body required.

Status polling is an alternative to webhooks for monitoring delivery progress. Poll delivery status at regular intervals to track updates.

Use polling when:

• Your application cannot receive webhook requests
• You need real-time status updates for specific deliveries
• You want to supplement webhook notifications
• You’re building a simple application without webhook infrastructure

Use webhooks when:

• You need to monitor many deliveries simultaneously
• You want instant notifications
• You want to reduce API calls
• You have server infrastructure to receive webhooks

Recommended polling frequencies based on delivery status:

• Active statuses (booking, accepted, arriving): Every 30-60 seconds
• In-transit (picked_up, in_transit): Every 60-120 seconds
• Final statuses (delivered, cancelled, failed): Stop polling

Rate Limiting Considerations:

• Respect the 200 requests/minute limit for delivery tracking endpoints
• Implement backoff for failed requests
• Use exponential backoff for rate-limited responses

• Set reasonable timeouts - Don’t wait indefinitely for responses
• Handle rate limits gracefully - Implement exponential backoff
• Store delivery state - Avoid re-polling completed deliveries
• Use conditional requests - Check Last-Modified headers if available
• Monitor API usage - Track your request count to avoid hitting limits
• Have a fallback - Consider switching to webhooks if polling becomes inefficient

Webhooks provide real-time notifications when delivery status changes occur. Instead of constantly polling our API, you can receive immediate updates by configuring webhook endpoints.

Configure your webhook URL when creating a delivery by including the webhookUrl field in your request. The webhook URL will receive real-time notifications for that delivery.

Webhook URL Requirements:

• Must be publicly accessible
• Should respond within 5 seconds
• Must return a 200 status code
• Supports HTTPS endpoints only

The following events are sent via webhooks:

All webhook payloads contain this structure:

{
  "event": "delivery.status_updated",
  "data": {
    "deliveryId": "delivery_1234567890",
    "status": "accepted",
    "timestamp": "2024-01-15T10:30:00Z",
    "provider": "yango",
    "trackingInfo": null
  },
  "timestamp": "2024-01-15T10:30:00Z"
}

Payload Fields:

• event: Type of event (see Webhook Events above)
• data.deliveryId: The delivery ID
• data.status: New delivery status
• data.provider: Provider handling the delivery (bolt, yango, uber)
• data.trackingInfo: Tracking details if available
• timestamp: When the webhook was sent (ISO 8601)

All webhook requests include security headers:

Headers:

• X-Sail-Signature: HMAC-SHA256 signature of the payload
• X-Sail-Timestamp: Unix timestamp of when webhook was sent

Signature Verification: The signature is calculated as: HMAC-SHA256(secret, payload)

Security Best Practices:

• Always verify webhook signatures
• Reject requests older than 5 minutes
• Use HTTPS for webhook endpoints
• Keep your webhook secret secure
• Implement rate limiting

Reliability Features:

• Automatic retries for failed deliveries
• Exponential backoff retry strategy
• Maximum of 5 retry attempts
• 5-second timeout per attempt

Retry Schedule:

• Attempt 1: Immediate
• Attempt 2: 30 seconds later
• Attempt 3: 2 minutes later
• Attempt 4: 10 minutes later
• Attempt 5: 30 minutes later

If all retries fail, the webhook is marked as failed and you can view failed attempts in your dashboard.

Use these tools to test webhooks during development:

• ngrok - Expose local endpoints to the internet
• webhook.site - Temporary webhook URL for testing
• RequestBin - Inspect webhook requests
• Local testing - Use curl to simulate webhook calls

# Test webhook locally with curl
curl -X POST http://localhost:3000/webhooks/sail \
  -H "Content-Type: application/json" \
  -H "X-Sail-Signature: sha256=test_signature" \
  -H "X-Sail-Timestamp: $(date +%s)" \
  -d '{"event":"delivery.status_updated","data":{"status":"delivered"}}'

• Respond quickly - Return within 5 seconds
• Process asynchronously - Don’t block webhook delivery
• Idempotency - Handle duplicate webhook deliveries
• Retry strategy - Implement your own retry logic for critical failures
• Logging - Log all webhook events for debugging
• Have fallback - Use polling if webhooks fail repeatedly

The API uses conventional HTTP status codes and returns detailed error information in JSON format to help you troubleshoot issues.

All error responses follow this consistent format:

{
	"error": {
		"code": "quote_expired",
		"message": "Quote not found or has expired — request new quotes"
	},
	"request_id": "req_1234567890_abc123def"
}

• error.code: Machine-readable error code for programmatic handling
• error.message: Human-readable error description
• request_id: Unique identifier for the request (useful for support)

• 200 OK: Request successful
• 201 Created: Resource created successfully
• 400 Bad Request: Invalid JSON or missing required fields
• 401 Unauthorized: Invalid or missing API key
• 403 Forbidden: Insufficient permissions
• 404 Not Found: Invalid delivery ID or endpoint
• 409 Conflict: Resource state conflict
• 422 Unprocessable Entity: Valid JSON but invalid data
• 429 Rate Limited: Too many requests
• 500 Internal Server Error: Unexpected server error
• 502 Bad Gateway: Upstream provider error
• 503 Service Unavailable: Temporary service outage

Authentication Errors

• auth_failed (401): Invalid or missing API key

Quote Errors

• missing_fields (400): Both pickup and destination are required
• invalid_coordinates (400): Coordinates must have lat and lng
• client_not_found (400): Invalid client configuration
• no_connected_accounts (403): No provider accounts connected
• quote_failed (500): Failed to retrieve delivery quotes

Booking Errors

• missing_quote_id (400): quoteId is required
• quote_expired (404): Quote not found or has expired
• quote_unauthorized (403): Quote belongs to a different client
• quote_stale (400): Quote is missing required data
• provider_not_connected (403): No provider account connected for this client
• no_active_connections (403): All provider connections are inactive
• booking_limit_reached (429): Monthly booking limit reached
• distance_too_short (400): Pickup and destination are too close (minimum 100m apart)
• booking_failed (502): Provider could not complete the booking

Delivery Errors

• delivery_not_found (404): Delivery does not exist or you do not have access
• not_cancellable (409): Delivery status does not allow cancellation
• provider_config_error (400): Provider configuration is incomplete
• cancel_not_supported (400): Cancellation not yet supported for this provider
• cancel_failed (502): Provider could not cancel the delivery
• tracking_failed (500): Failed to retrieve delivery status

Rate Limiting

• rate_limited (429): Too many requests per minute

All responses include these important headers:

Success Responses:

X-Sail-Status: Smooth Sailing
Content-Type: application/json
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 99
X-RateLimit-Reset: 1695123456
X-Request-ID: req_abc123def456

Error Responses:

X-Sail-Status: Rough Seas
Content-Type: application/json
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 98
X-RateLimit-Reset: 1695123456
X-Request-ID: req_abc123def456

• Smooth Sailing: Request successful (2xx)
• Rough Seas: Error response (4xx, 5xx)
• Becalmed: Rate limited (429)

1. Always Check HTTP Status

const response = await fetch(url, options);

if (!response.ok) {
  const error = await response.json();
  handleApiError(error);
  return;
}

const data = await response.json();

2. Handle Rate Limits Gracefully

if (response.status === 429) {
  const resetTime = parseInt(response.headers.get('X-RateLimit-Reset'));
  const waitTime = resetTime - Math.floor(Date.now() / 1000);

  if (waitTime > 0) {
    await new Promise(resolve => setTimeout(resolve, waitTime * 1000));
    // Retry the request
  }
}

3. Use Request IDs for Debugging

const requestId = response.headers.get('X-Request-ID');
console.log(`Request ${requestId} failed:`, error);

4. Implement Exponential Backoff

async function makeRequestWithRetry(url, options, maxRetries = 3) {
  for (let attempt = 0; attempt <= maxRetries; attempt++) {
    try {
      const response = await fetch(url, options);

      if (response.ok || response.status < 500) {
        return response; // Success or client error - don't retry
      }

      if (attempt === maxRetries) break;

      // Exponential backoff
      const delay = Math.min(1000 * Math.pow(2, attempt), 30000);
      await new Promise(resolve => setTimeout(resolve, delay));

    } catch (error) {
      if (attempt === maxRetries) throw error;

      const delay = Math.min(1000 * Math.pow(2, attempt), 30000);
      await new Promise(resolve => setTimeout(resolve, delay));
    }
  }

  throw new Error('Max retries exceeded');
}

5. Log Errors Appropriately

function logApiError(error, context = {}) {
  const logLevel = getLogLevel(error.code);

  console[logLevel]('API Error:', {
    code: error.code,
    message: error.message,
    requestId: context.requestId,
    timestamp: new Date().toISOString(),
    ...context
  });
}

function getLogLevel(errorCode) {
  const clientErrors = ['invalid_api_key', 'missing_required_field', 'invalid_quote'];
  const serverErrors = ['internal_error', 'provider_unavailable'];

  if (clientErrors.includes(errorCode)) return 'warn';
  if (serverErrors.includes(errorCode)) return 'error';
  return 'info';
}

Common Issues and Solutions

• 401 Unauthorized: Verify API key in Authorization header format: ApiKey your_key
• 429 Rate Limited: Implement rate limiting and exponential backoff
• Quote expired: Request a new quote before creating delivery
• Delivery not found: Verify delivery ID and account permissions
• Provider unavailable: Try again later or use different provider

The Sail widget allows you to embed ride price comparison directly into your website. Visitors can see real-time prices from multiple providers (Bolt, Uber, Yango) to reach your location.

Use cases:

• Event venues showing attendees how much it costs to get there
• Hotels displaying ride prices from airports
• Restaurants helping customers plan their visit
• Conference centers with pre-configured destination

1. Go to the Widgets page in your Platform dashboard
2. Click Create Widget and configure:
   • Name: A friendly name (e.g., “Homepage Widget”)
   • Allowed Domains: Enter up to 3 domains (e.g., yoursite.com). Press Enter or Comma to add each domain.
   • Destination (optional): Pre-configure your venue’s location
3. Use the Mobile Preview (eye icon on mobile) to test how it looks on smaller screens
4. Copy your Public Key (sail_pub_...)
5. Add the embed code to your website

* Either lat/lng or place_id is required. You can also set these in your widget configuration.

The simplest way to embed the widget. Copy and paste this HTML, customizing the destination and widget key.

Important: Include allow="geolocation" for the widget to access the user’s location.

A cleaner approach using a custom HTML element. Include the widget script and use the <sail-ride-widget> element.

For programmatic control, use the JavaScript API to create and configure widgets dynamically.

API Options:

SailWidget.init(selector, {
  destination: {
    lat: number,        // Required if no placeId
    lng: number,        // Required if no placeId
    placeId: string,    // Alternative to lat/lng
    name: string,       // Optional display name
    address: string     // Optional display address
  },
  theme: 'light' | 'dark' | 'auto',
  widgetKey: string,
  height: string,       // Default: '420px'
  width: string,        // Default: '100%'
  maxWidth: string      // Default: '420px'
});

Instead of coordinates, you can use a Google Place ID for your destination:

Find your venue’s Place ID using the Google Place ID Finder.

Geolocation Permission The widget requires user location permission to calculate ride prices. Users will be prompted when they click “Compare Ride Prices”.

Domain Whitelisting Your widget key is tied to specific domains (max 3 allowed per widget). You can manage allowed domains from the Widgets dashboard.

HTTPS Required The widget must be embedded on HTTPS pages for geolocation to work properly.

Rate Limiting Widget requests are rate-limited per key. For high-traffic sites, contact us for increased limits.

Mobile Support The widget is fully responsive and works on mobile devices. The iframe adapts to the container width.