Response format - Flow Payroll

Overview

Authentication API

Pay API

Statutory pay

Court orders

Holiday & leave

Pensions

Recurring line items

HMRC DPS

HMRC P-forms

Billing

Payment

Payroll journals

Reports

Beta

All API responses follow a consistent structure, giving you predictable parsing across every endpoint.

Success

{
  "message": {
    "text": "Operation completed successfully",
    "token": "operationCompletedSuccessfully"
  },
  "content": {
    "data": { },
    "metadata": {
      "dateFormat": "yyyy-MM-dd",
      "dateTimeFormat": "yyyy-MM-dd'T'HH:mm:ss.fffZ"
    }
  }
}

message.text — a human-readable summary.
message.token — a stable machine-readable key. Branch on this rather than on message.text, which may change wording or be localised.
content.data — the resource(s) returned by the endpoint.
content.metadata — context such as the date and date-time formats used in data.

Errors

Errors use the same envelope. The token identifies the error, and tokenArguments carries any parameters needed to render a message.

{
  "message": {
    "text": "Operation failed",
    "token": "operationFailed",
    "tokenArguments": [
      {
        "name": "argumentName",
        "value": "argumentValue"
      }
    ]
  }
}

Always key your handling off message.token. It is stable across releases and localisations, whereas message.text is presentation only.

HTTP status codes

Status	Meaning
`200` / `201`	Success.
`400`	Validation error — check `message.token` and `tokenArguments`.
`401`	Missing or invalid `X-Auth-Token` — see Authentication.
`403`	Authenticated but not authorised for the resource.
`404`	Resource not found within your organisation.
`429`	Rate limited — back off and retry.
`5xx`	Server error — retry with backoff; if it persists, contact support.