Resources

API Reference

Public REST API for integrating with EmbassyOS. Access citizen services, appointments, documents, and analytics programmatically.

Authentication

All API requests require a Bearer token in the Authorization header. Obtain tokens via the OAuth2 client credentials flow: send your client_id and client_secret to POST /api/v1/auth/token to receive an access_token. Use POST /api/v1/auth/refresh to renew before expiry. Tokens are short-lived; implement token caching in your client.

Base URL: https://api.embassyos.com

Authentication

Obtain, refresh, and revoke API access tokens.

POST/api/v1/auth/tokenAvailable

Obtain API access token via client credentials

Auth: None (client credentials)

POST/api/v1/auth/refreshAvailable

Refresh an expiring access token

Auth: None (client credentials)

POST/api/v1/auth/revokeAvailable

Revoke an active access token

Auth: Bearer token

Citizens

Manage registered citizen profiles and consular registration. Backlog: C12, C13.

GET/api/v1/citizensComing Soon

List registered citizens for a mission (paginated, filterable)

Auth: Bearer token (admin scope)

GET/api/v1/citizens/:idComing Soon

Get full citizen profile including registration details

Auth: Bearer token

POST/api/v1/citizensComing Soon

Auth: Bearer token (admin scope)

PATCH/api/v1/citizens/:idComing Soon

Update citizen profile fields

Auth: Bearer token

Service Requests

Submit, list, and manage consular service requests with stage tracking.

GET/api/v1/requestsBeta

List service requests with status, type, and date filters

Auth: Bearer token

GET/api/v1/requests/:idBeta

Get request details including timeline and stage history

Auth: Bearer token

POST/api/v1/requestsBeta

Submit a new service request

Auth: Bearer token

PATCH/api/v1/requests/:id/statusComing Soon

Update request status or transition to next stage

Auth: Bearer token (staff/admin scope)

GET/api/v1/requests/:id/documentsComing Soon

List documents attached to a service request

Auth: Bearer token

POST/api/v1/requests/:id/notesComing Soon

Add an internal note to a service request (staff/admin)

Auth: Bearer token (staff/admin scope)

Documents

Upload, download, verify, and manage citizen documents. Backlog: C12, C13, S9, A12.

POST/api/v1/documents/uploadComing Soon

Upload a document to citizen storage

Auth: Bearer token

GET/api/v1/documents/:idComing Soon

Download a document (signed URL)

Auth: Bearer token

DELETE/api/v1/documents/:idComing Soon

Delete a document from storage

Auth: Bearer token

PATCH/api/v1/documents/:id/verifyComing Soon

Mark a document as verified (staff review)

Auth: Bearer token (staff/admin scope)

Appointments

Book, reschedule, and cancel consular appointments. Backlog: C14, C15, A10.

GET/api/v1/appointments/slotsBeta

List available appointment slots for a mission

Auth: Bearer token

POST/api/v1/appointmentsBeta

Book an appointment for a specific service

Auth: Bearer token

PATCH/api/v1/appointments/:idComing Soon

Reschedule an existing appointment

Auth: Bearer token

DELETE/api/v1/appointments/:idComing Soon

Cancel an appointment

Auth: Bearer token

POST/api/v1/appointments/slotsComing Soon

Create or update availability slots (admin)

Auth: Bearer token (admin scope)

Staff

Manage staff profiles, assignments, and workload. Backlog: S7, S8, S11.

GET/api/v1/staffComing Soon

List staff members for a mission

Auth: Bearer token (admin scope)

GET/api/v1/staff/:idComing Soon

Get staff profile and service assignments

Auth: Bearer token

GET/api/v1/staff/:id/queueComing Soon

Get staff queue (requests assigned by service type)

Auth: Bearer token (staff scope)

PATCH/api/v1/staff/:id/assignmentsComing Soon

Update staff service assignments

Auth: Bearer token (admin scope)

Service Catalog

Manage the service catalog and workflow stages. Backlog: A9.

GET/api/v1/servicesComing Soon

List service types in the catalog

Auth: Bearer token

POST/api/v1/servicesComing Soon

Add a new service type to the catalog

Auth: Bearer token (admin scope)

PATCH/api/v1/services/:idComing Soon

Update service type details or toggle active status

Auth: Bearer token (admin scope)

Analytics

Service volume, performance metrics, and staff workload. Backlog: A11, S11, P9.

GET/api/v1/analytics/overviewComing Soon

Service volume, completion rates, and SLA metrics

Auth: Bearer token (admin scope)

GET/api/v1/analytics/servicesComing Soon

Per-service-type metrics and trends

Auth: Bearer token (admin scope)

GET/api/v1/analytics/staffComing Soon

Staff workload distribution and performance

Auth: Bearer token (admin scope)

Messaging

In-platform messaging between citizens and staff on service requests. Backlog: C17, S10.

GET/api/v1/requests/:id/messagesComing Soon

List messages on a service request thread

Auth: Bearer token

POST/api/v1/requests/:id/messagesComing Soon

Send a message on a service request thread

Auth: Bearer token

Notifications

Email and in-app notification delivery. Backlog: X1, C16.

GET/api/v1/notificationsComing Soon

List notifications for the authenticated user

Auth: Bearer token

PATCH/api/v1/notifications/:id/readComing Soon

Mark a notification as read

Auth: Bearer token