Getting Started with the API

ℹ️ The Columinity API (Beta) is only available for select customers on our "Enterprise"-tier. If you are on this tier and wish to use our API, please contact us for more information.

The page provides a 'Getting Started' guide for how to connect to the Columinity API. Please consult our complete Endpoint documentation to learn about all the endpoints, their parameters, and return values.

Features

The Columinity API offers endpoints to manage some of the entities on Columinity:

• Add, update, delete and archive teams
• Add, update, and delete coaches to/from Coaching Centers
• Add, update, and delete users to/from Teams Dashboards
• Retrieve scores for factors from our various models for teams in your organization(s)
• Export (.csv) reports also available in the app

We may extend the API with additional endpoints in the future if there is a business case for it.

Authenticating with the Columinity API

The Columinity API uses OAuth for authentication. The high-level flow is as follows:

1. Retrieve your personal ConsumerKey / ConsumerSecret pair for your account in Columinity from your profile. Click "My Account", then go to the "API Access"-section, and click the button to receive your tokens by email. This button is only available for Administrators in the Coaching Center (on an "Enterprise"-plan).
2. POST ConsumerKey / ConsumerSecret pair to /token endpoint
3. On success, receive an access token (JWT) that is valid for 12 hours
4. On failure, receive a BadRequest
5. Use the access access token on subsequent calls until it expires

An API session is inherently tied to a user account in Columinity. This means any actions performed under it have the same permissions as the account. Additionally, actions performed through the API are logged to the account.

To authenticate with the Columinity API, POST your ConsumerKey and ConsumerSecret to our https://externalapi.columinity.com/token as shown below:

POST /token HTTP/1.1
Host: https://externalapi.columinity.com
Content-Type: application/json
Accept: application/json

{ "ConsumerKey": "[ConsumerKey]", "ConsumerSecret": "[ConsumerSecret]" }

This returns a JSON web token with your access token:

{
    "access_token": "[accesstoken]",
    "expires_in": "2024-12-18T11:43:56Z"
}

Retain the value stored in access_token and pass it along in an "Authorization"-header for subsequent requests to the other endpoints of the Columinity API. The access_token will be valid until the date specified in "expires_in", when a new token must be requested.

A note on our hierarchy and users

Columinity is built around teams. We often want to group teams and analyze their aggregated results for various reasons. This is reflected in the hierarchy of Columinity:

• A team has its own Team Report. It helps them diagnose their process and repeat measurements.
• One or more teams are grouped into a Teams Dashboard. These typically reflect (sub)organizations, like a business unit, a department, or a client you work with. The Teams Dashboard allows analysis of the results of all or a subset of teams. Teams Dashboards have their own user accounts (Organization Users) that have access only to that Teams Dashboard.
• One or more Teams Dashboards are grouped into a Coaching Center. The Coaching Center allows analysis of all or a subset of (sub)organizations in a high-level overview. Coaching Centers have their own user accounts (Coaches), and they typically have access to all or a selection of Teams Dashboards from (sub)organizations).

When you create user accounts, we recommend creating Organization Users over Coaches where possible. Because Coaches have access to the Coaching Center and one or more Teams Dashboards, their functional experience is more complex than Organization Users, who can only access one Teams Dashboard. Moreover, Organization Users can also be restricted to specific teams if desired in addition to being restricted to one Teams Dashboard, which allows more fine-grained control and further reduces complexity. Coach accounts are helpful for people who need a high-level overview and/or coach many different teams across organizations.

Basic operations

Retrieving Coaching Centers

Some endpoints on the Columinity API require the unique key of the Coaching Center. To retrieve the available Coaching Centers, use the following GET-method to https://externalapi.columinity.com/v1/coachingcenters

GET /v1/coachingcenters HTTP/1.1
Host: https://externalapi.columinity.com
Authorization: Bearer [access_token]
Content-Type: application/json
Accept: application/json

This returns a list of one or more Coaching Centers:

{
    "items": [
        {
            "publicKey": "[unique key for Coaching Center]",
            "name": "Columinity"
        }
    ],
    "pageSize": 0,
    "page": 0,
    "totalItems": 1
}

Retrieving Teams Dashboards / Organizations

Some endpoints on the Columinity API require the unique key of the Teams Dashboard / Organization. To retrieve the available Teams Dashboards, use the following GET-method to https://externalapi.columinity.com/v1/organizations

GET /v1/organizations
HTTP/1.1
Host: https://externalapi.columinity.com
Authorization: Bearer [access_token]
Content-Type: application/json
Accept: application/json

This returns a list of one or more Teams Dashboards:

{
    "items": [
        {
            "publicKey": "[unique key for Teams Dashboard]",
            "name": "Columinity Teams Dashboard"
        }
    ],
    "pageSize": 0,
    "page": 0,
    "totalItems": 1
}

Get Teams for Teams Dashboard / Organization

To retrieve a list of teams for a Teams Dashboard, perform a GET operation with the OrganizationKey to load teams for:

GET /v1/teams/[organizationKey]
HTTP/1.1
Host: https://externalapi.columinity.com
Content-Type: application/json
Accept: application/json
Authorization: Bearer [access_token]

This returns a paged list of teams:

{
    "items": [
        {
            "publicKey": "[ unique key for team 1 ]",
            "name": "Team 1",
            "emailObfuscated": "c****y@t****s.com",
            "tags": [
                "Agile"
            ],
            "metaData": [],
            "teamTraitKeys": [ "agile" ],
            "archived": false
        },
        {
            "publicKey": "[ unique key for team 2 ]",
            "name": "Team 2",
            "emailObfuscated": "c****y@t****s.com",
            "tags": [
                "Scrum team"
            ],
            "metaData": [],
            "teamTraitKeys": [ "software", "agile" ],
            "archived": false
        },
    ],
    "pageSize": 2,
    "page": 0,
    "totalItems": 2
}

If multiple pages exist, the list can be paged by adding a page parameter to the query; /v1/teams/[organizationKey]?page=1. The page size can also be set to something else by adding page size as a query parameter: /v1/teams/[organizationKey]?page=1&pageSize=20. It is also possible to filter the list by adding a keyword or by filtering by status (archived or active). Please have a look at our endpoint documentation for details.

Creating a Team for a Teams Dashboard

To create a new team, perform a POST with the OrganizationKey of the Teams Dashboard you wish to add a team to:

POST /v1/teams/[organizationKey] 
HTTP/1.1
Host: https://externalapi.columinity.com
Content-Type: application/json
Accept: application/json
Authorization: Bearer [access_token]

{
  "Name": "My Team",
  "NotificationEmail": "team@team.com",
  "Tags": [ "Tag 1", "Tag 2" ],
  "TeamTraitKeys": [" agile", "software", "iterations" ],
  "MetaData": [
    {
      "Key": "internal_id",
      "Value": "our internal id for this team"
    }
  ]
}

If the operation succeeds, a 200/OK is returned with the new team's key. If an error occurs, a 400/BadRequest is returned with a description.

All write, update, and delete operations to the Columinity API are performed asynchronously. The 200/OK response you receive on success only means that the operation was validated and issued to the backend. The operation typically takes several seconds to complete ("eventual consistency"). Since there is currently no way to receive an announcement of completion, we recommend you pause for a few seconds after such operations before reading data. If an operation does not take effect, please get in touch with support.

Updating a Team

To update an existing team, perform a PUT operation with the key of the Teams Dashboard / Organization the team belongs to and the key of the team you wish to update:

PUT /v1/teams/[organizationKey]/[teamKey]
HTTP/1.1
Host: https://externalapi.columinity.com
Content-Type: application/json
Accept: application/json
Authorization: Bearer [access_token]

{
  "Name": "My Team",
  "NotificationEmail": "team@team.com",
  "Tags": [ "Tag 1", "Tag 2" ],
  "TeamTraitKeys": [ "agile" ],
  "MetaData": [
    {
      "Key": "internal_id",
      "Value": "our internal id for this team"
    }
  ]
}

If the operation succeeds, a 200/OK is returned with an empty body. If an error occurs, a 400/BadRequest is returned with a description. This operation is performed asynchronously, as described under 'Creating a team'.

Deleting a Team

To delete an existing team, perform a DELETE operation with the key of the Teams Dashboard / Organization the team belongs to and the key of the team you wish to delete:

DELETE /v1/teams/[organizationKey]/[teamKey]
HTTP/1.1
Host: https://externalapi.columinity.com
Content-Type: application/json
Accept: application/json
Authorization: Bearer [access_token]

If the operation succeeds, a 200/OK is returned with an empty body. A 400/BadRequest is returned with a description if an error occurs. This operation is performed asynchronously, as described under 'Creating a team'.

Retrieving factor scores for a Teams Dashboard

To load factor scores for sampling windows, you can query:

POST /v1/factorscores/[organizationkey]/organization 
HTTP/1.1
Host: localhost:8093
Content-Type: application/json
Accept: application/json
Authorization: Bearer [access_token]

{
  "ModelKey": "agilescrumteameffectiveness",
  "FactorKeys": ["9dca17c0-2155-4666-908f-ae28f29941af"],
  "PeriodGrouping": "PreviousMonth",
  "Benchmark": "TopSamplesByEffectiveness"
}

This returns the factor score for the selected factor ("Responsiveness") for the sampling window from 2025-04-02 to 2025-05-02, which includes 22 participants from five teams. The response includes a breakdown by teams and segments. If teams have "low-trust mode" enabled, they will be listed as "Anonymized".

{
    "from": "2025-04-02T09:12:17.2939918+02:00",
    "to": "2025-05-02T09:12:17.2939918+02:00",
    "items": [
        {
            "key": "9dca17c0-2155-4666-908f-ae28f29941af",
            "name": "Responsiveness",
            "score": 49,
            "upperConfidence": 62,
            "lowerConfidence": 37,
            "sampleSize": 22,
            "qualification": "Neutral",
            "breakdown": [
                {
                    "name": "Stakeholder",
                    "score": 46,
                    "type": "Segment",
                    "sampleSize": 10
                },
                {
                    "name": "TeamMember",
                    "score": 51,
                    "type": "Segment",
                    "sampleSize": 12
                },
                {
                    "name": "Anonymized",
                    "score": 46,
                    "type": "Team",
                    "sampleSize": 1
                },
                {
                    "name": "Columinity Fifth Team",
                    "score": 50,
                    "type": "Team",
                    "sampleSize": 1
                },
                {
                    "name": "Columinity Fourth Team",
                    "score": 58,
                    "type": "Team",
                    "sampleSize": 1
                },
                {
                    "name": "Columinity Second Team",
                    "score": 49,
                    "type": "Team",
                    "sampleSize": 1
                },
                {
                    "name": "Demo Team for Columinity",
                    "score": 37,
                    "type": "Team",
                    "sampleSize": 1
                }
            ],
            "delta": {
                "score": 0,
                "from": "2025-03-02T09:12:17.2939918+01:00",
                "to": "2025-04-02T09:12:17.2939918+02:00",
                "sampleSize": 0
            },
            "benchmark": {
                "score": 59,
                "upperConfidence": 73,
                "lowerConfidence": 45
            }
        }
    ],
    "pageSize": 0,
    "page": 0,
    "totalItems": 1
}

The end date of the sampling window can be specified using "ForDate", and the size of the sampling window can be adjusted through "PeriodGrouping". This also influences the delta period, which is always the period of the same duration before the selected period. If no specific factorkeys are provided, all factors for the selected model with response data are returned.

Exporting factor scores for a Teams Dashboard

The API makes it possible to programmatically export the various .CSV exports available in the Teams Dashboard or Coaching Center. For example, to export the factor scores for a Teams Dashboard, perform a POST operation with the key of the Organization / Teams Dashboard and the key of the Model (see "Get Models"):

POST /v1/export/[organizationkey]/csv/factorscores/organization 
HTTP/1.1
Host: localhost:8093
Content-Type: application/json
Accept: application/json
Authorization: Bearer [access_token]

{ 
   "ModelKey":"agilescrumteameffectiveness",
   "Benchmark": "TeamsFromSameClient",
   "PeriodGrouping": "PreviousQuarter"
}

This returns a 200/OK with the CSV as string content, for example:

Period,Factor,Team / Organization,Tags,Normalized Average Score (Weighted),Lower Quartile,Upper Quartile,Qualification,Benchmark,Benchmark Lower Quartile,Benchmark Upper Quartile
Sep 2024-Dec 2024,Responsiveness,All teams in period,,51,33,64,Neutral,59,46,73
Sep 2024-Dec 2024,Responsiveness,Columinity Second Team,,49
Sep 2024-Dec 2024,Responsiveness,Demo Team for Columinity,,50
Sep 2024-Dec 2024,Continuous Improvement,All teams in period,,51,40,67,Neutral,62,49,75
Sep 2024-Dec 2024,Continuous Improvement,Columinity Second Team,,46
Sep 2024-Dec 2024,Stakeholder Concern,All teams in period,,52,28,71,Neutral,59,44,75
Sep 2024-Dec 2024,Stakeholder Concern,Columinity Second Team,,47
Sep 2024-Dec 2024,Stakeholder Concern,Demo Team for Columinity,,45

Please consult our endpoint documentation to learn the available exports and filters.

Other operations

The Columinity API follows the same approach for most other entities. Consult our endpoint documentation for details. In general:

• To read an entity or data, use GET.
• To add a new entity, use POST.
• To update an existing entity, use PUT.
• To delete an existing entity, use DELETE.
• Lists of entities are always paged in the same manner.
• A 200/OK is returned when a create, update, or delete operation is successful.
• A 400/BadRequest is returned on errors or validation issues.
• A 404/NotFound is returned when an entity does not exist.
• A 500/InternalServerError is issued for unhandled errors.
• A 429/TooManyRequests is returned if you issued too many requests in a period. Please make sure to pause your operations for a few minutes to continue.
• Create, update, and delete operations execute asynchronously. The 200/OK only means the request was validated and issued to our backend.
• Endpoints are versioned. Provide the applicable version (default is 1).

Limitations

• Rate limits apply (typically 30 calls per minute). Please ensure your client can handle a 'TooManyRequests' response and pause operations for a minute.
• Use of the API is monitored. Abuse will result in a ban.
• We don't return email addresses from the API to protect and prevent privacy and anonimity, also in case of breaches.

Security Recommendations

• Never share the ConsumerKey / ConsumerSecret pair publicly. Instead, store it in a secure Password Vault. If the pair or part of it was accidentally shared, request a new pair from your profile ("My Account").