Add a person to payroll

curl --request POST \
  --url https://api.panoflow.io/v1/payroll/people \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "Ngozi Adeyemi",
  "email": "ngozi@adaezelogistics.ng",
  "role": "Operations assistant",
  "team": "Operations",
  "start_date": "2026-11-01",
  "bank_account": {
    "account_number": "0119337731",
    "bank_code": "058"
  },
  "pay_items": [
    {
      "type": "basic",
      "amount": {
        "amount": 10200000,
        "currency": "NGN"
      }
    },
    {
      "type": "housing",
      "amount": {
        "amount": 4250000,
        "currency": "NGN"
      }
    },
    {
      "type": "transport",
      "amount": {
        "amount": 2550000,
        "currency": "NGN"
      }
    }
  ]
}
'

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    name: 'Ngozi Adeyemi',
    email: 'ngozi@adaezelogistics.ng',
    role: 'Operations assistant',
    team: 'Operations',
    start_date: '2026-11-01',
    bank_account: {account_number: '0119337731', bank_code: '058'},
    pay_items: [
      {type: 'basic', amount: {amount: 10200000, currency: 'NGN'}},
      {type: 'housing', amount: {amount: 4250000, currency: 'NGN'}},
      {type: 'transport', amount: {amount: 2550000, currency: 'NGN'}}
    ]
  })
};

fetch('https://api.panoflow.io/v1/payroll/people', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.panoflow.io/v1/payroll/people"

payload = {
    "name": "Ngozi Adeyemi",
    "email": "ngozi@adaezelogistics.ng",
    "role": "Operations assistant",
    "team": "Operations",
    "start_date": "2026-11-01",
    "bank_account": {
        "account_number": "0119337731",
        "bank_code": "058"
    },
    "pay_items": [
        {
            "type": "basic",
            "amount": {
                "amount": 10200000,
                "currency": "NGN"
            }
        },
        {
            "type": "housing",
            "amount": {
                "amount": 4250000,
                "currency": "NGN"
            }
        },
        {
            "type": "transport",
            "amount": {
                "amount": 2550000,
                "currency": "NGN"
            }
        }
    ]
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

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

print(response.text)

{
  "id": "ppl_01J9NGK80Y3ZH6DZJJXXX7CK5Y",
  "object": "payroll_person",
  "created_at": "2026-10-28T11:00:00Z",
  "updated_at": "2026-10-28T11:00:00Z",
  "name": "Ngozi Adeyemi",
  "email": "ngozi@adaezelogistics.ng",
  "role": "Operations assistant",
  "team": "Operations",
  "status": "starting",
  "start_date": "2026-11-01",
  "bank_account": {
    "bank_code": "058",
    "bank_name": "GTBank",
    "account_number_last4": "7731",
    "account_name": "NGOZI ADEYEMI",
    "verified_at": "2026-10-28T10:59:58Z"
  },
  "pay_items": [
    {
      "type": "basic",
      "name": "Basic",
      "amount": {
        "amount": 10200000,
        "currency": "NGN"
      }
    },
    {
      "type": "housing",
      "name": "Housing",
      "amount": {
        "amount": 4250000,
        "currency": "NGN"
      }
    },
    {
      "type": "transport",
      "name": "Transport",
      "amount": {
        "amount": 2550000,
        "currency": "NGN"
      }
    }
  ],
  "pay": {
    "gross": {
      "amount": 17000000,
      "currency": "NGN"
    },
    "deductions": [
      {
        "deduction_type_id": "ded_01J1JX4WHRDD459GQ8H7QEZZS1",
        "name": "PAYE (income tax)",
        "short_name": "PAYE",
        "how": "Worked out from yearly pay and reliefs",
        "applies_to_everyone": true,
        "amount": {
          "amount": 1275000,
          "currency": "NGN"
        }
      },
      {
        "deduction_type_id": "ded_01JA0ZWSK9TPRM7N0MNS7C0JGQ",
        "name": "Pension",
        "short_name": "Pension",
        "how": "8% of basic, housing and transport",
        "applies_to_everyone": true,
        "amount": {
          "amount": 1360000,
          "currency": "NGN"
        }
      }
    ],
    "deduction_total": {
      "amount": 2635000,
      "currency": "NGN"
    },
    "net": {
      "amount": 14365000,
      "currency": "NGN"
    }
  }
}

{
  "error": {
    "response_code": "00",
    "type": "invalid_request",
    "code": "invalid_json",
    "message": "<string>",
    "request_id": "<string>",
    "param": "<string>",
    "doc_url": "<string>",
    "details": {}
  }
}

{
  "error": {
    "response_code": "00",
    "type": "invalid_request",
    "code": "invalid_json",
    "message": "<string>",
    "request_id": "<string>",
    "param": "<string>",
    "doc_url": "<string>",
    "details": {}
  }
}

{
  "error": {
    "response_code": "00",
    "type": "invalid_request",
    "code": "invalid_json",
    "message": "<string>",
    "request_id": "<string>",
    "param": "<string>",
    "doc_url": "<string>",
    "details": {}
  }
}

{
  "error": {
    "response_code": "00",
    "type": "invalid_request",
    "code": "invalid_json",
    "message": "<string>",
    "request_id": "<string>",
    "param": "<string>",
    "doc_url": "<string>",
    "details": {}
  }
}

{
  "error": {
    "response_code": "08",
    "type": "invalid_request",
    "code": "recipient_name_mismatch",
    "message": "GTBank says this account belongs to NGOZI ADEYEMI-BELLO. Check the details or confirm the name.",
    "param": "bank_account.account_number",
    "request_id": "req_01JJJHHQGGCWFBFF9JCM4SGFE6",
    "details": {
      "account_name": "NGOZI ADEYEMI-BELLO"
    }
  }
}

{
  "error": {
    "response_code": "00",
    "type": "invalid_request",
    "code": "invalid_json",
    "message": "<string>",
    "request_id": "<string>",
    "param": "<string>",
    "doc_url": "<string>",
    "details": {}
  }
}

{
  "error": {
    "response_code": "00",
    "type": "invalid_request",
    "code": "invalid_json",
    "message": "<string>",
    "request_id": "<string>",
    "param": "<string>",
    "doc_url": "<string>",
    "details": {}
  }
}

{
  "error": {
    "response_code": "00",
    "type": "invalid_request",
    "code": "invalid_json",
    "message": "<string>",
    "request_id": "<string>",
    "param": "<string>",
    "doc_url": "<string>",
    "details": {}
  }
}

People

Add a person to payroll

The bank account is confirmed by name enquiry through the partner bank before the person is saved; the name the bank returns is stored as bank_account.account_name. Use the Payments name-enquiry endpoint to show “Name confirmed by GTBank” before submitting. If the returned name does not match name and confirm_account_name is not true, the call fails with 422 recipient_name_mismatch and details.account_name.

The person is paid from the first run whose pay date is on or after start_date; until then status is starting. Company-wide deduction types apply automatically.

Error codes: invalid_api_key, parameter_invalid, parameter_missing, scope_missing, csrf_token_invalid, idempotency_key_reused, recipient_name_mismatch, name_enquiry_failed, account_number_invalid, amount_too_small, currency_not_enabled, bank_unavailable, rate_limited.

POST

payroll

people

Add a person to payroll

curl --request POST \
  --url https://api.panoflow.io/v1/payroll/people \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "Ngozi Adeyemi",
  "email": "ngozi@adaezelogistics.ng",
  "role": "Operations assistant",
  "team": "Operations",
  "start_date": "2026-11-01",
  "bank_account": {
    "account_number": "0119337731",
    "bank_code": "058"
  },
  "pay_items": [
    {
      "type": "basic",
      "amount": {
        "amount": 10200000,
        "currency": "NGN"
      }
    },
    {
      "type": "housing",
      "amount": {
        "amount": 4250000,
        "currency": "NGN"
      }
    },
    {
      "type": "transport",
      "amount": {
        "amount": 2550000,
        "currency": "NGN"
      }
    }
  ]
}
'

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    name: 'Ngozi Adeyemi',
    email: 'ngozi@adaezelogistics.ng',
    role: 'Operations assistant',
    team: 'Operations',
    start_date: '2026-11-01',
    bank_account: {account_number: '0119337731', bank_code: '058'},
    pay_items: [
      {type: 'basic', amount: {amount: 10200000, currency: 'NGN'}},
      {type: 'housing', amount: {amount: 4250000, currency: 'NGN'}},
      {type: 'transport', amount: {amount: 2550000, currency: 'NGN'}}
    ]
  })
};

fetch('https://api.panoflow.io/v1/payroll/people', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.panoflow.io/v1/payroll/people"

payload = {
    "name": "Ngozi Adeyemi",
    "email": "ngozi@adaezelogistics.ng",
    "role": "Operations assistant",
    "team": "Operations",
    "start_date": "2026-11-01",
    "bank_account": {
        "account_number": "0119337731",
        "bank_code": "058"
    },
    "pay_items": [
        {
            "type": "basic",
            "amount": {
                "amount": 10200000,
                "currency": "NGN"
            }
        },
        {
            "type": "housing",
            "amount": {
                "amount": 4250000,
                "currency": "NGN"
            }
        },
        {
            "type": "transport",
            "amount": {
                "amount": 2550000,
                "currency": "NGN"
            }
        }
    ]
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

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

print(response.text)

{
  "id": "ppl_01J9NGK80Y3ZH6DZJJXXX7CK5Y",
  "object": "payroll_person",
  "created_at": "2026-10-28T11:00:00Z",
  "updated_at": "2026-10-28T11:00:00Z",
  "name": "Ngozi Adeyemi",
  "email": "ngozi@adaezelogistics.ng",
  "role": "Operations assistant",
  "team": "Operations",
  "status": "starting",
  "start_date": "2026-11-01",
  "bank_account": {
    "bank_code": "058",
    "bank_name": "GTBank",
    "account_number_last4": "7731",
    "account_name": "NGOZI ADEYEMI",
    "verified_at": "2026-10-28T10:59:58Z"
  },
  "pay_items": [
    {
      "type": "basic",
      "name": "Basic",
      "amount": {
        "amount": 10200000,
        "currency": "NGN"
      }
    },
    {
      "type": "housing",
      "name": "Housing",
      "amount": {
        "amount": 4250000,
        "currency": "NGN"
      }
    },
    {
      "type": "transport",
      "name": "Transport",
      "amount": {
        "amount": 2550000,
        "currency": "NGN"
      }
    }
  ],
  "pay": {
    "gross": {
      "amount": 17000000,
      "currency": "NGN"
    },
    "deductions": [
      {
        "deduction_type_id": "ded_01J1JX4WHRDD459GQ8H7QEZZS1",
        "name": "PAYE (income tax)",
        "short_name": "PAYE",
        "how": "Worked out from yearly pay and reliefs",
        "applies_to_everyone": true,
        "amount": {
          "amount": 1275000,
          "currency": "NGN"
        }
      },
      {
        "deduction_type_id": "ded_01JA0ZWSK9TPRM7N0MNS7C0JGQ",
        "name": "Pension",
        "short_name": "Pension",
        "how": "8% of basic, housing and transport",
        "applies_to_everyone": true,
        "amount": {
          "amount": 1360000,
          "currency": "NGN"
        }
      }
    ],
    "deduction_total": {
      "amount": 2635000,
      "currency": "NGN"
    },
    "net": {
      "amount": 14365000,
      "currency": "NGN"
    }
  }
}

{
  "error": {
    "response_code": "00",
    "type": "invalid_request",
    "code": "invalid_json",
    "message": "<string>",
    "request_id": "<string>",
    "param": "<string>",
    "doc_url": "<string>",
    "details": {}
  }
}

{
  "error": {
    "response_code": "00",
    "type": "invalid_request",
    "code": "invalid_json",
    "message": "<string>",
    "request_id": "<string>",
    "param": "<string>",
    "doc_url": "<string>",
    "details": {}
  }
}

{
  "error": {
    "response_code": "00",
    "type": "invalid_request",
    "code": "invalid_json",
    "message": "<string>",
    "request_id": "<string>",
    "param": "<string>",
    "doc_url": "<string>",
    "details": {}
  }
}

{
  "error": {
    "response_code": "00",
    "type": "invalid_request",
    "code": "invalid_json",
    "message": "<string>",
    "request_id": "<string>",
    "param": "<string>",
    "doc_url": "<string>",
    "details": {}
  }
}

{
  "error": {
    "response_code": "08",
    "type": "invalid_request",
    "code": "recipient_name_mismatch",
    "message": "GTBank says this account belongs to NGOZI ADEYEMI-BELLO. Check the details or confirm the name.",
    "param": "bank_account.account_number",
    "request_id": "req_01JJJHHQGGCWFBFF9JCM4SGFE6",
    "details": {
      "account_name": "NGOZI ADEYEMI-BELLO"
    }
  }
}

{
  "error": {
    "response_code": "00",
    "type": "invalid_request",
    "code": "invalid_json",
    "message": "<string>",
    "request_id": "<string>",
    "param": "<string>",
    "doc_url": "<string>",
    "details": {}
  }
}

{
  "error": {
    "response_code": "00",
    "type": "invalid_request",
    "code": "invalid_json",
    "message": "<string>",
    "request_id": "<string>",
    "param": "<string>",
    "doc_url": "<string>",
    "details": {}
  }
}

{
  "error": {
    "response_code": "00",
    "type": "invalid_request",
    "code": "invalid_json",
    "message": "<string>",
    "request_id": "<string>",
    "param": "<string>",
    "doc_url": "<string>",
    "details": {}
  }
}

Authorizations

Authorization

string

header

required

Server API key, scoped. pk_test_ keys hit the sandbox tenant.

Headers

Idempotency-Key

string

Optional on non-money POSTs; honoured when sent.

Required string length: 1 - 255

X-Request-Id

string

Optional client correlation id, up to 128 characters. It is not echoed: the response's X-Request-Id is always our own req_… id. We log your value with the request as client_request_id, so support can find a request by either id. A longer value is refused with 400 parameter_invalid.

Maximum string length: 128

Body

application/json

name

string

required

Full name, as on their bank account.

Required string length: 1 - 120

start_date

string<date>

required

Calendar date, interpreted in Africa/Lagos.

Example:

"2026-11-07"

bank_account

object

required

Where the person is paid. Confirmed by name enquiry.

Show child attributes

pay_items

object[]

required

Monthly pay. Gross must be above zero.

Required array length: 1 - 20 elements

Show child attributes

string<email>

Maximum string length: 254

role

string

Job title, e.g. "Dispatch rider".

Maximum string length: 80

team

string

Team, e.g. "Operations".

Maximum string length: 60

confirm_account_name

boolean

default:false

Accept the bank's account name even if it differs from name.

metadata

object

Up to 20 string keys (≤ 40 chars) with string values (≤ 500 chars). Returned on the resource and its events.

Show child attributes

Response

The person, with their computed pay.

A person on payroll (ppl_…).

string

required

ppl_…

object

string

required

Always payroll_person.

Allowed value: "payroll_person"

created_at

string<date-time>

required

RFC 3339, UTC.

Example:

"2026-10-27T08:41:00Z"

updated_at

string<date-time>

required

RFC 3339, UTC.

Example:

"2026-10-27T08:41:00Z"

name

string

required

Full name.

status

enum<string>

required

active is paid; on_leave is on paid leave and still paid ("On leave, paid"); starting has a start date after today ("Starts 1 Nov"); offboarded is past their end date and never paid again.

Available options:

active,

on_leave,

starting,

offboarded

start_date

string<date>

required

Calendar date, interpreted in Africa/Lagos.

Example:

"2026-11-07"

bank_account

object

required

The person's bank account. Only the last four digits are returned.

Show child attributes

pay_items

object[]

required

Monthly earnings.

Show child attributes

pay

object

required

What the next run would pay, with current deductions (before any one-off bonus).

Show child attributes

string<email>

Where payslips are sent.

Maximum string length: 254

role

string

Job title.

team

string

Team.

end_date

string<date>

Calendar date, interpreted in Africa/Lagos.

Example:

"2026-11-07"

offboarded_at

string<date-time>

RFC 3339, UTC.

Example:

"2026-10-27T08:41:00Z"

metadata

object

Up to 20 string keys (≤ 40 chars) with string values (≤ 500 chars). Returned on the resource and its events.

Show child attributes

Accounts & transactions

Payments

Collections

Payroll

Approvals

Webhooks & events

OAuth

Add a person to payroll

Authorizations

Headers

Body

Response