Overview | Requirements / Support | REST Vs Others | API Endpoint | Versioning | Modules | Restrictions | Authentication | HTTP Verbs | Response Status Codes | Batch | Resources

READ ME FIRST!!

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.

Overview

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 api@workamajig.com 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

REST

• Stateless
• transport is browser neutral
• AJAX friendly
• URL's a definitive and can be expansive
• return structure is any format
• Adheres to an industry standard

SOAP

• stateful 
• XML is the protocol

Single Page

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

API Endpoint

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.

Example Request

Versioning

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.

Example Request

NB: current version: beta1

Modules

Modules vary by what you're trying to do. See the list below for valid modules.

Restrictions (Starting With Release 18.1.0.0)

NB: Reports already have their own rate limits.

All GET calls will have a per-minute restriction. See the module table above for the rate limits.

Authentication

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 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: 

1. Log into Workamajig

2. Click on the Main Menu

3. Click on Admin/Manager

4. Click on System Setup

5. Click on Connections

6. Click on API

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

User Token

Tokens can be found in two places, by 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)

1. Sign into Workamajig.
2. Click on the Main Menu.
3. Click on Admin/Manager.
4. Click on Employees.
5. Choose an employee.
6. Choose Security Controls.
7. 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)

1. Sign into Workamajig.
2. Click on your name on the top right.
3. You'll find the API User Token towards the bottom. Here you'll be able to generate and retrieve your user token.

Request Header

Add the generated tokens to the request headers "APIAccessToken" and "UserToken"

Example Request

APIAccessToken: zjhVgRIvcZItU8sCNjLn+0V56bJR8UOKOTDYeLTa43eQXynPgrWdrGK12xPaOdDZQ==

UserToken: 5sb8Wf94B0g3n4RGOqkBdPfX+wr2pmBTegnJ0+B6vt5iqn0q+jkZgN+gMRU4Y5+2AaXw=

HTTP Verbs

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.

Batch

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.

Sample:

Resources