Skip to main content

​
ULID

All Nmbr entities have an id. These ids are based on a customized version of ULIDs. Nmbr ULIDs take the form of a standard ULID prefixed with a namespace reference. For example, an employee may be emp_01JAV10D4QJ3500QANBTTBW9DW, and a company may be cmp_01JAV11013A9V4V0F30099BVGH.

​
Response Structure

Objects across the Nmbr API follow a consistent JSON structure, either a single Entity, a Pageable List, or a Non-Pageable List. Entities and Lists can be returned as the root response on an endpoint.

​
Entities

Entity Responses will follow the structure: 
{
    "id":  string (ULID),
    "object": string,
    "data": {
        // ...
    },
    "links": {
        "self": string (url)
    }
}

​
Pageable Lists

Pageable Lists contain up to 15 objects per-page and can be paged using the associated links data. The object type will always have the value list . 
{
    "object": "list",
    "data": [
        {
            "id": string (GUID),
            "object": string,
            "data": {
                // ...
                "created_at": string (ISO-8601),
                "updated_at":string (ISO-8601)
            },
            "links": {
                "self": string (url)
            }
        }
        // ...
    ],
    "links": {
        "first": string (url),
        "last": string (url),
        "prev": string (url)|null,
        "next": string (url)|null
    },
    "meta": {
        "current_page": int,
        "last_page": int,
        "per_page": int,
        "total": int,
        "has_more": boolean
    }
}

​
Non-Pageable Lists

Non-Pageable Lists are returned for lists with no related endpoint to page through. In these cases the complete data set will be returned as a list with no paging information. 
{
    "object": "list",
    "data": [
        {
            "id": string (GUID),
            "object": string,
            "data": {
                // ...
            },
            "links": {
                "self": url
            }
        }
        // ...
    ]
}
Entities will contain references to other objects - e.g an Employee will contain a Company reference. By default, these will be “stub” entities which will have no data attribute. They may be an Entity, a Pageable List or a Non-Pageable List. 
{
  "id": "01hfwg26zxk6bg8874nth78cgr",
  "object": "employee",
  "data": {
    "company": {
      "id": "01hfwg25dbyebq330k8c8ammpm",
      "object": "company",
      "links": {
        "self": "https://sandbox.nmbr.co/services/payroll/companies/01hfwg25dbyebq330k8c8ammpm"
      }
    },
    // ...
    "created_at": "2023-11-22T21:48:01.000000Z",
    "updated_at": "2023-11-22T21:48:01.000000Z"
  },
  "links": {
    "self": "https://sandbox.nmbr.co/services/payroll/employees/01hfwg26zxk6bg8874nth78cgr"
  }
}

​
Expanding Resources

If you would like to retrieve the data of a related resource inline, you may pass the expand array parameter to expand its contents. Request: 
curl 'https://sandbox.nmbr.co/services/payroll/employees/01hfwg26zxk6bg8874nth78cgr?expand[]=company' \
--header 'Authorization: Bearer Llk5NQVFt9bu2auhJBuBxFGih22VecGq8qUeDD0Q7aa0c5bf'
Response 
{
  "id": "01hfwg26zxk6bg8874nth78cgr",
  "object": "employee",
  "data": {
    "company": {
      "id": "01hfwg25dbyebq330k8c8ammpm",
      "object": "company",
      "data": {
        "name": "Bouchard Inc.",
        "pay_day_movement_setting": "forward",
        "status": "onboarding",
        "created_at": "2023-11-22T21:47:59.000000Z",
        "updated_at": "2023-11-22T21:47:59.000000Z"
      },
      "links": {
        "self": "https://sandbox.nmbr.co/services/payroll/companies/01hfwg25dbyebq330k8c8ammpm"
      }
    },
    // ...
    "created_at": "2023-11-22T21:48:01.000000Z",
    "updated_at": "2023-11-22T21:48:01.000000Z"
  },
  "links": {
    "self": "https://sandbox.nmbr.co/services/payroll/employees/01hfwg26zxk6bg8874nth78cgr"
  }
}
The API will return “stub” objects to represent related Entities and Lists of related Entities. These objects can be expanded to include their data by passing the expand parameter in your request. You can expand multiple layers down by defining dot (.) notation values to the expand array. In the following example, the company entity is expanded to a full company resource, and its pageable-list of business_entities is expanded into a list of business_entity resources. Request: 
curl 'https://sandbox.nmbr.co/services/payroll/employees/01hfwg26zxk6bg8874nth78cgr?expand[]=company.business_entities' \
--header 'Authorization: Bearer Llk5NQVFt9bu2auhJBuBxFGih22VecGq8qUeDD0Q7aa0c5bf'
Response: 
{
    "id": "01hfwg26zxk6bg8874nth78cgr",
    "object": "employee",
    "data": {
        "company": {
            "id": "01hfwg25dbyebq330k8c8ammpm",
            "object": "company",
            "data": {
                "name": "Bouchard Inc.",
                "pay_day_movement_setting": "forward",
                "status": "onboarding",
                "business_entities": {
                    "object": "list",
                    "data": [
                        {
                            "id": "01hfwg25fz7t023he2jr3b2nas",
                            "object": "business_entity",
                            "data": {
                                "business_number": "34y6y3",
                                // ...
                                },
                                "company": {
                                    "id": "01hfwg25dbyebq330k8c8ammpm",
                                    "object": "company",
                                    "links": {
                                        "self": "https://sandbox.nmbr.co/services/payroll/companies/01hfwg25dbyebq330k8c8ammpm"
                                    }
                                },
                                "created_at": "2023-11-22T21:47:59.000000Z",
                                "updated_at": "2023-11-22T21:47:59.000000Z"
                            },
                            "links": {
                                "self": "https://sandbox.nmbr.co/services/payroll/business_entities/01hfwg25fz7t023he2jr3b2nas"
                            }
                        }
                    ],
                    "links": {
                        "first": "https://sandbox.nmbr.co/services/payroll/business_entities?page=1",
                        "last": "https://sandbox.nmbr.co/services/payroll/business_entities?page=1",
                        "prev": null,
                        "next": null
                    },
                    "meta": {
                        "current_page": 1,
                        "last_page": 1,
                        "per_page": 15,
                        "total": 1,
                        "has_more": false
                    }
                },
                "created_at": "2023-11-22T21:47:59.000000Z",
                "updated_at": "2023-11-22T21:47:59.000000Z"
            },
            "links": {
                "self": "https://sandbox.nmbr.co/services/payroll/companies/01hfwg25dbyebq330k8c8ammpm"
            }
        },
        // ...
        "created_at": "2023-11-22T21:48:01.000000Z",
        "updated_at": "2023-11-22T21:48:01.000000Z"
    },
    "links": {
        "self": "https://sandbox.nmbr.co/services/payroll/employees/01hfwg26zxk6bg8874nth78cgr"
    }
}

​
Using the expand array

Multiple objects can be expanded by passing multiple values to the expand parameter. Some objects have properties which are arrays of data - if there is an expandable property in such an array, you must pass the dot-property of the array.property. For example, to expand the recurring_allowance in a allowance_line_item, you must pass the parameter expand[]=allowance.recurring_allowance. The expand parameter can also accept a comma separated list of expandable attributes: expand=company,allowance.recurring_allowance. Request 
curl 'https://sandbox.nmbr.co/services/payroll/\/allowance_line_items/01hfym068emnp93zxz94822ec5?expand[]=allowance.recurring_allowance' \
--header 'Authorization: Bearer Llk5NQVFt9bu2auhJBuBxFGih22VecGq8qUeDD0Q7aa0c5bf'
Response 
{
  "id": "01hfym068emnp93zxz94822ec5",
  "object": "allowance_line_item",
  "data": {
    "pay_stub": {
      "id": "01hfwg2784vc1408yhmjp4x81q",
      "object": "pay_stub",
      "links": {
        "self": "https://sandbox.nmbr.co/services/payroll/pay_stubs/01hfwg2784vc1408yhmjp4x81q"
      }
    },
    "line_item_type": "allowance",
    "amount": 10,
    "allowance": {
      "allowance_type": "automobile_and_motor_vehicle",
      "recurring_allowance": {
        "id": "01hfykqhej130bzjfryem64wjv",
        "object": "recurring_allowance",
        "data": {
          "employee": {
            "id": "01hfwg26zxk6bg8874nth78cgr",
            "object": "work_assignment",
            "links": {
              "self": "https://sandbox.nmbr.co/services/payroll/work_assignments/01hfwg26zxk6bg8874nth78cgr"
            }
          },
          "allowance_type": "automobile_and_motor_vehicle",
          "amount": 10,
          "effective_from": "2023-01-01T00:00:00.000000Z",
          "effective_to": null,
          "created_at": "2023-11-23T17:30:34.000000Z",
          "updated_at": "2023-11-23T17:30:34.000000Z"
        },
        "links": {
          "self": "https://sandbox.nmbr.co/services/payroll/allowances/01hfykqhej130bzjfryem64wjv"
        }
      }
    },
    "created_at": "2023-11-23T17:35:18.000000Z",
    "updated_at": "2023-11-23T17:35:18.000000Z"
  },
  "links": {
    "self": "https://sandbox.nmbr.co/services/payroll/allowance_line_items/01hfym068emnp93zxz94822ec5"
  }
}

​
Maximum expansion depth

expand parameters using dot-properties for deep expanding may go up to 4 layers deep. For example, the following is a valid expand argument on a pay_stub -work_assignment.pay_rate.expense_accounting_code.business_entity. However, no property on the business_entity may be expanded.

​
Expanding optional properties

Some resources will have expandable properties that are not returned by default (i.e no “stub” entity will be returned by default). These optional properties will be documented as available, but must be requested in the expand argument to be returned. The expand parameter can be used to reduce the total number of requests required to use the Nmbr API, however it should be used only when required, as there may be a noticeable performance difference when querying for a single entity with no expand argument, vs a query with multiple expand arguments - especially when expanding attributes in a list.

​
Error Response Structure

When a client error (4xx) occurs, the Nmbr API returns a standardized error response.

​
Bad Request (400)

A 400 status code indicates that the request was invalid. The response message explains why the request could not be processed. 
{
  "message": "The action is not allowed after a payroll has been run."
}

​
Unauthorized (401)

A 401 status code indicates that authentication has failed. 
{
  "message": "Unauthorized"
}

​
Forbidden (403)

A 403 status code indicates that the client does not have permission to perform the requested action. 
{
  "message": "Forbidden"
}

​
Not Found (404)

A 404 status code indicates that the requested resource does not exist. 
{
  "message": "Entity not found"
}

​
Unprocessable Entity (422)

A 422 status code is returned when validation errors occur. The response includes a summary message and an errors object detailing validation issues for each field. 
{
  "message": "The selected province code is invalid. (and 2 more errors)",
  "errors": {
    "province_code": ["The selected province code is invalid."],
    "country_code": ["The selected country code is invalid."],
    "sin": ["Not a valid sin number. Must be a string in format ^[0-9]{9}$"]
  }
}