curl --request PUT \
--url https://sandbox.nmbr.co/services/payroll/payrolls/{payroll} \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"pay_date": "2026-01-01",
"period_start": "2026-01-01",
"period_end": "2026-01-01"
}
'import requests
url = "https://sandbox.nmbr.co/services/payroll/payrolls/{payroll}"
payload = {
"pay_date": "2026-01-01",
"period_start": "2026-01-01",
"period_end": "2026-01-01"
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.put(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'PUT',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({pay_date: '2026-01-01', period_start: '2026-01-01', period_end: '2026-01-01'})
};
fetch('https://sandbox.nmbr.co/services/payroll/payrolls/{payroll}', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://sandbox.nmbr.co/services/payroll/payrolls/{payroll}",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "PUT",
CURLOPT_POSTFIELDS => json_encode([
'pay_date' => '2026-01-01',
'period_start' => '2026-01-01',
'period_end' => '2026-01-01'
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://sandbox.nmbr.co/services/payroll/payrolls/{payroll}"
payload := strings.NewReader("{\n \"pay_date\": \"2026-01-01\",\n \"period_start\": \"2026-01-01\",\n \"period_end\": \"2026-01-01\"\n}")
req, _ := http.NewRequest("PUT", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.put("https://sandbox.nmbr.co/services/payroll/payrolls/{payroll}")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"pay_date\": \"2026-01-01\",\n \"period_start\": \"2026-01-01\",\n \"period_end\": \"2026-01-01\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://sandbox.nmbr.co/services/payroll/payrolls/{payroll}")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Put.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"pay_date\": \"2026-01-01\",\n \"period_start\": \"2026-01-01\",\n \"period_end\": \"2026-01-01\"\n}"
response = http.request(request)
puts response.read_body{
"id": "<id>",
"object": "payroll",
"data": {
"business_entity": {
"id": "<id>",
"object": "business_entity",
"links": {
"self": "/business_entities/<id>"
}
},
"pay_schedule": {
"id": "<id>",
"object": "pay_schedule",
"links": {
"self": "/pay_schedules/<id>"
}
},
"type": "historical",
"period_number": 1,
"period_label": "1",
"period_start": "2026-01-01",
"period_end": "2026-01-01",
"pay_date": "2026-01-01",
"original_pay_date": "2026-01-08",
"debit_date": "2025-12-24",
"approval_due_at": "2025-12-24T21:30:00.000000Z",
"regular_periods_count": null,
"is_impacted_by_weekend_or_holiday": false,
"is_blocked_by_draft": false,
"note": null,
"employee_summary": {
"gross": null,
"subtractions": null,
"reimbursements": null,
"net": null
},
"contractor_summary": {
"gross": null,
"reimbursements": null,
"net": null
},
"company_summary": {
"taxes_and_contributions": null,
"benefits": null,
"total": null
},
"liability": null,
"cash_requirement": null,
"status": "draft",
"approved_at": null,
"is_stale": false,
"stale_since": null,
"source_payroll": null,
"warnings": {
"object": "list",
"data": []
},
"external_ref": null,
"created_at": "2026-01-01T00:00:00.000000Z",
"updated_at": "2026-01-01T00:00:00.000000Z"
},
"links": {
"self": "/payrolls/<id>"
}
}Update a payroll
curl --request PUT \
--url https://sandbox.nmbr.co/services/payroll/payrolls/{payroll} \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"pay_date": "2026-01-01",
"period_start": "2026-01-01",
"period_end": "2026-01-01"
}
'import requests
url = "https://sandbox.nmbr.co/services/payroll/payrolls/{payroll}"
payload = {
"pay_date": "2026-01-01",
"period_start": "2026-01-01",
"period_end": "2026-01-01"
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.put(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'PUT',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({pay_date: '2026-01-01', period_start: '2026-01-01', period_end: '2026-01-01'})
};
fetch('https://sandbox.nmbr.co/services/payroll/payrolls/{payroll}', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://sandbox.nmbr.co/services/payroll/payrolls/{payroll}",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "PUT",
CURLOPT_POSTFIELDS => json_encode([
'pay_date' => '2026-01-01',
'period_start' => '2026-01-01',
'period_end' => '2026-01-01'
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://sandbox.nmbr.co/services/payroll/payrolls/{payroll}"
payload := strings.NewReader("{\n \"pay_date\": \"2026-01-01\",\n \"period_start\": \"2026-01-01\",\n \"period_end\": \"2026-01-01\"\n}")
req, _ := http.NewRequest("PUT", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.put("https://sandbox.nmbr.co/services/payroll/payrolls/{payroll}")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"pay_date\": \"2026-01-01\",\n \"period_start\": \"2026-01-01\",\n \"period_end\": \"2026-01-01\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://sandbox.nmbr.co/services/payroll/payrolls/{payroll}")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Put.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"pay_date\": \"2026-01-01\",\n \"period_start\": \"2026-01-01\",\n \"period_end\": \"2026-01-01\"\n}"
response = http.request(request)
puts response.read_body{
"id": "<id>",
"object": "payroll",
"data": {
"business_entity": {
"id": "<id>",
"object": "business_entity",
"links": {
"self": "/business_entities/<id>"
}
},
"pay_schedule": {
"id": "<id>",
"object": "pay_schedule",
"links": {
"self": "/pay_schedules/<id>"
}
},
"type": "historical",
"period_number": 1,
"period_label": "1",
"period_start": "2026-01-01",
"period_end": "2026-01-01",
"pay_date": "2026-01-01",
"original_pay_date": "2026-01-08",
"debit_date": "2025-12-24",
"approval_due_at": "2025-12-24T21:30:00.000000Z",
"regular_periods_count": null,
"is_impacted_by_weekend_or_holiday": false,
"is_blocked_by_draft": false,
"note": null,
"employee_summary": {
"gross": null,
"subtractions": null,
"reimbursements": null,
"net": null
},
"contractor_summary": {
"gross": null,
"reimbursements": null,
"net": null
},
"company_summary": {
"taxes_and_contributions": null,
"benefits": null,
"total": null
},
"liability": null,
"cash_requirement": null,
"status": "draft",
"approved_at": null,
"is_stale": false,
"stale_since": null,
"source_payroll": null,
"warnings": {
"object": "list",
"data": []
},
"external_ref": null,
"created_at": "2026-01-01T00:00:00.000000Z",
"updated_at": "2026-01-01T00:00:00.000000Z"
},
"links": {
"self": "/payrolls/<id>"
}
}Authorizations
Bearer authentication header of the form Bearer <token>, where <token> is your auth token.
Path Parameters
Body
The date on which Employees and Contractors are paid.
An optional note on the payroll, visible to the partner.
255The start date of the pay period.
The end date of the pay period.
Response
OK
The unique identifier of the object in Nmbr.
The type of the object in Nmbr ("payroll").
Hide child attributes
Hide child attributes
The type of payroll. regular payrolls are generated automatically on the Pay Schedule. off_cycle Payrolls are created manually against a source regular payroll. historical and correction payrolls are used to record or correct prior periods.
correction, historical, off_cycle, regular The sequential number of this pay period within the calendar year of its pay_date, counting only regular payrolls. null for off-cycle, historical, and correction payrolls.
A human-readable label for this pay period.
The start date of the pay period.
The end date of the pay period.
The date on which Employees and Contractors are paid.
For payrolls on a custom-frequency Pay Schedule, the originally scheduled pay date before any movement for weekends or bank holidays. Used for year-to-date calculations and tax year assignment.
The expected date the company's account will be debited the cash_requirement amount.
The date and time, in UTC, by which the payroll must be approved to be processed on time.
The total number of regular pay periods in this Pay Schedule whose pay_date falls in the same calendar year as this payroll's pay_date. Used for year-to-date calculations.
Whether pay_date or approval_due_at has been moved to avoid falling on a weekend or bank holiday.
Whether this payroll is blocked from being approved because an earlier payroll on the same Pay Schedule is still in draft status.
An optional note on the payroll, visible to the partner.
A summary of pay across all Employees in this payroll.
Hide child attributes
Hide child attributes
The sum of all earnings and allowances.
The total of all deductions, taxes, and benefit contributions.
The total of non-taxable reimbursements.
The Employee net pay; when negative, a warning is included.
A summary of the company's obligations in this payroll.
The total amount owed by the company for this payroll, including Employee and Contractor net pay, employer tax contributions, and employer benefit contributions.
The total amount that will be debited from the company's account when this payroll is approved.
The current status of the payroll.
approved, draft, failed, paid, partially_paid, processing The date on which the payroll was approved.
Whether the payroll's tax calculations are out of date. When true, stale_since indicates when the payroll became stale.
The timestamp at which the payroll's tax calculations became stale and need to be recalculated. null if the payroll is up to date.
A reference to the object in an external system, e.g. the primary key of the object in your application's database. Nmbr doesn't use, validate, parse, or require this value to be unique - it simply stores it for your reference.
255The date and time the object was created in Nmbr.
The date and time the object was last updated in Nmbr.