{"openapi":"3.1.0","info":{"title":"Sendam Courier API","version":"1.0.0","description":"Use Sendam as the courier for your store, marketplace or ERP: quote a delivery, create a shipment, track it and receive signed webhooks. Cashless by design; shipments are paid from your prepaid wallet. Live in Lagos; Abuja and Port Harcourt are coming soon."},"servers":[{"url":"https://sendam.tailorlinks.org/api/v1"}],"security":[{"bearerAuth":[]}],"paths":{"/coverage":{"get":{"summary":"Cities and known landmarks","security":[],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/quotes":{"post":{"summary":"Price a delivery","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["dropoff"],"properties":{"pickup":{"type":"object","description":"Optional. Defaults to your saved shop address.","properties":{"name":{"type":"string","example":"Ngozi Nwosu"},"phone":{"type":"string","example":"08162209034"},"landmark":{"type":"string","example":"Opposite Mega Chicken, yellow gate"},"street":{"type":"string","example":"14 Admiralty Way"},"area":{"type":"string","example":"Lekki Phase 1"},"place_id":{"type":"string","example":"lekki-admiralty"},"lat":{"type":"number","example":6.447},"lng":{"type":"number","example":3.473},"notes":{"type":"string"}}},"dropoff":{"type":"object","description":"Send lat and lng (preferred), or a place_id / area from GET /coverage. Landmark-first: tell the rider what they will see.","properties":{"name":{"type":"string","example":"Ngozi Nwosu"},"phone":{"type":"string","example":"08162209034"},"landmark":{"type":"string","example":"Opposite Mega Chicken, yellow gate"},"street":{"type":"string","example":"14 Admiralty Way"},"area":{"type":"string","example":"Lekki Phase 1"},"place_id":{"type":"string","example":"lekki-admiralty"},"lat":{"type":"number","example":6.447},"lng":{"type":"number","example":3.473},"notes":{"type":"string"}}},"vehicle":{"type":"string","enum":["bike","van"],"default":"bike"},"express":{"type":"boolean","description":"2-hour delivery, same side of town only","default":false},"parcel":{"type":"object","properties":{"description":{"type":"string","example":"2 Ankara gowns"},"size":{"type":"string","enum":["small","medium","large"],"default":"medium"},"declared_value":{"type":"integer","description":"Naira","example":35000},"protection":{"type":"boolean","default":false}}}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Quote"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed; see error.fields","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/shipments":{"post":{"summary":"Create a shipment","description":"Debits your wallet and queues the delivery for dispatch. Send an Idempotency-Key header so retries never create duplicates.","parameters":[{"name":"Idempotency-Key","in":"header","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["dropoff","parcel"],"properties":{"pickup":{"type":"object","description":"Optional. Defaults to your saved shop address.","properties":{"name":{"type":"string","example":"Ngozi Nwosu"},"phone":{"type":"string","example":"08162209034"},"landmark":{"type":"string","example":"Opposite Mega Chicken, yellow gate"},"street":{"type":"string","example":"14 Admiralty Way"},"area":{"type":"string","example":"Lekki Phase 1"},"place_id":{"type":"string","example":"lekki-admiralty"},"lat":{"type":"number","example":6.447},"lng":{"type":"number","example":3.473},"notes":{"type":"string"}}},"dropoff":{"type":"object","description":"Send lat and lng (preferred), or a place_id / area from GET /coverage. Landmark-first: tell the rider what they will see.","properties":{"name":{"type":"string","example":"Ngozi Nwosu"},"phone":{"type":"string","example":"08162209034"},"landmark":{"type":"string","example":"Opposite Mega Chicken, yellow gate"},"street":{"type":"string","example":"14 Admiralty Way"},"area":{"type":"string","example":"Lekki Phase 1"},"place_id":{"type":"string","example":"lekki-admiralty"},"lat":{"type":"number","example":6.447},"lng":{"type":"number","example":3.473},"notes":{"type":"string"}}},"vehicle":{"type":"string","enum":["bike","van"],"default":"bike"},"express":{"type":"boolean","description":"2-hour delivery, same side of town only","default":false},"parcel":{"type":"object","properties":{"description":{"type":"string","example":"2 Ankara gowns"},"size":{"type":"string","enum":["small","medium","large"],"default":"medium"},"declared_value":{"type":"integer","description":"Naira","example":35000},"protection":{"type":"boolean","default":false}}},"reference":{"type":"string","description":"Your own order number","example":"ORDER-10492"},"buyer_confirms_address":{"type":"boolean","description":"WhatsApp the receiver a link to confirm their pin before dispatch","default":false},"see_am_first":{"type":"object","description":"Collect the item price in escrow; the receiver's delivery code releases it to you.","properties":{"item_price":{"type":"integer","minimum":1000,"example":35000}}}}}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Shipment"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Wallet balance too low","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation failed; see error.fields","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"get":{"summary":"List shipments","parameters":[{"name":"limit","in":"query","schema":{"type":"integer","default":20,"maximum":100}},{"name":"status","in":"query","schema":{"type":"string","enum":["awaiting_confirmation","ready","assigned","at_pickup","picked_up","arriving","delivered","failed","returned","cancelled"]}},{"name":"reference","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"const":"list"},"total":{"type":"integer"},"data":{"type":"array","items":{"$ref":"#/components/schemas/Shipment"}}}}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/shipments/{id}":{"get":{"summary":"Retrieve a shipment","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"SND-4KQ7P"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Shipment"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/shipments/{id}/cancel":{"post":{"summary":"Cancel before pickup","description":"Refunds the delivery fee to your wallet and any See Am First payment to the buyer.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Shipment"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Already picked up","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"webhooks":{"shipmentEvent":{"post":{"summary":"Shipment and escrow events","description":"Sent to your webhook URL with header X-Sendam-Signature: t=<unix seconds>,v1=<hex HMAC-SHA256(secret, t + '.' + raw body)>. Types: shipment.<status>, escrow.released, escrow.refunded, ping.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string","example":"shipment.delivered"},"created_at":{"type":"string","format":"date-time"},"data":{"$ref":"#/components/schemas/Shipment"}}}}}},"responses":{"200":{"description":"Return any 2xx within 8 seconds"}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"Your secret key, e.g. sk_test_…"}},"schemas":{"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"fields":{"type":"object","additionalProperties":{"type":"string"}}}}}},"Quote":{"type":"object","properties":{"object":{"const":"quote"},"currency":{"const":"NGN"},"total":{"type":"integer"},"vat":{"type":"integer"},"delivery_fee":{"type":"integer"},"protection_fee":{"type":"integer"},"discount":{"type":"integer"},"distance_km":{"type":"number"},"eta_minutes":{"type":"integer"},"delivery_window":{"type":"string"},"crosses_bridge":{"type":"boolean"},"wallet_balance":{"type":"integer"}}},"Shipment":{"type":"object","properties":{"id":{"type":"string","example":"SND-4KQ7P"},"object":{"const":"shipment"},"reference":{"type":["string","null"]},"status":{"type":"string","enum":["awaiting_confirmation","ready","assigned","at_pickup","picked_up","arriving","delivered","failed","returned","cancelled"]},"status_label":{"type":"string"},"city":{"type":"string","example":"lagos"},"vehicle":{"type":"string"},"express":{"type":"boolean"},"pickup":{"type":"object","description":"Send lat and lng (preferred), or a place_id / area from GET /coverage. Landmark-first: tell the rider what they will see.","properties":{"name":{"type":"string","example":"Ngozi Nwosu"},"phone":{"type":"string","example":"08162209034"},"landmark":{"type":"string","example":"Opposite Mega Chicken, yellow gate"},"street":{"type":"string","example":"14 Admiralty Way"},"area":{"type":"string","example":"Lekki Phase 1"},"place_id":{"type":"string","example":"lekki-admiralty"},"lat":{"type":"number","example":6.447},"lng":{"type":"number","example":3.473},"notes":{"type":"string"}}},"dropoff":{"type":"object","description":"Send lat and lng (preferred), or a place_id / area from GET /coverage. Landmark-first: tell the rider what they will see.","properties":{"name":{"type":"string","example":"Ngozi Nwosu"},"phone":{"type":"string","example":"08162209034"},"landmark":{"type":"string","example":"Opposite Mega Chicken, yellow gate"},"street":{"type":"string","example":"14 Admiralty Way"},"area":{"type":"string","example":"Lekki Phase 1"},"place_id":{"type":"string","example":"lekki-admiralty"},"lat":{"type":"number","example":6.447},"lng":{"type":"number","example":3.473},"notes":{"type":"string"}}},"parcel":{"type":"object","properties":{"description":{"type":"string","example":"2 Ankara gowns"},"size":{"type":"string","enum":["small","medium","large"],"default":"medium"},"declared_value":{"type":"integer","description":"Naira","example":35000},"protection":{"type":"boolean","default":false}}},"price":{"type":"object","properties":{"currency":{"const":"NGN"},"total":{"type":"integer"},"vat":{"type":"integer"},"delivery_fee":{"type":"integer"}}},"distance_km":{"type":"number"},"delivery_window":{"type":"string"},"see_am_first":{"type":["object","null"],"properties":{"item_price":{"type":"integer"},"fee":{"type":"integer"},"status":{"type":"string","enum":["pending","held","released","refunded"]}}},"rider":{"type":["object","null"],"properties":{"name":{"type":"string"},"phone":{"type":"string"},"plate":{"type":"string"},"lat":{"type":"number"},"lng":{"type":"number"}}},"eta_minutes":{"type":["integer","null"]},"tracking_url":{"type":"string","format":"uri"},"buyer_confirmation_url":{"type":["string","null"]},"events":{"type":"array","items":{"type":"object","properties":{"status":{"type":"string"},"at":{"type":"string","format":"date-time"},"note":{"type":["string","null"]}}}},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}}}}}