Introduction

Communications API

Overview

Organisation-scoped outbound email/SMS, in-app notifications, and per-user channel preferences. Cross-domain references use opaque recipient_id and links only.

Integration guide: Communications service docs

OpenAPI v0.1.0 · source openapi/communications.json

OpenAPI 3.0.0 · v0.1.0 · 13 operations

Operations

System

Liveness and generated documentation.

get/health

Health check

Example request

curl -sS \
  -X GET \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <jwt>" \
  "https://api.mayawealth.co.uk/communications/health"

Operation ID: getHealth

Responses

200
Service is running
application/json

get/v1/health

Health check (versioned)

Example request

curl -sS \
  -X GET \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <jwt>" \
  "https://api.mayawealth.co.uk/communications/v1/health"

Operation ID: getHealthV1

Responses

200
Service is running
application/json

Communications

Email and SMS.

get/v1/communications

List communications

Example request

curl -sS \
  -X GET \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <jwt>" \
  "https://api.mayawealth.co.uk/communications/v1/communications"

Organisation scope is JWT `orgId` only. Filter by `recipient_id` and/or `link_type` + `link_id` (opaque subject reference).

Operation ID: listCommunications

Parameters

Name	In	Type	Description
page	query	integer	—
page_size	query	integer	—
recipient_id	query	string (uuid)	—
link_type	query	string	—
link_id	query	string (uuid)	—

Responses

200
Communications
application/json
401
Missing or invalid JWT.
application/json
403
Authenticated but not permitted.
application/json
422
Validation failed.
application/json
429
Rate limit exceeded.
application/json
500
Unexpected server error.
application/json

post/v1/communications

Request communication

Example request

curl -sS \
  -X POST \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <jwt>" \
  -H "Content-Type: application/json" \
  "https://api.mayawealth.co.uk/communications/v1/communications"

Queues email or SMS. `recipient_id` and `links` are opaque UUIDs — this service does not call customers, bookings, or other APIs.

Operation ID: createCommunication

Request body(required)

application/jsonCommunicationCreate

Responses

201
Communication queued
application/json
400
Malformed request.
application/json
401
Missing or invalid JWT.
application/json
403
Authenticated but not permitted.
application/json
404
The requested resource was not found.
application/json
409
Conflict — version mismatch, idempotency conflict, or invalid state transition.
application/json
422
Validation failed.
application/json
429
Rate limit exceeded.
application/json
500
Unexpected server error.
application/json

get/v1/communications/{id}

Get communication

Example request

curl -sS \
  -X GET \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <jwt>" \
  "https://api.mayawealth.co.uk/communications/v1/communications/example-id"

Operation ID: getCommunication

Parameters

Name	In	Type	Description
id*	path	string	—

Responses

200
Communication
application/json
401
Missing or invalid JWT.
application/json
403
Authenticated but not permitted.
application/json
404
The requested resource was not found.
application/json
422
Validation failed.
application/json
429
Rate limit exceeded.
application/json
500
Unexpected server error.
application/json

Notifications

In-app notification inbox.

get/v1/notifications

Staff notification inbox

Example request

curl -sS \
  -X GET \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <jwt>" \
  "https://api.mayawealth.co.uk/communications/v1/notifications"

Operation ID: listNotifications

Parameters

Name	In	Type	Description
page	query	integer	—
page_size	query	integer	—
unread	query	string	Filter by read state.
kind	query	string	—
resource_id	query	string (uuid)	—
q	query	string	Case-insensitive substring search across title, body, kind, and related ids.

Responses

200
Notifications
application/json
401
Missing or invalid JWT.
application/json
403
Authenticated but not permitted.
application/json
422
Validation failed.
application/json
429
Rate limit exceeded.
application/json
500
Unexpected server error.
application/json

post/v1/notifications

Create staff notification

Example request

curl -sS \
  -X POST \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <jwt>" \
  -H "Content-Type: application/json" \
  "https://api.mayawealth.co.uk/communications/v1/notifications"

Queues an in-app notification for the JWT organisation. Other services should call this via service binding or integration JWT.

Operation ID: createNotification

Request body(required)

application/jsonNotificationCreate

Responses

201
Notification created
application/json
400
Malformed request.
application/json
401
Missing or invalid JWT.
application/json
403
Authenticated but not permitted.
application/json
404
The requested resource was not found.
application/json
409
Conflict — version mismatch, idempotency conflict, or invalid state transition.
application/json
422
Validation failed.
application/json
429
Rate limit exceeded.
application/json
500
Unexpected server error.
application/json

post/v1/notifications/search

Search notifications

Example request

curl -sS \
  -X POST \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <jwt>" \
  "https://api.mayawealth.co.uk/communications/v1/notifications/search"

Same filters and pagination as GET `/v1/notifications`, including optional `q` text search.

Operation ID: searchNotifications

Parameters

Name	In	Type	Description
page	query	integer	—
page_size	query	integer	—
unread	query	string	Filter by read state.
kind	query	string	—
resource_id	query	string (uuid)	—
q	query	string	Case-insensitive substring search across title, body, kind, and related ids.

Responses

200
Notifications
application/json
401
Missing or invalid JWT.
application/json
403
Authenticated but not permitted.
application/json
422
Validation failed.
application/json
429
Rate limit exceeded.
application/json
500
Unexpected server error.
application/json

get/v1/notifications/{id}

Get notification

Example request

curl -sS \
  -X GET \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <jwt>" \
  "https://api.mayawealth.co.uk/communications/v1/notifications/example-id"

Operation ID: getNotification

Parameters

Name	In	Type	Description
id*	path	string	—

Responses

200
Notification
application/json
401
Missing or invalid JWT.
application/json
403
Authenticated but not permitted.
application/json
404
The requested resource was not found.
application/json
422
Validation failed.
application/json
429
Rate limit exceeded.
application/json
500
Unexpected server error.
application/json

post/v1/notifications/{id}/read

Mark notification as read

Example request

curl -sS \
  -X POST \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <jwt>" \
  "https://api.mayawealth.co.uk/communications/v1/notifications/example-id/read"

Marks the notification read and sets `updated_at`. Read state cannot be reversed.

Operation ID: readNotification

Parameters

Name	In	Type	Description
id*	path	string	—

Responses

200
Notification
application/json
401
Missing or invalid JWT.
application/json
403
Authenticated but not permitted.
application/json
404
The requested resource was not found.
application/json
422
Validation failed.
application/json
429
Rate limit exceeded.
application/json
500
Unexpected server error.
application/json

User settings

Per-user notification channel preferences.

get/v1/settings

Current user notification preferences

Example request

curl -sS \
  -X GET \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <jwt>" \
  "https://api.mayawealth.co.uk/communications/v1/settings"

Per-user channel toggles (`in_app`, `email`, `sms`) for any Maya app. Scoped to JWT `orgId` and `actorId`.

Operation ID: getUserSettings

Responses

200
User settings
application/json

patch/v1/settings

Update current user notification preferences

Example request

curl -sS \
  -X PATCH \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <jwt>" \
  -H "Content-Type: application/json" \
  "https://api.mayawealth.co.uk/communications/v1/settings"

Operation ID: patchUserSettings

Request body(required)

application/jsonUserSettingsPatch

Responses

200
User settings updated
application/json
400
Malformed request.
application/json
401
Missing or invalid JWT.
application/json
403
Authenticated but not permitted.
application/json
404
The requested resource was not found.
application/json
409
Conflict — version mismatch, idempotency conflict, or invalid state transition.
application/json
422
Validation failed.
application/json
429
Rate limit exceeded.
application/json
500
Unexpected server error.
application/json

Audit

Immutable change log for this service.

get/v1/audit

Audit trail

Example request

curl -sS \
  -X GET \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <jwt>" \
  "https://api.mayawealth.co.uk/communications/v1/audit"

Operation ID: listAudit

Parameters

Name	In	Type	Description
page	query	integer	—
page_size	query	integer	—

Responses

200
Audit events
application/json
401
Missing or invalid JWT.
application/json
403
Authenticated but not permitted.
application/json
422
Validation failed.
application/json
429
Rate limit exceeded.
application/json
500
Unexpected server error.
application/json