People · terra API

GET /v3/account #

bearer driver_app beneficiary_app pass_app pass_web device credential

Response

Returns { "data": [Account] } with meta.next_cursor for the next page.

Field	Type		Constraints
`id`	string (uuid)	required	—
`first_name`	string	optional	—
`middle_name`	string \| null	optional	—
`last_name`	string \| null	optional	—
`phone`	string \| null	optional	—
`email`	string \| null	optional	—
`gender`	string \| null	optional	—
`kyc_status`	string \| null	optional	—
`status`	string	optional	—
`external_ref`	string \| null	optional	—
`created_at`	string (date-time)	optional	—
`wallets`	WalletSummary[]	optional	—
`updated_at`	string (date-time)	required	—
`deleted`	boolean	required	—

GET /v3/account/{id} #

bearer driver_app beneficiary_app pass_app pass_web device credential

Path parameters

Name	Type	Notes
`id`	string

Response

Returns { "data": AccountDetail }.

Field	Type		Constraints
`id`	string (uuid)	required	—
`first_name`	string	required	—
`middle_name`	string \| null	required	—
`last_name`	string \| null	required	—
`phone`	string \| null	required	—
`kyc_status`	string \| null	required	—
`status`	string	required	—
`external_ref`	string \| null	required	—
`students`	object[]	required	—
`wallets`	object[]	required	—

POST /v3/app/account #

bearer driver_app beneficiary_app people.create device credential

Request body

Field	Type		Constraints
`first_name`	string	required	max length 100
`middle_name`	string \| null	optional	max length 100
`last_name`	string \| null	optional	max length 100
`phone`	string \| null	optional	max length 20
`email`	string \| null	optional	max length 254
`gender`	string \| null	optional	`male` `female` `unspecified`
`national_id`	string \| null	optional	max length 32
`external_ref`	string \| null	optional	max length 64
`wallet_type_id`	string \| null	optional	—

Response

Returns { "data": AccountDetail }.

Field	Type		Constraints
`id`	string (uuid)	required	—
`first_name`	string	required	—
`middle_name`	string \| null	required	—
`last_name`	string \| null	required	—
`phone`	string \| null	required	—
`kyc_status`	string \| null	required	—
`status`	string	required	—
`external_ref`	string \| null	required	—
`students`	object[]	required	—
`wallets`	object[]	required	—

POST /v3/app/account/{id}/student #

bearer driver_app beneficiary_app people.create device credential

Path parameters

Name	Type	Notes
`id`	string

Request body

Field	Type		Constraints
`first_name`	string	required	max length 100
`middle_name`	string \| null	optional	max length 100
`last_name`	string \| null	optional	max length 100
`gender`	string \| null	optional	`male` `female` `unspecified`
`dob`	string \| null	optional	—
`grade`	string \| null	optional	max length 32
`relation`	string \| null	optional	max length 32
`external_ref`	string \| null	optional	max length 64
`wallet_type_id`	string \| null	optional	—

Response

Returns { "data": StudentWrite }.

Field	Type		Constraints
`id`	string (uuid)	required	—
`first_name`	string	required	—
`last_name`	string \| null	required	—
`grade`	string \| null	required	—
`status`	string	required	—

GET /v3/app/student #

bearer driver_app beneficiary_app parent_app device credential

Response

Returns { "data": [Student] } with meta.next_cursor for the next page.

Field	Type		Constraints
`id`	string (uuid)	required	—
`first_name`	string	optional	—
`middle_name`	string \| null	optional	—
`last_name`	string \| null	optional	—
`gender`	string \| null	optional	—
`dob`	string \| null	optional	—
`grade`	string \| null	optional	—
`status`	string	optional	—
`external_ref`	string \| null	optional	—
`alert_note`	string \| null	optional	—
`account_id`	string \| null	optional	—
`photo`	any	optional	—
`created_at`	string (date-time)	optional	—
`tags`	object[]	optional	—
`guardians`	Guardian[]	optional	—
`dropoff`	any	optional	—
`updated_at`	string (date-time)	required	—
`deleted`	boolean	required	—

GET /v3/app/tag #

bearer driver_app beneficiary_app device credential

Response

Returns { "data": [Tag] } with meta.next_cursor for the next page.

Field	Type		Constraints
`id`	string (uuid)	required	—
`name`	string	required	—
`entity`	string \| null	required	—
`color_hex`	string \| null	required	—

POST /v3/auth/invite/accept #

public 10,1

token + a password → an account.

Answers ONE way for a wrong token, a used one and an expired one. Telling them apart would confirm which tokens ever existed, and this endpoint is unauthenticated by necessity.

Hands back NO session, exactly like the password reset: holding an invite link proves somebody forwarded you a message, not who you are. They sign in with the password they just chose, which proves both.

Request body

Field	Type		Constraints
`token`	string	required	min length 48 · max length 48
`password`	string	required	min length 10 · max length 255

Response

Returns { "data": StaffInviteAccepted }.

Field	Type		Constraints
`accepted`	boolean	required	—
`email`	string \| null	required	—
`phone`	string \| null	required	—

GET /v3/group #

bearer driver_app beneficiary_app admin_web device credential

Query parameters

Name	Type		Constraints
`status`	string \| null	optional	`active` `suspended` `archived`

Response

Returns { "data": [Group] } with meta.next_cursor for the next page.

Field	Type		Constraints
`id`	string (uuid)	required	—
`name`	string	required	—
`is_default`	boolean	required	—
`status`	string	required	—
`member_count`	integer	required	—

GET /v3/pass/invite #

bearer pass_web device credential

GET invite — who has been asked and not yet arrived.

Response

Returns { "data": [StaffInvite] } with meta.next_cursor for the next page.

Field	Type		Constraints
`id`	string (uuid)	required	—
`name`	string	required	—
`email`	string \| null	required	—
`phone`	string \| null	required	—
`role_name`	string \| null	required	—
`staff_kind`	string \| null	required	—
`invited_by_name`	string \| null	required	—
`expires_at`	string	required	—
`created_at`	string	required	—

POST /v3/pass/invite #

bearer pass_web staff.manage device credential

POST invite — ask somebody to join.

The response carries the token ONCE. It is stored hashed and can never be read again, so a console that loses it re-invites rather than recovering it — the same bargain a password makes, for the same reason: this string is a way into the tenant.

Request body

Field	Type		Constraints
`first_name`	string	required	max length 80
`last_name`	string \| null	optional	max length 80
`email`	string \| null	optional	max length 160
`phone`	string \| null	optional	—
`tenant_role_id`	string \| null	optional	—
`staff_kind`	string \| null	optional	max length 40

Response

Returns { "data": StaffInviteMinted }.

Field	Type		Constraints
`id`	string (uuid)	required	—
`token`	string	required	—
`expires_at`	string	required	—

DELETE /v3/pass/invite/{id} #

bearer pass_web staff.manage device credential

withdraw one that has not been accepted.

Path parameters

Name	Type	Notes
`id`	string

Response

Returns { "data": Deleted }.

Field	Type		Constraints
`deleted`	boolean	required	—

POST /v3/portal/guardian #

bearer admin_web people.create device credential

POST guardian — create a guardian with no student attached yet.

The console's admin directory adds a parent BEFORE any learner is linked to them (learners are attached afterwards from the child's profile). Until now the only way a guardian account came into being was [link] — via a student — so the directory's "Add parent" had nowhere to post and was aimed at the STAFF endpoint with staff_kind: "guardian", which the StaffKind enum rightly refused.

Identity is the phone, exactly as in [link]: adding a parent who is already on this tenant returns the existing account rather than minting a second one, so a retry or a double-submit cannot split one family across two records.

Request body

Field	Type		Constraints
`first_name`	string	required	max length 100
`middle_name`	string \| null	optional	max length 100
`last_name`	string \| null	optional	max length 100
`email`	string \| null	optional	max length 254
`phone`	string	required	max length 20
`school_id`	string \| null	optional	—

Response

Returns { "data": GuardianCreated }.

Field	Type		Constraints
`account_id`	string (uuid)	required	—
`already_existed`	boolean	required	—

PATCH /v3/portal/guardian/{id} #

bearer admin_web people.update device credential

contact AND notification edits on a guardian (§1 mask).

The mask spans TWO tables, which is the whole difficulty. Contact fields are the account's own columns; the notification switches are users columns (0062) and accounts has none of them, so they are written one hop away through accounts.user_id. The console holds an account id for a parent — it sent that id to the staff endpoint before, which resolves a users row and rightly answered "User not found".

Path parameters

Name	Type	Notes
`id`	string

Request body

Field	Type		Constraints
`update_mask`	string[]	required	min items 1 · max items 9
`expected_row_version`	integer	required	min 1
`first_name`	string \| null	optional	max length 100
`middle_name`	string \| null	optional	max length 100
`last_name`	string \| null	optional	max length 100
`phone`	string \| null	optional	max length 20
`email`	string \| null	optional	max length 254
`receive_notifications`	boolean	optional	—
`receive_email_notifications`	boolean	optional	—
`receive_sms_notifications`	boolean	optional	—
`receive_whatsapp_notifications`	boolean	optional	—

Response

Returns { "data": WebUserDetail }.

Field	Type		Constraints
`id`	string (uuid)	required	—
`kind`	string	optional	—
`first_name`	string	required	—
`middle_name`	string \| null	optional	—
`last_name`	string \| null	optional	—
`email`	string \| null	optional	—
`phone`	string \| null	optional	—
`staff_kind`	string \| null	optional	—
`tenant_role_id`	string \| null	optional	—
`status`	string	required	—
`school_id`	string \| null	optional	—
`school_name`	string \| null	optional	—
`report_subscriptions`	string[]	optional	—
`receive_notifications`	boolean	optional	—
`receive_email_notifications`	boolean	optional	—
`receive_sms_notifications`	boolean	optional	—
`receive_whatsapp_notifications`	boolean	optional	—
`zones`	object[]	optional	—
`has_login`	boolean	optional	—
`students_count`	integer	optional	—
`subscription`	any	optional	—
`last_login_at`	string \| null	optional	—
`created_at`	string (date-time)	optional	—
`row_version`	integer	required	—
`students`	object[]	optional	—

POST /v3/portal/import #

bearer admin_web people.import device credential

Request body

Field	Type		Constraints
`kind`	string	required	`students` `staff`
`rows`	object[]	required	min items 1 · max items 500

Response

Returns { "data": [ImportOutcome] } with meta.next_cursor for the next page.

Field	Type		Constraints
`row`	integer	required	—
`ok`	boolean	required	—
`id`	string (uuid)	optional	—
`code`	string	optional	—

GET /v3/portal/metadata-field #

bearer admin_web device credential

Query parameters

Name	Type		Constraints
`entity`	string \| null	optional	`student` `account`

Response

Returns { "data": [MetadataField] } with meta.next_cursor for the next page.

Field	Type		Constraints
`id`	string (uuid)	required	—
`entity`	string	required	—
`name`	string	required	—
`description`	string \| null	required	—
`created_at`	string	optional	—

POST /v3/portal/metadata-field #

bearer admin_web settings.manage device credential

Request body

Field	Type		Constraints
`entity`	string	required	`student` `account`
`name`	string	required	max length 120
`description`	string \| null	optional	max length 255

Response

Returns { "data": Written }.

Field	Type		Constraints
`id`	string (uuid)	required	—

DELETE /v3/portal/metadata-field/{id} #

bearer admin_web settings.manage device credential

Path parameters

Name	Type	Notes
`id`	string

Response

Returns { "data": Written }.

Field	Type		Constraints
`id`	string (uuid)	required	—

PATCH /v3/portal/metadata-field/{id} #

bearer admin_web settings.manage device credential

Path parameters

Name	Type	Notes
`id`	string

Request body

Field	Type		Constraints
`name`	string	optional	max length 120
`description`	string \| null	optional	max length 255

Response

Returns { "data": Written }.

Field	Type		Constraints
`id`	string (uuid)	required	—

POST /v3/portal/role #

bearer admin_web roles.manage device credential

Request body

Field	Type		Constraints
`name`	string	required	max length 80
`capabilities`	string[]	required	min items 1

Response

Returns { "data": WebRole }.

Field	Type		Constraints
`id`	string (uuid)	required	—
`name`	string	required	—
`capabilities`	Capability[]	required	—
`created_at`	string \| null	required	—

DELETE /v3/portal/role/{id} #

bearer admin_web roles.manage device credential

Path parameters

Name	Type	Notes
`id`	string

Response

Returns { "data": Ack }.

Field	Type		Constraints
`ok`	boolean	required	—

PATCH /v3/portal/role/{id} #

bearer admin_web roles.manage device credential

Path parameters

Name	Type	Notes
`id`	string

Request body

Field	Type		Constraints
`name`	string	required	max length 80
`capabilities`	string[]	required	min items 1

Response

Returns { "data": WebRole }.

Field	Type		Constraints
`id`	string (uuid)	required	—
`name`	string	required	—
`capabilities`	Capability[]	required	—
`created_at`	string \| null	required	—

GET /v3/portal/student #

bearer admin_web device credential

Query parameters

Name	Type		Constraints
`q`	string \| null	optional	max length 100
`grade`	string \| null	optional	max length 20
`route_id`	string \| null	optional	—
`school`	string \| null	optional	—
`tag_id`	string \| null	optional	—
`cursor`	string \| null	optional	max length 200
`per_page`	integer \| null	optional	min 1 · max 500

Response

Returns { "data": [WebStudent] } with meta.next_cursor for the next page.

Field	Type		Constraints
`id`	string (uuid)	required	—
`first_name`	string	required	—
`middle_name`	string \| null	required	—
`last_name`	string \| null	required	—
`gender`	string \| null	required	—
`dob`	string \| null	required	—
`grade`	string \| null	required	—
`status`	string	required	—
`external_ref`	string \| null	required	—
`photo`	any	required	—
`row_version`	integer	required	—
`school_id`	string \| null	required	—
`school_name`	string \| null	required	—
`guardians`	Guardian[]	required	—
`band`	any	required	—
`route`	any	required	—
`today`	object	required	—
`today.checked_in`	boolean	required	—
`today.checked_in_at`	string \| null	required	—

POST /v3/portal/student #

bearer admin_web people.create device credential

Request body

Field	Type		Constraints
`first_name`	string	required	max length 100
`middle_name`	string \| null	optional	max length 100
`last_name`	string \| null	optional	max length 100
`gender`	string \| null	optional	`male` `female` `unspecified`
`dob`	string \| null	optional	—
`grade`	string \| null	optional	max length 32
`external_ref`	string \| null	optional	max length 64
`metadata`	array \| null	optional	max items 20
`parent_id`	string \| null	optional	—
`school`	string \| null	optional	—

Response

Returns { "data": WebStudentDetail }.

Field	Type		Constraints
`id`	string (uuid)	required	—
`first_name`	string	required	—
`middle_name`	string \| null	required	—
`last_name`	string \| null	required	—
`gender`	string \| null	required	—
`dob`	string \| null	required	—
`grade`	string \| null	required	—
`status`	string	required	—
`external_ref`	string \| null	required	—
`photo`	any	required	—
`row_version`	integer	required	—
`school_id`	string \| null	required	—
`school_name`	string \| null	required	—
`guardians`	Guardian[]	required	—
`band`	any	required	—
`route`	any	required	—
`today`	object	required	—
`today.checked_in`	boolean	required	—
`today.checked_in_at`	string \| null	required	—
`metadata`	object	required	—
`tags`	object[]	required	—
`wallet`	any	required	—
`band_history`	object[]	required	—
`trip_plans`	object[]	required	—
`home_location`	any	required	—
`recent_timeline`	TimelineEntry[]	required	—

DELETE /v3/portal/student/{id} #

bearer admin_web people.delete device credential

Path parameters

Name	Type	Notes
`id`	string

Response

Returns { "data": Ack }.

Field	Type		Constraints
`ok`	boolean	required	—

GET /v3/portal/student/{id} #

bearer admin_web device credential

Path parameters

Name	Type	Notes
`id`	string

Response

Returns { "data": WebStudentDetail }.

Field	Type		Constraints
`id`	string (uuid)	required	—
`first_name`	string	required	—
`middle_name`	string \| null	required	—
`last_name`	string \| null	required	—
`gender`	string \| null	required	—
`dob`	string \| null	required	—
`grade`	string \| null	required	—
`status`	string	required	—
`external_ref`	string \| null	required	—
`photo`	any	required	—
`row_version`	integer	required	—
`school_id`	string \| null	required	—
`school_name`	string \| null	required	—
`guardians`	Guardian[]	required	—
`band`	any	required	—
`route`	any	required	—
`today`	object	required	—
`today.checked_in`	boolean	required	—
`today.checked_in_at`	string \| null	required	—
`metadata`	object	required	—
`tags`	object[]	required	—
`wallet`	any	required	—
`band_history`	object[]	required	—
`trip_plans`	object[]	required	—
`home_location`	any	required	—
`recent_timeline`	TimelineEntry[]	required	—

PATCH /v3/portal/student/{id} #

bearer admin_web people.update device credential

Path parameters

Name	Type	Notes
`id`	string

Request body

Field	Type		Constraints
`update_mask`	string[]	required	min items 1 · max items 9
`expected_row_version`	integer	required	min 1
`first_name`	string \| null	optional	max length 100
`middle_name`	string \| null	optional	max length 100
`last_name`	string \| null	optional	max length 100
`gender`	string \| null	optional	`male` `female` `unspecified`
`dob`	string \| null	optional	—
`grade`	string \| null	optional	max length 32
`status`	string \| null	optional	`active` `suspended` `archived`
`external_ref`	string \| null	optional	max length 64
`metadata`	array \| null	optional	max items 20

Response

Returns { "data": WebStudentDetail }.

Field	Type		Constraints
`id`	string (uuid)	required	—
`first_name`	string	required	—
`middle_name`	string \| null	required	—
`last_name`	string \| null	required	—
`gender`	string \| null	required	—
`dob`	string \| null	required	—
`grade`	string \| null	required	—
`status`	string	required	—
`external_ref`	string \| null	required	—
`photo`	any	required	—
`row_version`	integer	required	—
`school_id`	string \| null	required	—
`school_name`	string \| null	required	—
`guardians`	Guardian[]	required	—
`band`	any	required	—
`route`	any	required	—
`today`	object	required	—
`today.checked_in`	boolean	required	—
`today.checked_in_at`	string \| null	required	—
`metadata`	object	required	—
`tags`	object[]	required	—
`wallet`	any	required	—
`band_history`	object[]	required	—
`trip_plans`	object[]	required	—
`home_location`	any	required	—
`recent_timeline`	TimelineEntry[]	required	—

POST /v3/portal/student/{id}/guardian #

bearer admin_web people.update device credential

link (creating the account if the phone is new).

Path parameters

Name	Type	Notes
`id`	string

Request body

Field	Type		Constraints
`phone`	string	required	max length 20
`name`	string \| null	optional	max length 200
`relation`	string \| null	optional	max length 40
`is_primary`	boolean \| null	optional	—

Response

Returns { "data": GuardianLinked }.

Field	Type		Constraints
`account_id`	string (uuid)	required	—
`name`	string	required	—
`already_linked`	boolean	required	—

DELETE /v3/portal/student/{id}/guardian/{accountId} #

bearer admin_web people.update device credential

tombstone the edge, keep the person.

Path parameters

Name	Type	Notes
`id`	string
`accountId`	string

Response

Returns { "data": Deleted }.

Field	Type		Constraints
`deleted`	boolean	required	—

GET /v3/portal/student/{id}/home-location #

bearer admin_web device credential

the pins, default first.

Path parameters

Name	Type	Notes
`id`	string

Response

Returns { "data": [HomeLocation] } with meta.next_cursor for the next page.

Field	Type		Constraints
`id`	string (uuid)	required	—
`label`	string \| null	optional	—
`lat`	number \| null	optional	—
`lng`	number \| null	optional	—
`is_default`	boolean	required	—

POST /v3/portal/student/{id}/home-location #

bearer admin_web people.update device credential

add a pin.

Path parameters

Name	Type	Notes
`id`	string

Request body

Field	Type		Constraints
`label`	string \| null	optional	max length 120
`lat`	number	required	min -90 · max 90
`lng`	number	required	min -180 · max 180
`is_default`	boolean \| null	optional	—

Response

Returns { "data": HomeLocation }.

Field	Type		Constraints
`id`	string (uuid)	required	—
`label`	string \| null	optional	—
`lat`	number \| null	optional	—
`lng`	number \| null	optional	—
`is_default`	boolean	required	—

DELETE /v3/portal/student/{id}/home-location/{hid} #

bearer admin_web people.update device credential

remove a pin.

Path parameters

Name	Type	Notes
`id`	string
`hid`	string

Response

Returns { "data": Deleted }.

Field	Type		Constraints
`deleted`	boolean	required	—

PATCH /v3/portal/student/{id}/home-location/{hid} #

bearer admin_web people.update device credential

edit label/coords.

Path parameters

Name	Type	Notes
`id`	string
`hid`	string

Request body

Field	Type		Constraints
`label`	string \| null	optional	max length 120
`lat`	number	optional	min -90 · max 90
`lng`	number	optional	min -180 · max 180

Response

Returns { "data": HomeLocation }.

Field	Type		Constraints
`id`	string (uuid)	required	—
`label`	string \| null	optional	—
`lat`	number \| null	optional	—
`lng`	number \| null	optional	—
`is_default`	boolean	required	—

PUT /v3/portal/student/{id}/home-location/{hid}/default #

bearer admin_web people.update device credential

make this the default pin.

Path parameters

Name	Type	Notes
`id`	string
`hid`	string

Response

Returns { "data": HomeLocation }.

Field	Type		Constraints
`id`	string (uuid)	required	—
`label`	string \| null	optional	—
`lat`	number \| null	optional	—
`lng`	number \| null	optional	—
`is_default`	boolean	required	—

POST /v3/portal/user #

bearer admin_web staff.manage device credential

Request body

Field	Type		Constraints
`first_name`	string	required	max length 100
`middle_name`	string \| null	optional	max length 100
`last_name`	string \| null	optional	max length 100
`email`	string \| null	optional	max length 254
`phone`	string	required	max length 20
`staff_kind`	string	required	`admin` `zone_manager` `teacher` `driver` `assistant` `gate_agent` `support` `operator` +2 more

Response

Returns { "data": WebUserDetail }.

Field	Type		Constraints
`id`	string (uuid)	required	—
`kind`	string	optional	—
`first_name`	string	required	—
`middle_name`	string \| null	optional	—
`last_name`	string \| null	optional	—
`email`	string \| null	optional	—
`phone`	string \| null	optional	—
`staff_kind`	string \| null	optional	—
`tenant_role_id`	string \| null	optional	—
`status`	string	required	—
`school_id`	string \| null	optional	—
`school_name`	string \| null	optional	—
`report_subscriptions`	string[]	optional	—
`receive_notifications`	boolean	optional	—
`receive_email_notifications`	boolean	optional	—
`receive_sms_notifications`	boolean	optional	—
`receive_whatsapp_notifications`	boolean	optional	—
`zones`	object[]	optional	—
`has_login`	boolean	optional	—
`students_count`	integer	optional	—
`subscription`	any	optional	—
`last_login_at`	string \| null	optional	—
`created_at`	string (date-time)	optional	—
`row_version`	integer	required	—
`students`	object[]	optional	—

DELETE /v3/portal/user/{id} #

bearer admin_web staff.manage device credential

Path parameters

Name	Type	Notes
`id`	string

Response

Returns { "data": Ack }.

Field	Type		Constraints
`ok`	boolean	required	—

PATCH /v3/portal/user/{id} #

bearer admin_web staff.manage device credential

Path parameters

Name	Type	Notes
`id`	string

Request body

Field	Type		Constraints
`update_mask`	string[]	required	min items 1 · max items 13
`expected_row_version`	integer	required	min 1
`first_name`	string \| null	optional	max length 100
`middle_name`	string \| null	optional	max length 100
`last_name`	string \| null	optional	max length 100
`email`	string \| null	optional	max length 254
`phone`	string \| null	optional	max length 20
`staff_kind`	string \| null	optional	`admin` `zone_manager` `teacher` `driver` `assistant` `gate_agent` `support` `operator` +2 more
`status`	string \| null	optional	`active` `suspended` `archived`
`tenant_role_id`	string \| null	optional	—
`report_subscriptions`	string[]	optional	max items 20
`receive_notifications`	boolean \| null	optional	—
`receive_email_notifications`	boolean \| null	optional	—
`receive_sms_notifications`	boolean \| null	optional	—
`receive_whatsapp_notifications`	boolean \| null	optional	—

Response

Returns { "data": WebUserDetail }.

Field	Type		Constraints
`id`	string (uuid)	required	—
`kind`	string	optional	—
`first_name`	string	required	—
`middle_name`	string \| null	optional	—
`last_name`	string \| null	optional	—
`email`	string \| null	optional	—
`phone`	string \| null	optional	—
`staff_kind`	string \| null	optional	—
`tenant_role_id`	string \| null	optional	—
`status`	string	required	—
`school_id`	string \| null	optional	—
`school_name`	string \| null	optional	—
`report_subscriptions`	string[]	optional	—
`receive_notifications`	boolean	optional	—
`receive_email_notifications`	boolean	optional	—
`receive_sms_notifications`	boolean	optional	—
`receive_whatsapp_notifications`	boolean	optional	—
`zones`	object[]	optional	—
`has_login`	boolean	optional	—
`students_count`	integer	optional	—
`subscription`	any	optional	—
`last_login_at`	string \| null	optional	—
`created_at`	string (date-time)	optional	—
`row_version`	integer	required	—
`students`	object[]	optional	—

POST /v3/portal/user/{id}/resend-welcome-email #

bearer admin_web staff.manage device credential

the invitation again, for the colleague whose first copy never landed. Nothing about the account changes; somebody who already has a password wants reset-password, and is told so rather than sent an email describing an account they no longer have.

Path parameters

Name	Type	Notes
`id`	string

Response

Returns { "data": Ack }.

Field	Type		Constraints
`ok`	boolean	required	—

POST /v3/portal/user/{id}/reset-password #

bearer admin_web staff.manage device credential

the §12.5 posture: the hash NULLs and the next login forces a set (credentials are never emailed around); every session the user held is revoked in the same call.

Path parameters

Name	Type	Notes
`id`	string

Response

Returns { "data": PasswordReset }.

Field	Type		Constraints
`must_set_password`	boolean	required	—

PUT /v3/portal/user/{id}/zones #

bearer admin_web staff.manage device credential

Path parameters

Name	Type	Notes
`id`	string

Request body

Field	Type		Constraints
`zone_ids`	string (uuid)[]	required	max items 50

Response

Returns { "data": ZoneAssignment }.

Field	Type		Constraints
`zone_ids`	string (uuid)[]	required	—

GET /v3/role #

bearer pass_web admin_web device credential

Response

Returns { "data": [WebRole] } with meta.next_cursor for the next page.

Field	Type		Constraints
`id`	string (uuid)	required	—
`name`	string	required	—
`capabilities`	Capability[]	required	—
`created_at`	string \| null	required	—

POST /v3/role #

bearer pass_web admin_web roles.manage device credential

Request body

Field	Type		Constraints
`name`	string	required	max length 80
`capabilities`	string[]	required	min items 1

Response

Returns { "data": WebRole }.

Field	Type		Constraints
`id`	string (uuid)	required	—
`name`	string	required	—
`capabilities`	Capability[]	required	—
`created_at`	string \| null	required	—

DELETE /v3/role/{id} #

bearer pass_web admin_web roles.manage device credential

Path parameters

Name	Type	Notes
`id`	string

Response

Returns { "data": Ack }.

Field	Type		Constraints
`ok`	boolean	required	—

PATCH /v3/role/{id} #

bearer pass_web admin_web roles.manage device credential

Path parameters

Name	Type	Notes
`id`	string

Request body

Field	Type		Constraints
`name`	string	required	max length 80
`capabilities`	string[]	required	min items 1

Response

Returns { "data": WebRole }.

Field	Type		Constraints
`id`	string (uuid)	required	—
`name`	string	required	—
`capabilities`	Capability[]	required	—
`created_at`	string \| null	required	—

GET /v3/student/{id}/timeline #

bearer parent_app admin_web device credential

Path parameters

Name	Type	Notes
`id`	string

Query parameters

Name	Type		Constraints
`kind`	string \| null	optional	`tap` `trip` `transaction`
`cursor`	string \| null	optional	max length 200
`per_page`	integer \| null	optional	min 1 · max 500

Response

Returns { "data": [TimelineEntry] } with meta.next_cursor for the next page.

Field	Type		Constraints
`kind`	string	required	`tap` `trip_boarded` `trip_dropped` `transaction`
`at`	string	required	—
`detail`	TimelineDetail	required	—

GET /v3/user #

bearer pass_web admin_web device credential

Query parameters

Name	Type		Constraints
`kind`	string \| null	optional	`staff` `guardian`
`q`	string \| null	optional	max length 100
`cursor`	string \| null	optional	max length 200
`per_page`	integer \| null	optional	min 1 · max 500

Response

Returns { "data": [WebUser] } with meta.next_cursor for the next page.

Field	Type		Constraints
`id`	string (uuid)	required	—
`kind`	string	optional	—
`first_name`	string	required	—
`middle_name`	string \| null	optional	—
`last_name`	string \| null	optional	—
`email`	string \| null	optional	—
`phone`	string \| null	optional	—
`staff_kind`	string \| null	optional	—
`tenant_role_id`	string \| null	optional	—
`status`	string	required	—
`school_id`	string \| null	optional	—
`school_name`	string \| null	optional	—
`report_subscriptions`	string[]	optional	—
`receive_notifications`	boolean	optional	—
`receive_email_notifications`	boolean	optional	—
`receive_sms_notifications`	boolean	optional	—
`receive_whatsapp_notifications`	boolean	optional	—
`zones`	object[]	optional	—
`has_login`	boolean	optional	—
`students_count`	integer	optional	—
`subscription`	any	optional	—
`last_login_at`	string \| null	optional	—
`created_at`	string (date-time)	optional	—
`row_version`	integer	required	—

GET /v3/user/{id} #

bearer pass_web admin_web device credential

Path parameters

Name	Type	Notes
`id`	string

Response

Returns { "data": WebUserDetail }.

Field	Type		Constraints
`id`	string (uuid)	required	—
`kind`	string	optional	—
`first_name`	string	required	—
`middle_name`	string \| null	optional	—
`last_name`	string \| null	optional	—
`email`	string \| null	optional	—
`phone`	string \| null	optional	—
`staff_kind`	string \| null	optional	—
`tenant_role_id`	string \| null	optional	—
`status`	string	required	—
`school_id`	string \| null	optional	—
`school_name`	string \| null	optional	—
`report_subscriptions`	string[]	optional	—
`receive_notifications`	boolean	optional	—
`receive_email_notifications`	boolean	optional	—
`receive_sms_notifications`	boolean	optional	—
`receive_whatsapp_notifications`	boolean	optional	—
`zones`	object[]	optional	—
`has_login`	boolean	optional	—
`students_count`	integer	optional	—
`subscription`	any	optional	—
`last_login_at`	string \| null	optional	—
`created_at`	string (date-time)	optional	—
`row_version`	integer	required	—
`students`	object[]	optional	—

POST /v3/user/{id}/reset-password #

bearer pass_web admin_web staff.manage device credential

the §12.5 posture: the hash NULLs and the next login forces a set (credentials are never emailed around); every session the user held is revoked in the same call.

Path parameters

Name	Type	Notes
`id`	string

Response

Returns { "data": PasswordReset }.

Field	Type		Constraints
`must_set_password`	boolean	required	—