Gomi — API Reference

Authentication

Google OAuth 2.0 with session cookie gomi_session.

Invite-only registration. Admin creates invite, user signs in with Google, account created if email matches.

Pagination

All list endpoints accept:

limit — default 20, max 100
offset — default 0

Errors: {"error": "message"}

Driver Status Flow

offline→ online→ on_job→ online→ offline

on_job is set automatically when a driver starts a job.

Job Status Flow

pending→ assigned→ in_progress→ completed

Admin/dispatcher can cancel at any point.

Roles

Admin web portal

Manage users, invites, roles
All dispatcher capabilities
System config, auth audit log

Dispatcher web portal

Create, assign, reassign, cancel jobs
Monitor drivers and job progress
View job audit trails

Driver mobile app

Clock in/out
View and execute assigned jobs
Upload proof of completion

Authentication

▶GET/auth/loginpublicRedirect to Google OAuth

Redirects the browser to Google's consent screen. After approval, Google redirects to /auth/callback.

▶GET/auth/callbackpublicOAuth callback

Creates the user account if a matching invite exists. Sets session cookie. Shows welcome page.

▶POST/auth/logoutauthenticatedDestroy session

Response

{"message": "logged out"}

▶GET/auth/meauthenticatedCurrent user

Response

{ "user": { "id": "a1b2c3d4", "email": "user@example.com", "first_name": "John", "last_name": "Doe", "avatar_url": "https://lh3.googleusercontent.com/...", "role": "driver", "status": "online", "created_at": "2026-03-31T09:00:00Z", "updated_at": "2026-03-31T10:00:00Z" } }

Profile

▶GET/api/profileauthenticatedGet your full profile

Returns the complete user record from the database.

▶PUT/api/profileauthenticatedUpdate your name

Request Body

Field	Type		Description
first_name	string	required	First name
last_name	string		Last name

Waste Types

▶GET/api/waste-typespublicList waste categories

Returns all waste types. Filter by country with ?country=JP or ?country=UG.

Japan

Burnable, Non-burnable, Plastic packaging, Paper/Cardboard, Bottles & Cans, PET bottles, Oversized, Hazardous

Uganda

General, Organic, Recyclables, Plastics, Hazardous/Medical, Construction debris, E-waste, Market waste

Admin — Invites

▶POST/api/admin/invitesadminCreate invite

Invite a new user by email. Invites expire in 7 days.

Request Body

Field	Type		Description
email	string	required	Email to invite
role	string		`admin`, `dispatcher`, or `driver` (default)

Response

{ "invite": {"id": "abc", "email": "new@example.com", "role": "driver", "status": "pending"}, "invite_url": "https://getgomi.xyz/auth/login?invite=token123", "message": "invite created. Share the invite_url with the user." }

▶GET/api/admin/invitesadminList invites

Returns all invites with inviter details. Supports limit and offset.

▶DELETE/api/admin/invites/{id}adminRevoke invite

Marks a pending invite as expired.

Admin — Users

▶GET/api/admin/usersadminList users

Query Parameters

Param	Description
search	Search by name or email (partial match)
role	Filter: `admin`, `dispatcher`, or `driver`
limit	Items per page
offset	Items to skip

▶GET/api/admin/users/{id}adminGet user

Full user profile by ID.

▶PATCH/api/admin/users/{id}/statusadminSet user status

Request Body

Field	Type		Values
status	string	required	`online`, `offline`, or `on_job`

▶PATCH/api/admin/users/{id}/roleadminChange role

Request Body

Field	Type		Values
role	string	required	`admin`, `dispatcher`, or `driver`

Admin — Audit Log

▶GET/api/admin/audit/authadminAuth event log

Supports limit and offset.

Dispatch — Jobs

Accessible by admin and dispatcher roles.

▶POST/api/dispatch/jobsadmin / dispatcherCreate job

Request Body

Field	Type		Description
title	string	required	Job title
description	string		Details
country_code	string		`JP` or `UG`
waste_type_id	string		ID from `/api/waste-types`
priority	string		`low`, `normal` (default), `high`, `urgent`
driver_id	string		Assign immediately, or assign later
latitude	number		GPS latitude
longitude	number		GPS longitude
address	string		Human-readable address
area_name	string		Ward or district name
scheduled_at	string		RFC 3339. e.g. `2026-04-01T09:00:00Z`
pickup_window_start	string		RFC 3339
pickup_window_end	string		RFC 3339
estimated_volume	string		e.g. "3 bags", "1 truck"
contact_name	string		On-site contact
contact_phone	string		Contact phone
recurring	boolean		Is this a recurring job?
recurrence_rule	string		e.g. `weekly:mon,thu`
notes	string		Additional notes

▶GET/api/dispatch/jobsadmin / dispatcherList jobs

Query Parameters

Param	Description
status	`pending`, `assigned`, `in_progress`, `completed`, `cancelled`
country	`JP` or `UG`
limit	Items per page
offset	Items to skip

▶GET/api/dispatch/jobs/{id}admin / dispatcherGet job + audit trail

Returns the full job record with waste type details and the complete audit trail of all actions taken on this job.

▶PUT/api/dispatch/jobs/{id}admin / dispatcherUpdate job

Update job details. Same fields as create (except driver_id and recurring).

▶POST/api/dispatch/jobs/{id}/assignadmin / dispatcherAssign to driver

Validates the driver exists, has the driver role, and is not offline.

Request Body

Field	Type
driver_id	string	required

▶POST/api/dispatch/jobs/{id}/reassignadmin / dispatcherReassign to different driver

Only works if the job is in pending or assigned status. Previous driver is notified.

Request Body

Field	Type
driver_id	string	required

▶POST/api/dispatch/jobs/{id}/canceladmin / dispatcherCancel job

Request Body

Field	Type	Description
notes	string	Cancellation reason

▶GET/api/dispatch/jobs/{id}/eventsadmin / dispatcherJob audit trail

Every action taken on this job: created, assigned, reassigned, started, completed, cancelled. Includes actor name and timestamp.

Driver

▶PUT/api/driver/statusdriverClock in / clock out

Set yourself online (clocking in) or offline (clocking out). The on_job status is set automatically when you start a job and cleared when you complete it.

Request Body

Field	Type		Values
status	string	required	`online` or `offline`

▶GET/api/driver/jobsdriverYour assigned jobs

Jobs assigned to you. Filter with ?status=assigned etc. Supports pagination.

▶GET/api/driver/jobs/{id}driverJob details

Full details for a job assigned to you, including waste type, location, pickup window, and contact info.

▶POST/api/driver/jobs/{id}/startdriverStart job

Marks the job as in_progress. Records started_at. Sets your status to on_job.

▶POST/api/driver/jobs/{id}/completedriverComplete job

Marks the job as completed. Records completed_at. Sets your status back to online.

Request Body

Field	Type	Description
notes	string	Completion notes
actual_volume	string	Actual volume collected, e.g. "4 bags"
photo_url_after	string	URL of proof-of-completion photo

▶GET/api/driver/statsdriverYour stats

Response

{ "stats": { "total": 50, "pending": 2, "assigned": 3, "in_progress": 1, "completed": 44 } }

Public

GET/healthpublicHealth check

GET/api/publicThis page. ?json=1 for JSON.

User Model

{ "id": "a1b2c3d4e5f6", "email": "user@example.com", "first_name": "John", "last_name": "Doe", "avatar_url": "https://lh3.googleusercontent.com/...", "role": "driver", "status": "online", "created_at": "2026-03-31T09:00:00Z", "updated_at": "2026-03-31T10:00:00Z" }

Job Model

{ "id": "f7e8d9c0b1a2", "title": "Shibuya Ward — Tuesday Collection", "description": "Regular burnable waste pickup", "status": "assigned", "country_code": "JP", "waste_type_id": "jp-burnable", "waste_type_name": "Burnable", "waste_type_icon": "\ud83d\udd25", "priority": "normal", "driver_id": "a1b2c3d4", "assigned_by": "x9y8z7w6", "latitude": 35.6595, "longitude": 139.7004, "address": "2 Chome Dogenzaka, Shibuya", "area_name": "Shibuya", "scheduled_at": "2026-04-01T08:00:00Z", "pickup_window_start": "2026-04-01T07:30:00Z", "pickup_window_end": "2026-04-01T09:00:00Z", "estimated_volume": "12 bags", "actual_volume": "", "contact_name": "Tanaka", "contact_phone": "+81-3-1234-5678", "photo_url_before": "", "photo_url_after": "", "recurring": 1, "recurrence_rule": "weekly:tue,fri", "notes": "", "started_at": null, "completed_at": null, "created_at": "2026-03-30T14:00:00Z", "updated_at": "2026-03-31T08:00:00Z" }

Gomi API · Buri Africa Ltd for eK Business System Co., Ltd

Gomi API v0.1.0

Authentication

Pagination

Driver Status Flow

Job Status Flow

Admin web portal

Dispatcher web portal

Driver mobile app

Response

Response

Request Body

Japan

Uganda

Request Body

Response

Query Parameters

Request Body

Request Body

Request Body

Query Parameters

Request Body

Request Body

Request Body

Request Body

Request Body

Response