GC Notify
API documentation

Get bulk job status

You can use the GC Notify API to retrieve the status and notification statistics for bulk sending jobs.

Get a list of bulk jobs

GET /v2/notifications/bulk

This endpoint returns bulk jobs created by the service associated with your API key, ordered from newest to oldest. The response is paginated.

Query parameters

older_than (optional)

Use the ID of a bulk job from the previous page to retrieve older jobs. The next page URL is returned in links.next when another page is available. You can use that URL directly or pass its older_than value in a new request.

"older_than": "684fca45-42d9-4cae-bf84-22a9f5fc9e6f"

Response

If the request is successful, the response body is json and the status code is 200:

{
  "bulk_jobs": [
    {
      "id": "684fca45-42d9-4cae-bf84-22a9f5fc9e6f",
      "original_file_name": "Bulk send name",
      "notification_count": 3,
      "template": "055d4e5c-27c2-4ea6-8736-d4c328279acf",
      "template_version": 4,
      "template_type": "email",
      "service": "f8ea1d5f-95db-4374-a6ad-5251a26173c8",
      "service_name": { "name": "Test service" },
      "created_by": {
        "id": "6887e196-437f-4e3a-aaee-c152dc54c900",
        "name": "Notify service user"
      },
      "api_key": {
        "id": "0bc38ecd-8be3-4896-a3f3-fc8178a782d6",
        "name": "Test",
        "key_type": "team"
      },
      "job_status": "pending",
      "scheduled_for": null,
      "processing_started": null,
      "processing_finished": null,
      "created_at": "2021-06-10T17:14:15.341308+00:00",
      "updated_at": null,
      "archived": false,
      "sender_id": null,
      "statistics": [
        { "status": "delivered", "count": 2 },
        { "status": "failed", "count": 1 }
      ]
    }
  ],
  "links": {
    "current": "https://api.notification.canada.ca/v2/notifications/bulk",
    "next": "https://api.notification.canada.ca/v2/notifications/bulk?older_than=684fca45-42d9-4cae-bf84-22a9f5fc9e6f"
  }
}

statistics contains one entry for each notification status and its count. It is an empty array when no statistics are available.

Get a bulk job by ID

GET /v2/notifications/bulk/{job_id}

Use this endpoint to retrieve one bulk job and its current status. The response has the same job fields as the list endpoint and is wrapped in a data object.

job_id (required)

The ID of the bulk job. You can find it in the response from POST /v2/notifications/bulk or in the bulk_jobs response from the list endpoint.

Cancel a bulk job

DELETE /v2/notifications/bulk/{job_id}

Use this endpoint to cancel a bulk job that is scheduled to send in the future but has not started sending yet. You cannot cancel a job if it:

  1. has already started sending
  2. has already finished sending
  3. has already been cancelled

job_id (required)

The ID of the bulk job you want to cancel.

Response

If the request is successful, the response body is json and the status code is 200. The job is returned with the same fields as Get a bulk job by ID, wrapped in a data object, with job_status set to cancelled:

{
  "data": {
    "id": "684fca45-42d9-4cae-bf84-22a9f5fc9e6f",
    "original_file_name": "Bulk send name",
    "notification_count": 3,
    "template": "055d4e5c-27c2-4ea6-8736-d4c328279acf",
    "template_version": 4,
    "template_type": "email",
    "job_status": "cancelled",
    "scheduled_for": "2021-06-10T18:00:00.000000+00:00",
    "created_at": "2021-06-10T17:14:15.341308+00:00",
    "updated_at": "2021-06-10T17:20:00.000000+00:00",
    "statistics": []
  }
}

Error codes

status_code message How to fix
400 Invalid job ID or older_than value Check that the value is a valid UUID. The older_than job must belong to your service.
403 AuthError Use the correct API key.
404 JobNotFoundError Check the bulk job ID.
409 JobAlreadyCancelledError The job has already been cancelled. You can't cancel it again.
409 JobCancellationNotAllowedError The job can no longer be cancelled because it has already started sending, has finished sending, or its scheduled time has passed. Only jobs that are still scheduled can be cancelled.

← Reports →