To use your API key, append to any API request.

GET https://api.northpass.com/v1/courses?api_key=API_KEY

All API requests must be made over HTTPS. API requests without authentication will also fail.

Northpass uses conventional HTTP response codes to indicate the success or failure of an API request. In general, codes in the 2xx range indicate success, codes in the 4xx range indicate an error that failed given the information provided. Northpass will follow the JSON-API error spec when encountering an error.

An example error response is as follows:

422

{
  "errors": [
    {
      "status": "422",
      "title": "Invalid Attribute",
      "detail": "Uh oh, that name has already been added",
      "source": {
        "pointer": "/data/attributes/name"
      }
    }
  ]
}

All top-level API resources have support for bulk fetches via "list" API methods. For instance you can list people, courses, and groups. These list API methods share a common structure, taking at least these two parameters: page and limit. Northpass utilizes offset-based pagination via the page and limit parameters.

To use pagination, append to any "list" API request.

GET https://api.northpass.com/v1/courses?page=2&limit=10

Pagination links appear in the links object that corresponds to a collection, as described by JSON-API. Pagination keys will be omitted to indicate that a particular link is unavailable.

An example of pagination links included in the returned JSON is as follows:

{
  "links": {
    "self": "https://api.northpass.com/v1/courses?page=2",
    "prev": "https://api.northpass.com/v1/courses",
    "next": "https://api.northpass.com/v1/courses?page=3"
  }
}

Any index/listing endpoint will allow filtering of the results. All filtering is done by using the filter query param. Any attribute that is returned in the result for a resource should be able to be used for filtering (eq uuid, or anything listed under attributes).

For brevity, all the examples do not use the full url, but it should be added back when using.

people?filter[name]=foo

https://api.northpass.com/v2/people?filter[name]=foo

Some examples are shown with no trailing [] and examples with a trailing []. The trailing [] is required when providing a list of values (eg see IN usage). When only providing one value, the trailing [] can be used or not, either is supported. For example, the following are identical:

people?filter[email][eq]=foo@example.com

people?filter[email][eq][]=foo@example.com

Equality filtering

Attribute must match value exactly

people?filter[email][eq]=foo@example.com

Contains filtering

Attribute must contain the provided value

people?filter[email][cont]=example.com

One of many filtering

Attribute must match one of the requested values exactly

people?filter[email][in][]=foo@example.com&filter[email][in][]=bar@example.com

Comparison filtering

Compare attribute using provided predicate

groups?filter[membership_count][gteq][]=1

Available predicates: lteq, gteq, lt, gt

Combining filters

For more complex filtering, you may need and or or combinators.

Example, filtering all groups with (membershipcount > 2 and name contains "Admin") or membershipcount = 0

groups?filter[and][or][membership_count][gt]=2&filter[and][or][name][cont]=Admin&filter[and][membership_count][eq]=0