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:
  • unfiled
  • pending
  • rejected
  • partially_filed
  • filed
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 JSON

List 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 JSON

Mark 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 JSON

Mark 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