Coly API documentation


Version 1.18

Table of contents

 

 

 

Introduction


The Coly API Documentation provides descriptive information for developers who would like to integrate the functionality of the Coly API into their solution.

The Coly engine is provided in four simple steps.

  1. Create a tenant.
  2. Distribute the link to the tenant for the assessment and profile.
  3. Create a unit and assign tenants to it.
  4. Match.

The API endpoints are documented in the same order as the user flow above.

Go to API section to get started!

 

 

Data Lifecycle Description


Our data models have several types(or layers) that define our approach. Simply speaking, the data lifecycle reveals steps and actions that should be taken to reach them.

Unit
Tenant
Assignment
Feedback
PsychometricTest

Diagram1: Visualisation of model dependencies

 

Primary models


Core-level models contain crucial data for system operations.

 

Tenant model


Tenant record access available
Assignment model
Archived
Updated
Joined2Unit
LeftUnit
Created
Closed
Opened
Disabled
Anonymised

 

Unit model


Unit record access available
Assignment model
Archived
Updated
TenantJoined
TenantLeft
Created
Closed
Opened
Disabled
Anonymised

 

 

API Endpoints & Auth header


Base API URL:

 

To connect with our API, you will need to generate an API key. Please follow these steps:

  1. Visit your settings page at Coly Console Settings.
  2. Follow the instructions to generate your unique API key.

After obtaining the API key, include it in all requests by setting the Authorization header as follows:

Remember to replace {yourApiKey} with your actual API key.

For example:

 

API Versioning:

The current version of our API is indicated by the v1 prefix in the base URL. This means all endpoints are accessed under this version. Should there be a transition to a new version (e.g., v2), we will provide advance notice and ensure backward compatibility, allowing continued access to v1 endpoints.

 

 

Main Response Structure


Our API leverages the Either pattern, a common approach in functional programming, to standardize the structure of all responses. This strategy enables the API to always return a 200 status code, regardless of whether the operation was successful. The outcome of the operation is conveyed in the response's type field, which can be either 'success' or 'failure'.

Note: While the following example uses TypeScript, the 'Either' pattern is language-agnostic and can be adapted to your preferred programming language:

 

In every response, you'll find the data property structured as one of the following:

 

The value of a successfull response will vary across different requests, but all error messages will conform to this structure:

 

In this format, the message field provides a human-readable explanation primarily for debugging. However, it may change over time, so it should not be relied upon for application logic. On the other hand, the FailCode is a unique, constant identifier for a specific type of failure and can be used to handle errors in your application.

Every API endpoint will provide a list of possible FailCodes for each request.

 

Here are examples of a successful and a failed request:

 

 

One common FailCode for all requests is InputValidation::Failed, which signifies an issue with the request body format. Example:

 

For the remainder of this API documentation, we will describe the structure of the 'value' field and the potential FailCodes for each request.

Although almost all requests return a 200 status code, there are a few exceptions:

 

 

Basic query params


For any of the entities below (tenant and unit), the following query params are supported when fetching from the backend:

 

Example:

  1. To fetch the first 20 tenants in ascending order by their last name and include their personality traits in the response, use the following query:

 

 

Tenants


The Tenants entity mainly refers to the tenants within a shared living space, or tenants taking the Psychometry Assessment using our product. Each tenant will have their personality and coreValues traits calculated after taking the assessment. The score they get will play a key role in matching the individual to a specific unit.

 

Create tenant


Creates Tenants record and returns it. It requires email , firstname, lastname to create a Tenants record.

 

Example request body

 

Response example

 

 

Get tenant information


Retrieve a single tenant's record with all the detailed pieces of information that you need.

 

Response example

 

 

Get list of tenants


Retrieves the list of tenant's records, with the total number of Tenants and their detailed pieces of information.

 

Response example

 

Available query options for tenant relations:

 

 

Update tenant


 

Example request body

 

Response example : Changed tenant name

 

 

Archive tenant


Archive Tenants record status.

 

Response example : Archive tenant

 

 

Restore tenant from archive


Restores a Tenants record from the archive.

 

Response example : Restore the achived tenant

 

 

Delete tenant from archive


Disabling and deleting Tenants record from archived.

Note that only the archived records can be deleted.

 

 

Tenant Error Codes


Here are the possible error codes for a failure response in the tenants route.
Record Not Found

When the desired record is missing:

 

Email Already In Use

When creating a Tenant record, the user's email should be unique and not be reused unless the tenant has been removed from the platform:

(Note that this error is prefixed with User, as it applies system-wide to any type of user.)

 

Archived Record Restriction

For archived records, they are not allowed to be matched, or assigned to units. To achieve this, you would need to restore the record first:

 

For non-archived records, you would have to archive the record first to disable/delete it:

 

Unknown

If there is a case of an unknown Error, there is a high chance of server-side error. Contact us through our email dev@coly.io with detailed information about the error:

 

Notifications


To initiate the assessment process for a tenant, use the endpoint below. This action triggers an automated email sequence to encourage the tenant to complete their psychometric assessment. The sequence includes an initial invitation followed by reminders if the assessment isn't completed within specific intervals.

 

Behavior:

Upon invoking this endpoint, an email is dispatched to the specified tenant, marking the commencement of a notification chain. If the tenant does not complete the assessment within 3 days, they receive a follow-up reminder. A final reminder is sent if the assessment remains incomplete 5 days after the initial email. Triggering this endpoint for a tenant will reset any existing reminder sequences for them, starting the process anew.

Example request body

A successful request returns {"type": "success"}, indicating the email sequence has been initiated. If the tenant cannot be found, the response will be {"type": "failure"}, accompanied by a failcode of Tenant::NotFound.

 

 

Units


The Units entity is a collection of Tenants. Usually refers to a unit of Tenants who live in a shared living space. A unit is created by title and capacity. A unit with tenants contains a calculated average score of the personality and coreValues, scale that can be used to match an incoming tenant.

 

 

Create unit


Creates Unit record and returns it. It requires a Unit name and a capacity of tenants for the unit.

 

Example request body

 

Response example

 

 

Get unit information


Retrieve a single Unit record with all the detailed pieces of information that you need, including personality and coreValues percentile.

 

Response example 1

 

Response Example 2:

 

 

Get list of units


Retrieves a list of Units records, with the total number of units and detailed information about each unit.

 

Response example:

 

Available query options for unit statuses:

 

Available query options for unit relations:

 

 

Update unit


Updates Unit record fields and returns it updated. You can alter the name and the capacity of the unit record you created.

 

Example request body

 

Response example : Changed unit capacity

 

 

Archive unit


Archive Unit record status.

 

Response example : Archive unit

 

 

Restore unit from archive


Restores a Unit record from the archive.

 

Response example : Restore the archived unit

 

 

Delete unit from archive


Disabling and deleting Unit record from archived.

Note that only the archived records can be deleted.

 

Response example: Unit record deleted

 

 

Unit Error Codes


Record Not Found

When the desired record is missing:

 

Unit Name Already In Use

When creating a Unit record, the unit's name should be unique. This includes the archived units as well:

 

Archived Record Restrictions

For archived records, you'll need restore them before they can be used again:

 

For non-archived records, you would have to archive the record first to disable/delete it:

 

Not Empty

In case there's an operation such as archive on a non-empty unit record:

 

Unknown

If there is a case of an unknown Error, there is a high chance of server-side error. Contact us through email at dev@coly.io with detailed information about the error:

 

 

Assignments


Assignments are used for adding and removing Tenants to and from a Unit. Assignments are indicating the relation between Tenants and Units records.

 

Assign tenant to unit


Assign a Tenant to a Unit. You would need both unitId and tenantId to create assignment records.

 

Example request body

 

Response example

The response will be an empty response, with the either pattern indicating success or failure. For example:

 

 

Remove tenant from unit


Remove a Tenant from a Unit. This closes the assignment for specified tenant by deleting or removing the assignment record.

 

Example request body

 

Response example

Same philosophy as in the POST /assignments endpoint. For example:

 

 

Assignment Error Codes


Unit Overflow

When no vacancies are left for the unit, attempting to assign new tenant records will not be possible:

 

Assigned Tenant Record Restriction

Tenant records are only allowed to be assigned to one unit at a time. In case of attempting to assign to multiple units:

 

Other error codes

These errors can also occure when attempting to assign records. Note that these are described in the tenant and unit routes above:

 

 

Matching


The Matching Engine provides a method for evaluating the compatibility between individuals and units within our system. Compatibility is quantified using a score ranging from 0 to 100. Detailed below are two endpoints:

  1. Match - This facilitates matching between a chosen source and target.
  2. Best Match - This fetches the most compatible units or individuals for a given source.

 

Match


The Match function compares a single source to multiple targets, and generates an array of scores to indicate the level of compatibility between each source and target. source can be a single tenant, single unit, or a an array of tenants (what we usually refer to as "virtual unit"). targets can be an array with combinations of units, tenants, or also a virtual units.

The response includes an object with a results field, which contains an array representing the compatibility of each match. The scores are indexed in the same order as the targets array in the request.

 

 

Example request body

 

Response example: Returns matching score

 

Example 2 request body (source is an array of tenants, i.e, "virtual unit")

 

Response 2 example: Returns matching score

 

Example 3 request body (targets now also includes a virtual unit, and a tenant)

 

Response 3 example: Returns matching score

 

Example request 4: The second unit happens to be empty

 

Example response 4: The response in case of a rejection

 

 

Best Match


The best match endpoint enables you to locate the best matching entity across the entire workspace for a specified source.

As you may have noted, there are no differences between resolved or rejected requests - best match will exclusively contain resolved matches. At most, 20 items will be included, but this may be fewer if the system currently lacks a sufficient number of individuals or units available for matching.

 

Example request body

 

Response example: Returns best matching score for tenant to units

 

Overlap handling


Overlap handling is implemented for all matching requests. It takes into account situations where some individuals appearing in the source also exist in the target entities. This may happen, for example, when matching an individual with a unit in which they are already a member. The default procedure for managing such scenarios involves the following steps:

By applying these rules, the overlap handling ensures that the same tenant doesn't feature in both the source and target when a match is being calculated, thus maintaining the integrity of the matching process.

 

Match Error Codes


The error codes possible to get from the match endpoint are:

These are described in the tenant and unit routes.

 

 

Throttling


In the context of the API, there's a throttler mechanism that enforces rate limits on the number of requests a client can make to ensure that the API remains responsive and available for all clients and to prevent one client from monopolizing the resources of the API.

When a client exceeds the rate limit, the API will return a 429 error to indicate that the client has exceeded its allowed number of requests. The client should wait a certain amount of time before retrying the request. The duration of the waiting time is included in the response headers in the form of the 'Retry-After' header.

 

 

Disclaimer


Please note that any data found on an object that is not explicitly mentioned in this document is not officially supported. Such values are susceptible to alterations at any time without prior notice.