---

Introduction

Thanks for visiting the Nowsta integration API documentation! Please contact us directly if you would like to integrate with our platform so that we can discuss the use case and make sure that your fields match the Nowsta fields that our users expect them to.

This API reference guide will help you build an application that is able to send event, shift, and position data to Nowsta, in addition to system inputs like persisted venues, clients, uniforms, that enrich that data.

If you have any questions about how to use this API, please don't hesitate to reach out for help.

Getting started

• The base production URL to make requests to is https://api.nowsta.com/. For staging server, it's https://api.staging.nowsta.com. We highly recommend that you start by contacting us and making sure that the integration works in a staging environment before using the production URL and keys.

• HTTPS is required. You may receive unexpected results using HTTP.

• Do not try making requests to the API from a web browser - cross-origin requests are not allowed.

• All endpoints expect to receive JSON and will return JSON. Please set your request headers accordingly.

Authentication

Example cURL command with appropriate headers (when the token is X8736QRf)

curl -X POST \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer X8736QRf' \
  -D '{ ... your payload ... }'

• Each auth token is associated with a particular company that purchases the integration, and can only be used for operations related to that company.

• To develop and test your integration, contact us and we will give you access to a demo account on our staging server.

• Nowsta provides in its UI a way for companies to obtain the authentication token valid for their account. This token should be entered somewhere on the integrating platform, such as a settings page.

• Whenever making requests on behalf of companies, the token provided to them should be provided in the Authorization HTTP request header, prepended by "Bearer". A Content-Type header should also be sent specifying that the server should expect application/json.

• Nowsta must first approve companies that request access to the integration. Any requests on behalf of unapproved companies will result in 403 responses with 1101 error codes.

Limits

All of our publication endpoints are currently limited to 32 items at a time. A response code of 422 will be returned for requests that exceed this batch size. Please split up your requests if you have more than 32 items to send.

Concurrent Requests

In order to prevent conflicts, until a publication request completes, all other publication requests for the same company will be queued, but the request will return immediately. The requests will be processed in the order that we received them, so we would highly encourage making requests to our API in serial instead of parallel to make sure that updates occur in the right order.

Errors

{
  "code": 1201,
  "message": "Parameter cannot be null"
}

Error objects (ERROR_OBJ) are used throughout all error responses. They consist of a code and human-readable message.

See the JSON to the right for an example.

Error codes

Error Code	Meaning
1000	Auth missing or invalid
1100	Access to referenced resource forbidden
1101	Access to integration forbidden*
1200	Parameter missing
1201	Parameter cannot be null
1202	Invalid param type
1203	Parameter size exceeds batch size limit
1204	Parameter is mutually exclusive with other parameters
1300	Specified relation not found [uniform, venue, client, position]
1400	Starts at is after ends at
1500	Object nesting is ambiguous*

*Error code 1101 indicates that the company has not been marked as active with your integration. If you are experiencing this error, please contact us and we will mark the account as active.

*Error code 1500 currently only occurs when a shift is nested within a different event than the one it was originally published with.

Additional codes may be added in the future.

401 Unauthorized

{
  "errors": [ERROR_OBJ]
}

The request auth token is missing or invalid.

The error response body will contain an array of ERROR_OBJ.

403 Forbidden

{
  "errors": [ERROR_OBJ]
}

The provided auth token does not authorize this action.

The error response body will contain an array of ERROR_OBJ.

422 Unprocessable Entity

422's differ depending on the endpoint, but will usually map invalid request input parameters to an array of ERROR_OBJ.

–––––––––

Events

Nowsta provides a single endpoint through which events and their shifts are "published" to Nowsta, allowing bulk event update and creation.

Publications

Example request

{
  "publications": [
    {
      "id": "125A",
      "name": "My Example Event",
      "starts_at": "2015-11-04T09:20:22Z",
      "ends_at": "2015-11-05T09:20:22Z",
      "worker_instructions": "Show up on time wearing nice clothing.",
      "time_zone": "America/Los_Angeles",
      "admin_notes": "Run payroll carefully for this event.",
      "supervisor_notes": "Be sure to gather time and attendance data",
      "budget_cents": 45000,
      "venue_id": "122B",
      "uniform_id": "165X",
      "client_id": "87RU",
      "invoice_cents": 65000,
      "salesperson": "John Smith",
      "archived_at": null,
      "display_id": "E12345",
      "shifts": [
        {
          "id": "15Q",
          "starts_at": "2015-11-04T09:20:22Z",
          "ends_at": "2015-11-05T09:20:22Z",
          "quantity": 8,
          "position_id": "189F",
          "instructions": "Bring your own bartending utensils."
        }
      ]
    }
  ]
}

In order to send event and shift data, you will only need to issue POST requests to this single endpoint, denoted publications. The endpoint is designed to accept bulk event updates and/or creations, and updates/creation/deletion of their corresponding shifts via a single call.

HTTP Request

POST /integrations/v1/events/publications

Query Parameters

Parameter	Type	Nullable	Constraints
publications	Array	N	Elements must be EVENT_PUBLICATION objects

EVENT_PUBLICATION Parameters

Parameter	Type	Nullable	Constraints
id	String	N	255 char limit
name	String	N	255 char limit
starts_at	DateTime (ISO8601)	N	Must be less than or equal to ends_at
ends_at	DateTime (ISO8601)	N
time_zone	String (TZ)	N	Canonical entry in tz database (e.g. "America/New_York", not UTC offset)
shifts	Array	N	Elements must be SHIFT_PUBLICATION objects
venue_id *	String	Y	Must have a registered mapping with Nowsta
uniform_id	String	Y	Must have a registered mapping with Nowsta
client_id	String	Y	Must have a registered mapping with Nowsta
division *	String	Y
booking_status	String	Y
archived_at	DateTime (ISO8601)	Y
display_id	String	Y
admin_notes	String	Y
worker_instructions	String	Y
supervisor_notes	String	Y
salesperson	String	Y	255 char limit
budget_cents	Integer	Y	Must be non-negative
invoice_cents	Integer	Y	Must be non-negative
number_of_guests	Integer	Y
venue_name *	String	Y
address1 *	String	Y
address2 *	String	Y
city *	String	Y
state *	String	Y
zip *	String	Y

* The division field is a plain string, but maps to an object in Nowsta. If a division with the same name already exists in Nowsta, it will use that one. Otherwise, the publication request will create a new division with the given name. Divisions in Nowsta are meant to be an umbrella category for events, staff, etc. They are typically reserved for enterprise customers with multiple, regional operations. Please consult with us before using this field. * Event-level venue fields (venue_name, address1, address2, etc) are mutually exclusive with providing a venue_id (mapped object). Providing both a venue_id and any of the event-level venue fields will result in a 422 error (code 1204).

SHIFT_PUBLICATION Parameters

Parameter	Type	Nullable	Constraints
id	String	N	255 char limit
starts_at	DateTime (ISO8601)	N	Must be less than or equal to ends_at
ends_at	DateTime (ISO8601)	N
quantity	Integer	N	Must be in the range [0, 1024]
position_id	String	N	Must have a registered mapping with Nowsta
instructions	String	Y

Remember that the action is a POST, not a PATCH, so it is not possible to only update a subset of data fields.

If parameters are omitted from the payload (e.g. equivalent fields do not exist on your platform), default values will be used, which for the moment are all null.

Consider, for example, that an event is created with a client, and is then updated with the client field omitted from the request. The null default value means that the client will be cleared from the event in Nowsta during this update. Note that this endpoint expects the number of shifts per event not to exceed around 20-30 shift objects, or else it can become slow, especially if many of these events are sent in batch. The presence of the archived_at key indicates to Nowsta that the event has been cancelled or otherwise removed and should not appear in the UI.

Success response

Status 202

{ "id": 123 }

All successful responses will return with a 202 Accepted status.

Note that a 202 is returned because we cannot always guarantee that every update request will be honored on receipt, if at all. In particular, without confirmation from a coordinator within Nowsta, we will not remove shifts or shift slots that unassign staff. (For example decreasing shift quantity below the number assigned, or archiving an event that has staff assigned or that has shifts that are published.)

If a request also includes other event or shift metadata changes, those other changes will not be affected by the restriction on shifts and may still be applied.

The body of the success response returns the ID of this particular request, which indicates its receipt and insertion into our job queue.

Error responses

Status 422

In this example, the first event and that event's second shift (in the orders given by the request) both had some invalid properties.

{
  "publications": {
    "0": {
      "event_prop1": [ERROR_OBJ,],
      "event_prop2": [ERROR_OBJ,],
      ...
      "shifts": {
        "1": {
          "shift_prop1": [ERROR_OBJ,],
          "shift_prop2": [ERROR_OBJ,],
          ...
        }
      }
    }
  }
}

403: The request attempts to update or reference one or more objects which do not belong to the company associated with the provided auth token.

422: Some input parameters are invalid or not present. The response has a similar structure to the request. Each invalid parameter will be mapped to an array of ERROR_OBJ’s, keyed under the index of the invalid entity (corresponding to the indices in the original request).

Venues

Publications

Example request

{
  "publications": [
    {
      "id": "125A",
      "name": "Jerry's Apartment",
      "address1": "129 West 81 Street",
      "address2": "5A",
      "city": "New York",
      "state": "NY",
      "zip": "10024",
      "contact_phone_number": "2015556893",
      "contact_email": "[email protected]",
      "contact_full_name": "Jerome Allen Seinfeld"
    }
  ]
}

In order to create or update venues on Nowsta, the API client must issue a

POST request to this endpoint.

HTTP Request

POST /integrations/v1/venues/publications

Query Parameters

Parameter	Type	Nullable	Constraints
publications	Array	N	Elements must be VENUE_PUBLICATION objects

VENUE_PUBLICATION Parameters

Parameter	Type	Nullable	Constraints
id	String	N	255 char limit
name	String	N	255 char limit
address1	String	Y	255 char limit
address2	String	Y	255 char limit
city	String	Y	255 char limit
state	String	Y	2 chars preferred (e.g. "NY")
zip	String	Y	255 char limit
notes	String	Y
contact_phone_number	String	Y	255 char limit
contact_email	String	Y	255 char limit
contact_full_name	String	Y	255 char limit

Remember that the action is a POST, not a PATCH, so it is not possible to only update a subset of data fields.

If parameters are omitted from the payload (e.g. equivalent fields do not exist on your platform), default values will be used, which for the moment are all null.

Success response

Status 202

{ "id": 123 }

All successful responses will return with a 202 Accepted status.

Note that a 202 is returned because we cannot always guarantee that every creation or update request will be honored on receipt, if at all. In particular, if a venue name already exists in the system, then the new venue name (whether it's from an update or creation request) will be altered to maintain Nowsta's uniqueness constraint on venue name.

The body of the success response returns the ID of this particular request, which indicates its receipt and insertion into our job queue.

Error responses

Status 422

In this example, the second venue (in the order given by the request) had some invalid properties

{
  "publications": {
    "1": {
      "venue_prop1": [ERROR_OBJ,],
      ...
    },
    ...
  }
}

403: The request attempts to update or reference one or more objects which do not belong to the company associated with the provided auth token.

422: Some input parameters are invalid or not present. The response has a similar structure to the request. Each invalid parameter will be mapped to an array of ERROR_OBJ’s, keyed under the index of the invalid entity (corresponding to the indices in the original request).

Clients

Publications

Example request

{
  "publications": [
    {
      "id": "125A",
      "name": "Vandelay Industries",
      "admin_notes": "Great architecture firm",
      "supervisor_notes": "Ask about the LaTex and LaTeX-related products.",
      "company_user_notes": "Notes workers see",
      "contact_phone_number": "2015556893",
      "contact_email": "[email protected]",
      "contact_full_name": "Arthur Vandelay"
    }
  ]
}

In order to create or update clients on Nowsta, the API client must issue a

POST request to this endpoint.

HTTP Request

POST /integrations/v1/clients/publications

Query Parameters

Parameter	Type	Nullable	Constraints
publications	Array	N	Elements must be CLIENT_PUBLICATION objects

CLIENT_PUBLICATION Parameters

Parameter	Type	Nullable	Constraints
id	String	N	255 char limit
name	String	N
admin_notes	String	Y
supervisor_notes	String	Y
company_user_notes	String	Y
contact_phone_number	String	Y	255 char limit
contact_email	String	Y	255 char limit
contact_full_name	String	Y	255 char limit

Remember that the action is a POST, not a PATCH, so it is not possible to only update a subset of data fields.

If parameters are omitted from the payload (e.g. equivalent fields do not exist on your platform), default values will be used, which for the moment are all null.

Success response

Status 202

{ "id": 123 }

All successful responses will return with a 202 Accepted status.

Note that a 202 is returned because we cannot always guarantee that every creation or update request will be honored on receipt, if at all. In particular, if a client name already exists in the system, then the new client name (whether it's from an update or creation request) will be altered to maintain Nowsta's uniqueness constraint on client name.

The body of the success response returns the ID of this particular request, which indicates its receipt and insertion into our job queue.

Error responses

Status 422

In this example, the second client (in the order given by the request) had some invalid properties

{
  "publications": {
    "1": {
      "client_prop1": [ERROR_OBJ,],
      ...
    },
    ...
  }
}

403: The request attempts to update or reference one or more objects which do not belong to the company associated with the provided auth token.

422: Some input parameters are invalid or not present. The response has a similar structure to the request. Each invalid parameter will be mapped to an array of ERROR_OBJ’s, keyed under the index of the invalid entity (corresponding to the indices in the original request).

Uniforms

Publications

Example request

{
  "publications": [
    {
      "id": "125A",
      "name": "The puffy shirt",
      "description": "Wear if you wanna be a pirate."
    }
  ]
}

In order to create or update uniforms on Nowsta, the API client must issue a

POST request to this endpoint.

HTTP Request

POST /integrations/v1/uniforms/publications

Query Parameters

Parameter	Type	Nullable	Constraints
publications	Array	N	Elements must be UNIFORM_PUBLICATION objects

UNIFORM_PUBLICATION Parameters

Parameter	Type	Nullable	Constraints
id	String	N	255 char limit
name	String	N	255 char limit
description	String	Y

Remember that the action is a POST, not a PATCH, so it is not possible to only update a subset of data fields.

If parameters are omitted from the payload (e.g. equivalent fields do not exist on your platform), default values will be used, which for the moment are all null.

Success response

Status 202

{ "id": 123 }

All successful responses will return with a 202 Accepted status.

Note that a 202 is returned because we cannot always guarantee that every creation or update request will be honored on receipt, if at all. In particular, if a uniform name already exists in the system, then the new uniform name (whether it's from an update or creation request) will be altered to maintain Nowsta's uniqueness constraint on uniform name.

The body of the success response returns the ID of this particular request, which indicates its receipt and insertion into our job queue.

Error responses

Status 422

In this example, the second uniform (in the order given by the request) had some invalid properties

{
  "publications": {
    "1": {
      "uniform_prop1": [ERROR_OBJ,],
      ...
    },
    ...
  }
}

403: The request attempts to update or reference one or more objects which do not belong to the company associated with the provided auth token.

422: Some input parameters are invalid or not present. The response has a similar structure to the request. Each invalid parameter will be mapped to an array of ERROR_OBJ’s, keyed under the index of the invalid entity (corresponding to the indices in the original request).

Positions

Publications

Example request

{
  "publications": [
    {
      "id": "125A",
      "name": "Comedian",
      "default_rate_cents": 3500,
      "instructions": "Make lots of jokes.",
      "description": "The most important position.",
      "supervisor": false,
      "pay_code": "456-123"
    }
  ]
}

In order to create or update positions on Nowsta, the API client must issue a

POST request to this endpoint.

HTTP Request

POST /integrations/v1/positions/publications

Query Parameters

Parameter	Type	Nullable	Constraints
publications	Array	N	Elements must be POSITION_PUBLICATION objects

POSITION_PUBLICATION Parameters

Parameter	Type	Nullable	Constraints
id	String	N	255 char limit
name	String	N	255 char limit
default_rate_cents	Integer	Y	Must be positive.
client_bill_rate_cents	Integer	Y	Must be positive.
instructions	String	Y
description	String	Y
supervisor	Boolean	N
pay_code	String	Y	255 char limit

Remember that the action is a POST, not a PATCH, so it is not possible to only update a subset of data fields.

If parameters are omitted from the payload (e.g. equivalent fields do not exist on your platform), default values will be used, which for the moment are all null.

Success response

Status 202

{ "id": 123 }

All successful responses will return with a 202 Accepted status.

Note that a 202 is returned because we cannot always guarantee that every creation or update request will be honored on receipt, if at all. In particular, if a position name already exists in the system, then the new position name (whether it's from an update or creation request) will be altered to maintain Nowsta's uniqueness constraint on position name.

The body of the success response returns the ID of this particular request, which indicates its receipt and insertion into our job queue.

Error responses

Status 422

In this example, the second position (in the order given by the request) had some invalid properties

{
  "publications": {
    "1": {
      "position_prop1": [ERROR_OBJ,],
      ...
    },
    ...
  }
}

403: The request attempts to update or reference one or more objects which do not belong to the company associated with the provided auth token.

422: Some input parameters are invalid or not present. The response has a similar structure to the request. Each invalid parameter will be mapped to an array of ERROR_OBJ’s, keyed under the index of the invalid entity (corresponding to the indices in the original request).

Workers

Publications

Example request

{
  "publications": [
    {
      "id": "1W",
      "first_name": "John",
      "last_name": "Smith",
      "email": "[email protected]",
      "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"
    }
  ]
}

In order to create or update workers on Nowsta, the API client must issue a

POST request to this endpoint.

HTTP Request

POST /integrations/v1/workers/publications

Query Parameters

Parameter	Type	Nullable	Constraints
publications	Array	N	Elements must be COMPANY_USER_PUBLICATION objects

COMPANY_USER_PUBLICATION Parameters

Parameter	Type	Nullable	Constraints
id	String	N	255 char limit
first_name	String	N	255 char limit
last_name	String	N	255 char limit
email	String	N	255 char limit
start_date	Date (ISO8601)	Y
birthday	Date (ISO8601)	Y
notes	String	Y
zip	String	Y	5 char limit
nickname	String	Y
emergency_contact_phone_number	String	Y	Valid US Phone
city	String	Y	255 char limit
rank	Integer	Y
pronouns	String	Y
tablet_access_code	String	Y
state	String	Y	255 chat limit
phone_number	String	Y	Valid Us Phone
payroll_id	String	Y
emergency_contact_name	String	Y
address_1	String	Y	255 char limit
address_2	String	Y	255 char limit

Remember that the action is a POST, not a PATCH, so it is not possible to only update a subset of data fields.

If parameters are omitted from the payload (e.g. equivalent fields do not exist on your platform), default values will be used, which for the moment are all null.

Updating Workers

Some worker information is shared between many companies, so there exists some restrictions when it comes to worker updating.

These parameters are allowed to be updated

COMPANY_USER_PUBLICATION Parameters

Parameter
email(*)
phone_number(*)
start_date
notes
rank
pronouns
tablet_access_code
payroll_id

Email and phone_number will only be updated by sending a request to the endpoint with a different email or phone_number and the the same ID of a previous one. The email or phone_number update will be allowed if the user hasn't set up an account yet

Email and tablet_access_code should be unique for each new worker on the company, the system scopes this fields per company

You'll not get a creation of a new worker even if you receive a 200 as a response code, when one of the fields mentioned above are not unique in the company

Some worker information updating will generate a desynchronization between the particular worker information in your company and the worker information that is shared between all other workers company.

COMPANY_USER_PUBLICATION Parameters

Parameter
first_name
last_name
address1
address2
state
city
zip
birthday
emergency_contact_name
emergency_contact_phone_number
pronouns
nickname

If you decide to update any of these fields the system will give you the chance of re-sync the worker data.

If you decide to go on with the re-sync, then you won't be able to update again any of the above parameters using this endpoint.

Success response

Status 202

{ "id": 123 }

All successful responses will return with a 202 Accepted status.

Note that a 202 is returned because we cannot always guarantee that every creation or update request will be honored on receipt, if at all. In particular, if a user and company user already exists in the system, then the worker data (whether it's from an update or creation request) will be saved as the new data for the worker.

The body of the success response returns the ID of this particular request, which indicates its receipt and insertion into our job queue.

Error responses

Status 422

In this example, the third position (in the order given by the request) had some invalid properties

{
  "publications": {
    "2": {
      "worker_prop1": [ERROR_OBJ,],
      ...
    },
    ...
  }
}

403: The request attempts to update or reference one or more objects which do not belong to the company associated with the provided auth token.

422: Some input parameters are invalid or not present. The response has a similar structure to the request. Each invalid parameter will be mapped to an array of ERROR_OBJ’s, keyed under the index of the invalid entity (corresponding to the indices in the original request).