Responses

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": "inherit",
        "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": "inherit",
                "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, an errors object detailing validation issues for each field, and an error_details object giving each failure a code.

{
  "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. It must be 9 digits."]
  },
  "error_details": {
    "province_code": [{ "code": "province_code" }],
    "country_code": [{ "code": "enum" }],
    "sin": [{ "code": "sin_format" }]
  }
}

Messages are returned in the language you request. See Localization.

Handling a failure by code

errors is written for a person to read. The wording follows the language you request and can change in any release, so branch your own code on error_details. error_details is keyed by field the same way errors is, including the dotted path a batch or bulk request reports (data.0.sin). Each entry describes one reason that field failed:

code names the reason. required, max and date_format name the rule the value broke. sin_format and province_code name a check Nmbr applies to that kind of value.
parameters carries the values behind the reason, and is present only for a code that has them. max reports its limit, so { "code": "max", "parameters": ["50"] } reads as 50 characters.

A code names the condition the value has to meet, not the way it failed. pay_date_in_future means the pay date has to be in the future. unchanged means the value has to match the one already stored. Read the code as the requirement, and the matching message in errors for what went wrong this time. The same reason reports the same code wherever it is checked. A record that could not be found is exists whether you referenced it by employee, by payroll or by remittance account, and the field tells you which one Nmbr could not find. Every field in errors has at least one entry in error_details, and a field that failed for more than one reason gets one entry per reason. Read a field’s entries as a set rather than as an ordered list. Existing codes do not get renamed. New ones ship with new checks, so handle a code you do not recognise as a plain rejection of that field. A code of unspecified means the failure has no narrower code yet, and may report one in a later release.

Too Many Requests (429)

A 429 status code indicates that you have gone over a rate limit. The request was not processed.

{
  "message": "Too Many Attempts."
}

The response includes a Retry-After header holding the number of seconds to wait before retrying, along with the X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers. See Rate Limits.

Overview

Bulk & Batch Operations

Partner

Companies

Employees

Contractors

Payrolls

Line Items

Banking

Reporting

Forms

Vacation Pay

Lookups

Calculations

Miscellaneous

ULID

Response Structure

Entities

Pageable Lists

Non-Pageable Lists

Expanding Resources

Using the `expand` array

Maximum expansion depth

Expanding optional properties

Error Response Structure

Bad Request (400)

Unauthorized (401)

Forbidden (403)

Not Found (404)

Unprocessable Entity (422)

Handling a failure by code

Too Many Requests (429)

​ULID

​Response Structure

​Entities

​Pageable Lists

​Non-Pageable Lists

​Related Resources

​Expanding Resources

​Using the expand array

​Maximum expansion depth

​Expanding optional properties

​Error Response Structure

​Bad Request (400)

​Unauthorized (401)

​Forbidden (403)

​Not Found (404)

​Unprocessable Entity (422)

​Handling a failure by code

​Too Many Requests (429)

ULID

Response Structure

Entities

Pageable Lists

Non-Pageable Lists

Related Resources

Expanding Resources

Using the `expand` array

Maximum expansion depth

Expanding optional properties

Error Response Structure

Bad Request (400)

Unauthorized (401)

Forbidden (403)

Not Found (404)

Unprocessable Entity (422)

Handling a failure by code

Too Many Requests (429)