Payroll
Minimum access level: Tax and Limited Accounting
. Only available for UK companies (i.e. those which support payroll in FreeAgent).
Provides read-only access to RTI payroll data generated within FreeAgent, including details on payments due.
Attributes
Attribute | Description | Kind |
---|---|---|
Period | ||
url | The unique identifier for the period | URI |
period | The pay period of the year (0-11) | Integer |
frequency | The pay frequency (Monthly/Weekly) | String |
dated_on | The date of pay for this period, in YYYY-MM-DD format |
Date |
status |
The filing status of this payroll period. One of:
|
String |
employment_allowance_claimed | Was Employment Allowance claimed in this pay period | Boolean |
employment_allowance_amount | The amount of Employment Allowance claimed in this pay period | Decimal |
construction_industry_scheme_deduction | The amount of liability already witheld under the CIS scheme this period | Decimal |
Payment | ||
due_on | The date on which a particular payment is due | Date |
amount_due | The amount due on that date | Decimal |
status | One of `unpaid` or `marked_as_paid`. `paid` is reserved for future use. Key is omitted if there are no payments to be made. | Decimal |
Payslip | ||
user | The unique identifier for the user being paid | URL |
tax_code | The HMRC tax code for the payslip | String |
dated_on | The date of the payslip in YYYY-MM-DD format |
Date |
basic_pay | Basic pay this period | Decimal |
tax_deducted | Tax deducted this period | Decimal |
employee_ni | Employee NI payable this period | Decimal |
employer_ni | Employer NI payable this period | Decimal |
other_deductions | Other deductions this period | Decimal |
student_loan_deduction | Student loan deductions this period | Decimal |
postgrad_loan_deduction | Postgraduate loan deductions this period | Decimal |
overtime | Overtime paid this period | Decimal |
commission | Commission paid this period | Decimal |
bonus | Bonus paid this period | Decimal |
allowance | Allowance paid this period | Decimal |
statutory_sick_pay | SSP this period | Decimal |
statutory_maternity_pay | SMP this period | Decimal |
statutory_paternity_pay | SPP this period | Decimal |
statutory_adoption_pay | SAP this period | Decimal |
statutory_parental_bereavement_pay | SPBP this period | Decimal |
absence_payments | Absence payments this period | Decimal |
other_payments | Other payments this period | Decimal |
employee_pension | Employee pension deductions this period | Decimal |
employer_pension | Employer pension deductions this period | Decimal |
attachments | Attachment deductions this period | Decimal |
payroll_giving | Payroll giving deductions this period | Decimal |
ni_calc_type | Calculation method for NI (Director/Employee) | String |
frequency | Pay frequency (Monthly/Weekly) | String |
additional_statutory_paternity_pay | ASPP this period | Decimal |
deductions_subject_to_nic_but_not_paye | Payroll deductions that are subject to NI but not income tax this period | Decimal |
other_deductions_from_net_pay | Other deductions this period | Decimal |
employee_pension_not_under_net_pay | Employee pension deductions not under net pay agreement this period | Decimal |
ni_letter | HMRC NI classification for this employee | String |
deduct_student_loan | Are student loan payments being deducted? | Boolean |
student_loan_deductions_plan | The student loan plan type (Plan 1/Plan 2) | String |
deduct_postgrad_loan | Are postgraduate loan payments being deducted? | Boolean |
week_1_month_1_basis | Deductions calculated on a W1M1 basis | Boolean |
deduction_free_pay | Pay this period not subject to NI or income tax | Decimal |
hours_worked | The number of hours worked this period | Decimal |
List all periods for a given tax year
Returns the list of all payroll periods for the given year end. For example, for the payroll year April 2020 - March 2021, the :year
parameter should be 2021.
GET https://api.freeagent.com/v2/payroll/:year
Response
Status: 200 OK
{
"periods": [
{
"url": "https://api.freeagent.com/v2/payroll/2021/0",
"period": 0,
"frequency": "Monthly",
"dated_on": "2020-04-25",
"status": "filed",
"employment_allowance_claimed": true,
"employment_allowance_amount": "0.0",
"construction_industry_scheme_deduction": "0.0",
"created_at": "2020-04-17T11:31:58.000Z",
"updated_at": "2020-04-17T12:42:54.000Z"
}
],
"payments": [
{
"due_on": "2020-05-22",
"amount_due": "738.19",
"status": "unpaid"
}
]
}
Show as XML<?xml version="1.0" encoding="UTF-8"?>
<freeagent>
<periods type="array">
<period>
<url>https://api.freeagent.com/v2/payroll/2021/0</url>
<period type="integer">0</period>
<frequency>Monthly</frequency>
<dated-on type="date">2017-02-25</dated-on>
<status>filed</status>
<employment-allowance-claimed type="boolean">true</employment-allowance-claimed>
<employment-allowance-amount type="decimal">0.0</employment-allowance-amount>
<constriction-industry-scheme-deduction type="decimal">0.0</constriction-industry-scheme-deduction>
<created-at type="dateTime">2017-02-17T11:31:58Z</created-at>
<updated-at type="dateTime">2017-02-17T12:42:54Z</updated-at>
</period>
</periods>
<payments type="array">
<payment>
<due-on type="date">2017-03-22</due-on>
<amount-due type="decimal">1454.95</amount-due>
<status>unpaid</status>
</payment>
</payments>
</freeagent>
Show as JSONList all payslips for a given period
Returns the list of all payslips for the given year and period.
GET https://api.freeagent.com/v2/payroll/:year/:period
Response
Status: 200 OK
{
"period": {
"url": "https://api.freeagent.com/v2/payroll/2021/0",
"period": 0,
"frequency": "Monthly",
"dated_on": "2020-04-25",
"status": "filed",
"employment_allowance_claimed": true,
"employment_allowance_amount": "0.0",
"construction_industry_scheme_deduction": "0.0",
"created_at": "2020-04-17T11:31:58.000Z",
"updated_at": "2020-04-17T12:42:54.000Z",
"payslips": [
{
"user": "https://api.freeagent.com/v2/users/86",
"tax_code": "1100L",
"dated_on": "2020-04-25",
"basic_pay": "2500.0",
"tax_deducted": "0.0",
"employee_ni": "0.0",
"employer_ni": "0.0",
"other_deductions": "0.0",
"student_loan_deduction": "0.0",
"postgrad_loan_deduction": "0.0",
"overtime": "0.0",
"commission": "0.0",
"bonus": "0.0",
"allowance": "0.0",
"statutory_sick_pay": "0.0",
"statutory_maternity_pay": "0.0",
"statutory_paternity_pay": "0.0",
"statutory_adoption_pay": "0.0",
"statutory_parental_bereavement_pay": "0.0",
"absence_payments": "0.0",
"other_payments": "0.0",
"employee_pension": "0.0",
"employer_pension": "0.0",
"attachments": "0.0",
"payroll_giving": "0.0",
"ni_calc_type": "Director",
"frequency": "Monthly",
"additional_statutory_paternity_pay": "0.0",
"deductions_subject_to_nic_but_not_paye": "0.0",
"other_deductions_from_net_pay": "0.0",
"employee_pension_not_under_net_pay": "0.0",
"ni_letter": "A",
"deduct_student_loan": false,
"deduct_postgrad_loan": false,
"week_1_month_1_basis": false,
"deduction_free_pay": "0.0",
"created_at": "2020-04-17T11:31:59.000Z",
"updated_at": "2020-04-17T11:31:59.000Z"
},
{
"user": "https://api.freeagent.com/v2/users/71",
"tax_code": "BR",
"dated_on": "2020-04-25",
"basic_pay": "1100.0",
"tax_deducted": "220.0",
"employee_ni": "0.0",
"employer_ni": "0.0",
"other_deductions": "0.0",
"student_loan_deduction": "0.0",
"postgrad_loan_deduction": "0.0",
"overtime": "0.0",
"commission": "0.0",
"bonus": "0.0",
"allowance": "0.0",
"statutory_sick_pay": "0.0",
"statutory_maternity_pay": "0.0",
"statutory_paternity_pay": "0.0",
"statutory_adoption_pay": "0.0",
"statutory_parental_bereavement_pay": "0.0",
"absence_payments": "0.0",
"other_payments": "0.0",
"employee_pension": "0.0",
"employer_pension": "0.0",
"attachments": "0.0",
"payroll_giving": "0.0",
"ni_calc_type": "Director",
"frequency": "Monthly",
"additional_statutory_paternity_pay": "0.0",
"deductions_subject_to_nic_but_not_paye": "0.0",
"other_deductions_from_net_pay": "0.0",
"employee_pension_not_under_net_pay": "0.0",
"ni_letter": "A",
"deduct_student_loan": true,
"deduct_postgrad_loan": false,
"week_1_month_1_basis": false,
"deduction_free_pay": "0.0",
"student_loan_deductions_plan": "Plan 1",
"hours_worked": "120.0",
"created_at": "2020-04-17T11:31:59.000Z",
"updated_at": "2020-04-17T11:31:59.000Z"
}
]
}
}
Show as XML<?xml version="1.0" encoding="UTF-8"?>
<freeagent>
<period>
<url>https://api.freeagent.com/v2/payroll/2021/0</url>
<period type="integer">0</period>
<frequency>Monthly</frequency>
<dated-on type="date">2020-04-25</dated-on>
<status>filed</status>
<employment-allowance-claimed type="boolean">true</employment-allowance-claimed>
<employment-allowance-amount type="decimal">0.0</employment-allowance-amount>
<constriction-industry-scheme-deduction type="decimal">0.0</constriction-industry-scheme-deduction>
<created-at type="dateTime">2020-04-17T11:31:58Z</created-at>
<updated-at type="dateTime">2020-04-17T12:42:54Z</updated-at>
<payslips type="array">
<payslip>
<user>https://api.freeagent.com/v2/users/86</user>
<tax-code>1250L</tax-code>
<dated-on type="date">2020-04-25</dated-on>
<basic-pay type="decimal">2500.0</basic-pay>
<tax-deducted type="decimal">0.0</tax-deducted>
<employee-ni type="decimal">0.0</employee-ni>
<employer-ni type="decimal">0.0</employer-ni>
<other-deductions type="decimal">0.0</other-deductions>
<student-loan-deduction type="decimal">0.0</student-loan-deduction>
<postgrad-loan-deduction type="decimal">0.0</postgrad-loan-deduction>
<overtime type="decimal">0.0</overtime>
<commission type="decimal">0.0</commission>
<bonus type="decimal">0.0</bonus>
<allowance type="decimal">0.0</allowance>
<statutory-sick-pay type="decimal">0.0</statutory-sick-pay>
<statutory-maternity-pay type="decimal">0.0</statutory-maternity-pay>
<statutory-paternity-pay type="decimal">0.0</statutory-paternity-pay>
<statutory-adoption-pay type="decimal">0.0</statutory-adoption-pay>
<statutory-parental-bereavement-pay type="decimal">0.0</statutory-parental-bereavement-pay>
<absence-payments type="decimal">0.0</absence-payments>
<other-payments type="decimal">0.0</other-payments>
<employee-pension type="decimal">0.0</employee-pension>
<employer-pension type="decimal">0.0</employer-pension>
<attachments type="decimal">0.0</attachments>
<payroll-giving type="decimal">0.0</payroll-giving>
<ni-calc-type>Director</ni-calc-type>
<frequency>Monthly</frequency>
<additional-statutory-paternity-pay type="decimal">0.0</additional-statutory-paternity-pay>
<deductions-subject-to-nic-but-not-paye type="decimal">0.0</deductions-subject-to-nic-but-not-paye>
<other-deductions-from-net-pay type="decimal">0.0</other-deductions-from-net-pay>
<employee-pension-not-under-net-pay type="decimal">0.0</employee-pension-not-under-net-pay>
<ni-letter>A</ni-letter>
<deduct-student-loan type="boolean">false</deduct-student-loan>
<deduct-postgrad-loan type="boolean">false</deduct-postgrad-loan>
<week-1-month-1-basis type="boolean">false</week-1-month-1-basis>
<deduction-free-pay type="decimal">0.0</deduction-free-pay>
<created-at type="dateTime">2020-04-17T11:31:59Z</created-at>
<updated-at type="dateTime">2020-04-17T11:31:59Z</updated-at>
</payslip>
<payslip>
<user>https://api.freeagent.com/v2/users/71</user>
<tax-code>BR</tax-code>
<dated-on type="date">2020-04-25</dated-on>
<basic-pay type="decimal">1100.0</basic-pay>
<tax-deducted type="decimal">220.0</tax-deducted>
<employee-ni type="decimal">0.0</employee-ni>
<employer-ni type="decimal">0.0</employer-ni>
<other-deductions type="decimal">0.0</other-deductions>
<student-loan-deduction type="decimal">0.0</student-loan-deduction>
<postgrad-loan-deduction type="decimal">0.0</postgrad-loan-deduction>
<overtime type="decimal">0.0</overtime>
<commission type="decimal">0.0</commission>
<bonus type="decimal">0.0</bonus>
<allowance type="decimal">0.0</allowance>
<statutory-sick-pay type="decimal">0.0</statutory-sick-pay>
<statutory-maternity-pay type="decimal">0.0</statutory-maternity-pay>
<statutory-paternity-pay type="decimal">0.0</statutory-paternity-pay>
<statutory-adoption-pay type="decimal">0.0</statutory-adoption-pay>
<statutory-parental-bereavement-pay type="decimal">0.0</statutory-parental-bereavement-pay>
<absence-payments type="decimal">0.0</absence-payments>
<other-payments type="decimal">0.0</other-payments>
<employee-pension type="decimal">0.0</employee-pension>
<employer-pension type="decimal">0.0</employer-pension>
<attachments type="decimal">0.0</attachments>
<payroll-giving type="decimal">0.0</payroll-giving>
<ni-calc-type>Director</ni-calc-type>
<frequency>Monthly</frequency>
<additional-statutory-paternity-pay type="decimal">0.0</additional-statutory-paternity-pay>
<deductions-subject-to-nic-but-not-paye type="decimal">0.0</deductions-subject-to-nic-but-not-paye>
<other-deductions-from-net-pay type="decimal">0.0</other-deductions-from-net-pay>
<employee-pension-not-under-net-pay type="decimal">0.0</employee-pension-not-under-net-pay>
<ni-letter>A</ni-letter>
<deduct-student-loan type="boolean">true</deduct-student-loan>
<student-loan-deductions-plan>Plan 1</student-loan-deductions-plan>
<deduct-postgrad-loan type="boolean">false</deduct-postgrad-loan>
<week-1-month-1-basis type="boolean">false</week-1-month-1-basis>
<deduction-free-pay type="decimal">0.0</deduction-free-pay>
<hours-worked type="decimal">120.0</hours-worked>
<created-at type="dateTime">2020-04-17T11:31:59Z</created-at>
<updated-at type="dateTime">2020-04-17T11:31:59Z</updated-at>
</payslip>
</payslips>
</period>
</freeagent>
Show as JSONMark a payment as paid
PUT https://api.freeagent.com/v2/payroll/:year/payments/:payment_date/mark_as_paid
Response
Status: 200 OK
{
"periods": [
{
"url": "https://api.freeagent.com/v2/payroll/2021/0",
"period": 0,
"frequency": "Monthly",
"dated_on": "2020-04-25",
"status": "filed",
"employment_allowance_claimed": true,
"employment_allowance_amount": "0.0",
"construction_industry_scheme_deduction": "0.0",
"created_at": "2020-04-17T11:31:58.000Z",
"updated_at": "2020-04-17T12:42:54.000Z"
}
],
"payments": [
{
"due_on": "2020-05-22",
"amount_due": "738.19",
"status": "paid"
}
]
}
Show as XML<?xml version="1.0" encoding="UTF-8"?>
<freeagent>
<periods type="array">
<period>
<url>https://api.freeagent.com/v2/payroll/2021/0</url>
<period type="integer">0</period>
<frequency>Monthly</frequency>
<dated-on type="date">2017-02-25</dated-on>
<status>filed</status>
<employment-allowance-claimed type="boolean">true</employment-allowance-claimed>
<employment-allowance-amount type="decimal">0.0</employment-allowance-amount>
<constriction-industry-scheme-deduction type="decimal">0.0</constriction-industry-scheme-deduction>
<created-at type="dateTime">2017-02-17T11:31:58Z</created-at>
<updated-at type="dateTime">2017-02-17T12:42:54Z</updated-at>
</period>
</periods>
<payments type="array">
<payment>
<due-on type="date">2017-03-22</due-on>
<amount-due type="decimal">1454.95</amount-due>
<status>paid</status>
</payment>
</payments>
</freeagent>
Show as JSONMark a payment as unpaid
GET https://api.freeagent.com/v2/payroll/:year/payments/:payment_date/mark_as_unpaid
Response
Status: 200 OK
{
"periods": [
{
"url": "https://api.freeagent.com/v2/payroll/2021/0",
"period": 0,
"frequency": "Monthly",
"dated_on": "2020-04-25",
"status": "filed",
"employment_allowance_claimed": true,
"employment_allowance_amount": "0.0",
"construction_industry_scheme_deduction": "0.0",
"created_at": "2020-04-17T11:31:58.000Z",
"updated_at": "2020-04-17T12:42:54.000Z"
}
],
"payments": [
{
"due_on": "2020-05-22",
"amount_due": "738.19",
"status": "unpaid"
}
]
}
Show as XML<?xml version="1.0" encoding="UTF-8"?>
<freeagent>
<periods type="array">
<period>
<url>https://api.freeagent.com/v2/payroll/2021/0</url>
<period type="integer">0</period>
<frequency>Monthly</frequency>
<dated-on type="date">2017-02-25</dated-on>
<status>filed</status>
<employment-allowance-claimed type="boolean">true</employment-allowance-claimed>
<employment-allowance-amount type="decimal">0.0</employment-allowance-amount>
<constriction-industry-scheme-deduction type="decimal">0.0</constriction-industry-scheme-deduction>
<created-at type="dateTime">2017-02-17T11:31:58Z</created-at>
<updated-at type="dateTime">2017-02-17T12:42:54Z</updated-at>
</period>
</periods>
<payments type="array">
<payment>
<due-on type="date">2017-03-22</due-on>
<amount-due type="decimal">1454.95</amount-due>
<status>unpaid</status>
</payment>
</payments>
</freeagent>
Show as JSON