API Reference

Introduction

Welcome to the developer documentation for WorkTaps.

We strive to make our system as flexible as possible and encourage you to reach out. Some reasons you want to contact us directly would be:

Authentication

The Worktaps API uses tokens to authenticate requests. You can view and manage your API tokens in the WorkTaps Dashboard. API tokens are used to authorize a request using one of the two HTTP headers:

You'll most likely use the Bearer token because it allows for cross-origin requests. We use the Basic protocol in the examples below because the syntax is simpler when making a curl request.

Error Handling

WorkTaps uses conventional HTTP response codes to indicate the success or failure of an API request. A successful response will result in a 200. An unsuccessful response will result in a 4xx.

Along with a 4xx error code, an errors object will be returned which contains an array of one or more human-readable problems which occurred and a optional error code specific to the endpoint being requested.

{
    "code": 4xxxx,
    "message": "A human description of the error."
}
Error Code Lookup

These are application specific error codes.

40000Unauthorized request
40001Location id [id] not found
40002Department id [id] not found
40003Account id [id] not found
40004First Name is required
40005Last Name is required
40006Email is required
40007Phone is required
40008Locations is required
40009Department is required
40010Role is required
40011Timezone is required
40012Term date is required
40013Meta fields are required
40014Meta field Job Title is required
40015Meta field Start Date is required
40017Email is invalid
40018Phone is invalid
40019Locations must be an array with at least one location
40020Role must EMPLOYEE, MANAGER, OWNER
40021Start Date is invalid
40022Start Date cannot be in the future
40023Timezone is invalid
40025State is invalid
40026Postal is invalid
40027Term Date is invalid
40028Term Date cannot be in the future
40029Email already exists
40030Phone already exists
40031Forbiden role - account is a manager on currently opened jobs: [Jobs]
50001Error while creating account
50002Error while deleting account
50003Error while updating account

Entity Types

Below are all of the various (JSON) object types which are returned by the WorkTaps API.

Account Type

Fields are contextualized to the organization the user belongs to.

idnumber

Unique ID for an account

createdDate

Date account was created. Note, this is the date that the user was added to WorkTaps initially, and not the hire date.

startDateDate

Organization hire date for account

firstNamestring

First name for an account

lastNamestring

Last name for an account

emailstring

Email address for an account

phonestring

Phone number in E.164 format

citystring

E.g. "San Francisco"

statestring

Always the two letter acronym. E.g. "CA"

streetstring

E.g. "615 Cleveland St."

postalstring

E.g. "90210"

timezonestring

E.g. "America/New_York" Format examples here

rolestring

Options are "EMPLOYEE", "MANAGER", or "OWNER"

jobTitlestring

A member's job within the organization

departmentDepartment

Department account belongs to (one-to-one)

locationsLocation[]

Locations account belongs to (one-to-many)

metaMeta

Meta fields for account

Department Type

idstring

Unique ID for department

namestring

Name of department

slugstring

A unique and URL-friendly version of the name

Location Type

idstring

Unique ID for location

namestring

Name of location

slugstring

A unique and URL-friendly version of the name

Meta Type

anyany

Fields added as a meta field will be displayed in this object. There cannot be duplicate names for meta fields.

Accounts

Create an account

POST /api/v1/account

curl -X POST \
  https://worktaps.com/api/v1/account \
  -u your-api-key: \
  -d firstName="John" \
  -d lastName="Doe"
Post Input
firstNamestringrequired

First name for an account

lastNamestringrequired

Last name for an account

emailstringoptional

Email address for an account. If a phone number is not provided, this field is required

phonestringoptional

Phone number in E.164 format. If a email is not provided, this field is required

citystringoptional

E.g. "San Francisco"

statestringoptional

Must be two letter acronym. E.g. "CA"

postalstringoptional

E.g. "90210"

timezonestringrequired

E.g. "America/New_York" Format examples here

rolestringrequired

Options are "EMPLOYEE", "MANAGER", or "OWNER"

metaMetaInputrequired

The meta field is required primarily to specify jobTitle and startDate for employee.

departmentDepartmentrequired

Department account belongs to (one-to-one)

locationsLocation[]required

Locations account belongs to (one-to-many). At least one is required.

MetaInput type

Values for all MetaInput strings are limited to 100 characters.

jobTitlestringrequired

A member's job within the organization

startDatestringrequired

Hired date for employee

anystringoptional

This may be any user defined property

Response

Full account object returned.

Get an account

GET /api/v1/account/:id

curl https://worktaps.com/api/v1/account/:id \
  -u your-api-key:
URL Arguments
:idstringrequired

ID for account.

Response

A full Account object will be returned if successful.

Update an account

PUT /api/v1/account/:id

curl -X PUT \
  https://worktaps.com/api/v1/account/:id \
  -u your-api-key: \
  -d firstName="John" \
  -d lastName="Doe"
URL Arguments
:idstringrequired

ID for account.

Post Input
firstNamestringoptional

First name for an account

lastNamestringoptional

Last name for an account

emailstringoptional

Email address for an account

phonestringoptional

Phone number in E.164 format

citystringoptional

E.g. "San Francisco"

statestringoptional

Must be two letter acronym. E.g. "CA"

postalstringoptional

E.g. "90210"

timezonestringoptional

E.g. "America/New_York" Format examples here

rolestringoptional

Options are "EMPLOYEE", "MANAGER", or "OWNER"

metaMetaInputoptional

The meta field is required primarily to specify jobTitle and startDate for employee.

departmentDepartmentoptional

Department account belongs to (one-to-one)

locationsLocation[]optional

Locations account belongs to (one-to-many). At least one is required.

MetaInput type

Values for all MetaInput strings are limited to 100 characters.

jobTitlestringoptional

A member's job within the organization

startDatestringoptional

Hired date for employee

anystringoptional

This may be any user defined property. This could be useful for storing custom ID's when doing reconciliation with other systems.

Response

An account object will be returned if successful.

Delete an account

DELETE /api/v1/account/:id

curl -X DELETE \
  https://worktaps.com/api/v1/account/:id \
  -d termDate="01/20/2010"
  -u your-api-key:
URL Arguments
:idstringrequired

ID for account.

Post Input
termDatestringrequired

The date the employee was termed

Response
removedboolean

Will always been true when when removed. Otherwise, an error will be returned.

List accounts

GET /api/v1/accounts

curl https://worktaps.com/api/v1/accounts?meta="{\"jobTitle\": \"Dish Washer\"} \
  -u your-api-key:
Query String Arguments
limitnumberoptional

The minimum is 1 and the maximum is 1000

pagestringoptional

Page number for request. This is calculated based on the limit

locationnumberoptional

ID for a location to filter by.

emailstringoptional

Search for an exact email match.

phonestringoptional

Search for an exact phone match. The string will be sanitized, so "(202)234-5678", "2022345678", "12022345678" and "+12022345678" are considered the same.

metastringoptional

Search for any meta fields. You may search for custom meta fields as well. The value must be in stringified json. For example:

Response
totalnumber

The total amount of records

recordsAccount[]

A collection of accounts

Departments

List departments

GET /api/v1/departments

curl https://worktaps.com/api/v1/departments \
  -u your-api-key:
Query String Arguments
limitnumberoptional

The minimum is 1 and the maximum is 1000

pagestringoptional

Page number for request. This is calculated based on the limit

Response
totalnumber

The total amount of records

recordsDepartment[]

A collection of departments

Locations

List locations

GET /api/v1/locations

curl https://worktaps.com/api/v1/locations \
  -u your-api-key:
Query String Arguments
limitnumberoptional

The minimum is 1 and the maximum is 1000

pagestringoptional

Page number for request. This is calculated based on the limit

Response
totalnumber

The total amount of records

recordsLocation[]

A collection of locations