Safra Partner API reference
Base URL https://safraway.com/api/partner/v1. Authenticate with Authorization: Bearer sk_live_…. Version 2026-08-21.
Reference
GET /openapi.json
OpenAPI specification. Public JSON document for this API. No authentication. Also mirrored at docs.safraway.com/openapi.json. Scope: none.
GET /cities
List trip cities. Cities you can use as fromCityId / toCityId when publishing trips and schedules. Scope: trips.read.
GET /places
Search places. Search pickup and drop-off places (P-codes) inside a city for fromPlacePcode / toPlacePcode. Scope: trips.read.
Company
GET /company
Get the authenticated company. The company is implied by the API key. Paths never include a company id. Scope: company.read.
PATCH /company
Update company profile. Partial update of public company fields such as description. Scope: company.write.
POST /company/logo
Upload company logo. Send a base64 image payload. Replaces the current logo. Scope: company.write.
DELETE /company/logo
Remove company logo. Deletes the current logo file. Scope: company.write.
Members
GET /members
List members. Drivers, staff, admins, and the owner attached to the company. Scope: members.read.
POST /members
Add a member by phone. The phone must already belong to a Safra user. Roles: owner cannot be assigned this way. Scope: members.write.
PATCH /members/{member}
Update a member role. Change the company role for an existing member. Scope: members.write.
DELETE /members/{member}
Remove a member. Detaches the user from the company. Does not delete their Safra account. Scope: members.write.
Fleet
GET /vehicles
List vehicles. Company fleet used when publishing trips. Scope: fleet.read.
POST /vehicles
Create a vehicle. Adds a vehicle to the company fleet. Scope: fleet.write.
PATCH /vehicles/{vehicle}
Update a vehicle. Partial update of fleet fields. Scope: fleet.write.
DELETE /vehicles/{vehicle}
Delete a vehicle. Fails if the vehicle is still attached to published trips. Scope: fleet.write.
Trips
GET /trips
List trips. Company trips, newest departure first. Scope: trips.read.
POST /trips
Publish a trip. Creates a published company trip. The assigned driver must be a company member. vehicleId is required. Scope: trips.write.
GET /trips/{trip}
Get a trip. Single trip belonging to the authenticated company. Scope: trips.read.
PATCH /trips/{trip}
Update a trip. Partial update of a published trip. Scope: trips.write.
DELETE /trips/{trip}
Cancel a trip. Cancels the trip. Existing bookings follow dashboard cancellation rules. Scope: trips.write.
POST /trips/{trip}/complete
Mark trip completed. Closes the trip after it has run. Scope: trips.write.
GET /trips/{trip}/manifest
Passenger manifest. Approved and boarded passengers for dispatch and boarding. Scope: trips.read.
Schedules
GET /schedules
List recurring schedules. Templates that publish trips on a recurrence (daily, weekly, …). Scope: schedules.read.
POST /schedules
Create a schedule. Same trip fields as publish, plus recurrence and time-of-day. City ids are strings such as damascus / aleppo. Scope: schedules.write.
GET /schedules/{schedule}
Get a schedule. Includes exceptions when loaded. Scope: schedules.read.
PATCH /schedules/{schedule}
Update a schedule. Partial update — send only fields to change. Omitted fields keep their current values. Scope: schedules.write.
DELETE /schedules/{schedule}
Delete a schedule. Stops future generation. Already published trips are not deleted. Scope: schedules.write.
POST /schedules/{schedule}/toggle
Enable or pause a schedule. Flip the schedule active flag. Scope: schedules.write.
POST /schedules/{schedule}/exceptions
Upsert a schedule exception. Skip or override a specific date (holiday, extra departure). Scope: schedules.write.
DELETE /schedules/{schedule}/exceptions/{exception}
Delete a schedule exception. Removes a date override. Scope: schedules.write.
Bookings
GET /bookings
List bookings. Bookings on this company’s trips, newest first. Scope: bookings.read.
POST /bookings
Create booking by phone. Finds or creates a passenger from the phone number and places a requested booking. source is partner_api. Auto-approve is not implied. Scope: bookings.write.
GET /bookings/{booking}
Get a booking. Includes trip, passenger, and payments when available. Scope: bookings.read.
PATCH /bookings/{booking}
Approve, reject, or cancel. status must be one of approved, rejected, cancelled. Scope: bookings.write.
POST /bookings/{booking}/boarded
Mark boarded. Passenger boarded. Sets boardedAt. Scope: bookings.write.
POST /bookings/{booking}/no-show
Mark no-show. Passenger did not board. Scope: bookings.write.
GET /bookings/{booking}/ticket
Get ticket payload. Company-view ticket data for printing or display. Scope: bookings.read.
Payments
GET /payments
List payments. Read-only. You cannot create Ziina charges from the Partner API. Scope: payments.read.
GET /payments/{payment}
Get a payment. Single payment on a company booking. Scope: payments.read.
GET /payments/{payment}/invoice.pdf
Download invoice PDF. Binary PDF. Send the same Bearer token. Scope: payments.read.
GET /payouts
List payouts. Company payout records. Scope: payments.read.
Reports
GET /dashboard
Dashboard snapshot. High-level counts for the company home. Scope: reports.read.
GET /reports
Reports payload. Aggregated booking and revenue figures. Scope: reports.read.
GET /reports/export
Export reports. Download a bookings/trips/revenue export. type and format are required query params. Scope: reports.read.
Reviews
GET /reviews
List reviews. Reviews left on this company’s trips. Scope: company.read.
Webhooks
GET /webhooks
List webhook endpoints. Configured HTTPS endpoints. Signing secrets are never returned after create. Scope: webhooks.read.
POST /webhooks
Create a webhook endpoint. Returns the endpoint plus secret once. Store the secret; it cannot be retrieved later. Do not include webhook.test in events — that event is only sent by the test ping. Scope: webhooks.write.
PATCH /webhooks/{endpoint}
Update a webhook endpoint. Change URL, events, or active flag. Scope: webhooks.write.
DELETE /webhooks/{endpoint}
Delete a webhook endpoint. Stops future deliveries. Scope: webhooks.write.
POST /webhooks/{endpoint}/test
Queue a test ping. Enqueues event webhook.test with a small payload. Scope: webhooks.write.
GET /webhooks/{endpoint}/deliveries
List deliveries. Recent delivery attempts for debugging. Scope: webhooks.read.