Partner Integration API

Once onboarded, you'll receive an API key. Include it in every request via the X-Api-Key header.

POST https://api.ezzyride.com/partner-api/v1/sync
Headers:
  X-Api-Key:    YOUR_API_KEY
  Content-Type: application/json
  Accept:       application/json

Send an array of vehicle objects. Maximum 500 vehicles per request.

{
  "vehicles": [
    {
      "external_reference": "SBT-12345",      // Required — your unique ID
      "brand":              "Toyota",
      "model":              "Land Cruiser",
      "year":               2022,
      "transmission":       "Automatic",
      "fuel_type":          "Diesel",
      "mileage":            45000,
      "engine_cc":          2800,
      "selling_price":      85000000,
      "color":              "White",
      "status":             "In Stock",
      "features":           "Sunroof|Leather Seats|Navigation",
      "description":        "Clean vehicle, low mileage…"
    }
  ]
}

Field Reference

A successful sync returns a summary of what happened.

{
  "success": true,
  "data": {
    "sync_id":        42,
    "total_vehicles": 15,
    "imported_count": 14,
    "failed_count":   1,
    "skipped_count":  0,
    "errors": [
      { "index": 7, "message": "Missing external_reference" }
    ]
  }
}

• Upsert behavior: If a vehicle with the same external_reference already exists, it will be updated — not duplicated.
• Field mapping: You can use your own field names. We configure the mapping on our side so you don't need to change your data format.
• Value mapping: Enum values (transmission, fuel type, etc.) are mapped automatically. Send values in your own format.
• Rate limit: Maximum 500 vehicles per request. For larger inventories, batch into multiple requests.
• Smart pricing: Price fields accept formatted strings like "UGX 85,000,000" or "85.5M" — they are parsed automatically.
• Features: Send features/extras as a delimited string (pipes |, commas, or semicolons). During onboarding, share a sample payload with your account manager so they can map your feature names to our system. Use your own naming — no changes needed on your end.
• Images: Include an images array with publicly accessible URLs (not behind authentication). Supported formats: JPEG, PNG, WebP. We download and store them on first sync. The first URL becomes the primary image.
• Video: Include a videoUrl field with a YouTube or video link for the vehicle listing.
• Removing vehicles: To remove a vehicle from the website, send it with "status": "sold" or "status": "draft" in your next sync. Sold vehicles are taken offline automatically. Draft vehicles are hidden from the public listing.
• Pricing: For international partners, send the CIF price in your configured currency (e.g. USD). We convert it to UGX using the current market rate for display. For local partners, send the price in UGX as-is.

1. Vehicles land as unpublished drafts — they are not visible on the website until reviewed by the EzzyRide team.
2. Our team reviews and publishes — we verify details, check images, and make the listing live. This typically happens within 24 hours.
3. Customers browse and inquire — once live, customers can view the vehicle, calculate estimated costs, and submit a purchase request.
4. You get notified — if you've configured a purchase callback URL, your system receives a notification automatically. Otherwise, your EzzyRide account manager will contact you directly.

When a customer on EzzyRide requests to purchase one of your vehicles, we can notify your system automatically. During onboarding, provide a callback URL to your account manager. We will send a POST request whenever a purchase request is made.

Request We Send

POST https://your-system.com/api/purchase-callback
Headers:
  Content-Type: application/json

{
  "event": "purchase_request",
  "external_reference": "YOUR-STOCK-REF",
  "vehicle_reference": "EZR-2026-00042",
  "vehicle": "Toyota Land Cruiser 2022",
  "customer": {
    "name":  "John Doe",
    "email": "john@example.com",
    "phone": "+256700123456"
  },
  "application_reference": "IMP-2026-00015",
  "requested_at": "2026-04-05T10:30:00+03:00"
}

Expected Response — Vehicle Available

{
  "success": true,
  "message": "Purchase request received",
  "partner_reference": "PR-2026-0042"  // optional — your internal tracking reference
}

Expected Response — Vehicle No Longer Available

If the vehicle has already been sold, reserved, or is otherwise unavailable on your side, respond with "success": false and a reason field. We will automatically release the reservation on our end and notify our team.

{
  "success": false,
  "reason": "sold",          // "sold", "reserved", or "unavailable"
  "message": "This vehicle was sold yesterday"  // optional — additional context
}

• We use the external_reference (your stock number) to identify the vehicle.
• If your endpoint returns a non-2xx status, we will retry up to 3 times with 60-second intervals.
• Accepted reason values: sold, reserved, unavailable
• This is optional — if no callback URL is configured, purchase requests are handled manually by your EzzyRide account manager.