Introduction

Welcome to the Onfolk API! This document describes how your application can integrate with Onfolk.

The base sandbox URL is: https://onfolk-sandbox.herokuapp.com

Authentication Process

Getting an access token

// Request
{
    "client_id": "",
    "client_secret": ""
}

// Response
{
    "access_token": ""
}

If an endpoint requires authentication (which is the default in our API) then you'll need an access token.

To do this you need to make a POST request to /auth/verify-client-credentials with the client id and client secret encoded in the body. It will return a JSON object with an access token.

Using an access token

To use the access token place it directly in the Authorization header (you do not need to prefix it with Bearer or anything else)

Employee Documentation

Create

{
  "employee": {
    "id": 12, // Read only
    "payroll_id":"123", // Optional if skip_for_payroll is true
    "employer_id": 17,
    "created_at": "" // Read only ISO8601 formatted
    "title": "Mr" 
    "forename": "",
    "middle_name": "",
    "surname": "",
    "date_of_birth": "2001-02-01", // YYYY-MM-DD
    "gender": "M", // Either M or F
    "address": {

    },
    "personal_email": "",
    "phone_number": "", // Please include country code
    "ni_number": "",
    "is_waiting_for_ni_number": false,
    "national_insurance_category": "A",
    "tax_code": {
    }
    "job_title": "",
    "new_starter": {
    }
    "start_data_submitted": true, // Read only?
    "leaving_date": "2002-03-27",
    "has_left": false // Read only
    "pay_frequency": "", // Either M1 or W1
    "off_payroll_worker": false,
    "hours_worked": null, // Optional used for salaried workers
    "has_student_loan": true,
    "student_loan_type": "" // One of plan_one, plan_two or plan_four
    "has_pension": true,
    "employee_pension_contribution_percentage": 5,
    "employer_pension_contribution_percentage": 3,
    "eligible_for_tax_relief": true, // Read only
    "enrolment_type": "AE" // Read only - todo: check format
    "salary": {} // Deprecated
    "is_director": false,
    "director_config": {}
    "sort_code": "" // 6 digits no dashes
    "account_number": "",
    "is_ready_for_payroll": false // Read only
    "emergency_contact": {}
    "skip_for_payroll": false // Used to signify contractors whose data we store but we do not include in payroll
  }
}

Path: /employee/create
HTTP Verb: POST
Schema: See right hand side
Response: Complete schema as above

Update

Path: /employee/update
HTTP Verb: POST
Schema: Same as create you just need to provide the employee id

Payschedule Documentation

Preview FPS

Path: /payschedule/preview-fps
HTTP Verb: GET
Query Params: employer_id
Response: See sidebar

{
    "fps_xml": "", // XML String in here
    "validation_errors": ["", ""] // Should be empty
}

List Payments

Path: /payschedule/list-payments
HTTP Verb: GET
Response: See sidebar

{
    "pay_date": "2021-04-07",
    "payments": [
        {
            "payment": {
                "id": 7,
                "amount_to_be_paid_to_employee": "72.34", // In GBP
            },
        }
    ]
}

Payschedule Documentation

Create

Path: /payschedule/weekly/create
HTTP Verb: POST
Schema: { "day_of_week": 4 // Sunday is 0, Saturday is 6 }
Response: { "id": 1, "day_of_week": 4, "current_period_id": 7, "employer_id": 4 }

Add Employee to Payschedule

Path: /payschedule/weekly/add-employee
HTTP Verb: POST
Schema: See sidebar

{
    "employee_id": 4,
    "pay_schedule_id": 17
}

Hours Documentation

Create

{
    "hours": {
        "id": 7, // Read only
        "employee_id": 18,
        "hourly_rate": 15.7,
        "number_of_hours": 18, // This should be an integer
    }
}

Path: /hours/create
HTTP Verb: POST
Schema: See sidebar