NAV Navbar
Examples
  • Introduction
  • Authentication
  • Users
  • Topics and Articles
  • Pathways
  • Enrolments
  • External Knowledge
  • Errors
  • Rate limits
  • Introduction

    Welcome to the Tribal Habits Public API V1! You can use our API to manage your Tribal Habits user accounts (list, show, create and update) and other entities.

    Authentication

    To authorize, use this code:

    # With shell, you can just pass the correct header with each request
    curl "api_endpoint_here"
      -H "Authorization: my_api_key"
    

    Make sure to replace my_api_key with your API key.

    Tribal Habits use API keys to allow access to the API. You may obtain an API key for your organisation by visiting the Admin / Account page.

    Tribal Habits requires the API key to be included in all API requests to the server in a header that looks like the following:

    Authorization: my_api_key

    There is an additional Zapier API key which can also be used as Authentication when integrating with our API via Zapier.

    Users

    Custom fields

    Organisations may configure custom fields to be associated with users to collect additional information such as demographics, organisational structure, etc. When configured, the corresponding attribute/value pairs are included in all API responses and can be set in calls to create and update. Custom field names are prefixed with X- so for example a custom field called City is denoted by X-City. The examples below assume an organisation has configured 2 custom fields called Country and State.

    Get all users

    curl "https://myorg.tribalhabits.com/papi/users"
      -H "Authorization: my_api_key"
    

    The above command returns JSON structured like this:

    {
      "total_records": 47,
      "max_per_page": 25,
      "current_page": 1,
      "total_pages": 2,
      "records": 
        [
          {
            "user_name": "12345",
            "first_name": "Bilbo",
            "last_name": "Baggins",
            "email": "bilbo@myorg.com",
            "manager_email": "manager@company.com",
            "manager_2_email": "manager2@company.com",
            "manager_3_email": "manager3@company.com",
            "manager_4_email": "manager4@company.com",
            "manager_5_email": "manager5@company.com",
            "mentor_email": "mentor@company.com",
            "lms_learner_id":"456",
            "lms_reference":"Testlms",
            "type":"Client",
            "active": true,
            "role_1": "Sales",
            "X-[Custom]": "Custom Field, see top of page for details."
          },
          ...
        ]
    }
    

    In this example, you could get the remaining 22 users with

    curl "https://myorg.tribalhabits.com/papi/users?page=2"
      -H "Authorization: my_api_key"
    

    This endpoint retrieves all users (paginated).

    HTTP request

    GET https://myorg.tribalhabits.com/papi/users

    Query parameters

    Parameter Default Description
    page 1 Results page to return
    max_per_page 25 Maximum number of results per page

    Create a new user

    curl "https://myorg.tribalhabits.com/papi/users"
      -H "Authorization: my_api_key"
      -H "Content-Type: application/json"
      -X POST
      -d '<request_body>'

    Example request body:

    {
      "user_name": "12345",
      "first_name": "Bilbo",
      "last_name": "Baggins",
      "email": "bilbo@myorg.com",
      "manager_email": "manager@company.com",
      "mentor_email": "mentor@company.com",
      "lms_learner_id":"456",
      "lms_reference":"Testlms",
      "type":"Client",
      "role_1":"Sales",
      "X-[Custom]": "Custom Field, see top of page for details."
    }
    

    The above command returns JSON structured like this:

    {
      "user_name": "12345",
      "first_name": "Bilbo",
      "last_name": "Baggins",
      "email": "bilbo@myorg.com",
      "manager_email": "manager@company.com",
      "mentor_email": "mentor@company.com",
      "lms_learner_id":"456",
      "lms_reference":"Testlms",
      "type":"Client",
      "active": true,
      "role_1":"Sales",
      "X-[Custom]": "Custom Field, see top of page for details."
    }
    

    This endpoint creates a new person. You can also enrol a person in a topic, article or pathway with enrolment fields. See http://support.tribalhabits.com/admin-enrolments/how-can-i-enrol-people-into-knowledge-via-a-spreadsheet for explanation of enrolment codes.

    HTTP Request

    POST https://myorg.tribalhabits.com/papi/users

    Request body fields

    Field Required Description
    user_name Yes Unique identifier for the new user
    first_name Yes User's first name -- used for display purposes
    last_name Yes User's last name -- used for display purposes
    email Yes User's email address (must be unique within your organisation) -- used for email notifications
    type No Type of user -- Staff (default value), Client or Prospect
    manager_N_email No Email address of the user's N manager -- used for email notifications. Where N can be 1..5.
    mentor_email No Email address of the user's mentor -- used for email notifications
    lms_learner_id No User's id in company LMS -- used for matching users in Tribal Habits
    lms_reference No Company LMS name -- used for matching users in Tribal Habits
    active No Specify false to create user account but disable login
    org_admin No Specify true to allow this user to become an administrator
    role_N No Role N assigned to user. Where N can be 1..5.
    send_invitation No Specify true to send an invitation email to new user.
    X-[Custom] No Custom field. See top of page for details.

    Get a specific user

    curl "https://myorg.tribalhabits.com/papi/users/12345"
      -H "Authorization: my_api_key"
    

    The above command returns JSON structured like this:

    {
      "user_name": "12345",
      "first_name": "Bilbo",
      "last_name": "Baggins",
      "email": "bilbo@myorg.com",
      "type": "Staff",
      "manager_email": "manager@company.com",
      "manager_2_email": null,
      "manager_3_email": null,
      "manager_4_email": null,
      "manager_5_email": null,
      "mentor_email": "mentor@company.com",
      "lms_learner_id":"456",
      "lms_reference":"Testlms",
      "type":"Client",
      "active": true,
      "role_1":"Sales",
      "X-[Custom]": "Custom Field, see top of page for details."
    }
    

    This endpoint retrieves a specific user.

    HTTP request

    GET https://myorg.tribalhabits.com/papi/users/USER_NAME

    URL parameters

    Parameter Description
    USER_NAME The unique identifier of the person to retrieve

    Update a specific user

    curl "https://myorg.tribalhabits.com/papi/users/12345"
      -H "Authorization: my_api_key"
      -H "Content-Type: application/json"
      -X PUT
      -d '<request_body>'

    Example request body:

    {
      "active": false
    }
    

    The above command returns JSON structured like this:

    {
      "user_name": "12345",
      "first_name": "Bilbo",
      "last_name": "Baggins",
      "email": "bilbo@myorg.com",
      "type": "Staff",
      "manager_email": "manager@company.com",
      "mentor_email": "mentor@company.com",
      "lms_learner_id":"456",
      "lms_reference":"Testlms",
      "active": false,
      "role_1":"Sales",
      "X-[Custom]": "Custom Field, see top of page for details."
    }
    

    This endpoint updates a specific user. Only fields that are supplied will be updated.

    See http://support.tribalhabits.com/admin-enrolments/how-can-i-enrol-people-into-knowledge-via-a-spreadsheet for explanation of enrolment codes.

    HTTP request

    PUT https://myorg.tribalhabits.com/papi/users/USER_NAME

    URL parameters

    Parameter Description
    USER_NAME The unique identifier of the person to update

    Request body fields

    Field Required Description
    first_name No User's first name -- used for display purposes
    last_name No User's last name -- used for display purposes
    email No User's email address (must be unique within your organisation) -- used for email notifications
    type No Type of user -- Staff (default value), Client or Prospect
    manager_N_email No Email address of the user's Nth manager -- used for email notifications. Where N can be 1..5.
    mentor_email No Email address of the user's mentor -- used for email notifications
    lms_learner_id No User's id in company LMS -- used for matching users in Tribal Habits
    lms_reference No Company LMS name -- used for matching users in Tribal Habits
    active No Specify false to create user account but disable login
    org_admin No Specify true to allow this user to become an administrator
    role_N No Role N assigned to user. Where N can be 1..5.
    X-[Custom] No Custom field. See top of page for details.

    Batch create / update

    curl "https://myorg.tribalhabits.com/papi/users/batch_save"
      -H "Authorization: my_api_key"
      -H "Content-Type: application/json"
      -X POST
      -d '<request_body>'

    Example request body:

    {
      "people":
        [
          {
            "user_name": "12345",
            "first_name": "Bilbo",
            "last_name": "Baggins",
            "email": "bilbo@myorg.com"
          },
          {
            "user_name": "12346",
            "first_name": "Frodo",
            "last_name": "Baggins",
            "email": "frodo@myorg.com"
          }
        ]
    }
    

    The above command returns JSON structured like this:

    {
      "created": 2,
      "updated": 0,
      "unchanged": 0
    }

    The following would also be a legal request body to deactivate 2 existing users:

    {
      "people":
        [
          {
            "user_name": "12345",
            "active": false
          },
          {
            "user_name": "12346",
            "active": false
          }
        ]
    }
    

    This endpoint enables you to create and/or update multiple users at one time. The requirements and semantics for create and update are as outlined above.

    HTTP request

    POST https://myorg.tribalhabits.com/papi/users/batch_save

    Request body fields

    Field Required Description
    people Yes An array of user objects whereby each user must include a user_name attribute denoting the unique id of the user to be created or updated.

    Topics and Articles

    Topic or Article.

    Get all topics and articles

    curl "https://myorg.tribalhabits.com/papi/topics"
      -H "Authorization: my_api_key"
    

    The above command returns JSON structured like this:

    {
      "total_records": 47,
      "max_per_page": 25,
      "current_page": 1,
      "total_pages": 2,
      "records": 
        [
          {
            "id":16,
            "title":"A topic title",
            "structure":"facts",
            "published_at":null,
            "assessment":true,
            "num_assessment_questions_to_ask":3,
            "num_assessment_questions_to_pass":1,
            "num_assessment_resets_permitted":3,
            "duration_in_minutes":12,
            "free":false,
            "restricted":false,
            "due_mode":"none",
            "due_date":null,
            "due_in_days":null,
            "visibility":"private",
            "allow_public_signup":false,
            "show_accessibility_section_headers":false,
            "show_narration_scripts":false,
            "knowledge_type":0,
            "manager_enrol":false,
            "certified_mode":"none",
            "certified_days":null,
            "certified_date":null,
            "show_certificate":true,
            "certificate_expire_event":0,
            "recertify":false,
            "recertification_days":0,
            "categories":[
              {
                "id":1,
                "name":"Sales",
                "show_explorers":true,
                "time_allocation":null,
                "points_allocation":null
              } 
            ],
            "topic_categories":[
              {
                "id":34,
                "category_id":6,
                "time_allocation":70,
                "points_allocation":0
              }
    ], "skills":[ { "id":13, "name":"First Aid" } ], "links":{ "standard":"https://myorg.tribalhabits.com/topics/16/explore", "internal_enrol":"https://myorg.tribalhabits.com/internals/437fafd440cdde8a4cb13955217f96ac", "external_enrol":"https://myorg.tribalhabits.com/externals/437fafd440cdde8a4cb13955217f96ac", "enrol_links":[ { "id":36, "entity_type":0, "link_type":1, "url":"https://myorg.tribalhabits.com/externals/437fafd440cdde8a4cb13955217f96ac", "reference":"testExt", "active":true, "lms_enrolments_count":0, "enrolment_limit":0 }, { "id":35, "entity_type":0, "link_type":0, "url":"https://myorg.tribalhabits.com/internals/437fafd440cdde8a4cb13955217f96ac", "reference":"testInt", "active":true, "lms_enrolments_count":0, "enrolment_limit":0 } ] }, "saved_searches":[ { "id":47, "q":[ { "op":"in", "attr":"category", "name":"Type", "values":[ "staff" ], "description":" Type is Staff" } ] } ], "version":{ "major":1, "minor":0, "created_at":"2019-07-01T15:23:56.815+10:00" }, "code":"TH-4-16", "scorm_file_count":0
    }, ... ] }

    In this example, you could get the remaining topics with

    curl "https://myorg.tribalhabits.com/papi/topics?page=2"
      -H "Authorization: my_api_key"
    

    This endpoint retrieves all topics and articles (paginated).

    knowledge_type can be either 0 or 1. Where 0 = topic, 1 = article.

    HTTP request

    GET https://myorg.tribalhabits.com/papi/topics

    Query parameters

    Parameter Default Description
    page 1 Results page to return
    max_per_page 25 Maximum number of results per page

    Get a specific topic

    curl "https://myorg.tribalhabits.com/papi/topics/12345"
      -H "Authorization: my_api_key"
    

    The above command returns JSON structured like this:

    {
      "id":16,
      "title":"A topic title",
      "structure":"facts",
      "published_at":null,
      "assessment":true,
      "num_assessment_questions_to_ask":3,
      "num_assessment_questions_to_pass":1,
      "num_assessment_resets_permitted":3,
      "duration_in_minutes":12,
      "free":false,
      "restricted":false,
      "due_mode":"none",
      "due_date":null,
      "due_in_days":null,
      "visibility":"private",
      "allow_public_signup":false,
      "show_accessibility_section_headers":false,
      "show_narration_scripts":false,
      "knowledge_type":0,
      "manager_enrol":false,
      "certified_mode":"none",
      "certified_days":null,
      "certified_date":null,
      "show_certificate":true,
      "certificate_expire_event":0,
      "recertify":false,
      "recertification_days":0,
      "categories":[
        {
          "id":1,
          "name":"Sales",
          "show_explorers":true,
          "time_allocation":null,
          "points_allocation":null
        } 
      ],
      "topic_categories":[
        {
          "id":34,
          "category_id":6,
          "time_allocation":70,
          "points_allocation":0
        }
    ], "skills":[ { "id":13, "name":"First Aid" } ], "links":{ "standard":"https://myorg.tribalhabits.com/topics/16/explore", "internal_enrol":"https://myorg.tribalhabits.com/internals/437fafd440cdde8a4cb13955217f96ac", "external_enrol":"https://myorg.tribalhabits.com/externals/437fafd440cdde8a4cb13955217f96ac", "enrol_links":[ { "id":36, "entity_type":0, "link_type":1, "url":"https://myorg.tribalhabits.com/externals/437fafd440cdde8a4cb13955217f96ac", "reference":"testExt", "active":true, "lms_enrolments_count":0, "enrolment_limit":0 }, { "id":35, "entity_type":0, "link_type":0, "url":"https://myorg.tribalhabits.com/internals/437fafd440cdde8a4cb13955217f96ac", "reference":"testInt", "active":true, "lms_enrolments_count":0, "enrolment_limit":0 } ] }, "saved_searches":[ { "id":47, "q":[ { "op":"in", "attr":"category", "name":"Type", "values":[ "staff" ], "description":" Type is Staff" } ] } ], "version":{ "major":1, "minor":0, "created_at":"2019-07-01T15:23:56.815+10:00" }, "code":"TH-4-16", "scorm_file_count":0
    }

    This endpoint retrieves a specific topic.

    HTTP request

    GET https://myorg.tribalhabits.com/papi/topics/ID

    URL parameters

    Parameter Description
    ID The unique identifier of a topic

    Pathways

    Pathways

    Get all pathways

    curl "https://myorg.tribalhabits.com/papi/pathways"
      -H "Authorization: my_api_key"
    

    The above command returns JSON structured like this:

    {
      "total_records":12,
      "max_per_page":25,
      "current_page":1,
      "total_pages":1,
      "records": 
        [
          {
           "num_complete_optional_topics":0,
           "manager_enrol":false,
           "certified_mode":"fixed_time",
           "certified_days":365,
           "certified_date":null,
           "show_certificate":false,
           "certificate_expire_event":1,
           "recertify":true,
           "recertification_days":12,
           "categories":[
              {
                 "id":8,
                 "name":"Health"
              }
    ], "skills":[ { "id":7, "name":"Manager1" } ], "links":{ "internal_enrol":"https://myorg.tribalhabits.com/internals/641960a27e9fdf42c689f0e265fbf2f4" }, "saved_searches":[ { "id":61, "q":[ { "op":"in", "attr":"category", "name":"Type", "values":[ "staff" ], "description":" Type is Staff" } ] } ], "code":"THP-4-22" }, ... ] }

    In this example, you could get the remaining pathways with

    curl "https://myorg.tribalhabits.com/papi/pathways?page=2"
      -H "Authorization: my_api_key"
    

    This endpoint retrieves all pathways (paginated).

    HTTP request

    GET https://myorg.tribalhabits.com/papi/pathways

    Query parameters

    Parameter Default Description
    page 1 Results page to return
    max_per_page 25 Maximum number of results per page

    Get a specific pathway

    curl "https://myorg.tribalhabits.com/papi/pathways/12345"
      -H "Authorization: my_api_key"
    

    The above command returns JSON structured like this:

    {
     "num_complete_optional_topics":0,
     "manager_enrol":false,
     "certified_mode":"fixed_time",
     "certified_days":365,
     "certified_date":null,
     "show_certificate":false,
     "certificate_expire_event":1,
     "recertify":true,
     "recertification_days":12,
     "categories":[
        {
           "id":8,
           "name":"Health"
        }
    ], "skills":[ { "id":7, "name":"Manager1" } ], "links":{ "internal_enrol":"https://myorg.tribalhabits.com/internals/641960a27e9fdf42c689f0e265fbf2f4" }, "saved_searches":[ { "id":61, "q":[ { "op":"in", "attr":"category", "name":"Type", "values":[ "staff" ], "description":" Type is Staff" } ] } ], "code":"THP-4-22" }

    This endpoint retrieves a specific pathway.

    HTTP request

    GET https://myorg.tribalhabits.com/papi/pathways/ID

    URL parameters

    Parameter Description
    ID The unique identifier of a pathway

    Enrolments

    Topic, Article and Pathway Enrolments

    Get all topic/article enrolments

    curl "https://myorg.tribalhabits.com/papi/topic_assignments"
      -H "Authorization: my_api_key"
    

    The above command returns JSON structured like this:

    {
      "total_records":371,
      "max_per_page":25,
      "current_page":1,
      "total_pages":15,
      "records":[
        {
          "id":6,
          "created_at":"2019-04-01T18:03:15.966+11:00",
          "completed_topic_at":"2019-10-23T15:27:09.829+11:00",
          "status":"Conquered",
          "due_date":null,
          "relationship":"reader",
          "conquered_minutes":7,
          "conquered_cpd_minutes":7,
          "enrolled_by":"PAPI",
          "certified_date":null,
          "recertification_allowed":true,
          "version":null,
          "skills_attained":[{
             "id":13,
             "name":"First Aid"
          }],
          "categories":[
            {
              "name":"Health",
              "minutes":39.5,
              "points":500
            }
    ], "person":{ "id":2, "name":"User1", "user_name": "12345", "link":"/people/users/7" }, "topic":{ "id":3, "title":"Confident and effective business networking", "link":"/knowledge/topics/3/overview", "knowledge_type":0, "show_certificate":true } }, ... ] }

    In this example, you could get the remaining topic/article enrolments with

    curl "https://myorg.tribalhabits.com/papi/topic_assignments?page=2"
      -H "Authorization: my_api_key"
    

    This endpoint retrieves all topic/article enrolments (paginated).

    HTTP request

    GET https://myorg.tribalhabits.com/papi/topic_assignments

    Query parameters

    Parameter Default Description
    page 1 Results page to return
    max_per_page 25 Maximum number of results per page

    Get a specific topic/article enrolment

    curl "https://myorg.tribalhabits.com/papi/topic_assignments/12345"
      -H "Authorization: my_api_key"
    

    The above command returns JSON structured like this:

    {
      "id":12345,
      "created_at":"2019-04-01T18:03:15.966+11:00",
      "completed_topic_at":"2019-10-23T15:27:09.829+11:00",
      "status":"Conquered",
      "due_date":null,
      "relationship":"reader",
      "conquered_minutes":7,
      "conquered_cpd_minutes":7,
      "enrolled_by":"PAPI",
      "certified_date":null,
      "recertification_allowed":true,
      "version":null,
      "skills_attained":[{
         "id":13,
         "name":"First Aid"
      }],
      "categories":[
        {
          "name":"Health",
          "minutes":39.5,
          "points":500
        }
    ], "person":{ "id":2, "name":"User1", "user_name": "12345", "link":"/people/users/7" }, "topic":{ "id":3, "title":"Confident and effective business networking", "link":"/knowledge/topics/3/overview", "knowledge_type":0, "show_certificate":true } }

    This endpoint retrieves a specific topic/article enrolment.

    HTTP request

    GET https://myorg.tribalhabits.com/papi/topic_assignments/ID

    URL parameters

    Parameter Description
    ID The unique identifier of a topic/article enrolment

    Get all pathway enrolments

    curl "https://myorg.tribalhabits.com/papi/pathway_assignments"
      -H "Authorization: my_api_key"
    

    The above command returns JSON structured like this:

    {
      "total_records":371,
      "max_per_page":25,
      "current_page":1,
      "total_pages":15,
      "records":[
        {
          "id":2,
          "created_at":"2019-08-08T15:51:31.424+10:00",
          "conquered_at":null,
          "status":"Unexplored",
          "due_date":"2019-12-03T10:54:00.000+11:00",
          "enrolled_by":"PAPI",
          "certified_date":null,
          "recertification_allowed":true,
          "skills_attained":[{
            "id":13,
            "name":"First Aid"
          }],
          "person":{
            "id":4,
            "name":"UserB",
            "user_name": "12345",
            "link":"/people/users/6"
          },
          "pathway":{
            "id":1,
            "title":"Test Pathway ABC",
            "link":"/knowledge/pathways/1/overview",
            "show_certificate":true
          }
        },
           ...
        ]
    }
    

    In this example, you could get the remaining pathway_enrolments with

    curl "https://myorg.tribalhabits.com/papi/pathway_assignments?page=2"
      -H "Authorization: my_api_key"
    

    This endpoint retrieves all pathway_enrolments (paginated).

    HTTP request

    GET https://myorg.tribalhabits.com/papi/pathway_assignments

    Query parameters

    Parameter Default Description
    page 1 Results page to return
    max_per_page 25 Maximum number of results per page

    Get a specific pathway enrolment

    curl "https://myorg.tribalhabits.com/papi/pathway_assignments/2"
      -H "Authorization: my_api_key"
    

    The above command returns JSON structured like this:

    {
      "id":2,
      "created_at":"2019-08-08T15:51:31.424+10:00",
      "conquered_at":null,
      "status":"Unexplored",
      "due_date":"2019-12-03T10:54:00.000+11:00",
      "enrolled_by":"PAPI",
      "certified_date":null,
      "recertification_allowed":true,
      "skills_attained":[{
        "id":13,
        "name":"First Aid"
      }],
      "person":{
        "id":4,
        "name":"UserB",
        "user_name": "12345",
        "link":"/people/users/6"
      },
      "pathway":{
        "id":1,
        "title":"Test Pathway ABC",
        "link":"/knowledge/pathways/1/overview",
        "show_certificate":true
      }
    }
    

    This endpoint retrieves a specific pathway enrolment.

    HTTP request

    GET https://myorg.tribalhabits.com/papi/pathway_assignments/ID

    URL parameters

    Parameter Description
    ID The unique identifier of a pathway enrolment

    Create or Update a topic/article/pathway enrolment

    curl "https://myorg.tribalhabits.com/papi/topic_assignments"
      -H "Authorization: my_api_key"
      -H "Content-Type: application/json"
      -X POST
      -d '<request_body>'

    Example request body:

    {
      "user_name": "user1@example.com", 
      "enrolment_code_1": "TH-4-77-NEW",
      "enrolment_code_1_due_date": "31/12/2021"
    }
    

    The above command returns JSON structured like this:

    {
      "id":12345,
      "created_at":"2019-04-01T18:03:15.966+11:00",
      "completed_topic_at":"2019-10-23T15:27:09.829+11:00",
      "status":"Conquered",
      "due_date":null,
      "relationship":"reader",
      "conquered_minutes":7,
      "conquered_cpd_minutes":7,
      "enrolled_by":"PAPI",
      "certified_date":null,
      "recertification_allowed":true,
      "version":null,
      "skills_attained":[{
         "id":13,
         "name":"First Aid"
      }],
      "categories":[
        {
          "name":"Health",
          "minutes":39.5,
          "points":500
        }
    ], "person":{ "id":2, "name":"user1@example.com", "user_name": "12345", "link":"/people/users/7" }, "topic":{ "id":3, "title":"Confident and effective business networking", "link":"/knowledge/topics/3/overview", "knowledge_type":0, "show_certificate":true } }

    This endpoint creates or updates a new topic/article/pathway enrolment.

    HTTP Request

    POST https://myorg.tribalhabits.com/papi/topic_assignments

    Request body fields

    Field Required Description
    user_name Yes User name identifier
    enrolment_code_N Yes The enrolment code as defined in http://support.tribalhabits.com/admin-enrolments/how-can-i-enrol-people-into-knowledge-via-a-spreadsheet. Where N is from 1..5.
    enrolment_code_N_due_date No When the enrolment is due. Where N is from 1..5.
    enrolment_code_N_conquered_date No When the enrolment was conquered. Where N is from 1..5.
    enrolment_code_N_certified_date No When the enrolment is certified up to. Where N is from 1..5.

    External Knowledge

    Knowledge obtained from a source external of Tribal Habits.

    Get all external_knowledges

    curl "https://myorg.tribalhabits.com/papi/external_knowledges"
      -H "Authorization: my_api_key"
    

    The above command returns JSON structured like this:

    {
      "total_records": 47,
      "max_per_page": 25,
      "current_page": 1,
      "total_pages": 2,
      "records": 
        [
          {
            "knowledge_type":1,
            "title":"title1",
            "code":"code1",
            "provider":"prov1",
            "date_obtained":"2021-06-01",
            "certificate_number":"CI1",
            "country_obtained":"AU",
            "state_obtained":"NSW",
            "expires":null,
            "qualification_level":null,
            "assessment_score":1.0,
            "total_time":2,
            "notes":"Notes",
            "klass":"ClassA"
          },
          ...
        ]
    }
    

    In this example, you could get the remaining external_knowledges with

    curl "https://myorg.tribalhabits.com/papi/external_knowledges?page=2"
      -H "Authorization: my_api_key"
    

    This endpoint retrieves all external_knowledges (paginated).

    HTTP request

    GET https://myorg.tribalhabits.com/papi/external_knowledges

    Query parameters

    Parameter Default Description
    page 1 Results page to return
    max_per_page 25 Maximum number of results per page

    Get a specific external knowledge

    curl "https://myorg.tribalhabits.com/papi/external_knowledges/12345"
      -H "Authorization: my_api_key"
    

    The above command returns JSON structured like this:

    {
      "knowledge_type":1,
      "title":"title1",
      "code":"code1",
      "provider":"prov1",
      "date_obtained":"2021-06-01",
      "certificate_number":"CI1",
      "country_obtained":"AU",
      "state_obtained":"NSW",
      "expires":null,
      "qualification_level":null,
      "assessment_score":1.0,
      "total_time":2,
      "notes":"Notes",
      "klass":"ClassA"
    }
    

    This endpoint retrieves a specific external knowledge.

    HTTP request

    GET https://myorg.tribalhabits.com/papi/external_knowledges/ID

    URL parameters

    Parameter Description
    ID The unique identifier of a external knowledge

    Create a new external knowledge

    curl "https://myorg.tribalhabits.com/papi/external_knowledges"
      -H "Authorization: my_api_key"
      -H "Content-Type: application/json"
      -X POST
      -d '<request_body>'

    Example request body:

    {
      "user_name": "johnny", 
      "title":"title1",
      "provider":"prov1",
      "knowledge_type":"1",
      "date_obtained":"1/6/2021"
    }
    

    The above command returns JSON structured like this:

    {
      "knowledge_type":1,
      "title":"title1",
      "code":"code1",
      "provider":"prov1",
      "date_obtained":"2021-06-01",
      "certificate_number":"CI1",
      "country_obtained":"AU",
      "state_obtained":"NSW",
      "expires":null,
      "qualification_level":null,
      "assessment_score":1.0,
      "total_time":2,
      "notes":"Notes",
      "klass":"ClassA"
    }
    

    This endpoint creates a new external knowledge.

    HTTP Request

    POST https://myorg.tribalhabits.com/papi/external_knowledges

    Request body fields

    Field Required Description
    user_name Yes Unique identifier for the new user
    knowledge_type Yes A choice of [1,2,3,4], where 1 = Training, 2 = Certification, 3 = Qualification, 4 = License
    title Yes Title of external knowledge
    code No Optional code for the external knowledge
    provider Yes Provider
    date_obtained Yes The date you obtained this knowledge
    certificate_number No Certificate Number
    country_obtained No Country in code form (eg 'AU' for Australia)
    state_obtained No State or Region in code form (eg 'NSW')
    expires No Date the knowledge expires
    qualification_level No Qualification
    assessment_score No Assessment score as a decimal, eg 1.2
    total_time No Time in minutes
    notes No Notes
    klass No Class of knowledge
    skill_N No Skill name attained in the knowledge. Where N is 1..3.
    category_N No Category name attained in the knowledge. Where N is 1..3.
    category_N_points No Points for the category. Where N is 1..3.
    category_N_time No Time in minutes for the category. Where N is 1..3.

    The country and region codes can be found in this site: https://github.com/country-regions/country-region-data/blob/master/data.json

    Update an external knowledge

    curl "https://myorg.tribalhabits.com/papi/external_knowledges/12345"
      -H "Authorization: my_api_key"
      -H "Content-Type: application/json"
      -X PUT
      -d '<request_body>'
    

    Example request body:

    {
      "user_name": "johnny", 
      "title":"title1",
      "provider":"prov1",
      "knowledge_type":"1",
      "date_obtained":"1/6/2021"
    }
    

    The above command returns JSON structured like this:

    {
      "knowledge_type":1,
      "title":"title1",
      "code":"code1",
      "provider":"prov1",
      "date_obtained":"2021-06-01",
      "certificate_number":"CI1",
      "country_obtained":"AU",
      "state_obtained":"NSW",
      "expires":null,
      "qualification_level":null,
      "assessment_score":1.0,
      "total_time":2,
      "notes":"Notes",
      "klass":"ClassA"
    }
    

    This endpoint updates an existing external knowledge.

    HTTP Request

    PUT https://myorg.tribalhabits.com/papi/external_knowledges/ID

    URL parameters

    Parameter Description
    ID The unique identifier of an external knowledge

    Request body fields

    Field Required Description
    knowledge_type No A choice of [1,2,3,4], where 1 = Training, 2 = Certification, 3 = Qualification, 4 = License
    title No Title of external knowledge
    code No Optional code for the external knowledge
    provider No Provider
    date_obtained No The date you obtained this knowledge
    certificate_number No Certificate Number
    country_obtained No Country in code form (eg 'AU' for Australia)
    state_obtained No State or Region in code form (eg 'NSW')
    expires No Date the knowledge expires
    qualification_level No Qualification
    assessment_score No Assessment score as a decimal, eg 1.2
    total_time No Time in minutes
    notes No Notes
    klass No Class of knowledge

    The country and region codes can be found in this site: https://github.com/country-regions/country-region-data/blob/master/data.json

    Errors

    The Tribal Habits API uses the following error codes:

    Error code Meaning
    400 Bad Request -- The request does not include a required parameter. See the response body for more details
    401 Unauthorized -- The request does include the API key or the API key is incorrect
    404 Not Found -- The specified resource could not be found
    406 Not Acceptable -- You requested a format that isn't json
    422 Unprocessable entity -- The record you are creating or updating is not valid (e.g. not an email address). See the response body for more details
    429 Too Many Requests -- You're making too many requests! Please slow down!
    500 Internal Server Error -- Dang! We had a problem with our server. Please let us know about it
    503 Service Unavailable -- We're temporarily offline for maintenance. Please try again later

    Please contact us if you encounter an error where the cause of the problem is not immediately clear from the response code and/or body!

    Rate limits

    We haven't implemented any rate limiting yet but reserve the right to do so later.

    Documentation powered by Slate