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.

Attributes

Attribute Description Kind
Period
url The unique identifier for the period URI
period The pay period of the year 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
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
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
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
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

List all periods for a given tax year

Returns the list of all payroll periods for the given year end - for the payroll year April 2016 - March 2017, the :year parameter should be 2017.

GET https://api.freeagent.com/v2/payroll/:year

Response

Status: 200 OK
{
    "periods": [
        {
            "url": "https://api.freeagent.com/v2/payroll/2017/10",
            "period": 10,
            "frequency": "Monthly",
            "dated_on": "2017-02-25",
            "status": "filed",
            "employment_allowance_claimed": true,
            "employment_allowance_amount": "0.0",
            "construction_industry_scheme_deduction": "0.0",
            "created_at": "2017-02-17T11:31:58.000Z",
            "updated_at": "2017-02-17T12:42:54.000Z"
        }
    ]
}
Show as XML
<?xml version="1.0" encoding="UTF-8"?>
<freeagent>
    <periods type="array">
        <period>
            <url>https://api.freeagent.com/v2/payroll/2017/10</url>
            <period type="integer">10</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>
</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/2017/10",
        "period": 10,
        "frequency": "Monthly",
        "dated_on": "2017-02-25",
        "status": "filed",
        "employment_allowance_claimed": true,
        "employment_allowance_amount": "0.0",
        "construction_industry_scheme_deduction": "0.0",
        "created_at": "2017-02-17T11:31:58.000Z",
        "updated_at": "2017-02-17T12:42:54.000Z",
        "payslips": [
            {
                "user": "https://api.freeagent.com/v2/users/86",
                "tax_code": "1100L",
                "dated_on": "2017-02-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",
                "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",
                "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,
                "week_1_month_1_basis": false,
                "deduction_free_pay": "0.0",
                "created_at": "2017-02-17T11:31:59.000Z",
                "updated_at": "2017-02-17T11:31:59.000Z"
            },
            {
                "user": "https://api.freeagent.com/v2/users/71",
                "tax_code": "BR",
                "dated_on": "2017-02-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",
                "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",
                "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,
                "week_1_month_1_basis": false,
                "deduction_free_pay": "0.0",
                "created_at": "2017-02-17T11:31:59.000Z",
                "updated_at": "2017-02-17T11:31:59.000Z"
            }
        ]
    }
}
Show as XML
<?xml version="1.0" encoding="UTF-8"?>
<freeagent>
    <period>
        <url>https://api.freeagent.com/v2/payroll/2017/10</url>
        <period type="integer">10</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>
        <payslips type="array">
            <payslip>
                <user>https://api.freeagent.com/v2/users/86</user>
                <tax-code>1100L</tax-code>
                <dated-on type="date">2017-02-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>
                <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>
                <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>
                <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">2017-02-17T11:31:59Z</created-at>
                <updated-at type="dateTime">2017-02-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">2017-02-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>
                <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>
                <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>
                <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">2017-02-17T11:31:59Z</created-at>
                <updated-at type="dateTime">2017-02-17T11:31:59Z</updated-at>
            </payslip>
        </payslips>
    </period>
</freeagent>
Show as JSON