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.nowsta-staging.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 HTTP headers (when the token is X8736QRf)

{ "Authorization": "Bearer X8736QRf" }

• 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".

• 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 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.

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

EVENT_PUBLICATION Parameters

SHIFT_PUBLICATION Parameters

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": "JS@Kramerica.biz",
      "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

VENUE_PUBLICATION Parameters

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": "GC@Vandel.ly",
      "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

CLIENT_PUBLICATION Parameters

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

UNIFORM_PUBLICATION Parameters

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

POSITION_PUBLICATION Parameters

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": "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"
    }
  ]
}

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

COMPANY_USER_PUBLICATION Parameters

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

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.

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

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).