North API

North provides a RESTful API for developers to use. This document covers the
available API authentication and various endpoints.

Authentication

Before you can use the API, you will first need to get an auth token. In order to do so,

1. Click on your profile name on the bottom left, then click API in the
   floating menu.
2. On the API screen, you will need to create a token. Provide a token name
   (any name that helps you recognize it later), select the applicable scopes, and click Create.
3. This creates a new token that will be displayed on screen. Please copy the
   token and keep it safe as it is shown only once.

The screenshots below indicate where you can find these screens.

Endpoints

The base endpoint for all North APIs is https://to.thenorth.io/

Scope: Basic

Current user info

• URL: /api/user/
• Method: GET

Returns information about the current user.

Example request:

GET /api/user/ HTTP/1.1
Authorization: Bearer $TOKEN
Host: to.thenorth.io

Example response:

HTTP/1.1 200 OK
content-type: application/json

{
    "first_name": "Alyssa",
    "has_saved_profile": true,
    "id": 2,
    "last_name": "P Hacker",
    "otype": "user",
    "photo_id": "17b894a8-75de-4a44-9fe9-54e6ff3cefd5",
    "referral_details": "",
    "referral_sources": [],
    "work_function": "Developer",
    "work_level": "Executive"
}

Other user public info

• URL: /api/users/$user_id/
• Method: GET

Returns information about another user. The user_id should be a numeric id of
the other user — this will be made available by other APIs (e.g. team
membership related APIs).

Example request:

GET /api/users/3/ HTTP/1.1
Authorization: Bearer $TOKEN
Host: to.thenorth.io

Example response:

HTTP/1.1 200 OK
content-type: application/json

{
    "first_name": "Ben",
    "id": 3,
    "last_name": "Bitdiddle",
    "otype": "user",
    "photo_id": "3a834388-d4b2-42ff-9065-1952d31e67c3"
}

Scope: Org management

List user organizations

• URL: /api/orgs/
• Method: GET

Returns a list of organizations that a user belongs to.

Example request:

GET /api/orgs/ HTTP/1.1
Authorization: Bearer $TOKEN
Host: to.thenorth.io

Example response:

HTTP/1.1 200 OK
content-type: application/json

[
    {
        "demo_org_expires_on": null,
        "description": "",
        "estimated_size": "",
        "external_object_providers": [],
        "id": 1,
        "is_billed_offline": false,
        "is_demo_org": false,
        "name": "ACME",
        "root_team_id": 1,
        "tzname": "UTC"
    }
]

Organization details

• URL: /api/orgs/$org_id/
• Method: GET

Returns details for a single organization. The id in the URL should be the
numeric id of the organization present in the id field.

Example request:

GET /api/orgs/1/ HTTP/1.1
Authorization: Bearer $TOKEN
Host: to.thenorth.io

Example response:

HTTP/1.1 200 OK
content-type: application/json

{
    "demo_org_expires_on": null,
    "description": "",
    "estimated_size": "",
    "external_object_providers": [],
    "feature_summary": {
        "allow_tasks": true
    },
    "id": 1,
    "is_billed_offline": false,
    "is_demo_org": false,
    "name": "ACME",
    "root_team_id": 1,
    "tzname": "UTC"
}

List teams in an organizations

• URL: /api/orgs/$org_id/teams/
• Method: GET

Lists the teams in an organization. org_id should be the numeric id of an
organization.

Example request:

GET /api/orgs/1/teams/ HTTP/1.1
Authorization: Bearer $TOKEN
Host: to.thenorth.io

Example response:

HTTP/1.1 200 OK
content-type: application/json

[
    {
        "archived_at": null,
        "archiver_id": null,
        "created_at": "2023-12-10T19:55:16.760775Z",
        "id": 1,
        "is_archived": false,
        "is_explicitly_archived": false,
        "is_org_like": true,
        "is_private": false,
        "name": "ACME",
        "organization_id": 1,
        "parent_id": null,
        "updated_at": "2024-01-08T08:42:39.193352Z"
    },
    {
        "archived_at": null,
        "archiver_id": null,
        "created_at": "2023-12-10T19:55:16.847385Z",
        "id": 4,
        "is_archived": false,
        "is_explicitly_archived": false,
        "is_org_like": false,
        "is_private": false,
        "name": "Design",
        "organization_id": 1,
        "parent_id": 1,
        "updated_at": "2024-01-08T08:43:49.155647Z"
    },
    {
        "archived_at": null,
        "archiver_id": null,
        "created_at": "2023-12-10T19:55:16.829584Z",
        "id": 3,
        "is_archived": false,
        "is_explicitly_archived": false,
        "is_org_like": false,
        "is_private": false,
        "name": "Engineering",
        "organization_id": 1,
        "parent_id": 1,
        "updated_at": "2024-01-08T08:43:31.757663Z"
    },
    {
        "archived_at": null,
        "archiver_id": null,
        "created_at": "2023-12-10T19:55:16.865006Z",
        "id": 5,
        "is_archived": false,
        "is_explicitly_archived": false,
        "is_org_like": false,
        "is_private": false,
        "name": "HR",
        "organization_id": 1,
        "parent_id": 1,
        "updated_at": "2024-01-08T08:43:11.626079Z"
    }
]

Details about a single team

• URL: /api/orgs/$org_id/teams/$team_id/
• Method: GET

Returns details about a single team. org_id should be the numeric id of the
organization and $id should be the numeric id of the team.

Notice that parent_id field in a team. This field will be null for one and
only team in an organization – the root team which encompasses all the org
members. This is the team with which all org level goals, KRs and initiatives are
associated. The root team id is also returned by the org detail API in the
root_team_id field.

Every other team will have its parent_id set to a numeric field. Most of the
time this will be the id of the root team.

Example request:

GET /api/orgs/1/teams/3/ HTTP/1.1
Authorization: Bearer $TOKEN
Host: to.thenorth.io

Example response:

HTTP/1.1 200 OK
content-type: application/json

{
    "archived_at": null,
    "archiver_id": null,
    "created_at": "2023-12-10T19:55:16.829584Z",
    "id": 3,
    "is_archived": false,
    "is_explicitly_archived": false,
    "is_org_like": false,
    "is_private": false,
    "name": "Engineering",
    "organization_id": 1,
    "parent_id": 1,
    "updated_at": "2024-01-08T08:43:31.757663Z"
}

List team memberships

• URL: /api/orgs/$org_id/teams/$team_id/memberships/
• Method: GET

Returns a list of team memberships. Each membership object contains three
fields:

1. type — the type of membership. Can be one of owner, regular, guest or
   guest-no-access.
2. user_id — id of the user who’s member of the team
3. user — an object containing more details about a user. Note that this will
   return additional information as compared to the other user public info
   endpoint.

Example request:

GET /api/orgs/1/teams/3/memberships/ HTTP/1.1
Authorization: Bearer $TOKEN
Connection: keep-alive
Host: to.thenorth.io

Example response:

HTTP/1.1 200 OK
content-type: application/json

[
    {
        "type": "owner",
        "user": {
            "email": "eva@example.com",
            "first_name": "Eva",
            "id": 5,
            "last_login": null,
            "last_name": "lu Ator",
            "otype": "user",
            "photo_id": "cfd6f1d6-f8a1-485b-9f09-2d3670f04eba",
            "work_function": "Developer",
            "work_level": "Executive"
        },
        "user_id": 5
    },
    {
        "type": "regular",
        "user": {
            "email": "cy@example.com",
            "first_name": "Cy",
            "id": 4,
            "last_login": null,
            "last_name": "D Fect",
            "otype": "user",
            "photo_id": "1b04fde2-5d20-4d41-bd89-d5535248c728",
            "work_function": "Developer",
            "work_level": "Executive"
        },
        "user_id": 4
    },
    {
        "type": "owner",
        "user": {
            "email": "alyssa@example.com",
            "first_name": "Alyssa",
            "id": 2,
            "last_login": "2024-01-07T03:07:01.454153Z",
            "last_name": "P Hacker",
            "otype": "user",
            "photo_id": "17b894a8-75de-4a44-9fe9-54e6ff3cefd5",
            "work_function": "Developer",
            "work_level": "Executive"
        },
        "user_id": 2
    }
]

Return about a single membership

• URL: /api/orgs/$org_id/teams/$team_id/memberships/$user_id/
• Method: GET

Returns detail about a single membership. user_id should be the numeric id of
the user.

Example request:

GET /api/orgs/1/teams/3/memberships/4/ HTTP/1.1
Authorization: Bearer $TOKEN
Host: to.thenorth.io

Example response:

HTTP/1.1 200 OK
content-type: application/json

{
    "type": "regular",
    "user": {
        "email": "cy@example.com",
        "first_name": "cy",
        "id": 4,
        "last_login": null,
        "last_name": "d fect",
        "otype": "user",
        "photo_id": "1b04fde2-5d20-4d41-bd89-d5535248c728",
        "work_function": "Developer",
        "work_level": "Executive"
    },
    "user_id": 4
}

Update a single membership

• URL: /api/orgs/$org_id/teams/$team_id/memberships/$user_id/
• Method: PATCH

Can be used to update the membership type of a single membership.

Example request:

PATCH /api/orgs/1/teams/3/memberships/4/ HTTP/1.1
Authorization: Bearer $TOKEN
Content-Type: application/json
Content-Length: 17
Host: to.thenorth.io

{
    "type": "owner"
}

Example response:

HTTP/1.1 200 OK
content-length: 244
content-type: application/json

{
    "type": "owner",
    "user": {
        "email": "cy@example.com",
        "first_name": "Cy",
        "id": 4,
        "last_login": null,
        "last_name": "D Fect",
        "otype": "user",
        "photo_id": "1b04fde2-5d20-4d41-bd89-d5535248c728",
        "work_function": "Developer",
        "work_level": "Executive"
    },
    "user_id": 4
}

Delete a single membership

• URL: /api/orgs/$org_id/teams/$team_id/memberships/$user_id/
• Method: PATCH

Can be used to delete a single membership.

Note: if a user is deleted from the root team they will be deleted from all
other teams in an organization.

Example request:

DELETE /api/orgs/1/teams/3/memberships/4/ HTTP/1.1
Authorization: Bearer $TOKEN
Host: to.thenorth.io

Example response:

HTTP/1.1 204 No Content
content-length: 0

Scope: OKRs and initiatives

List of goals

• URL: /api/orgs/$org_id/goals/
• Method: GET

List goals visible to a user in an organization.

Query params available to filter out goals:

1. team_id – id of the team to which the returned goals belong
2. owner_id – given user is either an owner or co-owner of goals or KRs
3. primary_owner_id – given user is the primary owner or goals or KRs
4. goal_owner_id – given user is either an owner or co-owner of goals
5. primary_goal_owner_id – given user is the primary owner of goals
6. kr_owner_id – given user is either an owner or co-owner of KRs
7. primary_kr_owner_id – given user is the primary owner of KRs
8. is_archived – whether the goals returned are archived or not (value can be either true or false).
9. parent_id – id of the goal to which returned goals are aligned

Goal details

• URL: /api/orgs/$org_id/goals/$goal_id/
• Method: GET

Returns details about a single goal.

Goal events

• URL: /api/orgs/$org_id/goals/$goal_id/events/
• Method: GET

Returns an array of all events related to a goal.

List of KRs

• URL: /api/orgs/$org_id/key_results/
• Method: GET

List KRs visible to a user in an organization.

Query params available to filter out KRs:

1. team_id – id of the team to which the returned KRs belong
2. owner_id – given user is either an owner or co-owner of goals or KRs
3. primary_owner_id – given user is the primary owner or goals or KRs
4. status – status of the returned KRs. Can be one of on-track, behind or at-risk.
5. is_archived – whether the KRs returned are archived or not (value can be either true or false).

KR details

• URL: /api/orgs/$org_id/key_results/$kr_id/
• Method: GET

Returns details about a single KR.

KR events

• URL: /api/orgs/$org_id/key_results/$kr_id/events/
• Method: GET

Returns an array of events related to a single KR.

List of initiatives

• URL: /api/orgs/$org_id/initiatives/
• Method: GET

List initiatives visible to a user in an organization.

Query params available to filter out initiatives:

1. team_id – id of the team to which initiatives belong
2. owner_id – given user is an owner or co-owner of initiatives
3. status – status of the returned initiatives. Can be one of not-started, on-track, behind, at-risk or done.
4. is_archived – whether the initiative is archived or not
5. is_closed – whether the initiative is closed or not
6. nql – for advanced filtering needs, one can provide NQL in this query param

Initiative details

• URL: /api/orgs/$org_id/initiatives/$initiative_id/
• Method: GET

Returns details about a single initiative.

Initiative events

• URL: /api/orgs/$org_id/initiatives/$initiative_id/events/
• Method: GET

Returns an array of events about a single initiative.