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:

You'd like help discussing your strategy for integration
You're hitting limitations with the API
You have any other questions or feedback

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:

Authorization: Bearer your-api-token
Authorization: Basic your-api-token: (note the colon on the end)

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

50004Error while updating location

50005Error while updating location

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"
birthDatestring	E.g. "YYYY-MM-DD"
employeeIdstring	E.g. "73546"
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

firstNamestring	required	First name for an account
lastNamestring	required	Last name for an account
emailstring	optional	Email address for an account. If a phone number is not provided, this field is required
phonestring	optional	Phone number in E.164 format. If a email is not provided, this field is required
citystring	optional	E.g. "San Francisco"
statestring	optional	Must be two letter acronym. E.g. "CA"
postalstring	optional	E.g. "90210"
birthDatestring	optional	E.g. "YYYY-MM-DD"
employeeIdstring	optional	E.g. "73546"
timezonestring	required	E.g. "America/New_York" Format examples here
rolestring	required	Options are "EMPLOYEE", "MANAGER", or "OWNER"
metaMetaInput	required	The meta field is required primarily to specify jobTitle and startDate for employee.
departmentDepartment	required	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.

jobTitlestring	required	A member's job within the organization
startDatestring	required	Hired date for employee
anystring	optional	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

:idstring

required

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

:idstring

required

ID for account.

Post Input

firstNamestring	optional	First name for an account
lastNamestring	optional	Last name for an account
emailstring	optional	Email address for an account
phonestring	optional	Phone number in E.164 format
citystring	optional	E.g. "San Francisco"
statestring	optional	Must be two letter acronym. E.g. "CA"
postalstring	optional	E.g. "90210"
birthDatestring	optional	E.g. "YYYY-MM-DD"
employeeIdstring	optional	E.g. "73546"
timezonestring	optional	E.g. "America/New_York" Format examples here
rolestring	optional	Options are "EMPLOYEE", "MANAGER", or "OWNER"
metaMetaInput	optional	The meta field is required primarily to specify jobTitle and startDate for employee.
departmentDepartment	optional	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.

jobTitlestring	optional	A member's job within the organization
startDatestring	optional	Hired date for employee
anystring	optional	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

:idstring

required

ID for account.

Post Input

termDatestring

required

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

limitnumber	optional	The minimum is 1 and the maximum is 1000
pagestring	optional	Page number for request. This is calculated based on the limit
locationnumber	optional	ID for a location to filter by.
emailstring	optional	Search for an exact email match.
phonestring	optional	Search for an exact phone match. The string will be sanitized, so "(202)234-5678", "2022345678", "12022345678" and "+12022345678" are considered the same.
metastring	optional	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

limitnumber	optional	The minimum is 1 and the maximum is 1000
pagestring	optional	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

limitnumber	optional	The minimum is 1 and the maximum is 1000
pagestring	optional	Page number for request. This is calculated based on the limit

Response

totalnumber	The total amount of records
recordsLocation[]	A collection of locations

Create location

POST /api/v1/locations

curl -X POST \ 
  https://worktaps.com/api/v1/locations \
  -u your-api-key:

Post Input

namestring	required	Name of location
websitestring	optional	Website of location
phonestring	optional	Phone number in E.164 format.
streetstring	optional	Street of location
citystring	optional	E.g. "San Francisco"
postalstring	optional	E.g. "90210"
statestring	optional	Must be two letter acronym. E.g. "CA"
aboutstring	optional	Description of the location
areacodestring	optional	Areacode of the location
timezonestring	optional	E.g. "America/New_York" Format examples here

Response

Full locations object returned.

Update location

PUT /api/v1/locations/id

curl -X PUT \ 
  https://worktaps.com/api/v1/locations/:id \
  -u your-api-key:

URL Arguments

:idstring

required

ID for location.

Post Input

namestring	optional	Name of location
websitestring	optional	Website of location
phonestring	optional	Phone number in E.164 format.
streetstring	optional	Street of location
citystring	optional	E.g. "San Francisco"
postalstring	optional	E.g. "90210"
statestring	optional	Must be two letter acronym. E.g. "CA"
aboutstring	optional	Description of the location
areacodestring	optional	Areacode of the location
timezonestring	optional	E.g. "America/New_York" Format examples here

Response

Full locations object returned.