openapi: 3.2.0 info: title: Nowsta Integration Workers API version: 1.0.0 description: "The Nowsta Integration API lets an approved partner platform publish event, shift and position data\ninto Nowsta, along with the supporting system inputs — venues, clients, uniforms and workers — that\nenrich that data.\n\nThe API is deliberately narrow: every resource is exposed through a single bulk \"publications\"\nendpoint that accepts an array of objects and performs create-or-update by the caller's own external\n`id`. There are no read (GET), PATCH or DELETE operations in the public integration surface.\n\nSemantics published by Nowsta and preserved here:\n\n* Every publication is a **POST, not a PATCH** — omitted fields are reset to their default (`null`),\n so callers must send the complete object on every update.\n* Every successful publication returns **202 Accepted** with the id of the queued job; Nowsta cannot\n guarantee a request is honoured on receipt (for example it will not remove shifts or shift slots\n that would unassign already-scheduled staff without coordinator confirmation).\n* Batches are limited to **32 items**; larger batches are rejected with 422 / error code 1203.\n* Publication requests for the same company are **queued and processed serially**, so callers are\n advised to issue requests in series rather than in parallel.\n* Access is **allow-listed**: Nowsta must approve a company before its token works, otherwise\n requests return 403 with error code 1101.\n\nDERIVATION NOTE — this document was transcribed by API Evangelist from Nowsta's own published\nIntegration API reference (the Slate-generated site formerly at https://developer.nowsta.com/,\ncaptured at https://web.archive.org/web/20240603053309/https://developer.nowsta.com/). Every path,\nmethod, field name, type, nullability, constraint, status code and error code below appears verbatim\nin that reference. Nowsta does not publish a machine-readable specification; nothing here was\ninvented. The live production API was probed on 2026-08-01 and confirmed to still serve these paths\n(unauthenticated POST returns `401 {\"errors\":[{\"code\":1000,\"message\":\"Nil JSON web token\"}]}`)." contact: name: Nowsta url: https://www.nowsta.com/ x-evidence: generated: '2026-08-01' method: generated source: https://web.archive.org/web/20240603053309/https://developer.nowsta.com/ original_docs_host: https://developer.nowsta.com/ original_docs_status: DNS NXDOMAIN as of 2026-08-01 (developer docs host decommissioned) live_probe: url: https://api.nowsta.com/integrations/v1/events/publications method: POST http_status: 401 body: '{"errors":[{"code":1000,"message":"Nil JSON web token"}]}' fetched: '2026-08-01' servers: - url: https://api.nowsta.com description: Production - url: https://api.nowsta-staging.com description: Staging / demo (access granted by Nowsta on request) security: - bearerAuth: [] tags: - name: Workers description: Bulk publication of company users (workers). paths: /integrations/v1/workers/publications: post: tags: - Workers operationId: publishWorkers summary: Publish workers description: Bulk create or update workers (company users) on Nowsta, matched on the caller's own `id`. Worker records are partly shared across every company a person works for, so update rules are restricted. Freely updatable via this endpoint - `start_date`, `notes`, `rank`, `pronouns`, `tablet_access_code`, `payroll_id`, and `email`/`phone_number` (the latter two only when the worker has not yet set up an account, by resending the same `id` with a different value). Updating `first_name`, `last_name`, `address1`, `address2`, `state`, `city`, `zip`, `birthday`, `emergency_contact_name`, `emergency_contact_phone_number`, `pronouns` or `nickname` desynchronizes the worker record between your company and the shared cross-company record; Nowsta then offers a re-sync, after which those fields can no longer be updated through this endpoint. requestBody: required: true content: application/json: schema: type: object required: - publications properties: publications: type: array maxItems: 32 items: $ref: '#/components/schemas/CompanyUserPublication' example: publications: - id: 1W first_name: John last_name: Smith email: john@nowsta.com start_date: '2022-01-01T12:00:00Z' birthday: '2000-01-01' notes: The notes zip: '25554' nickname: a nickname emergency_contact_phone_number: '2125555555' city: City x rank: '1' pronouns: Her tablet_access_code: 123CODE state: NY phone_number: '2125555559' payroll_id: 123-PAY emergency_contact_name: Johnnys Saver address1: 129 West 81 Street address2: 122 West 84 Street responses: '202': $ref: '#/components/responses/Accepted' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '422': $ref: '#/components/responses/UnprocessableEntity' components: schemas: ErrorObject: type: object description: The ERROR_OBJ used throughout every error response - a numeric `code` plus a human-readable `message`. properties: code: type: integer description: Nowsta error code. See errors/nowsta-problem-types.yml for the published registry. example: 1201 message: type: string example: Parameter cannot be null ErrorsResponse: type: object properties: errors: type: array items: $ref: '#/components/schemas/ErrorObject' CompanyUserPublication: type: object description: COMPANY_USER_PUBLICATION — a worker. required: - id - first_name - last_name - email properties: id: type: string maxLength: 255 first_name: type: string maxLength: 255 last_name: type: string maxLength: 255 email: type: string maxLength: 255 start_date: type: - string - 'null' format: date description: ISO 8601. birthday: type: - string - 'null' format: date description: ISO 8601. notes: type: - string - 'null' zip: type: - string - 'null' maxLength: 5 nickname: type: - string - 'null' emergency_contact_phone_number: type: - string - 'null' description: Valid US phone number. city: type: - string - 'null' maxLength: 255 rank: type: - integer - 'null' pronouns: type: - string - 'null' tablet_access_code: type: - string - 'null' state: type: - string - 'null' maxLength: 255 phone_number: type: - string - 'null' description: Valid US phone number. payroll_id: type: - string - 'null' emergency_contact_name: type: - string - 'null' address1: type: - string - 'null' maxLength: 255 description: Documented as `address_1` in the parameter table and as `address1` in the request example; transcribed here as published in the example payload. address2: type: - string - 'null' maxLength: 255 description: Documented as `address_2` in the parameter table and as `address2` in the request example; transcribed here as published in the example payload. PublicationAccepted: type: object description: The id of the publication request, indicating receipt and insertion into Nowsta's job queue. properties: id: type: integer example: 123 UnprocessableEntityBody: type: object description: Validation failures keyed by the index of the entity in the submitted `publications` array. Each field maps to an array of ERROR_OBJ. Nowsta publishes the shape but not a strict schema, so this is modelled as a free-form object rather than invented. properties: publications: type: object additionalProperties: true additionalProperties: true responses: UnprocessableEntity: description: Some input parameters are invalid or absent, or the batch exceeded the 32-item limit. The body mirrors the request structure - each invalid parameter is mapped to an array of error objects, keyed by the index of the offending entity in the original request (and nested under `shifts` for shift-level problems on the events endpoint). content: application/json: schema: $ref: '#/components/schemas/UnprocessableEntityBody' example: publications: '0': starts_at: - code: 1400 message: Starts at is after ends at shifts: '1': position_id: - code: 1300 message: Specified relation not found Unauthorized: description: The request auth token is missing or invalid (error code 1000). content: application/json: schema: $ref: '#/components/schemas/ErrorsResponse' example: errors: - code: 1000 message: Nil JSON web token Forbidden: description: The provided auth token does not authorize this action — either the company has not been marked active for the integration (code 1101) or the request references objects belonging to another company (code 1100). content: application/json: schema: $ref: '#/components/schemas/ErrorsResponse' example: errors: - code: 1101 message: Access to integration forbidden Accepted: description: Accepted and queued. Nowsta returns 202 because it cannot always guarantee that an update will be honoured on receipt — in particular it will not remove shifts or shift slots that would unassign staff without coordinator confirmation, and colliding venue/client/uniform/position names are altered to preserve uniqueness. The body carries the id of the queued job. content: application/json: schema: $ref: '#/components/schemas/PublicationAccepted' example: id: 123 securitySchemes: bearerAuth: type: http scheme: bearer description: 'A per-company integration token issued by Nowsta and retrieved by the customer from the Nowsta UI, then entered into the integrating platform (for example on a settings page). The token is scoped to the single company that purchased the integration and only authorizes operations for that company. Send it as `Authorization: Bearer `. HTTPS is required; cross-origin browser requests are not permitted. Nowsta must first approve a company for the integration — requests on behalf of an unapproved company return 403 with error code 1101.' externalDocs: description: Nowsta Integration API reference (archived) url: https://web.archive.org/web/20240603053309/https://developer.nowsta.com/