{"openapi":"3.1.0","info":{"title":"Nory Public API","description":"Public API for partners integrating with Nory.\n\n**Partner guides:** [/developers](/developers) — getting started, auth, pagination, errors.\n\nPagination: list endpoints return a `data` array and a `nextCursor` token. When `nextCursor` is `null`, there are no more pages.\n\nV0 is currently in limited preview, subject to change.","version":"0.1.0"},"paths":{"/health":{"get":{"summary":"Health","operationId":"health_health_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/api/v1/employees":{"get":{"tags":["employees"],"summary":"List employees","description":"Deactivated employees are excluded: an employee you previously saw that no longer appears in results has been deactivated or deleted.","operationId":"list_employees_api_v1_employees_get","security":[{"NoryApiKey":[]}],"parameters":[{"name":"cursor","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Cursor"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"default":50,"title":"Limit"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmployeesListResponse"}}}},"401":{"description":"Authentication required or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"API key lacks required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds to wait before retrying","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"502":{"description":"Upstream service error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"tags":["employees"],"summary":"Create employee","description":"**Requires a write-enabled API key.** Keys are read-only by default; calls with a read-only key return `403`. Contact Nory to enable write access for your integration.\n\n**Request.** Required fields identify the person and place them in the brand: `firstName`, `lastName`, `email`, `primaryLocationId` (an id from `GET /locations`), and `primaryPositionId` (an id from `GET /positions?locationId=` for that location). Optional `wage` lets you set pay on create when you have it — send it with both `amount` and `type`, or omit it entirely for the defaults below. Optional `externalReference` carries your own identifier for the person, so you can reference them without keeping an id mapping table; when supplied it is unique within your brand. Optional `startDate` sets the day their employment starts, as `YYYY-MM-DD`; it may be in the future, or omit it for the default below. Optional `contractedHours` sets their contracted hours per week, up to `168`; omit it when there are none. Optional `preferredName` sets the name they go by. Optional `contractType` sets their contract type; omit it for the default below. Some optional fields hold personal data and are accepted only when the brand's data agreement with your integration covers creating them, otherwise the request returns `403` with each uncovered field listed in `details`; each such field says so in its own description. On success, the response matches `GET /employees/{id}`.\n\n**Server defaults.** Attributes required internally but not supplied in the request are filled by Nory:\n\n- **Wage amount** → `0` when `wage` is omitted\n- **Wage type** → `hourly` when `wage` is omitted (`hourly` | `salary` | `daily`)\n- **Contract type** → `full time` when `contractType` is omitted (`full time` | `part time` | `contractor`)\n- **Start date** → the date you create them, when `startDate` is omitted\n- **Location assignment** → the home location only (`primaryLocationId`); no additional locations\n- **Invite** not sent — creating an employee does not email login credentials; inviting remains an in-app action\n\n**Email must be unused.** `email` identifies the person across Nory, so a create whose address is already in use returns `409` and creates nothing. Treat it as \"pick another address\" — the response does not report where the address is in use, and a `409` is not evidence that the person exists in your brand. Do not retry a `409` unchanged.\n\n**`externalReference` is unique when supplied.** A later create that reuses the same value in this brand returns `409` and creates nothing. Omit it and Nory has no partner-side key to de-dupe on: two creates with different emails will both succeed even if they represent the same person in your system.\n\n**`Idempotency-Key` (optional header).** Lets you retry a create without risking a duplicate: once Nory has recorded a completed keyed create, resending the same key and body returns the existing employee with `200` and `Idempotent-Replayed: true` instead of creating twice — or `404` if that employee has since been deleted. Reusing a key with a different request returns `422`; a concurrent retry of an in-flight request returns `409`.","operationId":"create_employee_api_v1_employees_post","security":[{"NoryApiKey":[]}],"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Optional client-generated key (max 255 chars) that makes the create safe to retry","title":"Idempotency-Key"},"description":"Optional client-generated key (max 255 chars) that makes the create safe to retry"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateEmployeeRequest"}}}},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmployeeResponse"}}}},"401":{"description":"Authentication required or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"API key lacks required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds to wait before retrying","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"502":{"description":"Upstream service error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Request conflicts with existing state","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"200":{"description":"Replay of a create already completed with this Idempotency-Key; nothing new is created","headers":{"Idempotent-Replayed":{"description":"true when the response replays a previously completed create","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmployeeResponse"}}}}}}},"/api/v1/employees/{employee_id}":{"get":{"tags":["employees"],"summary":"Get employee","description":"A deactivated employee returns `404`, the same as an unknown id.","operationId":"get_employee_api_v1_employees__employee_id__get","security":[{"NoryApiKey":[]}],"parameters":[{"name":"employee_id","in":"path","required":true,"schema":{"type":"string","title":"Employee Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmployeeResponse"}}}},"401":{"description":"Authentication required or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"API key lacks required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds to wait before retrying","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"502":{"description":"Upstream service error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v1/locations":{"get":{"tags":["locations"],"summary":"List locations","description":"Locations that have been deleted are left out.","operationId":"list_locations_api_v1_locations_get","security":[{"NoryApiKey":[]}],"parameters":[{"name":"cursor","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Cursor"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"default":50,"title":"Limit"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LocationsListResponse"}}}},"401":{"description":"Authentication required or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"API key lacks required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds to wait before retrying","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v1/positions":{"get":{"tags":["positions"],"summary":"List positions","description":"Positions at a location that has been deleted are left out.","operationId":"list_positions_api_v1_positions_get","security":[{"NoryApiKey":[]}],"parameters":[{"name":"cursor","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Cursor"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"default":50,"title":"Limit"}},{"name":"locationId","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Only positions at this location (a /locations id); unknown or deleted locations return 404. Cursors are bound to their filters and your brand: changing filters mid-walk returns 422, so restart pagination.","title":"Locationid"},"description":"Only positions at this location (a /locations id); unknown or deleted locations return 404. Cursors are bound to their filters and your brand: changing filters mid-walk returns 422, so restart pagination."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PositionsListResponse"}}}},"401":{"description":"Authentication required or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"API key lacks required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds to wait before retrying","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v1/departments":{"get":{"tags":["departments"],"summary":"List departments","description":"Departments at a location that has been deleted are left out.","operationId":"list_departments_api_v1_departments_get","security":[{"NoryApiKey":[]}],"parameters":[{"name":"cursor","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Cursor"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"default":50,"title":"Limit"}},{"name":"locationId","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Only departments at this location (a /locations id); unknown or deleted locations return 404. Cursors are bound to their filters and your brand: changing filters mid-walk returns 422, so restart pagination.","title":"Locationid"},"description":"Only departments at this location (a /locations id); unknown or deleted locations return 404. Cursors are bound to their filters and your brand: changing filters mid-walk returns 422, so restart pagination."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DepartmentsListResponse"}}}},"401":{"description":"Authentication required or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"API key lacks required permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds to wait before retrying","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}},"components":{"schemas":{"CountryCode":{"type":"string","enum":["GB","IE","US","MT","AE","ES","BH","KW","OM","QA","SA","NL","FR","DE"],"title":"CountryCode","description":"ISO 3166-1 alpha-2 country codes matching Node-Middleware."},"CreateEmployeeRequest":{"properties":{"firstName":{"type":"string","maxLength":255,"minLength":1,"pattern":".*\\S.*","title":"Firstname"},"lastName":{"type":"string","maxLength":255,"minLength":1,"pattern":".*\\S.*","title":"Lastname"},"preferredName":{"anyOf":[{"type":"string","maxLength":255,"minLength":1,"pattern":".*\\S.*"},{"type":"null"}],"title":"Preferredname","description":"Optional. The name this person goes by. Any non-blank text up to 255 characters."},"email":{"type":"string","format":"email","title":"Email"},"primaryLocationId":{"type":"string","minLength":1,"pattern":".*\\S.*","title":"Primarylocationid","description":"Home location id from GET /locations. A deleted location is rejected."},"primaryPositionId":{"type":"string","minLength":1,"pattern":".*\\S.*","title":"Primarypositionid","description":"Primary job position id from `GET /positions?locationId=` for the home location. Positions belong to one location, so an id from another location is rejected."},"wage":{"anyOf":[{"$ref":"#/components/schemas/CreateEmployeeWage"},{"type":"null"}],"description":"Optional pay. Omit it and defaults apply: amount `0`, type `hourly`. When supplied, both `amount` and `type` are required."},"startDate":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"title":"Startdate","description":"Optional. The date this person's employment starts, as `YYYY-MM-DD`. May be in the future. Omit it and Nory uses the date you create them, so send it whenever you know it."},"dateOfBirth":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"title":"Dateofbirth","description":"Optional. This person's date of birth, as `YYYY-MM-DD`; it can't be in the future. Accepted only when the brand's data agreement with your integration covers creating it; otherwise the request returns `403`. Sending `null` is the same as leaving it out."},"gender":{"anyOf":[{"type":"string","enum":["male","female","declined"]},{"type":"null"}],"title":"Gender","description":"Optional. This person's gender: `male`, `female`, or `declined` when they chose not to say. Accepted only when the brand's data agreement with your integration covers creating it; otherwise the request returns `403`. Sending `null` is the same as leaving it out."},"biologicalSex":{"anyOf":[{"type":"string","enum":["male","female"]},{"type":"null"}],"title":"Biologicalsex","description":"Optional. This person's sex as reported to the tax authority, `male` or `female`. Accepted only when the brand's data agreement with your integration covers creating it; otherwise the request returns `403`. Sending `null` is the same as leaving it out."},"personalPhone":{"anyOf":[{"type":"string","pattern":"^\\+[1-9][0-9]{6,14}$"},{"type":"null"}],"title":"Personalphone","description":"Optional. This person's personal phone number in E.164 format: `+`, the country code and the number, with no spaces, such as `+447700900123`. Accepted for brands in any country. Accepted only when the brand's data agreement with your integration covers creating it; otherwise the request returns `403`. Sending `null` is the same as leaving it out."},"taxId":{"anyOf":[{"type":"string","pattern":"^[A-Za-z0-9 -]+$"},{"type":"null"}],"title":"Taxid","description":"Optional. This person's tax identifier. Accepted only for brands based in the United Kingdom, as a National Insurance number, or the United States, as a Social Security number. For a brand in any other country, Ireland included, sending it returns `422`. A number that isn't valid for the brand's country also returns `422`, including placeholder numbers such as `QQ123456C` or `123-45-6789`. Spaces and hyphens are removed and letters are stored in capitals, so `ab 12 34 56 c` is stored as `AB123456C` and `123-45-6780` as `123456780`. Accepted only when the brand's data agreement with your integration covers creating it; otherwise the request returns `403`. Sending `null` is the same as leaving it out."},"homeAddress":{"anyOf":[{"$ref":"#/components/schemas/CreateHomeAddress"},{"type":"null"}],"description":"Optional. This person's home address. `line1`, `city`, `postalCode` and `country` are required, and `region` too for a brand in the United States, where it must be the state's full name and `postalCode` a ZIP code; otherwise the request returns `422`. Accepted only when the brand's data agreement with your integration covers creating it; otherwise the request returns `403`. Sending `null` is the same as leaving it out."},"bankAccount":{"anyOf":[{"oneOf":[{"$ref":"#/components/schemas/CreateUkLocalBankAccount"},{"$ref":"#/components/schemas/CreateIbanBankAccount"},{"$ref":"#/components/schemas/CreateUsLocalBankAccount"}],"discriminator":{"propertyName":"type","mapping":{"iban":"#/components/schemas/CreateIbanBankAccount","ukLocal":"#/components/schemas/CreateUkLocalBankAccount","usLocal":"#/components/schemas/CreateUsLocalBankAccount"}}},{"type":"null"}],"title":"Bankaccount","description":"Optional. This person's bank account for payroll, as the `type` the brand's country uses: `ukLocal` for a brand in the United Kingdom, `iban` for Ireland and `usLocal` for the United States. A brand in any other country, a `type` that doesn't match the brand's country or a value that fails its check returns `422`. Spaces and hyphens are removed from numbers, and the IBAN and BIC are stored in capitals. For a brand in the United States the details are stored in Nory but not passed on to payroll. Accepted only when the brand's data agreement with your integration covers creating it; otherwise the request returns `403`. Sending `null` is the same as leaving it out."},"contractedHours":{"anyOf":[{"type":"number","maximum":168.0,"exclusiveMinimum":0.0},{"type":"null"}],"title":"Contractedhours","description":"Optional. Contracted hours per week, up to `168`. Decimals are fine, so send `37.5` if that is the contract. Omit it when this person has no contracted hours; `0` is not accepted."},"contractType":{"anyOf":[{"type":"string","enum":["full time","part time","contractor"]},{"type":"null"}],"title":"Contracttype","description":"Optional. This person's contract type: `full time`, `part time` or `contractor`. Omit it and Nory uses `full time`."},"externalReference":{"anyOf":[{"type":"string","maxLength":255,"minLength":1,"pattern":".*\\S.*"},{"type":"null"}],"title":"Externalreference","description":"Optional. Your own identifier for this person in your system, stored by Nory and returned on reads so you do not need your own id mapping table. Nory does not interpret the value — any non-blank string up to 255 characters is accepted. When supplied, it must be unique within your brand: a create that reuses an existing value returns `409` and creates nothing. Omit it and Nory cannot de-dupe on your id — two creates with different emails will both succeed even if they are the same person in your system."}},"additionalProperties":false,"type":"object","required":["firstName","lastName","email","primaryLocationId","primaryPositionId"],"title":"CreateEmployeeRequest","description":"Request body for `POST /employees`."},"CreateEmployeeWage":{"properties":{"amount":{"type":"number","minimum":0.0,"title":"Amount","description":"Pay amount. Must be `0` or greater."},"type":{"type":"string","enum":["hourly","salary","daily"],"title":"Type","description":"Pay type."}},"additionalProperties":false,"type":"object","required":["amount","type"],"title":"CreateEmployeeWage"},"CreateHomeAddress":{"properties":{"line1":{"type":"string","maxLength":255,"minLength":1,"pattern":".*\\S.*","title":"Line1","description":"First line of the address: the building and street."},"line2":{"anyOf":[{"type":"string","maxLength":255},{"type":"null"}],"title":"Line2","description":"Optional. Second line of the address."},"city":{"type":"string","maxLength":255,"minLength":1,"pattern":".*\\S.*","title":"City","description":"Town or city."},"region":{"anyOf":[{"type":"string","maxLength":255},{"type":"null"}],"title":"Region","description":"The county or region. Optional, except for a brand in the United States, where it's required and must be the state's full name, such as `Washington`."},"postalCode":{"type":"string","maxLength":20,"minLength":1,"pattern":"^[A-Za-z0-9 -]*[A-Za-z0-9][A-Za-z0-9 -]*$","title":"Postalcode","description":"Postal code, in letters, digits, spaces and hyphens. For a brand in the United States, a ZIP code such as `98101` or `98101-1234`."},"country":{"$ref":"#/components/schemas/CountryCode","description":"ISO 3166-1 alpha-2 code of the country, one of the countries Nory operates in."}},"additionalProperties":false,"type":"object","required":["line1","city","postalCode","country"],"title":"CreateHomeAddress"},"CreateIbanBankAccount":{"properties":{"type":{"type":"string","const":"iban","title":"Type","description":"`iban`: an IBAN, and optionally the BIC."},"accountHolderName":{"anyOf":[{"type":"string","maxLength":255,"minLength":1,"pattern":".*\\S.*"},{"type":"null"}],"title":"Accountholdername","description":"Optional. The name on the account."},"iban":{"type":"string","maxLength":50,"pattern":"^[A-Za-z0-9 ]+$","title":"Iban","description":"The IBAN."},"bic":{"anyOf":[{"type":"string","maxLength":20,"pattern":"^[A-Za-z0-9 ]+$"},{"type":"null"}],"title":"Bic","description":"Optional. The BIC, 8 or 11 characters."}},"additionalProperties":false,"type":"object","required":["type","iban"],"title":"CreateIbanBankAccount"},"CreateUkLocalBankAccount":{"properties":{"type":{"type":"string","const":"ukLocal","title":"Type","description":"`ukLocal`: a UK account number and sort code."},"accountHolderName":{"anyOf":[{"type":"string","maxLength":255,"minLength":1,"pattern":".*\\S.*"},{"type":"null"}],"title":"Accountholdername","description":"Optional. The name on the account."},"accountNumber":{"type":"string","maxLength":40,"pattern":"^[0-9 -]+$","title":"Accountnumber","description":"The 8-digit account number."},"sortCode":{"type":"string","maxLength":40,"pattern":"^[0-9 -]+$","title":"Sortcode","description":"The 6-digit sort code."}},"additionalProperties":false,"type":"object","required":["type","accountNumber","sortCode"],"title":"CreateUkLocalBankAccount"},"CreateUsLocalBankAccount":{"properties":{"type":{"type":"string","const":"usLocal","title":"Type","description":"`usLocal`: a US account and ABA routing number."},"accountHolderName":{"anyOf":[{"type":"string","maxLength":255,"minLength":1,"pattern":".*\\S.*"},{"type":"null"}],"title":"Accountholdername","description":"Optional. The name on the account."},"accountNumber":{"type":"string","maxLength":40,"pattern":"^[0-9 -]+$","title":"Accountnumber","description":"The account number, 4 to 17 digits."},"routingNumber":{"type":"string","maxLength":40,"pattern":"^[0-9 -]+$","title":"Routingnumber","description":"The 9-digit ABA routing number."},"accountType":{"type":"string","enum":["checking","savings"],"title":"Accounttype","description":"`checking` or `savings`."}},"additionalProperties":false,"type":"object","required":["type","accountNumber","routingNumber","accountType"],"title":"CreateUsLocalBankAccount"},"DepartmentResponse":{"properties":{"id":{"type":"string","title":"Id","description":"Opaque, stable string identifier."},"name":{"type":"string","title":"Name"},"locationId":{"type":"string","title":"Locationid","description":"The `/locations` id of the branch this department belongs to."}},"type":"object","required":["id","name","locationId"],"title":"DepartmentResponse"},"DepartmentsListResponse":{"properties":{"data":{"items":{"$ref":"#/components/schemas/DepartmentResponse"},"type":"array","title":"Data"},"nextCursor":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Nextcursor"}},"type":"object","required":["data"],"title":"DepartmentsListResponse"},"EmployeePosition":{"properties":{"positionId":{"type":"string","title":"Positionid","description":"Opaque, stable string identifier."},"departmentId":{"type":"string","title":"Departmentid","description":"Opaque, stable string identifier."}},"type":"object","required":["positionId","departmentId"],"title":"EmployeePosition"},"EmployeePositionAssignment":{"properties":{"locationId":{"type":"string","title":"Locationid","description":"Opaque, stable string identifier."},"positions":{"items":{"$ref":"#/components/schemas/EmployeePosition"},"type":"array","title":"Positions"}},"type":"object","required":["locationId","positions"],"title":"EmployeePositionAssignment"},"EmployeeResponse":{"properties":{"id":{"type":"string","title":"Id","description":"Opaque, stable string identifier."},"firstName":{"type":"string","title":"Firstname"},"lastName":{"type":"string","title":"Lastname"},"preferredName":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Preferredname","description":"The name this person goes by; `null` when none is set."},"email":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Email"},"externalReference":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Externalreference","description":"Your identifier for this person, when you supplied one; `null` otherwise. Scoped to your integration: other integrations' references are never shown."},"primaryLocationId":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Primarylocationid","description":"The `/locations` id of this person's home location; `null` when none is set, it is not one of your brand's locations, or it has been deleted."},"primaryPositionId":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Primarypositionid","description":"The `/positions` id of this person's primary position at `primaryLocationId`; `null` when there is no primary location or the position isn't found there."},"primaryDepartmentId":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Primarydepartmentid","description":"The `/departments` id of this person's primary department at `primaryLocationId`; `null` when there is no primary location or the department isn't found there."},"reportsToEmployeeId":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Reportstoemployeeid","description":"The `id` of this person's line manager, resolvable via `GET /employees/{id}`; `null` when no manager is set or the manager is no longer an active employee of your brand."},"startDate":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Startdate","description":"The date this person's employment started, as `YYYY-MM-DD`. Can be in the future for someone who has been onboarded but has not started yet. For someone rehired onto their original record this stays their first start date. An employee created without a start date falls back to the date the record was created. A small number of records created before September 2026 carry an unreliable one instead."},"leaveDate":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Leavedate","description":"The person's last working day, as `YYYY-MM-DD`; `null` when no leaving date is set, which is the case for almost everyone. Someone whose last working day is today is still returned today, and shortly after it passes they stop being returned at all, so a person disappearing from the list is how a completed leaver is reported. A date already in the past means their departure is still being processed."},"dateOfBirth":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Dateofbirth","description":"Date of birth, as `YYYY-MM-DD`; `null` when none is recorded. Returned only when the brand's data agreement with your integration covers it, and left out of the response otherwise."},"gender":{"anyOf":[{"type":"string","enum":["male","female","declined"]},{"type":"null"}],"title":"Gender","description":"This person's gender: `male`, `female`, or `declined` when they chose not to say; `null` when none is recorded. Returned only when the brand's data agreement with your integration covers it, and left out of the response otherwise."},"biologicalSex":{"anyOf":[{"type":"string","enum":["male","female"]},{"type":"null"}],"title":"Biologicalsex","description":"The person's sex as reported to the tax authority, `male` or `female`; `null` when none is recorded. Returned only when the brand's data agreement with your integration covers it, and left out of the response otherwise."},"personalPhone":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Personalphone","description":"This person's personal phone number as recorded; `null` when none is recorded. Numbers sent through `POST /employees` are in E.164 format, but numbers entered in Nory may be in a local format. Returned only when the brand's data agreement with your integration covers it, and left out of the response otherwise."},"taxId":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Taxid","description":"This person's tax identifier as recorded, such as a UK National Insurance number, an Irish PPS number or a US Social Security number, or in some countries a national ID number; `null` when none is recorded. Numbers sent through `POST /employees` have spaces and hyphens removed, but numbers entered in Nory may not. Returned for a brand in any country, but only when the brand's data agreement with your integration covers it, and left out of the response otherwise."},"homeAddress":{"anyOf":[{"$ref":"#/components/schemas/HomeAddress"},{"type":"null"}],"description":"This person's home address as recorded; `null` when none is recorded. Returned only when the brand's data agreement with your integration covers it, and left out of the response otherwise."},"bankAccount":{"anyOf":[{"oneOf":[{"$ref":"#/components/schemas/UkLocalBankAccount"},{"$ref":"#/components/schemas/IbanBankAccount"},{"$ref":"#/components/schemas/UsLocalBankAccount"}],"discriminator":{"propertyName":"type","mapping":{"iban":"#/components/schemas/IbanBankAccount","ukLocal":"#/components/schemas/UkLocalBankAccount","usLocal":"#/components/schemas/UsLocalBankAccount"}}},{"type":"null"}],"title":"Bankaccount","description":"This person's bank account as recorded, as the `type` the brand's country uses: `ukLocal` for the United Kingdom, `usLocal` for the United States and `iban` elsewhere; `null` when none is recorded. Details sent through `POST /employees` are checked for the brand's country, but details entered in Nory may not be in the format each field describes. Returned only when the brand's data agreement with your integration covers it, and left out of the response otherwise."},"payrollId":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Payrollid","description":"The brand's payroll identifier for this person; `null` when none is set. Employees created through `POST /employees` are given a generated one."},"contractedHours":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Contractedhours","description":"Contracted hours per week; `null` when none is set."},"contractType":{"anyOf":[{"type":"string","enum":["full time","part time","contractor"]},{"type":"null"}],"title":"Contracttype","description":"This person's contract type: `full time`, `part time` or `contractor`; `null` when none is set."},"wage":{"$ref":"#/components/schemas/EmployeeWage","description":"Pay basis of this person's primary position. The pay amount is not returned."},"locationIds":{"items":{"type":"string"},"type":"array","title":"Locationids","description":"The `/locations` ids of every location this person works at, home location first. Locations outside your brand, and deleted ones, are left out."},"positionAssignments":{"items":{"$ref":"#/components/schemas/EmployeePositionAssignment"},"type":"array","title":"Positionassignments","description":"This person's positions at each of their locations, one entry per `locationIds` entry. A position that isn't found at a location is left out of that entry."}},"type":"object","required":["id","firstName","lastName","wage","locationIds","positionAssignments"],"title":"EmployeeResponse"},"EmployeeWage":{"properties":{"type":{"type":"string","enum":["hourly","salary","daily"],"title":"Type","description":"How this person is paid on their primary position. `hourly` is a rate per hour, `salary` a yearly salary, and `daily` a rate per day."}},"type":"object","required":["type"],"title":"EmployeeWage"},"EmployeesListResponse":{"properties":{"data":{"items":{"$ref":"#/components/schemas/EmployeeResponse"},"type":"array","title":"Data"},"nextCursor":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Nextcursor"}},"type":"object","required":["data"],"title":"EmployeesListResponse"},"ErrorBody":{"properties":{"type":{"type":"string","enum":["invalid_request_error","authentication_error","authorization_error","rate_limit_error","api_error"],"title":"Type"},"code":{"type":"string","title":"Code"},"message":{"type":"string","title":"Message"},"details":{"anyOf":[{"items":{"$ref":"#/components/schemas/ErrorDetail"},"type":"array"},{"type":"null"}],"title":"Details"},"requestId":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Requestid"},"docUrl":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Docurl"}},"type":"object","required":["type","code","message"],"title":"ErrorBody"},"ErrorDetail":{"properties":{"param":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Param"},"code":{"type":"string","title":"Code"},"message":{"type":"string","title":"Message"}},"type":"object","required":["code","message"],"title":"ErrorDetail"},"ErrorResponse":{"properties":{"error":{"$ref":"#/components/schemas/ErrorBody"}},"type":"object","required":["error"],"title":"ErrorResponse"},"HomeAddress":{"properties":{"line1":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Line1","description":"First line of the address; `null` when not recorded."},"line2":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Line2","description":"Second line of the address; `null` when not recorded."},"city":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"City","description":"Town or city; `null` when not recorded."},"region":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Region","description":"The county or region, or for an address in the United States the state's full name; `null` when not recorded."},"postalCode":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Postalcode","description":"Postal code; `null` when not recorded."},"country":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Country","description":"ISO 3166-1 alpha-2 code when Nory knows the country, otherwise the country as recorded; `null` when not recorded."}},"type":"object","title":"HomeAddress"},"IbanBankAccount":{"properties":{"type":{"type":"string","const":"iban","title":"Type","description":"`iban`: an IBAN and BIC."},"accountHolderName":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Accountholdername","description":"The name on the account; `null` when not recorded."},"iban":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Iban","description":"The IBAN; `null` when not recorded."},"bic":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Bic","description":"The BIC; `null` when not recorded."}},"type":"object","required":["type","accountHolderName","iban","bic"],"title":"IbanBankAccount"},"LocationResponse":{"properties":{"id":{"type":"string","title":"Id","description":"Opaque, stable string identifier."},"name":{"type":"string","title":"Name"}},"type":"object","required":["id","name"],"title":"LocationResponse"},"LocationsListResponse":{"properties":{"data":{"items":{"$ref":"#/components/schemas/LocationResponse"},"type":"array","title":"Data"},"nextCursor":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Nextcursor"}},"type":"object","required":["data"],"title":"LocationsListResponse"},"PositionResponse":{"properties":{"id":{"type":"string","title":"Id","description":"Opaque, stable string identifier."},"name":{"type":"string","title":"Name"},"department":{"type":"string","title":"Department"},"departmentId":{"type":"string","title":"Departmentid","description":"The `/departments` id of this position's department at the same location."},"locationId":{"type":"string","title":"Locationid","description":"The `/locations` id of the branch this position belongs to."}},"type":"object","required":["id","name","department","departmentId","locationId"],"title":"PositionResponse"},"PositionsListResponse":{"properties":{"data":{"items":{"$ref":"#/components/schemas/PositionResponse"},"type":"array","title":"Data"},"nextCursor":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Nextcursor"}},"type":"object","required":["data"],"title":"PositionsListResponse"},"UkLocalBankAccount":{"properties":{"type":{"type":"string","const":"ukLocal","title":"Type","description":"`ukLocal`: a UK account number and sort code."},"accountHolderName":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Accountholdername","description":"The name on the account; `null` when not recorded."},"accountNumber":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Accountnumber","description":"The account number; `null` when not recorded."},"sortCode":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Sortcode","description":"The sort code; `null` when not recorded."}},"type":"object","required":["type","accountHolderName","accountNumber","sortCode"],"title":"UkLocalBankAccount"},"UsLocalBankAccount":{"properties":{"type":{"type":"string","const":"usLocal","title":"Type","description":"`usLocal`: a US account and ABA routing number."},"accountHolderName":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Accountholdername","description":"The name on the account; `null` when not recorded."},"accountNumber":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Accountnumber","description":"The account number; `null` when not recorded."},"routingNumber":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Routingnumber","description":"The ABA routing number; `null` when not recorded."},"accountType":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Accounttype","description":"`checking` or `savings`; `null` when not recorded."}},"type":"object","required":["type","accountHolderName","accountNumber","routingNumber","accountType"],"title":"UsLocalBankAccount"}},"securitySchemes":{"NoryApiKey":{"type":"http","description":"Nory API Key","scheme":"bearer"}}},"tags":[{"name":"employees","description":"Employee records in a brand. Each carries stable ID references to join against the `/locations`, `/positions` and `/departments` endpoints, plus `reportsToEmployeeId`, the line manager's own `/employees` id. Deactivated employees are never returned: deactivating an employee removes it from list and single responses."},{"name":"locations","description":"Locations within a brand. Employee records reference these via `locationIds` and `primaryLocationId`. Locations that have been deleted are left out."},{"name":"positions","description":"Job positions within a brand — one row per branch position. Each carries an opaque, stable `id`, a `locationId` (the branch's `/locations` id) and a `departmentId` (a `/departments` id). List ordering is opaque (internal row order), not alphabetical. Employee records reference these via `positionAssignments[].positions[].positionId` and `primaryPositionId`. Positions at a location that has been deleted are left out."},{"name":"departments","description":"Departments within a brand, one row per branch department. Each carries an opaque, stable `id` and a `locationId` (the branch's `/locations` id). List ordering is opaque (internal row order), not alphabetical. Employee records reference these via `primaryDepartmentId` and `positionAssignments[].positions[].departmentId`, and `/positions` rows via `departmentId`. Departments at a location that has been deleted are left out."}]}