NOTE: This is an overview document to provide general information regarding the Workamajig API.
For full documentation and sample code, please access the API guide provided from within the Workamajig UI via Menu > Admin/Manager > System Setup > Account Information > Connections > API > API Internal Documentation Link.
The Workamajig API was developed around REST. The API is designed to have resource-oriented URLs and to use HTTP response codes to indicate API errors. We use built-in HTTP features, like HTTP authentication and HTTP verbs, which can be understood by off-the-shelf HTTP clients. Currently, the Workamajig API only supports GET, POST, PUT and DELETE.
We support cross-origin resource sharing to allow you to interact securely from a client-side web application.
JSON will be returned from all responses from the API, including errors.
NOTE: Please contact firstname.lastname@example.org if you need further assistance.
Requirements / Support
Currently, the Workamajig API will only run on IIS 7 or higher.
Why don't why we support IIS 6?
IIS 6 is not supported because the POST verb cannot be configured to interact with Adobe's AMF needed to interact with the flash.
Workamajig Minimum Version: 10.5.8.7
Full documentation, along with sample code, is available within Workamajig: Menu>Admin/Manager>System Setup>Account Information: Connections>API
REST Vs Others
- transport is browser neutral
- AJAX friendly
- URL's a definitive and can be expansive
- return structure is any format
- Adheres to an industry standard
- XML is the protocol
- Will only support GET or POST
- Only allows for one URL
- return structure is any format
Stateful vs Stateless
- APIs should be stateless because a GET on a given URL should always return the same result.
The API endpoint is your server URL slash API followed by the version and lastly by the module you wish to connect to. See the versioning and modules sections for more information.
Versioning is controlled using the 3rd position in the URL. The current version of the API is beta1. You'll be notified a few months in advance before any versions are deprecated.
NB: current version: beta1
Modules vary by what you're trying to do. See the list below for valid modules.
|Module||Status||Rate Limit (calls per minute)|
|diary (GET only)||active||50|
|reports(GET only)||active||See Report Doc|
|team (GET only)||active||50|
Restrictions (Starting With Release 220.127.116.11)
NB: Reports already have their own rate limits.
All calls GET calls will have a per-minute restriction. See the module table above for the rate limits.
All API clients will need to generate an API access token and user token. See the API Access Token keys section below for instructions on how to obtain your tokens.
Workamajig is a user-centric application. In order to maintain continuity, you will need to either use an existing user's API user token or to create a brand new user and generate a user token. All rights assigned to this user will be maintained when using an API call. If the user does not have the proper security rights you will receive a 401 (unauthorized) error response. See the tokens section below for instructions on how to obtain your token(s).
API Access Token
To obtain an API access token you'll need an admin to log into your Workamajig Platinum instance and generate a token. To get to the API Settings:
Log into Workamajig
Click on the Main Menu
Click on Admin/Manager
Click on System Setup
Click on Connections
Click on API
Click Generate New Company Token
Optional: If you know you want to generate system-wide User Tokens, there's a button in this section that'll allow you to do that. Please note that when you generate system-wide user tokens, previously generated tokens will be overwritten. We recommend individually creating user tokens as you add new employees instead.
Tokens can be found in two places, clicking on your name on the top right or using the employee screen.
Employee Screen (You can only view user tokens here not generate them)
- Sign into Workamajig.
- Click on the Main Menu.
- Click on Admin/Manager.
- Click on Employees.
- Choose an employee.
- Choose Security Controls.
- On the right, you'll see API User Token. Please note it's not the Auth Token.
Clicking on your name (starting with version 10.6.2.2)
- Sign into Workamajig.
- Click on your name on the top right.
- You'll find the API User Token on towards the bottom. Here you'll be able to generate and retrieve your user token.
Add the generated tokens to the request headers "APIAccessToken" and "UserToken"
Verb - Used for ...
GET - Get a resource or list resources
POST - Create a resource
PUT - Update a resource
DELETE - Delete a resource
Response Status Codes
Response - Notes
200 - Success, and there is a response body.
201 - Success, when creating resources. Some APIs return 200 when successfully creating a resource. Look at the docs for the API you're using to be sure.
207 - Multi status. Some items are successful while others contain errors.
400 - The parameters in the URL or in the request body aren't valid.
401 - The user token or the API access token is most likely invalid.
404 - Not Found. Usually returned on a GET, this means the data you were looking for was not found.
429 - Too many requests.
500 - Internal server error.
NOTE: The initial intent of batch processing is to allow multiple updates or adds within one request.
Although we don't prevent the same entity (project, vendor, contact, etc) from being updated two or more times within a given batch we do not guarantee the order in which items in a batch get processed.
For POST, PUT and DELETE verbs you can batch your request by creating an array of objects in JSON.
Currently, you're restricted to 100 items in each request.