Organisation emails

Change an organisation's wording for one email

A JSON Merge Patch (RFC 7396): leave a field out to keep it, send null to clear it (the email then uses the inherited wording), send text to change it. Plain text only, with the placeholders the email lists, written {{like.this}}. enabled: false switches off an email that can be switched off (canBeSwitchedOff; 400 email_cannot_be_switched_off otherwise), true switches it back on, null follows the account (or, for the account, sends it). Send every field as null to go back to the standard wording. Every save is kept as a version (see the revisions operation). Applies to this organisation only. Refused wording answers 400 with one validationIssues entry per thing to fix, and nothing is saved. Emails sent after the save carry it. API tokens cannot change or preview an organisation’s emails (403 email_settings_need_a_person).

PATCH

organisations

{organisationId}

email-settings

{eventType}

Change an organisation's wording for one email

curl --request PATCH \
  --url https://api.sandbox.flowpayroll.ai/v1/notification-settings/organisations/{organisationId}/email-settings/{eventType} \
  --header 'Content-Type: application/merge-patch+json' \
  --header 'X-Auth-Token: <api-key>' \
  --header 'X-Org-Id: <api-key>' \
  --data '
{
  "subject": "<string>",
  "heading": "<string>",
  "intro": "<string>",
  "closing": "<string>",
  "buttonLabel": "<string>",
  "enabled": true
}
'

import requests

url = "https://api.sandbox.flowpayroll.ai/v1/notification-settings/organisations/{organisationId}/email-settings/{eventType}"

payload = {
    "subject": "<string>",
    "heading": "<string>",
    "intro": "<string>",
    "closing": "<string>",
    "buttonLabel": "<string>",
    "enabled": True
}
headers = {
    "X-Auth-Token": "<api-key>",
    "X-Org-Id": "<api-key>",
    "Content-Type": "application/merge-patch+json"
}

response = requests.patch(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'PATCH',
  headers: {
    'X-Auth-Token': '<api-key>',
    'X-Org-Id': '<api-key>',
    'Content-Type': 'application/merge-patch+json'
  },
  body: JSON.stringify({
    subject: '<string>',
    heading: '<string>',
    intro: '<string>',
    closing: '<string>',
    buttonLabel: '<string>',
    enabled: true
  })
};

fetch('https://api.sandbox.flowpayroll.ai/v1/notification-settings/organisations/{organisationId}/email-settings/{eventType}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.sandbox.flowpayroll.ai/v1/notification-settings/organisations/{organisationId}/email-settings/{eventType}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "PATCH",
  CURLOPT_POSTFIELDS => json_encode([
    'subject' => '<string>',
    'heading' => '<string>',
    'intro' => '<string>',
    'closing' => '<string>',
    'buttonLabel' => '<string>',
    'enabled' => true
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/merge-patch+json",
    "X-Auth-Token: <api-key>",
    "X-Org-Id: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.sandbox.flowpayroll.ai/v1/notification-settings/organisations/{organisationId}/email-settings/{eventType}"

	payload := strings.NewReader("{\n  \"subject\": \"<string>\",\n  \"heading\": \"<string>\",\n  \"intro\": \"<string>\",\n  \"closing\": \"<string>\",\n  \"buttonLabel\": \"<string>\",\n  \"enabled\": true\n}")

	req, _ := http.NewRequest("PATCH", url, payload)

	req.Header.Add("X-Auth-Token", "<api-key>")
	req.Header.Add("X-Org-Id", "<api-key>")
	req.Header.Add("Content-Type", "application/merge-patch+json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.patch("https://api.sandbox.flowpayroll.ai/v1/notification-settings/organisations/{organisationId}/email-settings/{eventType}")
  .header("X-Auth-Token", "<api-key>")
  .header("X-Org-Id", "<api-key>")
  .header("Content-Type", "application/merge-patch+json")
  .body("{\n  \"subject\": \"<string>\",\n  \"heading\": \"<string>\",\n  \"intro\": \"<string>\",\n  \"closing\": \"<string>\",\n  \"buttonLabel\": \"<string>\",\n  \"enabled\": true\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.sandbox.flowpayroll.ai/v1/notification-settings/organisations/{organisationId}/email-settings/{eventType}")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Patch.new(url)
request["X-Auth-Token"] = '<api-key>'
request["X-Org-Id"] = '<api-key>'
request["Content-Type"] = 'application/merge-patch+json'
request.body = "{\n  \"subject\": \"<string>\",\n  \"heading\": \"<string>\",\n  \"intro\": \"<string>\",\n  \"closing\": \"<string>\",\n  \"buttonLabel\": \"<string>\",\n  \"enabled\": true\n}"

response = http.request(request)
puts response.read_body

{
  "message": {
    "text": "<string>",
    "token": "<string>",
    "tokenArguments": [
      {
        "name": "<string>",
        "value": "<unknown>"
      }
    ]
  },
  "validationIssues": [
    {
      "field": "<string>",
      "reason": "<string>",
      "reasonToken": "<string>",
      "reasonTokenArguments": [
        {
          "name": "<string>",
          "value": "<unknown>"
        }
      ]
    }
  ],
  "content": {
    "data": {
      "eventType": "<string>",
      "level": "Organisation",
      "audience": "Employees",
      "enabled": true,
      "canBeSwitchedOff": true,
      "wording": {
        "subject": "<string>",
        "heading": "<string>",
        "intro": "<string>",
        "closing": "<string>",
        "buttonLabel": "<string>"
      },
      "inherited": {
        "subject": "<string>",
        "heading": "<string>",
        "intro": "<string>",
        "closing": "<string>",
        "buttonLabel": "<string>"
      },
      "standard": {
        "subject": "<string>",
        "heading": "<string>",
        "intro": "<string>",
        "closing": "<string>",
        "buttonLabel": "<string>"
      },
      "placeholders": [
        {
          "key": "<string>",
          "sample": "<string>"
        }
      ],
      "hasButton": true,
      "locked": [
        "<string>"
      ],
      "updatedDate": "2023-11-07T05:31:56Z",
      "updatedBy": "<string>",
      "standardFromAddress": "<string>"
    },
    "metadata": {
      "dateFormat": "<string>",
      "dateTimeFormat": "<string>",
      "paginationToken": "<string>"
    }
  }
}

{
  "message": {
    "text": "<string>",
    "token": "<string>",
    "tokenArguments": [
      {
        "name": "<string>",
        "value": "<unknown>"
      }
    ]
  },
  "validationIssues": [
    {
      "field": "<string>",
      "reason": "<string>",
      "reasonToken": "<string>",
      "reasonTokenArguments": [
        {
          "name": "<string>",
          "value": "<unknown>"
        }
      ]
    }
  ]
}

{
  "message": {
    "text": "<string>",
    "token": "<string>",
    "tokenArguments": [
      {
        "name": "<string>",
        "value": "<unknown>"
      }
    ]
  },
  "validationIssues": [
    {
      "field": "<string>",
      "reason": "<string>",
      "reasonToken": "<string>",
      "reasonTokenArguments": [
        {
          "name": "<string>",
          "value": "<unknown>"
        }
      ]
    }
  ]
}

{
  "message": {
    "text": "<string>",
    "token": "<string>",
    "tokenArguments": [
      {
        "name": "<string>",
        "value": "<unknown>"
      }
    ]
  },
  "validationIssues": [
    {
      "field": "<string>",
      "reason": "<string>",
      "reasonToken": "<string>",
      "reasonTokenArguments": [
        {
          "name": "<string>",
          "value": "<unknown>"
        }
      ]
    }
  ]
}

{
  "message": {
    "text": "<string>",
    "token": "<string>",
    "tokenArguments": [
      {
        "name": "<string>",
        "value": "<unknown>"
      }
    ]
  },
  "validationIssues": [
    {
      "field": "<string>",
      "reason": "<string>",
      "reasonToken": "<string>",
      "reasonTokenArguments": [
        {
          "name": "<string>",
          "value": "<unknown>"
        }
      ]
    }
  ]
}

{
  "message": {
    "text": "<string>",
    "token": "<string>",
    "tokenArguments": [
      {
        "name": "<string>",
        "value": "<unknown>"
      }
    ]
  },
  "validationIssues": [
    {
      "field": "<string>",
      "reason": "<string>",
      "reasonToken": "<string>",
      "reasonTokenArguments": [
        {
          "name": "<string>",
          "value": "<unknown>"
        }
      ]
    }
  ]
}

{
  "message": {
    "text": "<string>",
    "token": "<string>",
    "tokenArguments": [
      {
        "name": "<string>",
        "value": "<unknown>"
      }
    ]
  },
  "validationIssues": [
    {
      "field": "<string>",
      "reason": "<string>",
      "reasonToken": "<string>",
      "reasonTokenArguments": [
        {
          "name": "<string>",
          "value": "<unknown>"
        }
      ]
    }
  ]
}

Authorizations

X-Auth-Token

string

header

required

Your access token (raw token, no Bearer prefix)

X-Org-Id

string

header

required

The organisation to act on. Required only when your credentials can reach more than one organisation; optional for a single organisation.

Path Parameters

organisationId

string

required

The organisation to act on. It must be the one selected with X-Org-Id: a request naming two different organisations is refused with 403.

eventType

enum<string>

required

The email, by the event name its webhook delivery events carry, as listed by the list operation: PayslipGeneratedEvent, P45GeneratedEvent, P60GeneratedEvent, EmployeePensionEnrolmentEvent, ReportReadyEvent, WebhookEndpointFailingEvent, WebhookEndpointDisabledEvent.

Available options:

PayslipGeneratedEvent,

P45GeneratedEvent,

P60GeneratedEvent,

EmployeePensionEnrolmentEvent,

ReportReadyEvent,

WebhookEndpointFailingEvent,

WebhookEndpointDisabledEvent

Body

Absent: keep. null: clear and inherit. Text: set.

subject

string | null

heading

string | null

intro

string | null

closing

string | null

buttonLabel

string | null

enabled

boolean | null

false: switch the email off. true: on. null: follow the account.

Response

message

object

required

Show child attributes

validationIssues

object[] | null

Show child attributes

content

object

Show child attributes

Change an organisation's wording for one email

curl --request PATCH \
  --url https://api.sandbox.flowpayroll.ai/v1/notification-settings/organisations/{organisationId}/email-settings/{eventType} \
  --header 'Content-Type: application/merge-patch+json' \
  --header 'X-Auth-Token: <api-key>' \
  --header 'X-Org-Id: <api-key>' \
  --data '
{
  "subject": "<string>",
  "heading": "<string>",
  "intro": "<string>",
  "closing": "<string>",
  "buttonLabel": "<string>",
  "enabled": true
}
'

import requests

url = "https://api.sandbox.flowpayroll.ai/v1/notification-settings/organisations/{organisationId}/email-settings/{eventType}"

payload = {
    "subject": "<string>",
    "heading": "<string>",
    "intro": "<string>",
    "closing": "<string>",
    "buttonLabel": "<string>",
    "enabled": True
}
headers = {
    "X-Auth-Token": "<api-key>",
    "X-Org-Id": "<api-key>",
    "Content-Type": "application/merge-patch+json"
}

response = requests.patch(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'PATCH',
  headers: {
    'X-Auth-Token': '<api-key>',
    'X-Org-Id': '<api-key>',
    'Content-Type': 'application/merge-patch+json'
  },
  body: JSON.stringify({
    subject: '<string>',
    heading: '<string>',
    intro: '<string>',
    closing: '<string>',
    buttonLabel: '<string>',
    enabled: true
  })
};

fetch('https://api.sandbox.flowpayroll.ai/v1/notification-settings/organisations/{organisationId}/email-settings/{eventType}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.sandbox.flowpayroll.ai/v1/notification-settings/organisations/{organisationId}/email-settings/{eventType}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "PATCH",
  CURLOPT_POSTFIELDS => json_encode([
    'subject' => '<string>',
    'heading' => '<string>',
    'intro' => '<string>',
    'closing' => '<string>',
    'buttonLabel' => '<string>',
    'enabled' => true
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/merge-patch+json",
    "X-Auth-Token: <api-key>",
    "X-Org-Id: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.sandbox.flowpayroll.ai/v1/notification-settings/organisations/{organisationId}/email-settings/{eventType}"

	payload := strings.NewReader("{\n  \"subject\": \"<string>\",\n  \"heading\": \"<string>\",\n  \"intro\": \"<string>\",\n  \"closing\": \"<string>\",\n  \"buttonLabel\": \"<string>\",\n  \"enabled\": true\n}")

	req, _ := http.NewRequest("PATCH", url, payload)

	req.Header.Add("X-Auth-Token", "<api-key>")
	req.Header.Add("X-Org-Id", "<api-key>")
	req.Header.Add("Content-Type", "application/merge-patch+json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.patch("https://api.sandbox.flowpayroll.ai/v1/notification-settings/organisations/{organisationId}/email-settings/{eventType}")
  .header("X-Auth-Token", "<api-key>")
  .header("X-Org-Id", "<api-key>")
  .header("Content-Type", "application/merge-patch+json")
  .body("{\n  \"subject\": \"<string>\",\n  \"heading\": \"<string>\",\n  \"intro\": \"<string>\",\n  \"closing\": \"<string>\",\n  \"buttonLabel\": \"<string>\",\n  \"enabled\": true\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.sandbox.flowpayroll.ai/v1/notification-settings/organisations/{organisationId}/email-settings/{eventType}")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Patch.new(url)
request["X-Auth-Token"] = '<api-key>'
request["X-Org-Id"] = '<api-key>'
request["Content-Type"] = 'application/merge-patch+json'
request.body = "{\n  \"subject\": \"<string>\",\n  \"heading\": \"<string>\",\n  \"intro\": \"<string>\",\n  \"closing\": \"<string>\",\n  \"buttonLabel\": \"<string>\",\n  \"enabled\": true\n}"

response = http.request(request)
puts response.read_body

{
  "message": {
    "text": "<string>",
    "token": "<string>",
    "tokenArguments": [
      {
        "name": "<string>",
        "value": "<unknown>"
      }
    ]
  },
  "validationIssues": [
    {
      "field": "<string>",
      "reason": "<string>",
      "reasonToken": "<string>",
      "reasonTokenArguments": [
        {
          "name": "<string>",
          "value": "<unknown>"
        }
      ]
    }
  ],
  "content": {
    "data": {
      "eventType": "<string>",
      "level": "Organisation",
      "audience": "Employees",
      "enabled": true,
      "canBeSwitchedOff": true,
      "wording": {
        "subject": "<string>",
        "heading": "<string>",
        "intro": "<string>",
        "closing": "<string>",
        "buttonLabel": "<string>"
      },
      "inherited": {
        "subject": "<string>",
        "heading": "<string>",
        "intro": "<string>",
        "closing": "<string>",
        "buttonLabel": "<string>"
      },
      "standard": {
        "subject": "<string>",
        "heading": "<string>",
        "intro": "<string>",
        "closing": "<string>",
        "buttonLabel": "<string>"
      },
      "placeholders": [
        {
          "key": "<string>",
          "sample": "<string>"
        }
      ],
      "hasButton": true,
      "locked": [
        "<string>"
      ],
      "updatedDate": "2023-11-07T05:31:56Z",
      "updatedBy": "<string>",
      "standardFromAddress": "<string>"
    },
    "metadata": {
      "dateFormat": "<string>",
      "dateTimeFormat": "<string>",
      "paginationToken": "<string>"
    }
  }
}

{
  "message": {
    "text": "<string>",
    "token": "<string>",
    "tokenArguments": [
      {
        "name": "<string>",
        "value": "<unknown>"
      }
    ]
  },
  "validationIssues": [
    {
      "field": "<string>",
      "reason": "<string>",
      "reasonToken": "<string>",
      "reasonTokenArguments": [
        {
          "name": "<string>",
          "value": "<unknown>"
        }
      ]
    }
  ]
}

{
  "message": {
    "text": "<string>",
    "token": "<string>",
    "tokenArguments": [
      {
        "name": "<string>",
        "value": "<unknown>"
      }
    ]
  },
  "validationIssues": [
    {
      "field": "<string>",
      "reason": "<string>",
      "reasonToken": "<string>",
      "reasonTokenArguments": [
        {
          "name": "<string>",
          "value": "<unknown>"
        }
      ]
    }
  ]
}

{
  "message": {
    "text": "<string>",
    "token": "<string>",
    "tokenArguments": [
      {
        "name": "<string>",
        "value": "<unknown>"
      }
    ]
  },
  "validationIssues": [
    {
      "field": "<string>",
      "reason": "<string>",
      "reasonToken": "<string>",
      "reasonTokenArguments": [
        {
          "name": "<string>",
          "value": "<unknown>"
        }
      ]
    }
  ]
}

{
  "message": {
    "text": "<string>",
    "token": "<string>",
    "tokenArguments": [
      {
        "name": "<string>",
        "value": "<unknown>"
      }
    ]
  },
  "validationIssues": [
    {
      "field": "<string>",
      "reason": "<string>",
      "reasonToken": "<string>",
      "reasonTokenArguments": [
        {
          "name": "<string>",
          "value": "<unknown>"
        }
      ]
    }
  ]
}

{
  "message": {
    "text": "<string>",
    "token": "<string>",
    "tokenArguments": [
      {
        "name": "<string>",
        "value": "<unknown>"
      }
    ]
  },
  "validationIssues": [
    {
      "field": "<string>",
      "reason": "<string>",
      "reasonToken": "<string>",
      "reasonTokenArguments": [
        {
          "name": "<string>",
          "value": "<unknown>"
        }
      ]
    }
  ]
}

{
  "message": {
    "text": "<string>",
    "token": "<string>",
    "tokenArguments": [
      {
        "name": "<string>",
        "value": "<unknown>"
      }
    ]
  },
  "validationIssues": [
    {
      "field": "<string>",
      "reason": "<string>",
      "reasonToken": "<string>",
      "reasonTokenArguments": [
        {
          "name": "<string>",
          "value": "<unknown>"
        }
      ]
    }
  ]
}

Overview

Administration API

Email Wording API

Authentication API

Billing

Court orders

HMRC DPS

HMRC P-forms

Holiday & leave

Integrations

Pay API

Payment

Payroll journals

Pensions

Recurring line items

Reports

Salary

Statutory pay

Webhooks

Change an organisation's wording for one email

Authorizations

Path Parameters

Body

Response