Employees

Send a CSV of changes to existing employees

Needs permission employee:write, or any of employee-payroll:write, working-pattern:write.

One row per employee, found by the id column (the Employee ID the employee export leads with); the other columns are employee fields, by their path or by columns. Only cells that differ from the employee now are changed, and an empty cell leaves the field as it is. Nothing changes yet: the file is compared in the background, and GET /employees/imports/{importId} shows the preview once its status is Ready. At most 10,000 rows and 5 MB.

POST

employees

imports

Send a CSV of changes to existing employees

curl --request POST \
  --url https://api.sandbox.flowpayroll.ai/v1/employees/imports \
  --header 'Content-Type: application/json' \
  --header 'X-Auth-Token: <api-key>' \
  --header 'X-Org-Id: <api-key>' \
  --data '
{
  "csv": "<string>",
  "columns": [
    {
      "header": "Team",
      "field": "department"
    }
  ]
}
'

import requests

url = "https://api.sandbox.flowpayroll.ai/v1/employees/imports"

payload = {
    "csv": "<string>",
    "columns": [
        {
            "header": "Team",
            "field": "department"
        }
    ]
}
headers = {
    "X-Auth-Token": "<api-key>",
    "X-Org-Id": "<api-key>",
    "Content-Type": "application/json"
}

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

print(response.text)

const options = {
  method: 'POST',
  headers: {
    'X-Auth-Token': '<api-key>',
    'X-Org-Id': '<api-key>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({csv: '<string>', columns: [{header: 'Team', field: 'department'}]})
};

fetch('https://api.sandbox.flowpayroll.ai/v1/employees/imports', 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/employees/imports",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'csv' => '<string>',
    'columns' => [
        [
                'header' => 'Team',
                'field' => 'department'
        ]
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/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/employees/imports"

	payload := strings.NewReader("{\n  \"csv\": \"<string>\",\n  \"columns\": [\n    {\n      \"header\": \"Team\",\n      \"field\": \"department\"\n    }\n  ]\n}")

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

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

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

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

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.sandbox.flowpayroll.ai/v1/employees/imports")
  .header("X-Auth-Token", "<api-key>")
  .header("X-Org-Id", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"csv\": \"<string>\",\n  \"columns\": [\n    {\n      \"header\": \"Team\",\n      \"field\": \"department\"\n    }\n  ]\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.sandbox.flowpayroll.ai/v1/employees/imports")

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

request = Net::HTTP::Post.new(url)
request["X-Auth-Token"] = '<api-key>'
request["X-Org-Id"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"csv\": \"<string>\",\n  \"columns\": [\n    {\n      \"header\": \"Team\",\n      \"field\": \"department\"\n    }\n  ]\n}"

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

{
  "message": {
    "text": "<string>",
    "token": "<string>",
    "tokenArguments": [
      {
        "name": "<string>",
        "value": "<unknown>"
      }
    ]
  },
  "content": {
    "metadata": {
      "dateFormat": "<string>",
      "dateTimeFormat": "<string>",
      "paginationToken": "<string>"
    },
    "data": {
      "importId": "01JD8Y7Q3N4M5P6R7S8T9V0W1X",
      "status": "Ready",
      "progress": {
        "done": 3120,
        "total": 7000
      },
      "counts": {
        "total": 120,
        "changed": 37,
        "unchanged": 80,
        "problems": 3,
        "updated": 36,
        "failed": 1
      },
      "skippedColumns": [
        {
          "header": "Payroll ID",
          "reason": "Cannot be changed from a file; it has its own screen"
        }
      ],
      "rows": [
        {
          "row": 2,
          "employeeId": "01JD8Y7Q3N4M5P6R7S8T9V0W1X",
          "changes": [
            {
              "field": "department",
              "from": "Sales",
              "to": "Operations"
            }
          ],
          "problems": [
            {
              "message": "Enter a number, such as 1234.56, not \"lots\"",
              "column": "Hours per week"
            }
          ],
          "outcome": "Updated"
        }
      ],
      "rowsTruncated": false,
      "createdAt": "2026-11-08T10:00:00Z",
      "error": "Add the Employee ID column: it is how each row finds its employee.",
      "completedAt": "2026-11-08T10:00:40Z"
    }
  },
  "validationIssues": [
    {
      "field": "<string>",
      "reason": "<string>",
      "reasonToken": "<string>",
      "reasonTokenArguments": [
        {
          "name": "<string>",
          "value": "<unknown>"
        }
      ]
    }
  ]
}

{
  "message": {
    "text": "<string>",
    "token": "<string>",
    "tokenArguments": [
      {
        "name": "<string>",
        "value": "<unknown>"
      }
    ]
  },
  "content": {
    "metadata": {
      "dateFormat": "<string>",
      "dateTimeFormat": "<string>",
      "paginationToken": "<string>"
    },
    "data": "<unknown>"
  },
  "validationIssues": [
    {
      "field": "<string>",
      "reason": "<string>",
      "reasonToken": "<string>",
      "reasonTokenArguments": [
        {
          "name": "<string>",
          "value": "<unknown>"
        }
      ]
    }
  ]
}

{
  "message": {
    "text": "<string>",
    "token": "<string>",
    "tokenArguments": [
      {
        "name": "<string>",
        "value": "<unknown>"
      }
    ]
  },
  "content": {
    "metadata": {
      "dateFormat": "<string>",
      "dateTimeFormat": "<string>",
      "paginationToken": "<string>"
    },
    "data": "<unknown>"
  },
  "validationIssues": [
    {
      "field": "<string>",
      "reason": "<string>",
      "reasonToken": "<string>",
      "reasonTokenArguments": [
        {
          "name": "<string>",
          "value": "<unknown>"
        }
      ]
    }
  ]
}

{
  "message": {
    "text": "<string>",
    "token": "<string>",
    "tokenArguments": [
      {
        "name": "<string>",
        "value": "<unknown>"
      }
    ]
  },
  "content": {
    "metadata": {
      "dateFormat": "<string>",
      "dateTimeFormat": "<string>",
      "paginationToken": "<string>"
    },
    "data": "<unknown>"
  },
  "validationIssues": [
    {
      "field": "<string>",
      "reason": "<string>",
      "reasonToken": "<string>",
      "reasonTokenArguments": [
        {
          "name": "<string>",
          "value": "<unknown>"
        }
      ]
    }
  ]
}

{
  "message": {
    "text": "<string>",
    "token": "<string>",
    "tokenArguments": [
      {
        "name": "<string>",
        "value": "<unknown>"
      }
    ]
  },
  "content": {
    "metadata": {
      "dateFormat": "<string>",
      "dateTimeFormat": "<string>",
      "paginationToken": "<string>"
    },
    "data": "<unknown>"
  },
  "validationIssues": [
    {
      "field": "<string>",
      "reason": "<string>",
      "reasonToken": "<string>",
      "reasonTokenArguments": [
        {
          "name": "<string>",
          "value": "<unknown>"
        }
      ]
    }
  ]
}

{
  "message": {
    "text": "<string>",
    "token": "<string>",
    "tokenArguments": [
      {
        "name": "<string>",
        "value": "<unknown>"
      }
    ]
  },
  "content": {
    "metadata": {
      "dateFormat": "<string>",
      "dateTimeFormat": "<string>",
      "paginationToken": "<string>"
    },
    "data": "<unknown>"
  },
  "validationIssues": [
    {
      "field": "<string>",
      "reason": "<string>",
      "reasonToken": "<string>",
      "reasonTokenArguments": [
        {
          "name": "<string>",
          "value": "<unknown>"
        }
      ]
    }
  ]
}

Authorizations

X-Auth-Token

string

header

required

Access token obtained from OAuth2 client credentials flow

X-Org-Id

string

header

required

Organisation to scope the request to. Required when the principal can access more than one organisation; optional for single-organisation principals (the authorizer resolves it automatically).

Headers

Request-Id

string

Optional. Your id for this request: it is carried into every log line about it, so quote it when you contact support.

Body

application/json

The file, and which field each heading holds

A CSV of changes to existing employees, one row per employee.

csv

string

required

The file's text. Its first row is the headings, and one column must be id (the Employee ID the export leads with). Only the cells that differ from the employee now are changed; an empty cell leaves the field as it is.

columns

object[] | null

Which field each heading holds, for headings that are not a field's path. Headings that are a field's path need no entry.

Show child attributes

Response

File received; the preview is being prepared. Location is the import, Retry-After how soon to look; the organisation's open apps also hear employeeImportChanged over the websocket.

message

object

required

A readable message about the outcome and a stable token a client can branch on.

Show child attributes

content

object

The data the request returns with its metadata; left out on a response that carries no data, such as most errors.

Show child attributes

validationIssues

object[] | null

Each field the request was refused for and why; left out when the request was not refused for its fields.

Show child attributes

Send a CSV of changes to existing employees

curl --request POST \
  --url https://api.sandbox.flowpayroll.ai/v1/employees/imports \
  --header 'Content-Type: application/json' \
  --header 'X-Auth-Token: <api-key>' \
  --header 'X-Org-Id: <api-key>' \
  --data '
{
  "csv": "<string>",
  "columns": [
    {
      "header": "Team",
      "field": "department"
    }
  ]
}
'

import requests

url = "https://api.sandbox.flowpayroll.ai/v1/employees/imports"

payload = {
    "csv": "<string>",
    "columns": [
        {
            "header": "Team",
            "field": "department"
        }
    ]
}
headers = {
    "X-Auth-Token": "<api-key>",
    "X-Org-Id": "<api-key>",
    "Content-Type": "application/json"
}

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

print(response.text)

const options = {
  method: 'POST',
  headers: {
    'X-Auth-Token': '<api-key>',
    'X-Org-Id': '<api-key>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({csv: '<string>', columns: [{header: 'Team', field: 'department'}]})
};

fetch('https://api.sandbox.flowpayroll.ai/v1/employees/imports', 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/employees/imports",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'csv' => '<string>',
    'columns' => [
        [
                'header' => 'Team',
                'field' => 'department'
        ]
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/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/employees/imports"

	payload := strings.NewReader("{\n  \"csv\": \"<string>\",\n  \"columns\": [\n    {\n      \"header\": \"Team\",\n      \"field\": \"department\"\n    }\n  ]\n}")

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

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

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

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

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.sandbox.flowpayroll.ai/v1/employees/imports")
  .header("X-Auth-Token", "<api-key>")
  .header("X-Org-Id", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"csv\": \"<string>\",\n  \"columns\": [\n    {\n      \"header\": \"Team\",\n      \"field\": \"department\"\n    }\n  ]\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.sandbox.flowpayroll.ai/v1/employees/imports")

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

request = Net::HTTP::Post.new(url)
request["X-Auth-Token"] = '<api-key>'
request["X-Org-Id"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"csv\": \"<string>\",\n  \"columns\": [\n    {\n      \"header\": \"Team\",\n      \"field\": \"department\"\n    }\n  ]\n}"

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

{
  "message": {
    "text": "<string>",
    "token": "<string>",
    "tokenArguments": [
      {
        "name": "<string>",
        "value": "<unknown>"
      }
    ]
  },
  "content": {
    "metadata": {
      "dateFormat": "<string>",
      "dateTimeFormat": "<string>",
      "paginationToken": "<string>"
    },
    "data": {
      "importId": "01JD8Y7Q3N4M5P6R7S8T9V0W1X",
      "status": "Ready",
      "progress": {
        "done": 3120,
        "total": 7000
      },
      "counts": {
        "total": 120,
        "changed": 37,
        "unchanged": 80,
        "problems": 3,
        "updated": 36,
        "failed": 1
      },
      "skippedColumns": [
        {
          "header": "Payroll ID",
          "reason": "Cannot be changed from a file; it has its own screen"
        }
      ],
      "rows": [
        {
          "row": 2,
          "employeeId": "01JD8Y7Q3N4M5P6R7S8T9V0W1X",
          "changes": [
            {
              "field": "department",
              "from": "Sales",
              "to": "Operations"
            }
          ],
          "problems": [
            {
              "message": "Enter a number, such as 1234.56, not \"lots\"",
              "column": "Hours per week"
            }
          ],
          "outcome": "Updated"
        }
      ],
      "rowsTruncated": false,
      "createdAt": "2026-11-08T10:00:00Z",
      "error": "Add the Employee ID column: it is how each row finds its employee.",
      "completedAt": "2026-11-08T10:00:40Z"
    }
  },
  "validationIssues": [
    {
      "field": "<string>",
      "reason": "<string>",
      "reasonToken": "<string>",
      "reasonTokenArguments": [
        {
          "name": "<string>",
          "value": "<unknown>"
        }
      ]
    }
  ]
}

{
  "message": {
    "text": "<string>",
    "token": "<string>",
    "tokenArguments": [
      {
        "name": "<string>",
        "value": "<unknown>"
      }
    ]
  },
  "content": {
    "metadata": {
      "dateFormat": "<string>",
      "dateTimeFormat": "<string>",
      "paginationToken": "<string>"
    },
    "data": "<unknown>"
  },
  "validationIssues": [
    {
      "field": "<string>",
      "reason": "<string>",
      "reasonToken": "<string>",
      "reasonTokenArguments": [
        {
          "name": "<string>",
          "value": "<unknown>"
        }
      ]
    }
  ]
}

{
  "message": {
    "text": "<string>",
    "token": "<string>",
    "tokenArguments": [
      {
        "name": "<string>",
        "value": "<unknown>"
      }
    ]
  },
  "content": {
    "metadata": {
      "dateFormat": "<string>",
      "dateTimeFormat": "<string>",
      "paginationToken": "<string>"
    },
    "data": "<unknown>"
  },
  "validationIssues": [
    {
      "field": "<string>",
      "reason": "<string>",
      "reasonToken": "<string>",
      "reasonTokenArguments": [
        {
          "name": "<string>",
          "value": "<unknown>"
        }
      ]
    }
  ]
}

{
  "message": {
    "text": "<string>",
    "token": "<string>",
    "tokenArguments": [
      {
        "name": "<string>",
        "value": "<unknown>"
      }
    ]
  },
  "content": {
    "metadata": {
      "dateFormat": "<string>",
      "dateTimeFormat": "<string>",
      "paginationToken": "<string>"
    },
    "data": "<unknown>"
  },
  "validationIssues": [
    {
      "field": "<string>",
      "reason": "<string>",
      "reasonToken": "<string>",
      "reasonTokenArguments": [
        {
          "name": "<string>",
          "value": "<unknown>"
        }
      ]
    }
  ]
}

{
  "message": {
    "text": "<string>",
    "token": "<string>",
    "tokenArguments": [
      {
        "name": "<string>",
        "value": "<unknown>"
      }
    ]
  },
  "content": {
    "metadata": {
      "dateFormat": "<string>",
      "dateTimeFormat": "<string>",
      "paginationToken": "<string>"
    },
    "data": "<unknown>"
  },
  "validationIssues": [
    {
      "field": "<string>",
      "reason": "<string>",
      "reasonToken": "<string>",
      "reasonTokenArguments": [
        {
          "name": "<string>",
          "value": "<unknown>"
        }
      ]
    }
  ]
}

{
  "message": {
    "text": "<string>",
    "token": "<string>",
    "tokenArguments": [
      {
        "name": "<string>",
        "value": "<unknown>"
      }
    ]
  },
  "content": {
    "metadata": {
      "dateFormat": "<string>",
      "dateTimeFormat": "<string>",
      "paginationToken": "<string>"
    },
    "data": "<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

Send a CSV of changes to existing employees

Authorizations

Headers

Body

Response