NAV Navbar
Examples
  • Introduction
  • Authentication
  • Users
  • 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).

    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

    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 "http://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": null,
            "active": true,
            "X-Country": "Australia",
            "X-State": "QLD"
          },
          ...
        ]
    }
    

    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",
      "X-Country": "Australia",
      "X-State": "QLD"
    }
    

    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": null,
      "active": true,
      "X-Country": "Austalia",
      "X-State": null,
    }
    

    This endpoint creates a new person.

    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_email No Email address of the user's manager -- used for email notifications
    active No Specify false to create user account but disable login
    X-Country No Assumes organisation has defined a custom field called Country
    X-State No Assumes organisation has defined a custom field called State

    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": null,
      "active": true,
      "X-Country": "Australia",
      "X-State": "QLD"
    }
    

    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": null,
      "active": false,
      "X-Country": "Austalia",
      "X-State": null,
    }
    

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

    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_email No Email address of the user's manager -- used for email notifications
    active No Specify false to deactivate an account or true to re-activate
    X-Country No Assumes organisation has defined a custom field called Country
    X-State No Assumes organisation has defined a custom field called State

    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.

    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