Types, Formats and Conventions

HTTP Methods and URLs

In general, an API resource is accessed or acted upon using an HTTP method and a URL. The HTTP methods used are:

  • GET - Retrieve an object
  • POST - Create an object
  • PUT - Update (or create) an object
  • DELETE - Delete an object

The general URL scheme is /{resource class}/{id}/{sub resource or operation}, resources denoted in singular form (i.e. /job/123456, not /jobs/123456).

Response Codes

Some commonly used HTTP response codes:

Successful requests
200OK The request was successful, the response body contains the requested content.
204No Content The request was successful, but there's no content (it's "null").
Client errors
400Bad Request Something is not right in the query parameters you supplied.
401Unauthorized You haven't supplied valid credentials (API key and/or token) required for the request.
403Forbidden Credentials are correct but you don't have permission to access the resource.
404Not Found There's no resource at that URL.
406Not Acceptable Something in the content is not acceptable (formatting, not passing validation logic, etc)
Server errors
500Server Error Oops. We've messed up. Try it again, once, but don't expect too much. We'll get on it ASAP.
503Service Unavailable Something is taking too long or temporarily offline. Try again in a while.


Query and form parameters have some common types and follow some conventions listed below.

Flag Flag parameters are true if included, false if omitted (so, false is default). So if there's a parameter called sendMessage you'd set it true by including the sendMessage parameter, and false by leaving it out.
Timestamp Timestamps are specified as number of milliseconds since January 1st 1970 UTC (the epoch). Otherwise known as UNIX timestamps.

Media Type

Almost all data is transferred using JSON as the media type. There are some exceptions though, for example some resources that contain dense information more suitable to a tabular format. CSV (comma separated values) are typically used for that.

Unless otherwise stated in the documentation, JSON is used. So you'll typically see this header in the response:

Content-Type: application/json; charset=UTF-8

In case of errors (both client and server ones) you'll simply get a status code and oftentimes a plain text response describing the error.

JSON Content

JSON specifies a pretty clear structure but not how some data types are to be conveyed. So here are some conventions in use throughout the API:

Date and Time

Dates and timestamps are specified as number of milliseconds since January 1st 1970 UTC (the epoch). Otherwise known as UNIX timestamps.

PUT Operations are Patching

All POST/PUT operations affect only the attributes you include (which in some other APIs are a PATCH operation). So for example, if you include only the title attribute when you update a job, only the title is changed and all other attributes remain unchanged.

Common Attributes

This section describes some common attributes that are present in most objects used throughout the API.


Objects typically contain a creationTimeStamp describing when it was created and a creatorId (which is a user ID) of the creator.

Groups and Sharing

An object can either be private or shared with a group. Private objects are only accessible by its creator (creatorId attribute). Shared objects have a groupId attribute that indicates the group it's shared within. If you don't specify a groupId the object will be shared with the calling user's primary group (primaryGroupId) if the shareAllWithPrimaryGroup flag is set, or the calling API key's primary authorized group (if any).

IDs, UUIDs and Syncing

For historical reasons, relations between objects are specified with both numeric IDs and UUIDs throughout the API.

Referring to Objects

Object relations are often represented both by an ID (i.e. groupId) and an UUID (i.e. groupUuid) in the JSON content. When groupId is mentioned throughout the documentation you may use groupUuid instead.

When creating/updating relations (POST and PUT calls), make sure you don't specify both ID and UUID (especially not conflicting IDs, or else).

Storing References

At some point you probably want to sync some object in Coredination with some object in another system. When storing references to Coredination objects in another system, please use the UUID whenever possible instead of the numeric ID. Numeric IDs may change in the future if we need to make changes to the underlying database infrastructure. Our plan is to eventually remove the numerical IDs from the API and only use UUIDs.

Object Creation

When creating objects, in some cases you can use either POST (and let the server assign ID) or PUT with a client-generated URL path. The latter variant has a significant advantage, especially when used on a mobile device or shaky network: If a request times out and is resent, you won't end up with two objects in case the first request actually was received by the server.

Custom Fields

Custom fields are available on a number of resources, including (but not limited to) jobs, reports and customers. They will typically be represented in the a JSON structure as a list with customFields as the property name.

The JSON representation of a custom field looks something like this:

	"internal": false,
	"label": "Person on duty",
	"name": "persononduty",
	"required": true,
	"searchable": false,
	"type": "STRING",
	"typeInfo": "person_name",
	"value": "John Smith",
	"viewPermission": null,
	"weight": 1


The following are valid values for the type property:

STRING A text string (one line)
TEXT A multi-line text field
INTEGER An integer
BOOLEAN A boolean value, shown as a checkbox while editing, label presented while viewing if value is "true"
CHECKBOX A boolean value, shown as a checkbox while editing or viewing
TEXT A multi-line text field
SELECT A drop-down menu of (a few) options. Available options are specified in the typeInfo field, separated by newline. See the discussion on type information below.
DATE A date, stored as a timestamp since epoch
TIME A time of day, stored as a timestamp since midnight
DATETIME A date and time of day, stored as a timestamp since epoch
HEADER Just a header. Not allowing any input
SIGNATURE Unofficial Presents a signature pad, stored as a custom JSON structure
OK_ACTION_NOTE Unofficial An OK/Action checkbox field with (optional) note

Type information

The typeInfo field is used to specify how input of the field is to be accepted. For STRING or TEXT fields, it's used mainly to help mobile applications present the right keyboard variant. For SELECT fields it's used to store the available options.

For STRING and TEXT fields, the following typeInfo values have special meanings:

numeric A numeric value. Apps show a numeric keyboard.
person_name A person name. Apps auto-complete and capitalize accordingly.
email_address An e-mail address. Apps show an @-sign keyboard, auto-complete and capitalize accordingly.
phone_no A phone number. Apps show an appropriate keyboard.
no_suggestions Apps should not auto-complete.

The Coredination applications keep the type information indefinitely, since i.e. jobs don't refer back to their template and thus need their type information anytime a field needs to be changed by a user. The reason for us not referring back to templates is to allow templates to change over time while allowing changes to 'instances' (i.e. jobs) even after a template has changed. The drawback is that type information will be duplicated a lot. So, most importantly, SELECT fields with a lot of options should be avoided if possible. If your application makes use of custom fields and you don't agree with the reasoning above, feel free to remove type information for custom fields when it suits your application. The type information is only used for editing fields within the applications, not presentation.