Payd logo
Documentation Powered by ReDoc

Workforce Digital Twin Payd API (1.0.1)

Download OpenAPI specification:Download

Payd API Support: support@justpayd.com

Introduction

Why Payd?

Payd lets employees access their earned wages before payday.
This is commonly referred to as Earned Wage Access (EWA) and is a modern digital fuss-free version of a cash advance.

EWA helps employees meet unexpected expenses and saves them from:

  • High fees of payday loans, credit cards or overdraft fees.
  • Loosing face by ask their friends, family or employer to borrow money.
  • Financial stress

EWA helps employers:

  • Improve retention
  • Immediately reward employees working extra shifts and overtime
  • Offer financial wellness to their teams

How to integrate with Payd?

To enable EWA we need to know about your employees, how much they get paid, when they take leave and when they work. This information is already stored in one or more tools as part of your workforce management system.
Once your company have signed up we provision a digital twin that keeps in sync with your workforce management system. We use this digital twin to calculate accrued earnings and issue salary advances on your behalf when requested by employees all without impacting your systems.

There are five general ways to keep the Payd digital twin in sync:

  1. An API based push integration - As this page details.
  2. An API based pull integration.
  3. An automated bot based push integration.
  4. A manual file upload via the Payd web portal.
  5. Manual updates via the Payd web portal.

(1) & (2) are intended for our payroll, scheduling, and attendance partners. We prefer (1) as it reduces overheads for all parties but can do (2). (3) is required where we're not able to gain access to a providers API. (4) lets you export a file from your existing tools then upload in our web portal.
(5) lets you make changes directly via the web portal, it's perfect when you have a small number of employees.

Authentication

All requests require an x-api-key header. A key will be issued which provides access to a specific company in a specific environment. This means a different key is used in the dev, pre-prod, and prod environments.

ApiKeyAuth

An api key will be issued for each service that needs to sync in each specific environment.

Security Scheme Type API Key
Header parameter name: x-api-key

Request Throttling

To maintain the integrity of the digital twin api service each key is assigned rate limits. These will be calibrated during integration based on the sector and size of the organization. If a 429 - Too Many Requests response is received please us so we can investigate.

Employees

Manage employees

Record joiners, leavers or employee detail updates

An asynchronous end point to notify of eligible employees and manage existing employees.

Uniqueness of employee_id

Each employee should have a unique employee_id, in most cases this will be their payroll number or employee code. However, if your WFM system reuses payroll numbers such as on a per group or division basis a different id will be required that can be guaranteed to be unique across the company.

Updates

Where a matching employee_id is found their details will be updated with those provided. To maintain data integrity requests will be rejected that simultaneously alter:

  • given_name and (work_phone or personal_phone)
  • (work_phone or personal_phone) and (personal_email or work_email)
Request Body schema: application/json

A collection of employee objects

Array ()
employee_id
required
string

Unique ID for this employee

work_email
string <email>

Work email on which to reach the employee

personal_email
string <email>

Personal email on which to reach the employee

given_name
string

The given name of the employee

family_name
string

The family name of the employee

honorific
string

The honorific to use for the employee

work_phone
string <phone>

The employees work issued phone number

personal_phone
string <phone>

The employees personal phone number

custom_info
object

Any additional information that is deemed necessary on a per company basis to support service operation

To comply with PDPA and GDPR regulations requests that send this without prior agreement of the data that is to be shared will recieve a 451 Unavailable For Legal Reasons

contract_id
string

An contract id of the contract to assign or update.

If not provided then contract_stop_on will apply to all contracts this employee is assigned to.

contract_start_on
string <date>

The date in YYYY-MM-DD format that the employee contract defined by contract_id commenced.

This field is ignored where no contract_id is provided. This is a saftey data integrity mechanism to prevent inadvently back-filling wages and displaying an incorrect balance to employees.

contract_stop_on
string <date>

The date in YYYY-MM-DD format that the employee contract defined by contract_id concluded.

For convienence, where no contract_id is provided it is assumed the employee is leaving the company on this date and therefore will apply to all contracts that this employee is on.

Responses

Request samples

Content type
application/json
[
  • {
    }
]

Response samples

Content type
application/json
{
  • "job_id": "string",
  • "target_entity": "pay-schedules",
  • "count_received": 0,
  • "count_pending": 0,
  • "count_rejected": 0,
  • "count_accepted": 0,
  • "error_summary": [
    ]
}

Pay Schedules

Manage pay schedules

Record new or updated pay schedules

An asynchronous end point to notify of new or updated pay schedules.

Request Body schema: application/json

A collection of pay_schedule objects

Array ()
employee_id
required
string

Unique ID for this employee

work_email
string <email>

Work email on which to reach the employee

personal_email
string <email>

Personal email on which to reach the employee

given_name
string

The given name of the employee

family_name
string

The family name of the employee

honorific
string

The honorific to use for the employee

work_phone
string <phone>

The employees work issued phone number

personal_phone
string <phone>

The employees personal phone number

custom_info
object

Any additional information that is deemed necessary on a per company basis to support service operation

To comply with PDPA and GDPR regulations requests that send this without prior agreement of the data that is to be shared will recieve a 451 Unavailable For Legal Reasons

contract_id
string

An contract id of the contract to assign or update.

If not provided then contract_stop_on will apply to all contracts this employee is assigned to.

contract_start_on
string <date>

The date in YYYY-MM-DD format that the employee contract defined by contract_id commenced.

This field is ignored where no contract_id is provided. This is a saftey data integrity mechanism to prevent inadvently back-filling wages and displaying an incorrect balance to employees.

contract_stop_on
string <date>

The date in YYYY-MM-DD format that the employee contract defined by contract_id concluded.

For convienence, where no contract_id is provided it is assumed the employee is leaving the company on this date and therefore will apply to all contracts that this employee is on.

Responses

Request samples

Content type
application/json
[
  • {
    }
]

Response samples

Content type
application/json
{
  • "job_id": "string",
  • "target_entity": "pay-schedules",
  • "count_received": 0,
  • "count_pending": 0,
  • "count_rejected": 0,
  • "count_accepted": 0,
  • "error_summary": [
    ]
}

Contracts

Manage contracts

Record new or updated contracts.

An asynchronous end point to notify of new or updated contracts. A single contract may be applied to multiple employees based on team, division or grade. This ensures consistent rates, overtime rules, and approval workflows are applied.

Request Body schema: application/json

A collection of contract objects

Array ()
contract_id
required
string

unique id for this contract

pay_schedule_id
required
string

The id of the pay schedule to use when calculating earned wages on this contract.

currency
required
string

The ISO 4217 currency code.

wage_rate_period
required
string
Enum: "hourly" "daily" "weekly" "bi-weekly" "semi-monthly" "monthly" "annually" "adhoc"

The periodicity of the pay amount For the avoidance of doubt on definitions:

  • bi-weekly - every two weeks, paid 26 times a year
  • semi-monthly - twice a month, paid 24 times a year
wage_rate_amount
required
number <integer>

The amount of pay in minor currency units that this contract attracts

custom_info
object

Any additional information that is deemed necessary on a per company basis to support service operation. Holiday allowance, grade or position, and overtime rules are useful to define here.

Responses

Request samples

Content type
application/json
[
  • {
    }
]

Response samples

Content type
application/json
{
  • "job_id": "string",
  • "target_entity": "pay-schedules",
  • "count_received": 0,
  • "count_pending": 0,
  • "count_rejected": 0,
  • "count_accepted": 0,
  • "error_summary": [
    ]
}

Retrieve a collection of the contracts on record

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Retrieve the contract with the given id

path Parameters
contract_id
required
string

id of the specific contract to retrieve

Responses

Response samples

Content type
application/json
{
  • "contract_id": "string",
  • "pay_schedule_id": "string",
  • "currency": "string",
  • "wage_rate_period": "hourly",
  • "wage_rate_amount": 0,
  • "custom_info": { }
}

Shifts

Record new or updated resource requirements

An asynchronous end point to notify of shifts are available or have been scheduled, worked or approved.

Request Body schema: application/json

A collection of shift objects

Array ()
shift_id
required
string

Unique id of this shift. This id should remain constant through any changes to it's properties. This allows auditability of any changes such as status, assigned employee, contract, or start and end times.

shift_status
required
string
Enum: "available" "scheduled" "declined" "voided" "no_show" "submitted" "provisionally_approved" "approved"

The status of this shift in the planning and approval workflow. Not all of these status codes may be relevant for specific workflow.

  • available - The shift is yet to be assigned to an employee but the resource requirement is known.
  • scheduled - The shift has been assign to an employee.
  • declined - Where the employee has the ability to decline a shift this can be recorded. The shift will be automatically marked as available.
  • voided - The resource is no longer required or was recorded in error
  • no_show - Where the shift was scheduled but the employee failed to attend
  • submitted - Records that the shift was worked making any necessary updates to properties such as start_at and end_at
  • provisionally_approved - Use where one or more approvals are required. custom_info property may be used to detail the approver.
    • Where it has been agreed that submitted but yet to be approved shifts count towards available balance then the shift will automatically transition to this state following the submitted state.
  • approved - The shift has been formally approved and will now be counted towards their available balance.
employee_id
string

Unique ID of the employee who is assigned to work or has worked this shift

contract_id
string

Unique ID of the contract that applies to this shift. The contract describes the wage rates, overtime logic etc. that will apply for this shift

start_at
required
string <date-time>

The date and optionally time the shift begins Where only the date is known use 00:00:00 as the time component.

stop_at
required
string <date-time>

The datetime the shift ends. Only provide if start_at contains both a specific date and time component. Otherwise hours will be assumed by the contract

custom_info
object

Any additional information that is deemed necessary on a per company basis to support service operation

Responses

Request samples

Content type
application/json
[
  • {
    }
]

Response samples

Content type
application/json
{
  • "job_id": "string",
  • "target_entity": "pay-schedules",
  • "count_received": 0,
  • "count_pending": 0,
  • "count_rejected": 0,
  • "count_accepted": 0,
  • "error_summary": [
    ]
}

Additions

Record new or updated additions

An asynchronous end point to notify of new or updated additions.

Request Body schema: application/json

A collection of addition objects

Array ()
payment_id
required
string

unique id for this payment

employee_id
required
string

Unique id of the employee who is the beneficiary or remitter for this payment

contract_id
string

The optional id of the contract related to this payment

currency
string

The ISO 4217 currency code.

Required if contract_id is undefined or if the payment is to be made in a different currency than the contract.

amount
required
number <integer>

The amount of this payment in minor currency units

custom_info
object

Any additional information that is deemed necessary on a per company basis to support service operation

Responses

Request samples

Content type
application/json
[
  • {
    }
]

Response samples

Content type
application/json
{
  • "job_id": "string",
  • "target_entity": "pay-schedules",
  • "count_received": 0,
  • "count_pending": 0,
  • "count_rejected": 0,
  • "count_accepted": 0,
  • "error_summary": [
    ]
}

Deductions

Record new or updated deductions

An asynchronous end point to notify of new or updated deductions.

Request Body schema: application/json

A collection of deduction objects

Array ()
payment_id
required
string

unique id for this payment

employee_id
required
string

Unique id of the employee who is the beneficiary or remitter for this payment

contract_id
string

The optional id of the contract related to this payment

currency
string

The ISO 4217 currency code.

Required if contract_id is undefined or if the payment is to be made in a different currency than the contract.

amount
required
number <integer>

The amount of this payment in minor currency units

custom_info
object

Any additional information that is deemed necessary on a per company basis to support service operation

Responses

Request samples

Content type
application/json
[
  • {
    }
]

Response samples

Content type
application/json
{
  • "job_id": "string",
  • "target_entity": "pay-schedules",
  • "count_received": 0,
  • "count_pending": 0,
  • "count_rejected": 0,
  • "count_accepted": 0,
  • "error_summary": [
    ]
}

The Job Status Model

job_id
required
string

A unique ID for this job. Use it to query the status

target_entity
required
string
Enum: "pay-schedules" "contracts" "employees" "shifts" "deductions" "additions"

The type of entity the job is working on

count_received
required
integer

The number of records received

count_pending
required
integer

The number of records waiting to be processed

count_rejected
required
integer

The number of records that have been rejected

count_accepted
required
integer

The number of records that have been accepted

error_summary
Array of strings

Optional summary of any errors encountered

{
  • "job_id": "string",
  • "target_entity": "pay-schedules",
  • "count_received": 0,
  • "count_pending": 0,
  • "count_rejected": 0,
  • "count_accepted": 0,
  • "error_summary": [
    ]
}

The Pay Schedule Model

pay_schedule_id
required
string

Unique id for this pay schedule

frequency
required
string
Enum: "hourly" "daily" "weekly" "bi-weekly" "semi-monthly" "monthly" "annually" "adhoc"

The frequency of the pay cycle For the avoidance of doubt on definitions:

  • bi-weekly - every two weeks, paid 26 times a year
  • semi-monthly - twice a month, paid 24 times a year
alignment
string
Enum: "arrears" "aligned" "advance"

How payday is aligned to the accrual period.

Array of objects (pay_period)
custom_info
object

Any additional information that is deemed necessary on a per company basis to support service operation

{
  • "pay_schedule_id": "string",
  • "frequency": "hourly",
  • "alignment": "arrears",
  • "periods": [
    ],
  • "custom_info": { }
}

The Employee Model

employee_id
required
string

Unique ID for this employee

work_email
string <email>

Work email on which to reach the employee

personal_email
string <email>

Personal email on which to reach the employee

given_name
string

The given name of the employee

family_name
string

The family name of the employee

honorific
string

The honorific to use for the employee

work_phone
string <phone>

The employees work issued phone number

personal_phone
string <phone>

The employees personal phone number

custom_info
object

Any additional information that is deemed necessary on a per company basis to support service operation

To comply with PDPA and GDPR regulations requests that send this without prior agreement of the data that is to be shared will recieve a 451 Unavailable For Legal Reasons

contract_id
string

An contract id of the contract to assign or update.

If not provided then contract_stop_on will apply to all contracts this employee is assigned to.

contract_start_on
string <date>

The date in YYYY-MM-DD format that the employee contract defined by contract_id commenced.

This field is ignored where no contract_id is provided. This is a saftey data integrity mechanism to prevent inadvently back-filling wages and displaying an incorrect balance to employees.

contract_stop_on
string <date>

The date in YYYY-MM-DD format that the employee contract defined by contract_id concluded.

For convienence, where no contract_id is provided it is assumed the employee is leaving the company on this date and therefore will apply to all contracts that this employee is on.

{
  • "employee_id": "string",
  • "work_email": "user@example.com",
  • "personal_email": "user@example.com",
  • "given_name": "string",
  • "family_name": "string",
  • "honorific": "string",
  • "work_phone": "+65-6225-5577",
  • "personal_phone": "+65-6225-5577",
  • "custom_info": { },
  • "contract_id": "string",
  • "contract_start_on": "2019-08-24",
  • "contract_stop_on": "2019-08-24"
}

The Contract Model

contract_id
required
string

unique id for this contract

pay_schedule_id
required
string

The id of the pay schedule to use when calculating earned wages on this contract.

currency
required
string

The ISO 4217 currency code.

wage_rate_period
required
string
Enum: "hourly" "daily" "weekly" "bi-weekly" "semi-monthly" "monthly" "annually" "adhoc"

The periodicity of the pay amount For the avoidance of doubt on definitions:

  • bi-weekly - every two weeks, paid 26 times a year
  • semi-monthly - twice a month, paid 24 times a year
wage_rate_amount
required
number <integer>

The amount of pay in minor currency units that this contract attracts

custom_info
object

Any additional information that is deemed necessary on a per company basis to support service operation. Holiday allowance, grade or position, and overtime rules are useful to define here.

{
  • "contract_id": "string",
  • "pay_schedule_id": "string",
  • "currency": "string",
  • "wage_rate_period": "hourly",
  • "wage_rate_amount": 0,
  • "custom_info": { }
}

The Shift Model

shift_id
required
string

Unique id of this shift. This id should remain constant through any changes to it's properties. This allows auditability of any changes such as status, assigned employee, contract, or start and end times.

shift_status
required
string
Enum: "available" "scheduled" "declined" "voided" "no_show" "submitted" "provisionally_approved" "approved"

The status of this shift in the planning and approval workflow. Not all of these status codes may be relevant for specific workflow.

  • available - The shift is yet to be assigned to an employee but the resource requirement is known.
  • scheduled - The shift has been assign to an employee.
  • declined - Where the employee has the ability to decline a shift this can be recorded. The shift will be automatically marked as available.
  • voided - The resource is no longer required or was recorded in error
  • no_show - Where the shift was scheduled but the employee failed to attend
  • submitted - Records that the shift was worked making any necessary updates to properties such as start_at and end_at
  • provisionally_approved - Use where one or more approvals are required. custom_info property may be used to detail the approver.
    • Where it has been agreed that submitted but yet to be approved shifts count towards available balance then the shift will automatically transition to this state following the submitted state.
  • approved - The shift has been formally approved and will now be counted towards their available balance.
employee_id
string

Unique ID of the employee who is assigned to work or has worked this shift

contract_id
string

Unique ID of the contract that applies to this shift. The contract describes the wage rates, overtime logic etc. that will apply for this shift

start_at
required
string <date-time>

The date and optionally time the shift begins Where only the date is known use 00:00:00 as the time component.

stop_at
required
string <date-time>

The datetime the shift ends. Only provide if start_at contains both a specific date and time component. Otherwise hours will be assumed by the contract

custom_info
object

Any additional information that is deemed necessary on a per company basis to support service operation

{
  • "shift_id": "string",
  • "shift_status": "available",
  • "employee_id": "string",
  • "contract_id": "string",
  • "start_at": "2019-08-24T14:15:22Z",
  • "stop_at": "2019-08-24T14:15:22Z",
  • "custom_info": { }
}

The Payment Model

payment_id
required
string

unique id for this payment

employee_id
required
string

Unique id of the employee who is the beneficiary or remitter for this payment

contract_id
string

The optional id of the contract related to this payment

currency
string

The ISO 4217 currency code.

Required if contract_id is undefined or if the payment is to be made in a different currency than the contract.

amount
required
number <integer>

The amount of this payment in minor currency units

custom_info
object

Any additional information that is deemed necessary on a per company basis to support service operation

{
  • "payment_id": "string",
  • "employee_id": "string",
  • "contract_id": "string",
  • "currency": "string",
  • "amount": 0,
  • "custom_info": { }
}