Declaration Notification Service - API Contract

GET /api/v1/declaration-notifications/api/v1/declaration-notifications

List notification events for declarations

Public

Response Example

{
  "data": [
    {
      "notification_id": "notif_CC9F01",
      "declaration_id": "decl_88A1",
      "notification_type": "delivery",
      "recipient_id": "drv_0042",
      "sent_at": "2026-03-21T10:00:05Z",
      "status": "delivered"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 5
  }
}

GET /api/v1/declaration-notifications/api/v1/declaration-notifications/:notification_id

Get a single notification event by ID

Public

Response Example

{
  "notification_id": "notif_CC9F01",
  "declaration_id": "decl_88A1",
  "notification_type": "delivery",
  "recipient_id": "drv_0042",
  "sent_at": "2026-03-21T10:00:05Z",
  "status": "delivered",
  "channel": "push"
}

POST /api/v1/declaration-notifications/api/v1/declaration-notifications/delivery

Send a declaration delivery notification to a driver

Public

Request Example

{
  "driver_id": "drv_0042",
  "declaration_id": "decl_88A1"
}

Response Example

{
  "notification_id": "notif_CC9F01",
  "declaration_id": "decl_88A1",
  "notification_type": "delivery",
  "recipient_id": "drv_0042",
  "sent_at": "2026-03-26T09:00:00Z",
  "status": "delivered"
}

PUT /api/v1/declaration-notifications/api/v1/declaration-notifications/:notification_id

Update a notification record (e.g. mark retried, update status)

Public

Request Example

{
  "status": "failed",
  "failure_reason": "push_token_expired"
}

Response Example

{
  "notification_id": "notif_CC9F01",
  "status": "failed",
  "failure_reason": "push_token_expired",
  "updated_at": "2026-03-26T09:05:00Z"
}

DELETE /api/v1/declaration-notifications/api/v1/declaration-notifications/:notification_id

Delete a notification record

Public

Response Example

{
  "notification_id": "notif_CC9F01",
  "deleted": true
}

POST /api/v1/declaration-notifications/api/v1/declaration-notifications/reminders

Schedule an acknowledgement reminder for a declaration

Public

Request Example

{
  "declaration_id": "decl_88A1",
  "reminder_delay_hours": 48
}

Response Example

{
  "notification_id": "notif_CC9F02",
  "declaration_id": "decl_88A1",
  "notification_type": "reminder",
  "scheduled_at": "2026-03-28T10:00:00Z",
  "status": "scheduled"
}

POST /api/v1/declaration-notifications/api/v1/declaration-notifications/coordinator

Notify a coordinator that a declaration has been acknowledged

Public

Request Example

{
  "coordinator_id": "usr_coord_004",
  "declaration_id": "decl_88A1"
}

Response Example

{
  "notification_id": "notif_CC9F03",
  "declaration_id": "decl_88A1",
  "notification_type": "coordinator_ack",
  "recipient_id": "usr_coord_004",
  "sent_at": "2026-03-22T14:36:00Z",
  "status": "delivered"
}

DELETE /api/v1/declaration-notifications/api/v1/declaration-notifications/reminders/:declaration_id

Cancel all pending reminder notifications for a declaration

Public

Response Example

{
  "declaration_id": "decl_88A1",
  "cancelled_count": 2,
  "cancelled_at": "2026-03-26T09:30:00Z"
}

Additional Metadata

{
  "contract_summary": {
    "total_contracts": 410,
    "total_endpoints": 2416,
    "api_styles_used": [
      "rest"
    ]
  },
  "generated_at": "2026-03-26T06:55:53.316Z"
}