openapi: 3.0.1
info:
  description: The NotifyNL REST API. Read [our documentation](https://docs.notifynl.nl) for more details.
  title: NotifyNL API
  version: 1.0.3
  license:
    name: European Union Public Licence v1.2
    url: https://eupl.eu/
  x-logo:
    url: https://omc-notify.gitbook.io/omc-notify-docs/~gitbook/image?url=https%3A%2F%2F1558516846-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Forganizations%252FnXcWmFpocmdy1LTho1Vw%252Fsites%252Fsite_DzlDE%252Ficon%252FBXd2A6ANNvmovbp4YeNR%252Ffavicon.png%3Falt%3Dmedia%26token%3D2ad71981-de69-4eac-85a7-7c2b476d1ee1&width=32&dpr=1&quality=100&sign=aaa4205a&sv=2
    altText: NotifyNL
servers:
  - url: https://api.notifynl.nl
tags:
  - name: Send a message
    description: Send a message.
  - name: Get message data
    description: Get message status
  - name: Get a template
    description: Get a template
  - name: Get received text messages
    description: Get received text messages
paths:
  /v2/notifications/sms:
    post:
      description: You can use this endpoint to send text message.  You can configure callbacks that provide delivery receipts by following the instructions in [our documentation](https://docs.notifynl.nl/rest-api.html#callbacks).
      operationId: sendTextMessage
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SendTextMessageRequest'
        description: requestPayload
        required: true
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SendTextMessageResponse'
          description: Created
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SendNotificaitonRequestError'
          description: Bad request. Check the `message` in the response to find out why your request failed.
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthError'
          description: Auth error. Check the `message` in the response to find out why your request failed.
        '429':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LimitError'
          description: Rate or service limit error. Check the `message` in the response to find out why your request failed.
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServerError'
          description: Internal server error. Check the `message` in the response to find out why your request failed.
      callbacks:
        onSmsSend:
          '{$callback_url}':
            post:
              requestBody:
                description: |-
                  Callbacks are when NotifyNL sends POST requests to your service. You can get callbacks when sms you’ve sent is delivered or fails.

                  ### Set up callbacks

                  You must provide:

                  - a URL where Notify will post the callback to
                  - a bearer token which Notify will put in the authorisation header of the requests

                  To do this:

                  1. [Sign in to NotifyNL](https://admin.notifynl.nl/sign-in).
                  1. Go to the __API integration__ page.
                  1. Select __Callbacks__.

                  ### Retry callbacks

                  If Notify sends a `POST` request to your service, but the request fails then we will retry.

                  We will retry every 5 minutes, up to a maximum of 5 times.

                  ### Delivery receipts

                  When you send an text message, Notify will send a receipt to your callback URL with the status of the message. This is an automated method to get the status of messages.

                  This functionality works with test API keys, but does not work with smoke testing phone numbers.

                  The callback message is formatted in JSON. All of the values are strings, apart from the template version, which is a number. The key, description and format of the callback message arguments will be:
                  |Key | Description | Format|
                  |:---|:---|:---|
                  |`id` | Notify’s id for the status receipts | UUID|
                  |`reference` | The reference sent by the service | `12345678` or null|
                  |`to` | The phone number of the recipient | `07700912345`|
                  |`status` | The status of the notification | `delivered`, `permanent-failure`, `temporary-failure` or `technical-failure`|
                  |`created_at` | The time the service sent the request | `2017-05-14T12:15:30.000000Z`|
                  |`completed_at` | The last time the status was updated | `2017-05-14T12:15:30.000000Z` or null|
                  |`sent_at` | The time the notification was sent | `2017-05-14T12:15:30.000000Z` or null|
                  |`notification_type` | The notification type | `sms`|
                  |`template_id` | The id of the template that was used | UUID|
                  |`template_version` | The version number of the template that was used | `1`|
                content:
                  application/json:
                    schema:
                      $ref: '#/components/schemas/SmsCallbackRequest'
              responses:
                2XX:
                  description: Success
                4XX:
                  description: Failed
                5XX:
                  description: Failed
              security:
                - BearerAuth: []
              summary: Text message callback
      security:
        - BearerAuth: []
      summary: Send a text message
      tags:
        - Send a message
  /v2/notifications/email:
    post:
      description: You can use this endpoint to send email.  You can configure callbacks that provide delivery receipts by following the instructions in [our documentation](https://docs.notifynl.nl/rest-api.html#callbacks).
      operationId: sendEmail
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SendEmailRequest'
        description: requestPayload
        required: true
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SendEmailResponse'
          description: Created
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SendNotificaitonRequestError'
          description: Bad request. Check the `message` in the response to find out why your request failed.
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthError'
          description: Auth error. Check the `message` in the response to find out why your request failed.
        '429':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LimitError'
          description: Rate or service limit error. Check the `message` in the response to find out why your request failed.
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServerError'
          description: Internal server error. Check the `message` in the response to find out why your request failed.
      callbacks:
        onEmailSend:
          '{$callback_url}':
            post:
              requestBody:
                description: |-
                  Callbacks are when NotifyNL sends POST requests to your service. You can get callbacks when email you’ve sent is delivered or fails.

                  ### Set up callbacks

                  You must provide:

                  - a URL where Notify will post the callback to
                  - a bearer token which Notify will put in the authorisation header of the requests

                  To do this:

                  1. [Sign in to NotifyNL](https://admin.notifynl.nl/sign-in).
                  1. Go to the __API integration__ page.
                  1. Select __Callbacks__.

                  ### Retry callbacks

                  If Notify sends a `POST` request to your service, but the request fails then we will retry.

                  We will retry every 5 minutes, up to a maximum of 5 times.

                  ### Delivery receipts

                  When you send an email, Notify will send a receipt to your callback URL with the status of the message. This is an automated method to get the status of messages.

                  This functionality works with test API keys, but does not work with smoke testing email addresses.

                  The callback message is formatted in JSON. All of the values are strings, apart from the template version, which is a number. The key, description and format of the callback message arguments will be:
                  |Key | Description | Format|
                  |:---|:---|:---|
                  |`id` | Notify’s id for the status receipts | UUID|
                  |`reference` | The reference sent by the service | `12345678` or null|
                  |`to` | The email address of the recipient | `hello@gov.uk`|
                  |`status` | The status of the notification | `delivered`, `permanent-failure`, `temporary-failure` or `technical-failure`|
                  |`created_at` | The time the service sent the request | `2017-05-14T12:15:30.000000Z`|
                  |`completed_at` | The last time the status was updated | `2017-05-14T12:15:30.000000Z` or null|
                  |`sent_at` | The time the notification was sent | `2017-05-14T12:15:30.000000Z` or null|
                  |`notification_type` | The notification type | `email`|
                  |`template_id` | The id of the template that was used | UUID|
                  |`template_version` | The version number of the template that was used | `1`|
                content:
                  application/json:
                    schema:
                      $ref: '#/components/schemas/EmailCallbackRequest'
              responses:
                2XX:
                  description: Success
                4XX:
                  description: Failed
                5XX:
                  description: Failed
              security:
                - BearerAuth: []
              summary: Email callback
      security:
        - BearerAuth: []
      summary: Send an email
      tags:
        - Send a message
  /v2/notifications/letter:
    post:
      description: You can use this endpoint to send letter.
      operationId: sendLetter
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SendLetterRequest'
            examples:
              Letter:
                value:
                  template_id: f33517ff-2a88-4f6e-b855-c550268ce08a
                  personalisation:
                    address_line_1: The Occupier
                    address_line_2: 123 High Street
                    address_line_3: Richmond upon Thames
                    address_line_4: Middlesex
                    address_line_5: SW14 6BF
                    address_line_6: string
                    address_line_7: string
                    name: John Smith
                    application_id: '4134325'
                    required_documents:
                      - passport
                      - utility bill
                      - other id
                  reference: STRING
              Precompiled Letter:
                value:
                  reference: STRING
                  content: base64EncodedPDFFile
                  postage: second
        description: requestPayload
        required: true
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SendLetterResponse'
              examples:
                Letter:
                  value:
                    id: 740e5834-3a29-46b4-9a6f-16142fde533a
                    reference: STRING
                    content:
                      subject: SUBJECT TEXT
                      body: LETTER TEXT
                    uri: https://api.notifynl.nl/v2/notifications/740e5834-3a29-46b4-9a6f-16142fde533a
                    template:
                      id: f33517ff-2a88-4f6e-b855-c550268ce08a
                      version: 1
                      uri: https://api.notifynl.nl/v2/template/f33517ff-2a88-4f6e-b855-c550268ce08a
                    scheduled_for: null
                Precompiled Letter:
                  value:
                    id: 740e5834-3a29-46b4-9a6f-16142fde533a
                    reference: your-letter-reference
                    postage: postage-you-have-set-or-default
          description: Created
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SendNotificaitonRequestError'
          description: Bad request. Check the `message` in the response to find out why your request failed.
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthError'
          description: Auth error. Check the `message` in the response to find out why your request failed.
        '429':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LimitError'
          description: Rate or service limit error. Check the `message` in the response to find out why your request failed.
      security:
        - BearerAuth: []
      summary: Send a letter
      tags:
        - Send a message
  /v2/notifications/{notification_id}:
    get:
      description: You can use this endpoint to get the data for one message. The data includes the status of the message. The status will vary depending on the type of message you have sent.<br />You can only get the data for messages sent within the retention period. The default retention period is 7 days.<br />You can omit any of these optional arguments to ignore these filters.
      operationId: getMessageData
      parameters:
        - description: The ID of the notification. You can find the notification ID in the response to the original notification method call.
          example: 740e5834-3a29-46b4-9a6f-16142fde533a
          in: path
          name: notification_id
          schema:
            type: string
          required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetOneMessageResponse'
          description: Success
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetMessageValidationError'
          description: Bad request. Check the `message` in the response to find out why your request failed.
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthError'
          description: Auth error. Check the `message` in the response to find out why your request failed.
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetMessageNoResultFoundError'
          description: Result not found. Check the `message` in the response to find out why your request failed.
      security:
        - BearerAuth: []
      summary: Get the data for one message
      tags:
        - Get message data
  /v2/notifications:
    get:
      description: This API call returns one page with data for up to 250 messages. You can get either the most recent messages, or get older messages by specifying a particular notification ID in the `older_than` argument.<br />You can only get the data for messages that are 7 days old or newer.<br />This will return all your messages with statuses. They will display in pages of up to 250 messages each.<br />You can omit any of these arguments to ignore these filters.
      operationId: getMultipleMessagesStatus
      parameters:
        - description: You can filter by `email`, `sms` or `letter`
          in: query
          name: template_type
          schema:
            type: string
            enum:
              - email
              - sms
              - letter
        - description: You can filter by message status.
          in: query
          name: status
          schema:
            type: string
            enum:
              - accepted
              - created
              - sending
              - pending
              - sent
              - received
              - delivered
              - cancelled
              - pending-virus-check
              - virus-scan-failed
              - validation-failed
              - permanent-failure
              - temporary-failure
              - technical-failure
          examples:
            Emails:
              summary: Emails Status
              description: |
                | Status | Description |
                | --- | --- |
                | `created` | NotifyNL has placed the message in a queue, ready to be sent to the provider. It should only remain in this state for a few seconds. |
                | `sending` | NotifyNL has sent the message to the provider. The provider will try to deliver the message to the recipient for up to 72 hours. NotifyNL is waiting for delivery information. |
                | `delivered` | The message was successfully delivered. |
                | `permanent-failure` | The provider could not deliver the message because the email address was wrong. You should remove these email addresses from your database. |
                | `temporary-failure` | The provider could not deliver the message. This can happen when the recipient’s inbox is full or their anti-spam filter rejects your email. [Check your content does not look like spam](https://www.gov.uk/service-manual/design/sending-emails-and-text-messages#protect-your-users-from-spam-and-phishing) before you try to send the message again. |
                | `technical-failure` | Your message was not sent because there was a problem between Notify and the provider.  <br>You’ll have to try sending your messages again. |
            Text Message:
              summary: Text Message Status
              description: |-
                | Status | Description |
                | --- | --- |
                | `created` | NotifyNL has placed the message in a queue, ready to be sent to the provider. It should only remain in this state for a few seconds. |
                | `sending` | NotifyNL has sent the message to the provider. The provider will try to deliver the message to the recipient for up to 72 hours. NotifyNL is waiting for delivery information. |
                | `pending` | NotifyNL is waiting for more delivery information.  <br>NotifyNL received a callback from the provider but the recipient’s device has not yet responded. Another callback from the provider determines the final status of the text message. |
                | `sent` | The message was sent to an international number. The mobile networks in some countries do not provide any more delivery information. The NotifyNL website displays this status as ‘Sent to an international number’. |
                | `delivered` | The message was successfully delivered. If a recipient blocks your sender ID or mobile number, your message will still show as delivered. |
                | `permanent-failure` | The provider could not deliver the message. This can happen if the phone number was wrong or if the network operator rejects the message. If you’re sure that these phone numbers are correct, you should [contact NotifyNL support](https://admin.notifynl.nl/support). If not, you should remove them from your database. You’ll still be charged for text messages that cannot be delivered. |
                | `temporary-failure` | The provider could not deliver the message. This can happen when the recipient’s phone is off, has no signal, or their text message inbox is full. You can try to send the message again. You’ll still be charged for text messages to phones that are not accepting messages. |
                | `technical-failure` | Your message was not sent because there was a problem between Notify and the provider.  <br>You’ll have to try sending your messages again. You will not be charged for text messages that are affected by a technical failure. |
            Letter:
              summary: Letter Status
              description: |-
                | Status | Description |
                | --- | --- |
                | `accepted` | NotifyNL has sent the letter to the provider to be printed. |
                | `received` | The provider has printed and dispatched the letter. |
                | `cancelled` | Sending cancelled. The letter will not be printed or dispatched. |
                | `technical-failure` | NotifyNL had an unexpected error while sending the letter to our printing provider. |
                | `permanent-failure` | The provider cannot print the letter. Your letter will not be dispatched. |
            Precompiled Letter:
              summary: Precompiled Letter Status
              description: |-
                | Status | Description |
                | --- | --- |
                | `accepted` | NotifyNL has sent the letter to the provider to be printed. |
                | `received` | The provider has printed and dispatched the letter. |
                | `cancelled` | Sending cancelled. The letter will not be printed or dispatched. |
                | `pending-virus-check` | NotifyNL has not completed a virus scan of the precompiled letter file. |
                | `virus-scan-failed` | NotifyNL found a potential virus in the precompiled letter file. |
                | `validation-failed` | Content in the precompiled letter file is outside the printable area. See the [NotifyNL letter specification](https://admin.notifynl.nl/using-notify/guidance/letter-specification) for more information. |
                | `technical-failure` | NotifyNL had an unexpected error while sending the letter to our printing provider. |
                | `permanent-failure` | The provider cannot print the letter. Your letter will not be dispatched. |
        - description: An identifier you can create if necessary. This reference identifies a single notification or a batch of notifications. It must not contain any personal information such as name or postal address.
          name: reference
          in: query
          schema:
            type: string
          example: STRING
        - description: Input the ID of a notification into this argument. If you use this argument, the method returns the next 250 received notifications older than the given ID.<br />If you leave out this argument, the method returns the most recent 250 notifications.<br />The client only returns notifications that are 7 days old or newer. If the notification specified in this argument is older than 7 days, the client returns an empty response.
          name: older_than
          in: query
          schema:
            type: string
          example: 740e5834-3a29-46b4-9a6f-16142fde533a
        - description: Includes notifications sent as part of a batch upload.<br />If you leave out this argument, the method only returns notifications sent using the API.
          name: include_jobs
          in: query
          schema:
            type: boolean
          example: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetMultipleMessagesResponse'
          description: Success
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetMessageValidationError'
          description: Bad request. Check the `message` in the response to find out why your request failed.
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthError'
          description: Auth error. Check the `message` in the response to find out why your request failed.
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetMessageNoResultFoundError'
          description: Result not found. Check the `message` in the response to find out why your request failed.
      security:
        - BearerAuth: []
      summary: Get the data for multiple messages
      tags:
        - Get message data
  /v2/notifications/{notification_id}/pdf:
    get:
      description: You can use this endpoint to get PDF contents of a letter.
      operationId: getLetterPdfContents
      parameters:
        - description: |-
            The ID of the notification. You can find the notification ID in the response to the original notification method call.
            You can also find it by [signing in to NotifyNL](https://admin.notifynl.nl/sign-in) and going to the **API integration** page.
          example: 740e5834-3a29-46b4-9a6f-16142fde533a
          in: path
          name: notification_id
          schema:
            type: string
          required: true
      responses:
        '200':
          content:
            application/pdf:
              schema:
                type: string
                format: binary
          description: If the request to the client is successful, the client will return bytes representing the raw PDF data.
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetMessageValidationError'
          description: Bad request. Check the `message` in the response to find out why your request failed.
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthError'
          description: Auth error. Check the `message` in the response to find out why your request failed.
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetMessageNoResultFoundError'
          description: Result not found. Check the `message` in the response to find out why your request failed.
      security:
        - BearerAuth: []
      summary: Get the the PDF contents of a letter
      tags:
        - Get message data
  /v2/received-text-messages:
    get:
      description: |-
        **Get received text messages**
        This API call returns one page of up to 250 received text messages. You can get either the most recent messages, or get older messages by specifying a particular notification ID in the older_than argument.
        You can only get the data for messages that are 7 days old or newer.
        **Enable received text messages**
        To receive text messages:
        1.  Go to the **Text message settings** section of the **Settings** page.
        2.  Select **Change** on the **Receive text messages** row.
      operationId: getReceivedMessagesStatus
      parameters:
        - description: The ID of a received text message. If this is passed, the response will only list text messages received before that message.
          in: query
          name: older_than
          schema:
            type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetReceivedTextMessagesResponse'
          description: Success
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetMessageValidationError'
          description: Bad request. Check the `message` in the response to find out why your request failed.
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthError'
          description: Auth error. Check the `message` in the response to find out why your request failed.
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetMessageNoResultFoundError'
          description: Result not found. Check the `message` in the response to find out why your request failed.
      security:
        - BearerAuth: []
      summary: Get received text messages
      tags:
        - Get received text messages
  /v2/templates:
    get:
      description: This returns the latest version of all templates.
      operationId: GetTemplates
      parameters:
        - name: type
          in: query
          description: 'If you leave out this argument, the method returns all templates. Otherwise you can filter by: email, sms, letter'
          required: false
          schema:
            $ref: '#/components/schemas/TemplatesRequest'
          examples:
            sms:
              summary: type=sms
              description: Show templates of type SMS
              value: sms
            email:
              summary: type=email
              description: Show templates of type email
              value: email
            letter:
              summary: type=letter
              description: Show templates of type email
              value: letter
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TemplatesResponse'
              examples:
                sms:
                  value:
                    templates:
                      - id: b7a59abd-0ab2-4538-b619-8da9f9089e08
                        name: Test SMS Template
                        type: sms
                        created_at: '2024-08-12T11:03:12.000000Z'
                        updated_at: '2024-08-12T11:03:34.994540Z'
                        version: 2
                        created_by: someone@example.com
                        body: Hi ((firstname)), We have received your letter dated ((date)).  No further action is required.
                        subject: null
                        postage: null
                        letter_contact_block: null
                        personalisation:
                          date:
                            required: true
                          firstname:
                            required: true
                email:
                  value:
                    templates:
                      - id: 8604d595-c65e-4d80-ae33-34fd08c736a5
                        name: Test Email Template
                        type: email
                        created_at: '2024-08-12T10:40:20.000000Z'
                        updated_at: '2024-08-12T10:45:47.890097Z'
                        version: 3
                        created_by: someone@example.com
                        body: "Hi ((firstname)),\r\nWe have received your letter dated ((date)).\r\n No further action is required."
                        subject: Test Email
                        letter_contact_block: null
                        postage: null
                        personalisation:
                          date:
                            required: true
                          firstname:
                            required: true
                letter:
                  value:
                    templates:
                      - id: 142d3a1b-f6cb-4bbb-9732-e1d9f9f2fed4
                        name: Test Letter Template
                        type: letter
                        postage: second
                        created_at: '2024-08-20T19:50:43.000000Z'
                        updated_at: '2024-08-20T19:51:51.980848Z'
                        version: 2
                        created_by: someone@example.com
                        body: Hi ((firstname)), We have received your letter dated ((date)).  No further action is required.
                        subject: Test Letter
                        letter_contact_block: |-
                          From Address
                          City
                        personalisation:
                          date:
                            required: true
                          firstname:
                            required: true
                type not set:
                  value:
                    templates:
                      - id: b7a59abd-0ab2-4538-b619-8da9f9089e08
                        name: Test SMS Template
                        type: sms
                        created_at: '2024-08-12T11:03:12.000000Z'
                        updated_at: '2024-08-12T11:03:34.994540Z'
                        version: 2
                        created_by: someone@example.com
                        body: Hi ((firstname)), We have received your letter dated ((date)).  No further action is required.
                        subject: null
                        postage: null
                        letter_contact_block: null
                        personalisation:
                          date:
                            required: true
                          firstname:
                            required: true
                      - id: 8604d595-c65e-4d80-ae33-34fd08c736a5
                        name: Test Email Template
                        type: email
                        created_at: '2024-08-12T10:40:20.000000Z'
                        updated_at: '2024-08-12T10:45:47.890097Z'
                        version: 3
                        created_by: someone@example.com
                        body: "Hi ((firstname)),\r\nWe have received your letter dated ((date)).\r\n No further action is required."
                        subject: Test Email
                        letter_contact_block: null
                        postage: null
                        personalisation:
                          date:
                            required: true
                          firstname:
                            required: true
                      - id: 142d3a1b-f6cb-4bbb-9732-e1d9f9f2fed4
                        name: Test Letter Template
                        type: letter
                        postage: second
                        created_at: '2024-08-20T19:50:43.000000Z'
                        updated_at: '2024-08-20T19:51:51.980848Z'
                        version: 2
                        created_by: someone@example.com
                        body: Hi ((firstname)), We have received your letter dated ((date)).  No further action is required.
                        subject: Test Letter
                        letter_contact_block: |-
                          From Address
                          City
                        personalisation:
                          date:
                            required: true
                          firstname:
                            required: true
          description: If the request is successful, the response body is json and the status code is 200
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TemplatesRequestError'
              example:
                errors:
                  - error: ValidationError
                    message: type pigeon is not one of [sms, email, letter]
                status_code: 400
          description: 'Make sure that the provided type is one of: email, sms, letter'
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthError'
          description: Auth error. Check the `message` in the response to find out why your request failed.
        '429':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LimitError'
          description: Rate or service limit error. Check the `message` in the response to find out why your request failed.
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServerError'
          description: Internal server error. Check the `message` in the response to find out why your request failed.
      security:
        - BearerAuth: []
      summary: Get all templates
      tags:
        - Get a template
  /v2/template/{template_id}:
    get:
      description: This returns the latest version of the template.
      operationId: GetTemplatesById
      parameters:
        - name: template_id
          in: path
          description: The ID of the template. [Sign in to NotifyNL](https://admin.notifynl.nl/sign-in) and go to the Templates page to find it.
          required: true
          schema:
            $ref: '#/components/schemas/TemplateByIdRequest'
          example: b7a59abd-0ab2-4538-b619-8da9f9089e08
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TemplateResponse'
              example:
                id: b7a59abd-0ab2-4538-b619-8da9f9089e08
                name: Test SMS Template
                type: sms
                created_at: '2024-08-12T11:03:12.000000Z'
                updated_at: '2024-08-12T11:03:34.994540Z'
                version: 2
                created_by: someone@example.com
                body: Hi ((firstname)), We have received your letter dated ((date)).  No further action is required.
                subject: null
                postage: null
                letter_contact_block: null
                personalisation:
                  date:
                    required: true
                  firstname:
                    required: true
          description: If the request is successful, the response body is json and the status code is 200
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TemplatesRequestValidationError'
              example:
                errors:
                  - error: ValidationError
                    message: id is not a valid UUID
                status_code: 400
          description: 'Make sure that the provided type is one of: email, sms, letter'
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthError'
          description: Auth error. Check the `message` in the response to find out why your request failed.
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TemplateNoResultError'
              example:
                errors:
                  - error: NoResultFound
                    message: No result found
                status_code: 404
          description: Check your template ID
        '429':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LimitError'
          description: Rate or service limit error. Check the `message` in the response to find out why your request failed.
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServerError'
          description: Internal server error. Check the `message` in the response to find out why your request failed.
      security:
        - BearerAuth: []
      summary: Get template by ID
      tags:
        - Get a template
  /v2/template/{template_id}/version/{version}:
    get:
      description: This returns the latest version of the template.
      operationId: GetTemplatesByIdAndVersion
      parameters:
        - name: template_id
          in: path
          description: The ID of the template. [Sign in to NotifyNL](https://admin.notifynl.nl/sign-in) and go to the Templates page to find it.
          required: true
          schema:
            $ref: '#/components/schemas/TemplateByIdRequest'
          example: b7a59abd-0ab2-4538-b619-8da9f9089e08
        - name: version
          in: path
          description: The version number of the template.
          required: true
          schema:
            $ref: '#/components/schemas/TemplateByIdAndVersionRequest'
          example: 1
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TemplateResponse'
              example:
                id: b7a59abd-0ab2-4538-b619-8da9f9089e08
                name: Test SMS Template
                type: sms
                created_at: '2024-08-12T11:03:12.000000Z'
                updated_at: '2024-08-12T11:03:34.994540Z'
                version: 2
                created_by: someone@example.com
                body: Hi ((firstname)), We have received your letter dated ((date)).  No further action is required.
                subject: null
                postage: null
                letter_contact_block: null
                personalisation:
                  date:
                    required: true
                  firstname:
                    required: true
          description: If the request is successful, the response body is json and the status code is 200
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TemplatesRequestValidationError'
              example:
                errors:
                  - error: ValidationError
                    message: id is not a valid UUID
                status_code: 400
          description: 'Make sure that the provided type is one of: email, sms, letter'
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthError'
          description: Auth error. Check the `message` in the response to find out why your request failed.
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TemplateNoResultError'
              example:
                errors:
                  - error: NoResultFound
                    message: No result found
                status_code: 404
          description: Check your template ID and version
        '429':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LimitError'
          description: Rate or service limit error. Check the `message` in the response to find out why your request failed.
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServerError'
          description: Internal server error. Check the `message` in the response to find out why your request failed.
      security:
        - BearerAuth: []
      summary: Get template by ID and version
      tags:
        - Get a template
  /v2/template/{template_id}/preview:
    post:
      description: This generates a preview version of a template.
      operationId: previewTemplate
      parameters:
        - name: template_id
          in: path
          description: The ID of the template. [Sign in to NotifyNL](https://admin.notifynl.nl/sign-in) and go to the Templates page to find it.
          required: true
          schema:
            $ref: '#/components/schemas/TemplateByIdRequest'
          example: b7a59abd-0ab2-4538-b619-8da9f9089e08
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TemplatePreviewRequest'
        description: requestPayload
        required: false
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TemplatePreviewResponse'
          description: Created
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TemplatePreviewRequestError'
          description: Bad request. Check the `message` in the response to find out why your request failed.
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthError'
          description: Auth error. Check the `message` in the response to find out why your request failed.
        '429':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LimitError'
          description: Rate or service limit error. Check the `message` in the response to find out why your request failed.
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServerError'
          description: Internal server error. Check the `message` in the response to find out why your request failed.
      security:
        - BearerAuth: []
      summary: Generate a preview template
      tags:
        - Get a template
components:
  schemas:
    SendTextMessageRequest:
      type: object
      description: The Send Text Message Request Payload
      properties:
        phone_number:
          type: string
          description: The phone number of the recipient of the text message. This can be a NL or international number.
          example: '+447900900123'
          maxLength: 15
          minLength: 7
        template_id:
          type: string
          description: |-
            To find the template ID:

            1.  [Sign in to NotifyNL](https://admin.notifynl.nl/sign-in).
            2.  Go to the **Templates** page and select the relevant template.
            3.  Select **Copy template ID to clipboard**.
          example: f33517ff-2a88-4f6e-b855-c550268ce08a
        personalisation:
          type: object
          description: 'You can leave out this argument if a template does not have any placeholder fields for personalised information.<br/>If a template has placeholder fields for personalised information such as name or reference number, you must provide their values in a dictionary with key value pairs. For example:'
          properties:
            first_name:
              type: string
              example: Amala
            application_date:
              type: string
              example: '2018-01-01'
        reference:
          type: string
          description: You can leave out this argument if you do not have a reference. An identifier you can create if necessary. This reference identifies a single notification or a batch of notifications. It must not contain any personal information such as name or postal address.
          example: STRING
        sms_sender_id:
          type: string
          description: |-

            A unique identifier of the sender of the text message notification.
            To find the text message sender:

            1.  [Sign in to NotifyNL](https://admin.notifynl.nl/sign-in).
            2.  Go to the **Settings** page.
            3.  In the **Text Messages** section, select **Manage** on the **Text Message sender** row.

            You can then either:

            *   copy the sender ID that you want to use and paste it into the method
            *   select **Change** to change the default sender that the service will use, and select **Save**

            You can leave out this argument if your service only has one text message sender, or if you want to use the default sender.
          example: 8e222534-7f05-4972-86e3-17c5d9f894e2
      required:
        - phone_number
        - template_id
    SendTextMessageResponse:
      type: object
      description: The Send Text Message Response Payload
      properties:
        id:
          type: string
          example: 740e5834-3a29-46b4-9a6f-16142fde533a
        reference:
          type: string
          example: STRING
        scheduled_for:
          type: string
          nullable: true
          example: null
        content:
          type: object
          properties:
            body:
              type: string
              example: MESSAGE TEXT
            from_number:
              type: string
              example: SENDER
        uri:
          type: string
          example: https://api.notifynl.nl/v2/notifications/740e5834-3a29-46b4-9a6f-16142fde533a
        template:
          type: object
          properties:
            id:
              type: string
              example: f33517ff-2a88-4f6e-b855-c550268ce08a
            version:
              type: number
              example: 1
            uri:
              type: string
              example: https://api.notifynl.nl/v2/template/ceb50d92-100d-4b8b-b559-14fa3b091cd
    SendNotificaitonRequestError:
      type: object
      description: Bad request error response
      properties:
        errors:
          type: array
          items:
            type: object
            properties:
              error:
                type: string
                example: ValidationError
                description: Error type
              message:
                type: string
                example: X is a required property
                description: Error message
        status_code:
          type: integer
          example: 400
    AuthError:
      type: object
      description: Auth error response
      properties:
        errors:
          type: array
          items:
            type: object
            properties:
              error:
                type: string
                example: AuthError
                description: Error type
              message:
                type: string
                example: 'Error: Your system clock must be accurate to within 30 seconds'
                description: Error string
        status_code:
          type: integer
          example: 403
    LimitError:
      type: object
      description: Rate or service limit error response
      properties:
        errors:
          type: array
          items:
            type: object
            properties:
              error:
                type: string
                example: TooManyRequestsError
                description: Error type
              message:
                type: string
                example: Exceeded rate limit for key type TEAM/TEST/LIVE of 3000 requests per 60 seconds
                description: Error string
        status_code:
          type: integer
          example: 429
    ServerError:
      type: array
      description: Rate or service limit error response
      items:
        type: object
        properties:
          error:
            type: string
            example: Exception
          message:
            type: string
            example: Internal server error
            description: Notify was unable to process the request, resend your notification.
    SmsCallbackRequest:
      type: object
      properties:
        id:
          type: string
          example: 75a36070-55dc-4dc1-ac33-89da9377d989
        reference:
          type: string
          example: null
        to:
          type: string
          example: '07777777777'
        status:
          type: string
          example: delivered
        created_at:
          type: string
          example: '2023-09-16T16:50:09.090424Z'
        completed_at:
          type: string
          example: '2023-09-16T16:50:10.042907Z'
        sent_at:
          type: string
          example: '2023-09-16T16:50:09.219763Z'
        notification_type:
          type: string
          example: sms
        template_id:
          type: string
          example: 8496188f-3f35-401b-9b8c-f97a528c5b76
        template_version:
          type: number
          example: 1
      required: []
    SendEmailRequest:
      type: object
      description: The Send Email Request Payload
      properties:
        email_address:
          type: string
          description: The email address of the recipient.
          example: sender@something.com
          maxLength: 250
          minLength: 5
        template_id:
          type: string
          description: |-
            To find the template ID:

            1.  [Sign in to NotifyNL](https://admin.notifynl.nl/sign-in).
            2.  Go to the **Templates** page and select the relevant template.
            3.  Select **Copy template ID to clipboard**.
          example: f33517ff-2a88-4f6e-b855-c550268ce08a
        one_click_unsubscribe_url:
          type: string
          description: |-
            You can leave out this argument if the email being sent is not a subscription email.

            If you send subscription emails you must let recipients opt out of receiving them. Read our Using Notify page for more information about [unsubscribe links](https://admin.notifynl.nl/using-notify/unsubscribe-links).

            The one-click unsubscribe URL will be added to the headers of your email. Email clients will use it to add an unsubscribe button.

            The one-click unsubscribe URL must respond to an empty `POST` request by unsubscribing the user from your emails. You can include query parameters to help you identify the user.

            Your unsubscribe URL and response must comply with the guidance specified in [Section 3.1 of IETF RFC 8058](https://www.rfcreader.com/#rfc8058_line139).

            **Unsubscribe link at the bottom of the email (recommended)**

            To add an unsubscribe link at the bottom of your email, use square brackets around the link text and round brackets around the URL. Make sure there are no spaces between the brackets or the link will not work.

            Use this example if you have a webpage for users to manage their email subscriptions:

            ```json
            [Unsubscribe](https://www.example.gov.uk/unsubscribe)
            ```
            Your webpage should ask the recipients to confirm that they want to unsubscribe. 

            If you do not have your own webpage, you can add a ‘mailto’ link to let users send an email to your team instead. For example:

            ```json
            [Unsubscribe](mailto:example@gov.uk?subject=unsubscribe)
            ```
            The email address should be a shared inbox managed by your team, not your own email address.
          example: https://example.com/unsubscribe.html?opaque=123456789
        personalisation:
          type: object
          description: |-
            You can leave out this argument if a template does not have any placeholder fields for personalised information.

            If a template has placeholder fields for personalised information such as name or reference number, you must provide their values in a dictionary with key value pairs. For example:
          properties:
            first_name:
              type: string
              example: Amala
            application_date:
              type: string
              example: '2018-01-01'
            required_documents:
              type: array
              description: Pass in a list and it will appear as bullet points in the message.
              items:
                type: string
              example:
                - passport
                - utility bill
                - other id
            link_to_file:
              type: object
              description: |-
                You can leave out this argument if you do not have any file to attach.

                To send a file by email, add a placeholder to the template then upload a file. The placeholder will contain a secure link to download the file.

                The links are unique and unguessable. NotifyNL cannot access or decrypt your file.

                Your file will be available to download for a default period of 26 weeks (6 months).

                To help protect your files you can also:

                * ask recipients to confirm their email address before downloading
                * choose the length of time that a file is available to download**Add contact details to the file download page**

                1. [Sign in to NotifyNL](https://admin.notifynl.nl/sign-in).
                1. Go to the __Settings__ page.
                1. In the __Email__ section, select __Manage__ on the __Send files by email__ row.
                1. Enter the contact details you want to use, and select __Save__. 

                **Add a placeholder to the template**

                1. [Sign in to NotifyNL](https://admin.notifynl.nl/sign-in).
                1. Go to the __Templates__ page and select the relevant email template.
                1. Select __Edit__.
                1. Add a placeholder to the email template using double brackets. For example: 'Download your file at: ((link_to_file))'

                Your email should also tell recipients how long the file will be available to download.

                **Upload your file**

                You can upload the following file types:

                - PDF (.pdf)
                - CSV (.csv)
                - Text (.odt, .txt, .rtf, .json)
                - MS Word Document (.doc, .docx)
                - Ms Excel Spreadsheet (.xlsx)

                Your file must be smaller than 2MB. [Contact the NotifyNL team](https://admin.notifynl.nl/support/ask-question-give-feedback) if you need to send other file types.

                You’ll need to convert the file into a string that is base64 encoded.

                Pass the encoded string into an object with a `file` key, and put that in the personalisation argument.

                **Set the filename**

                You should provide a filename when you upload your file.

                The filename should tell the recipient what the file contains. A memorable filename can help the recipient to find the file again later.

                The filename must end with a file extension. For example, `.csv` for a CSV file. If you include the wrong file extension, recipients may not be able to open your file.

                The filename should be no more that 100 characters long

                If you do not provide a filename for your file, Notify will:

                * generate a random filename
                * try to add the correct file extension

                If Notify cannot add the correct file extension, recipients may not be able to open your file.

                **Ask recipients to confirm their email address before they can download the file**

                When a recipient clicks the link in the email you’ve sent them, they have to enter their email address. Only someone who knows the recipient’s email address can download the file.

                This security feature is turned on by default.

                **Turn off email address check (not recommended)**

                If you do not want to use this feature, you can turn it off on a file-by-file basis.

                You should not turn this feature off if you send files that contain:

                * personally identifiable information
                * commercially sensitive information
                * information classified as ‘OFFICIAL’ or ‘OFFICIAL-SENSITIVE’ under the [Government Security Classifications](https://www.gov.uk/government/publications/government-security-classifications) policy

                To let the recipient download the file without confirming their email address, set the `confirm_email_before_download` flag to `false`.

                **Choose the length of time that a file is available to download**

                Set the number of weeks you want the file to be available using the `retention_period` key.

                You can choose any value between <code>1 week</code> and <code>26 weeks</code>. When deciding this, you should consider:

                * the need to protect the recipient’s personal information
                * whether the recipient will need to download the file again later

                If you do not choose a value, the file will be available for the default period of 26 weeks (6 months).

                Files sent before 12 April 2023 had a longer default period of 78 weeks (18 months).
              properties:
                file:
                  type: string
                  format: byte
                  description: File as base64 encoded string
                  example: file as base64 encoded string
                filename:
                  type: string
                  description: File name
                  maxLength: 100
                  example: report.csv
                confirm_email_before_download:
                  type: boolean
                  description: To let the recipient download the file without confirming their email address, set the `confirm_email_before_download` flag to `false`.
                  example: false
                retention_period:
                  type: string
                  description: The length of time that a file is available to download in weeks.  Choose between <code>1 week</code> and <code>26 weeks</code>
                  example: 4 weeks
              required:
                - file
        reference:
          type: string
          description: |-
            You can leave out this argument if you do not have a reference.

            An identifier you can create if necessary. This reference identifies a single notification or a batch of notifications. It must not contain any personal information such as name or postal address.
          example: STRING
        email_reply_to_id:
          type: string
          description: |-
            You can leave out this argument if your service only has one reply-to email address, or you want to use the default email address.

            This is an email address specified by you to receive replies from your users. You must add at least one reply-to email address before your service can go live.

            To add a reply-to email address:

            1.  [Sign in to NotifyNL](https://admin.notifynl.nl/sign-in).
            2.  Go to the **Settings** page.
            3.  In the **Email** section, select **Manage** on the **Reply-to email addresses** row.
            4.  Select **Add reply-to address**.
            5.  Enter the email address you want to use, and select **Add**.
          example: STRING
      required:
        - email_address
        - template_id
    SendEmailResponse:
      type: object
      description: The Send Email Response Payload
      properties:
        id:
          type: string
          example: 740e5834-3a29-46b4-9a6f-16142fde533a
        reference:
          type: string
          example: STRING
        scheduled_for:
          type: string
          nullable: true
          example: null
        content:
          type: object
          properties:
            subject:
              type: string
              example: SUBJECT TEXT
            body:
              type: string
              example: MESSAGE TEXT
            from_email:
              type: string
              example: SENDER EMAIL
            one_click_unsubscribe_url:
              type: string
              example: https://example.com/unsubscribe.html?opaque=123456789
              nullable: true
        uri:
          type: string
          example: https://api.notifynl.nl/v2/notifications/740e5834-3a29-46b4-9a6f-16142fde533a
        template:
          type: object
          properties:
            id:
              type: string
              example: f33517ff-2a88-4f6e-b855-c550268ce08a
            version:
              type: number
              example: 1
            uri:
              type: string
              example: https://api.notifynl.nl/v2/template/f33517ff-2a88-4f6e-b855-c550268ce08a
    EmailCallbackRequest:
      type: object
      properties:
        id:
          type: string
          example: 75a36070-55dc-4dc1-ac33-89da9377d989
        reference:
          type: string
          example: null
        to:
          type: string
          example: example@mail.com
        status:
          type: string
          example: delivered
        created_at:
          type: string
          example: '2023-09-16T16:50:09.090424Z'
        completed_at:
          type: string
          example: '2023-09-16T16:50:10.042907Z'
        sent_at:
          type: string
          example: '2023-09-16T16:50:09.219763Z'
        notification_type:
          type: string
          example: email
        template_id:
          type: string
          example: 8496188f-3f35-401b-9b8c-f97a528c5b76
        template_version:
          type: number
          example: 2
      required: []
    SendNormalLetterRequest:
      type: object
      description: The Letter Request Payload
      properties:
        template_id:
          type: string
          description: |-
            To find the template ID:

            1.  [Sign in to NotifyNL](https://admin.notifynl.nl/sign-in).
            2.  Go to the **Templates** page and select the relevant template.
            3.  Select **Copy template ID to clipboard**.
          example: f33517ff-2a88-4f6e-b855-c550268ce08a
        personalisation:
          type: object
          description: |-
            The personalisation argument always contains the following parameters for the letter recipient’s address:

            **The address must have at least 3 lines.**

            The last line needs to be a real NL postcode or the name of a country outside the NL.

            Notify checks for international addresses and will automatically charge you the correct postage.

            The `postcode` personalisation argument has been replaced. If your template still uses `postcode`, Notify will treat it as the last line of the address.

            Any other placeholder fields included in the letter template also count as required parameters. You need to provide their values in a dictionary with key value pairs. For example:
          properties:
            address_line_1:
              type: string
              example: The Occupier
            address_line_2:
              type: string
              example: 123 High Street
            address_line_3:
              type: string
              example: Richmond upon Thames
            address_line_4:
              type: string
              example: Middlesex
            address_line_5:
              type: string
              example: SW14 6BF
            address_line_6:
              type: string
            address_line_7:
              type: string
            name:
              type: string
              example: John Smith
            application_id:
              type: string
              example: '4134325'
            required_documents:
              type: array
              items:
                type: string
              example:
                - passport
                - utility bill
                - other id
          required:
            - address_line_1
            - address_line_2
            - address_line_3
        reference:
          type: string
          description: You can leave out this argument if you do not have a reference. An identifier you can create if necessary. This reference identifies a single notification or a batch of notifications. It must not contain any personal information such as name or postal address.
          example: STRING
      required:
        - template_id
        - personalisation
    SendPrecompiledLetterRequest:
      type: object
      description: The Precompiled Send Letter Request Payload
      properties:
        reference:
          type: string
          description: An identifier you can create if necessary. This reference identifies a single notification or a batch of notifications. It must not contain any personal information such as name or postal address.
          example: STRING
        content:
          type: string
          format: byte
          description: The precompiled letter must be a PDF file which meets [the NotifyNL letter specification](https://admin.notifynl.nl/using-notify/guidance/letter-specification). You’ll need to convert the file into a string that is base64 encoded.
          example: base64EncodedPDFFile
        postage:
          type: string
          description: You can choose first class, second class or economy mail postage for your precompiled letter. Set the value to <code>first</code> for first class, <code>second</code> for second class or <code>economy</code> for economy mail. If you do not pass in this argument, the postage will default to second class. During processing of the letter notify will detect international addresses automatically and may change the postage value to <code>europe</code> or <code>rest-of-world</code> automatically.
          example: base64EncodedPDFFile
      required:
        - reference
        - content
    SendLetterRequest:
      oneOf:
        - $ref: '#/components/schemas/SendNormalLetterRequest'
        - $ref: '#/components/schemas/SendPrecompiledLetterRequest'
    SendNormalLetterResponse:
      type: object
      description: The Send Normal Letter Response Payload
      properties:
        id:
          type: string
          example: 740e5834-3a29-46b4-9a6f-16142fde533a
        reference:
          type: string
          example: STRING
        content:
          type: object
          properties:
            subject:
              type: string
              example: SUBJECT TEXT
            body:
              type: string
              example: LETTER TEXT
        uri:
          type: string
          example: https://api.notifynl.nl/v2/notifications/740e5834-3a29-46b4-9a6f-16142fde533a
        template:
          type: object
          properties:
            id:
              type: string
              example: f33517ff-2a88-4f6e-b855-c550268ce08a
            version:
              type: number
              example: 1
            uri:
              type: string
              example: https://api.notifynl.nl/v2/template/f33517ff-2a88-4f6e-b855-c550268ce08a
        scheduled_for:
          type: string
          nullable: true
          example: null
    SendPrecompiledLetterResponse:
      type: object
      description: The Send Precompiled Letter Response Payload
      properties:
        id:
          type: string
          example: 740e5834-3a29-46b4-9a6f-16142fde533a
        reference:
          type: string
          example: STRING
        postage:
          type: string
          example: postage-you-have-set-or-None
    SendLetterResponse:
      oneOf:
        - $ref: '#/components/schemas/SendNormalLetterResponse'
        - $ref: '#/components/schemas/SendPrecompiledLetterResponse'
    GetOneMessageResponse:
      type: object
      description: The Send Email Response Payload
      properties:
        id:
          type: string
          description: Required - notification ID
          example: 740e5834-3a29-46b4-9a6f-16142fde533a
        reference:
          type: string
          nullable: true
          description: Optional
          example: STRING
        email_address:
          type: string
          nullable: true
          description: Required for emails
          example: sender@something.com
        phone_number:
          type: string
          nullable: true
          description: Required for text messages
          example: '+447900900123'
        line_1:
          type: string
          nullable: true
          description: Required for letter
          example: ADDRESS LINE 1
        line_2:
          type: string
          nullable: true
          description: Required for letter
          example: ADDRESS LINE 2
        line_3:
          type: string
          nullable: true
          description: Required for letter
          example: ADDRESS LINE 3
        line_4:
          type: string
          nullable: true
          description: Required for letter
          example: ADDRESS LINE 4
        line_5:
          type: string
          nullable: true
          description: Required for letter
          example: ADDRESS LINE 5
        line_6:
          type: string
          nullable: true
          description: Required for letter
          example: ADDRESS LINE 6
        postcode:
          type: string
          nullable: true
          description: Required for letter
          example: NW1 2TZ
        postage:
          type: string
          nullable: true
          description: Required for letter
          enum:
            - first
            - second
            - economy
            - europe
            - rest-of-world
          example: first / second / economy / europe / rest-of-world
        type:
          type: string
          description: Required
          enum:
            - sms
            - letter
            - email
          example: sms / letter / email
        status:
          type: string
          description: Required
          example: sending / delivered / permanent-failure / temporary-failure / technical-failure
        template:
          type: object
          properties:
            id:
              type: string
              description: Required - template ID
              example: f33517ff-2a88-4f6e-b855-c550268ce08a
            version:
              type: number
              example: 1
            uri:
              type: string
              description: Required
              example: /v2/template/{id}/{version}
        body:
          type: string
          description: Required - body of notification
          example: STRING
        subject:
          type: string
          nullable: true
          description: Required for email- subject of email
          example: STRING
        created_at:
          type: string
          description: Required - date and time notification created
          example: '2024-05-17T15:58:38.342838Z'
        created_by_name:
          type: string
          nullable: true
          description: Optional - name of the person who sent the notification if sent manually
          example: STRING
        sent_at:
          type: string
          description: Optional - date and time notification sent to provider
          example: '2024-05-17T15:58:30.143000Z'
        completed_at:
          type: string
          description: Optional - date and time notification delivered or failed
          example: '2024-05-17T15:59:10.321000Z'
        scheduled_for:
          type: string
          nullable: true
          description: Optional - date and time notification has been scheduled to be sent at
          example: '2024-05-17T09:00:00.000000Z'
        one_click_unsubscribe_url:
          type: string
          nullable: true
          description: Optional - URL that you provided so your recipients can unsubscribe
          example: STRING
        is_cost_data_ready:
          type: boolean
          description: '`true` if cost data is ready, and `false` if it isn''t'
          example: true
        cost_in_pounds:
          type: number
          format: float
          description: Optional - cost of the notification in pounds. The cost does not take free allowance into account
          example: 0.0027
        cost_details:
          oneOf:
            - type: object
              title: sms
              properties:
                billable_sms_fragments:
                  type: number
                  description: Optional - for text messages, number of billable sms fragments in your text message
                  example: 1
                international_rate_multiplier:
                  type: number
                  description: Optional - for text messages, for international sms rate is multiplied by this value
                  example: 1
                sms_rate:
                  type: number
                  format: float
                  description: Optional - for text messages, cost of 1 sms fragment
                  example: 0.0027
            - type: object
              title: letter
              properties:
                billable_sheets_of_paper:
                  type: number
                  description: Optional - for letters, number of sheets of paper in the letter you sent
                  example: 2
                postage:
                  type: string
                  description: Optional - for letters
                  enum:
                    - first
                    - second
                    - economy
                    - europe
                    - rest-of-world
                  example: first / second / economy / europe / rest-of-world
            - type: object
              title: email
              properties: {}
    GetMessageValidationError:
      type: object
      description: Validation error response
      properties:
        errors:
          type: array
          items:
            type: object
            properties:
              error:
                type: string
                example: NoResultFound
              message:
                type: string
                example: id is not a valid UUID
                description: Check the notification ID
        status_code:
          type: integer
          example: 400
    GetMessageNoResultFoundError:
      type: object
      description: No result found error response
      properties:
        errors:
          type: array
          items:
            type: object
            properties:
              error:
                type: string
                example: NoResultFound
              message:
                type: string
                example: No result found
                description: Check the notification ID
        status_code:
          type: integer
          example: 404
    GetMultipleMessagesResponse:
      type: object
      description: The Send Text Message Response Payload
      properties:
        notifications:
          type: array
          description: Multiple message notifications
          items:
            $ref: '#/components/schemas/GetOneMessageResponse'
        links:
          type: object
          required:
            - current
          description: Pagination links
          properties:
            current:
              type: string
              example: https://api.notifynl.nl/v2/notifications?template_type=sms&status=delivered
            next:
              type: string
              description: Optional property, only included if the query parameter filers return some data
              example: https://api.notifynl.nl/v2/notifications?older_than=last_id_in_list&template_type=sms&status=delivered
    GetReceivedTextMessageResponse:
      type: object
      description: The received text message payload
      properties:
        id:
          type: string
          example: 740e5834-3a29-46b4-9a6f-16142fde533a
        created_at:
          type: string
          example: '2024-05-17T15:58:38.342838Z'
        service_id:
          type: string
          example: STRING
        notify_number:
          type: string
          example: STRING
        user_number:
          type: string
          example: STRING
        content:
          type: string
          example: STRING
    GetReceivedTextMessagesResponse:
      type: object
      description: Recieved text messages
      properties:
        received_text_messages:
          type: array
          description: Multiple received text messages, empty if no text messages received
          items:
            $ref: '#/components/schemas/GetReceivedTextMessageResponse'
        links:
          type: object
          required:
            - current
          description: Pagination links
          properties:
            current:
              type: string
              example: https://api.notifynl.nl/v2/received-text-messages
            next:
              type: string
              example: https://api.notifynl.nl/v2/received-text-messages?older_than=last_id_in_list
    TemplatesRequest:
      type: string
      enum:
        - sms
        - email
        - letter
    TemplateResponse:
      type: object
      properties:
        id:
          type: string
          example: f33517ff-2a88-4f6e-b855-c550268ce08a
          description: required string - template ID
        name:
          type: string
          example: Test template
          description: required string - template name
        type:
          type: string
          enum:
            - sms
            - email
            - letter
          example: sms
          description: required string
        created_at:
          type: string
          example: '2024-08-12T10:40:20.000000Z'
          description: required string - date and time template created
        updated_at:
          type: string
          example: '2024-08-12T10:45:47.890097Z'
          description: required string - date and time template last updated
        version:
          type: integer
          example: 3
        created_by:
          type: string
          example: someone@example.com
          description: required string
        body:
          type: string
          example: Hi ((firstname)), We have received your letter dated ((date)).  No further action is required.
          description: required string - body of notification
        subject:
          type: string
          nullable: true
          example: Test
          description: required string for email - subject of email, otherwise null
        postage:
          type: string
          enum:
            - first
            - second
            - economy
            - europe
            - rest-of-world
            - null
          nullable: true
          example: second
          description: required string for letter - postage type, otherwise null
        personalisation:
          type: object
          example:
            date:
              required: true
            firstname:
              required: true
          description: object containaing personalisation parameters - empty if no personalisation in the template
        letter_contact_block:
          type: string
          nullable: true
          example: ''
          description: optional string - null if not a letter template or contact block not set
    TemplatesResponse:
      type: object
      description: If the request is successful, the response body is json and the status code is 200
      properties:
        templates:
          type: array
          items:
            $ref: '#/components/schemas/TemplateResponse'
    TemplatesRequestError:
      type: object
      description: 'If the request is not successful, the API returns json containing the relevant error code. '
      properties:
        errors:
          type: array
          items:
            type: object
            properties:
              error:
                type: string
                example: ValidationError
                description: Error type
              message:
                type: string
                example: type pigeon is not one of [sms, email, letter]
                description: Error message
        status_code:
          type: integer
          example: 400
    TemplateByIdRequest:
      type: string
      example: b7a59abd-0ab2-4538-b619-8da9f9089e08
    TemplatesRequestValidationError:
      type: object
      description: 'If the request is not successful, the API returns json containing the relevant error code. '
      properties:
        errors:
          type: array
          items:
            type: object
            properties:
              error:
                type: string
                example: ValidationError
                description: Error type
              message:
                type: string
                example: id is not a valid UUID
                description: Error message
        status_code:
          type: integer
          example: 400
    TemplateNoResultError:
      type: object
      description: If the request is not successful, the API returns json containing the relevant error code.
      properties:
        errors:
          type: array
          items:
            type: object
            properties:
              error:
                type: string
                example: NoResultFound
              message:
                type: string
                example: No result found
                description: Check your [template ID](https://docs.notifynl.nl/rest-api.html#get-a-template-by-id-arguments-template-id-required)
        status_code:
          type: integer
          example: 404
    TemplateByIdAndVersionRequest:
      type: integer
      example: 1
    TemplatePreviewRequest:
      type: object
      description: If a template has placeholder fields for personalised information such as name or reference number, you need to provide their values in a dictionary with key value pairs.
      properties:
        personalisation:
          type: object
          description: 'You can leave out this argument if a template does not have any placeholder fields for personalised information.<br/>If a template has placeholder fields for personalised information such as name or reference number, you must provide their values in a dictionary with key value pairs. For example:'
          properties:
            firstname:
              type: string
              example: Amala
            date:
              type: string
              example: 19/08/2024
    TemplatePreviewResponse:
      type: object
      description: If the request is successful, the response body is json and the status code is 200
      properties:
        id:
          type: string
          example: b7a59abd-0ab2-4538-b619-8da9f9089e08
        type:
          type: string
          enum:
            - sms
            - email
            - letter
          example: sms
          description: required string
        version:
          type: integer
          example: 2
        body:
          type: string
          example: Hi Amala, We have received your letter dated 19/08/2024.  No further action is required.
          description: required string - body of notification
        html:
          type: string
          nullable: true
          example: null
          description: html representation of the notification to be sent - null for sms
        subject:
          type: string
          nullable: true
          example: null
          description: required string for email - subject of email, otherwise null
        postage:
          type: string
          nullable: true
          example: null
          description: required string for letter - postage type, otherwise null
    TemplatePreviewRequestError:
      type: object
      description: Bad request error response
      properties:
        errors:
          type: array
          items:
            type: object
            properties:
              error:
                type: string
                example: BadRequestError
                description: Error type
              message:
                type: string
                example: 'Missing personalisation: [PERSONALISATION FIELD]'
                description: Error message
        status_code:
          type: integer
          example: 400
  securitySchemes:
    BearerAuth:
      description: |-
        The authorisation header is an [API key](#api-keys) that is encoded using [JSON Web Tokens](https://jwt.io/). You must include an authorisation header.

        JSON Web Tokens have a standard header and a payload. The header consists of:

        ```json
        {
           "type":"JWT",
           "alg":"HS256"
        }
        ```

        The payload consists of:

        ```json
        {
           "iss": "26785a09-ab16-4eb0-8407-a37497a57506",
           "iat": 1568818578
        }
        ```

        JSON Web Tokens are encoded using a secret key with the following format: ```3d844edf-8d35-48ac-975b-e847b4f122b0```

        That secret key forms a part of your [API key](#api-keys), which follows the format

        `{key_name}-{iss-uuid}-{secret-key-uuid}`.

        For example, if your API key is

        `my_test_key-26785a09-ab16-4eb0-8407-a37497a57506-3d844edf-8d35-48ac-975b-e847b4f122b0`: 

        * your API key name is `my_test_key` 
         * your iss (your service id) is `26785a09-ab16-4eb0-8407-a37497a57506` 
         * your secret key is `3d844edf-8d35-48ac-975b-e847b4f122b0` 

        `iat` (issued at) is the current time in UTC in epoch seconds. The token expires within 30 seconds of the current time. 

        Refer to the [JSON Web Tokens website](https://jwt.io/) for more information on encoding your authorisation header.

        When you have an encoded and signed token, add that token to a header as follows:

        ```json
        "Authorization": "Bearer encoded_jwt_token"
        ```
      scheme: bearer
      type: http
