Twilio connector — endpoints

How to call the connector. The formal schema is the OpenAPI specification (Notification, openapi/source/connector/notifications/notifications.yml); this page covers the call contract and examples. Internal processing is in the architecture; caveats in the connector notes.

This is an internal connector API called by the Ark Platform, not by end clients. Message content arrives already templated/validated by the Platform.

Authentication

All /v1/notifications/* endpoints require a bearer token (OAuth2 client-credentials JWT). Health endpoints are unauthenticated probes.

Method	Path	Purpose
POST	/v1/notifications	Send or schedule an SMS
GET	/v1/notifications	List notifications (optional id filter)
GET	/v1/notifications/{notificationId}	Get one notification
DELETE	/v1/notifications/{notificationId}	Cancel a scheduled SMS
POST	/v1/notifications/{notificationId}/purge	Purge a notification
GET	/health · /health/readiness · /health/liveness	Probes (see architecture)

All responses wrap a NotificationData object: { notificationId, status, vendorId?, deliveryDateTime?, isPurged, errorDetails? }. status is the normalised Ark status (lifecycle); vendorId is the Twilio message SID.

---

POST /v1/notifications — send or schedule

Body — SendNotificationRequest:

Field	Required	Notes
notificationId	✓	UUID; the Ark id used for idempotency, lookup, cancel, purge
contactChannel	✓	Must be SMS — anything else → 400 (see the connector notes)
channelIdentifier	✓	Recipient phone in E.164 format (e.g. +61491570006)
messageContent	✓ (for SMS here)	Final message text; must be non-empty
messageType	✓ in schema	Accepted but not used by the connector
scheduledDateTime	—	ISO-8601; if present, must be > 5 min and ≤ 35 days ahead
templateId / templateVariables	—	Accepted by the schema but not used — templating is the Platform's job

// Request
{ "notificationId": "12345678-1234-1234-1234-123456789abc",
  "contactChannel": "SMS", "channelIdentifier": "+61491570006",
  "messageContent": "Your account balance is $1,234.56" }
// Response (SendNotificationResponse)
{ "notification": { "notificationId": "1234…abc", "vendorId": "SM…", "status": "DELIVERED",
                    "deliveryDateTime": null, "isPurged": false } }

---

GET /v1/notifications — list

Param	In	Required	Notes
arkNotificationIds	query	—	Comma-separated Ark ids to filter by; omit for all

Returns { "notifications": NotificationData[] }, read from the local store (not Twilio).

GET /v1/notifications/{notificationId} — get one

Returns one NotificationData (with errorDetails if a send failed). 404 if unknown.

DELETE /v1/notifications/{notificationId} — cancel

Cancels a scheduled SMS at Twilio and marks it CANCELLED. Only notifications whose stored status is scheduled or accepted can be cancelled.

• 404 if unknown / never reached Twilio; 412 if not in a cancellable state.

POST /v1/notifications/{notificationId}/purge — purge

Attempts to delete the message at Twilio (best-effort) and flags the local record purged (isPurged: true) for compliance. Idempotent: an already-purged or never-sent record returns its current state without calling Twilio. See the connector notes.

• 404 if unknown.

---

Errors

HTTP	Code	When
400	GEN000000	Request body/params fail schema validation
400	NOT000001	contactChannel is not SMS
400	NOT000004	Missing message content
401	GEN001002	Missing or invalid bearer token
404	NOT004001	No notification for the id
412	NOT012001	Cancel attempted on a non-cancellable status
422	NOT022003	scheduledDateTime outside the 5-min–35-day window
500	NOT100002	Local database write failure
500	NOT100004	Twilio send/credential failure
500	NOT100006	Twilio cancellation failure