openapi: 3.1.0
info:
  title: GOV.UK Notify Notifications API
  description: GOV.UK Notify is a UK government notification service operated by the Government Digital Service (GDS) that enables central government, local authorities, NHS organisations, and other eligible public bodies to send emails, text messages, and letters to citizens on behalf of government services. The API uses JWT-based authentication and supports template-driven personalisation.
  version: 2.0.0
  contact:
    url: https://www.notifications.service.gov.uk/support
  license:
    name: MIT
    url: https://github.com/alphagov/notifications-api/blob/main/LICENSE
  termsOfService: https://www.notifications.service.gov.uk/terms
servers:
- url: https://api.notifications.service.gov.uk
  description: GOV.UK Notify production API
security:
- bearerAuth: []
tags:
- name: Notifications
  description: Send and retrieve notifications (email, SMS, letters)
paths:
  /v2/notifications/sms:
    post:
      operationId: sendSms
      summary: Send a text message
      description: Send a text message (SMS) notification to a recipient using a pre-defined template.
      tags:
      - Notifications
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SendSmsRequest'
            example:
              phone_number: '+447900900123'
              template_id: f33517ff-2a88-4f6e-b855-c550268ce08a
              personalisation:
                name: Jane
              reference: unique-ref-001
      responses:
        '201':
          description: SMS notification created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotificationResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/ServerError'
  /v2/notifications/email:
    post:
      operationId: sendEmail
      summary: Send an email notification
      description: Send an email notification to a recipient using a pre-defined template. Can also be used to send a file by email by including a link_to_file object in the personalisation field.
      tags:
      - Notifications
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SendEmailRequest'
            example:
              email_address: citizen@example.com
              template_id: f33517ff-2a88-4f6e-b855-c550268ce08a
              personalisation:
                name: Jane
              reference: unique-ref-002
              one_click_unsubscribe_url: https://example.com/unsubscribe
      responses:
        '201':
          description: Email notification created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotificationResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/ServerError'
  /v2/notifications/letter:
    post:
      operationId: sendLetter
      summary: Send a letter notification
      description: Send a letter notification to a recipient using a pre-defined template, or send a precompiled letter as a base64-encoded PDF.
      tags:
      - Notifications
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SendLetterRequest'
            examples:
              template_letter:
                summary: Template-based letter
                value:
                  template_id: f33517ff-2a88-4f6e-b855-c550268ce08a
                  personalisation:
                    address_line_1: The Occupier
                    address_line_2: 123 High Street
                    address_line_3: London
                    postcode: SW14 6BF
                    name: Jane
                  reference: unique-ref-003
              precompiled_letter:
                summary: Precompiled PDF letter
                value:
                  reference: unique-ref-004
                  content: JVBERi0xLjUgb2JqZWN0...
                  postage: second
      responses:
        '201':
          description: Letter notification created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotificationResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/ServerError'
  /v2/notifications/{notification_id}:
    get:
      operationId: getNotification
      summary: Get notification by ID
      description: Retrieve the status and details of a single notification by its UUID.
      tags:
      - Notifications
      parameters:
      - name: notification_id
        in: path
        required: true
        description: UUID of the notification
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Notification details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Notification'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/ServerError'
  /v2/notifications/{notification_id}/pdf:
    get:
      operationId: getLetterPdf
      summary: Get letter PDF
      description: Download the PDF file for a letter notification.
      tags:
      - Notifications
      parameters:
      - name: notification_id
        in: path
        required: true
        description: UUID of the letter notification
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: PDF binary content
          content:
            application/pdf:
              schema:
                type: string
                format: binary
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/ServerError'
  /v2/notifications:
    get:
      operationId: listNotifications
      summary: List notifications
      description: Retrieve a list of notifications sent by the service, optionally filtered by type, status, or reference. Returns up to 250 notifications per request with pagination.
      tags:
      - Notifications
      parameters:
      - name: template_type
        in: query
        required: false
        description: Filter by notification type
        schema:
          type: string
          enum:
          - email
          - sms
          - letter
      - name: status
        in: query
        required: false
        description: Filter by notification status
        schema:
          type: string
      - name: reference
        in: query
        required: false
        description: Filter by client reference string
        schema:
          type: string
      - name: older_than
        in: query
        required: false
        description: UUID of a notification; returns notifications older than this ID (pagination)
        schema:
          type: string
          format: uuid
      - name: include_jobs
        in: query
        required: false
        description: Include notifications from CSV batch uploads
        schema:
          type: boolean
      responses:
        '200':
          description: List of notifications
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotificationList'
        '403':
          $ref: '#/components/responses/Forbidden'
        '500':
          $ref: '#/components/responses/ServerError'
components:
  schemas:
    TemplateRef:
      type: object
      properties:
        id:
          type: string
          format: uuid
        version:
          type: integer
        uri:
          type: string
          format: uri
    ErrorResponse:
      type: object
      properties:
        status_code:
          type: integer
        errors:
          type: array
          items:
            type: object
            properties:
              error:
                type: string
                description: Machine-readable error type
              message:
                type: string
                description: Human-readable error description
    NotificationResponse:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: UUID of the created notification
        reference:
          type: string
          description: Client reference (if provided)
        content:
          type: object
          description: Rendered notification content
          properties:
            body:
              type: string
              description: Rendered message body
            subject:
              type: string
              description: Rendered email subject (email notifications only)
            from_number:
              type: string
              description: SMS sender (SMS notifications only)
        uri:
          type: string
          format: uri
          description: API URL to retrieve this notification
        template:
          $ref: '#/components/schemas/TemplateRef'
        scheduled_for:
          type: string
          format: date-time
          nullable: true
          description: Scheduled send time (if applicable)
    SendSmsRequest:
      type: object
      required:
      - phone_number
      - template_id
      properties:
        phone_number:
          type: string
          description: UK mobile phone number of the recipient (E.164 format recommended)
          example: '+447900900123'
        template_id:
          type: string
          format: uuid
          description: UUID of the SMS template to use
        personalisation:
          type: object
          additionalProperties:
            type: string
          description: Key-value pairs to fill template placeholders
        reference:
          type: string
          description: Client-supplied unique reference for this notification
        sms_sender_id:
          type: string
          format: uuid
          description: UUID of the SMS sender to use (overrides service default)
    Notification:
      type: object
      properties:
        id:
          type: string
          format: uuid
        reference:
          type: string
          nullable: true
        email_address:
          type: string
          format: email
          description: Recipient email (email notifications only)
        phone_number:
          type: string
          description: Recipient phone number (SMS notifications only)
        line_1:
          type: string
          description: First address line (letter notifications only)
        line_2:
          type: string
          nullable: true
        line_3:
          type: string
          nullable: true
        line_4:
          type: string
          nullable: true
        line_5:
          type: string
          nullable: true
        line_6:
          type: string
          nullable: true
        postcode:
          type: string
          nullable: true
        type:
          type: string
          enum:
          - email
          - sms
          - letter
        status:
          type: string
          description: Current delivery status of the notification
        template:
          $ref: '#/components/schemas/TemplateRef'
        body:
          type: string
          description: Rendered notification body
        subject:
          type: string
          nullable: true
          description: Rendered email subject (email only)
        created_at:
          type: string
          format: date-time
        sent_at:
          type: string
          format: date-time
          nullable: true
        completed_at:
          type: string
          format: date-time
          nullable: true
        estimated_delivery:
          type: string
          format: date-time
          nullable: true
          description: Estimated delivery time (letter notifications)
        cost_in_pounds:
          type: number
          format: float
          nullable: true
          description: Cost of the notification in GBP
        cost_details:
          type: object
          nullable: true
          description: Breakdown of cost components
        postage:
          type: string
          nullable: true
          description: Postage class used (letter notifications only)
        created_by_name:
          type: string
          nullable: true
          description: Name of the user who sent the notification (if sent via UI)
    SendEmailRequest:
      type: object
      required:
      - email_address
      - template_id
      properties:
        email_address:
          type: string
          format: email
          description: Email address of the recipient
        template_id:
          type: string
          format: uuid
          description: UUID of the email template to use
        personalisation:
          type: object
          additionalProperties: true
          description: Key-value pairs to fill template placeholders. Use a link_to_file object value to send a file by email.
        reference:
          type: string
          description: Client-supplied unique reference for this notification
        one_click_unsubscribe_url:
          type: string
          format: uri
          description: HTTPS URL for one-click unsubscribe (recommended for bulk sends)
        email_reply_to_id:
          type: string
          format: uuid
          description: UUID of a reply-to email address configured on the service
        sanitise_content_for:
          type: array
          items:
            type: string
          description: Array of personalisation field names whose content should be sanitised
    SendLetterRequest:
      type: object
      properties:
        template_id:
          type: string
          format: uuid
          description: UUID of the letter template (required for template-based letters)
        personalisation:
          type: object
          additionalProperties:
            type: string
          description: Address lines and template placeholder values. address_line_1, address_line_2, and address_line_3 are required minimum address fields.
        reference:
          type: string
          description: Client-supplied unique reference for this notification
        content:
          type: string
          format: byte
          description: Base64-encoded PDF content (for precompiled letters; mutually exclusive with template_id)
        postage:
          type: string
          enum:
          - first
          - second
          - economy
          description: Postage class for precompiled letters
    NotificationList:
      type: object
      properties:
        notifications:
          type: array
          items:
            $ref: '#/components/schemas/Notification'
        links:
          type: object
          properties:
            current:
              type: string
              format: uri
            next:
              type: string
              format: uri
              description: URL to retrieve the next page of results
  responses:
    Forbidden:
      description: Authentication failed or API key lacks permission
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            status_code: 403
            errors:
            - error: AuthError
              message: 'Invalid token: API key not found'
    NotFound:
      description: Requested resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            status_code: 404
            errors:
            - error: NoResultFound
              message: No result found
    RateLimited:
      description: Rate limit exceeded (3,000 messages per minute per API key)
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            status_code: 429
            errors:
            - error: TooManyRequestsError
              message: Exceeded send limits (3000) for today
    BadRequest:
      description: Validation error in request body or parameters
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            status_code: 400
            errors:
            - error: ValidationError
              message: phone_number is not a valid phone number
    ServerError:
      description: Internal server error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            status_code: 500
            errors:
            - error: Exception
              message: Internal server error
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: JWT token signed with HS256 using the service API key secret. Tokens are short-lived and must include iss (service ID), iat (issued at), and exp (expiry) claims.