Users

List all users in Skillhive

This is also the main endpoint for searching for users.

Endpoint: /api/v2/users

Method	Action	Parameters
GET	List users	`offset`: `int` fetch profiles starting from (optional, default: 0) `limit`: `int` how many profiles to get (optional, default: 20, limit 0-50) Optional search options: `query` A generic search term to search for `skills[]` Match users by these skills. Optional sort parameters: `name` Sort in alphabetical order (default) `competence` Sort by matched competence (only available when searching users by skills) `interest` Sort by matched interest (only available when searching users by skills) `recommendations` Sort by the number of recommendations the users have got (only available when searching users by skills) `price` Sort by user defined price (only available in select sites)

An example of a return response:

{
  "data": [ // The returned user collection
    { // A user object
      "type": "users",
      "id": "12345",      // The user id
      "attributes": {     // User attributes
        "first-name": "Jaakko",
        "last-name": "Naakka",
        "email": "jaakko.naakka@intunex.fi",
        "description": "",
        "location": [
          "Finland",
          "Akaa"
        ],
        "unit": [
          "Development"
        ],
        "phone": [
          "123455"
        ],
        "mobile": [
          "123466"
        ],
        "is-enabled": true,
        "access-level": "admin",
        "img-url": {
          "small": "<Absolute URL to small version of user icon>",
          "medium": "Absolute <URL to medium version of user icon>",
          "large": "Absolute <URL to large version of user icon>"
          "xlarge": "Absolute <URL to extra large version of user icon>"
          "master": "Absolute <URL to the original version of user icon>"
        },
        "competence": 0,      // Competence, interest and...
        "interest": 0,        // ... recommendations are only available
        "recommendations": 0, // ... when you're searching users by skills.
        "created-at": "Thu, 07 Jun 2012 15:25:42 +0300",
        "updated-at": "Thu, 14 Sep 2017 11:36:17 +0300",
        "price": 145, // Prices are only used in some sites
        "price2": 8.45,
        "price3": 780,
        "alt-id": "cds7csd9423423" // An alternate id used only to identify user accounts in other services
      },
      "links": {
        "self": "/api/v2/users/2972"  // API link to the user profile itself
      }
    },
    ... // More user accounts.
  ],
  "meta": {
    "total-count": 145 // Number of user account.
  }
}

Get or update a single user

Endpoint: /api/v2/users/:user_id

Method	Action	Parameters
GET	Get user profile defined by `user_id`	N/A
PATCH	Update a user profile identified by `user_id`	N/A

Get a Single User

An example of a return response to a GET request:

{
  "data": {
    "type": "users",
    "id": "12345",      // The user id
    "attributes": {     // User attributes
      "first-name": "Jaakko",
      "last-name": "Naakka",
      "email": "jaakko.naakka@intunex.fi",
      "description": "",
      "location": [
        "Finland",
        "Akaa"
      ],
      "unit": [
        "Development"
      ],
      "phone": [
        "123455"
      ],
      "mobile": [
        "123466"
      ],
      "is-enabled": true,
      "access-level": "admin",
      "img-url": {
        "small": "<Absolute URL to small version of user icon>",
        "medium": "Absolute <URL to medium version of user icon>",
        "large": "Absolute <URL to large version of user icon>"
        "xlarge": "Absolute <URL to extra large version of user icon>"
        "master": "Absolute <URL to the original version of user icon>"
      },
      "is-supervisor": true,
      "competence": 0,      // Competence, interest and...
      "interest": 0,        // ... recommendations are only available
      "recommendations": 0, // ... when you're searching users by skills.
  "terms-accepted-at": "Wed, 21 Feb 2018 20:50:26 +0200",
      "created-at": "Thu, 07 Jun 2012 15:25:42 +0300",
      "updated-at": "Thu, 14 Sep 2017 11:36:17 +0300",
      "price": 145, // Prices are only used in some sites
      "price2": 8.45,
      "price3": 780,
      "alt-id": "cds7csd9423423", // An alternate id used only to identify user accounts in other services
      "feedback-avg": 3.45,
      "feedback-avg-latest": 4.49,
      "feedback-avg-latest-at": "Mon, 20 Feb 2023 08:25:42 +0300",
    }
  },
  relationships": {
    "roles": {
      "data": [
        {
          "type": "userroles",
          "id": "47244"
        },
        {
          "type": "userroles",
          "id": "14251"
        }
      ]
    }    
  },
  "included": [
    {
      "type": "userroles",
      "id": "47244",
      "attributes": {
        "title": "Software Developers"
      }
    },
    {
      "type": "userroles",
      "id": "14251",
      "attributes": {
        "title": "Design Team"
      }
    },
  ]
}

Update a single user

Here's an example PATCH request to update a user's first and last name. When updating a user profile, it's only necessary to send the values for the updated fields.

Here's en example json data for a PATCH request to /api/v2/users/12345

{
    "data": {
    "attributes": {
      "first-name": "Jane",
      "last-name": "Doe"
    }
  }
}

The return response will include the full, updated user profile.

The Return Response

As you can see, when you fetch a single user profile, the response includes a lot more information about the user than the generic list endpoint does.

The relationships key includes some details about the relationships the user has to some other types of models. In this case, it describes all the roles the user has. This is very convenient, as you can get a lot more information about the user in a single GET request.

The included key holds a list of some objects (or partial objects) that are included in the response. In this case it includes partial details about the roles the user has. This includes just the title and the id of the user role. This information is enough to show what roles the user has and create links to the user roles themselves.

Here is a more detailed description of all the user attributes and how to update them:

Attribute	Type	Required	Notes
id	string	true	ID is always provided by Skillhive and it cannot be changed. At the moment, all ids are of type `int` but this will change into strings in the future.
first-name	string	true	First name of the user.
last-name	string	true	Last name of the user.
email	string	true
description	string	false	The description summary of the user.
location	array	false	An array of strings.
unit	array	false	An array of strings.
additional-info	string	false	Additional info used only in some customer sites. Max length 300 characters.
phone	array	false	Array of phone numbers as strings.
mobile	array	false	Array of mobile numbers as strings.
job-title	array	false	Array of strings.
website	array	false	Array of strings.
skype	array	false	Array of strings.
linkedin	array	false	Array of strings. The absolute URL to LinkedIn profile. Notice, this is updated automatically when user authorizes Skillhive to fetch their LinkedIn profile data. This value cannot be changed in Skillhive.
twitter	array	false	Array of strings.
is-enabled	boolean	true	A simple boolean stating if the user account is enabled or not. Disabled users cannot log in and will not show up in user listings or searches. NOTICE! This value can only be changed by administrators and not the users themselves.
is-supervisor	boolean	true	Is the user a supervisor of any other users. This value cannot be updated through the API, it's calculated based on user relationships.
access-level	string	true	User's access level. Allowed values are `user`, `admin`, `ext` and `excluded`. NOTICE! This value can only be changed by administrators and not he users themselves.
price	double	false	Price is only used in some sites. Notice, sorting user accounts in search results is only possible based on `price` atteibute, not `price2` or `price3`.
price2	double	false	Price is only used in some sites. Notice, sorting user accounts in search results is only possible based on `price` atteibute, not `price2` or `price3`.
price3	double	false	Price is only used in some sites. Notice, sorting user accounts in search results is only possible based on `price` atteibute, not `price2` or `price3`.
alt-id	string	false	An alternate id that's only used in integrations to other service.
terms-accepted-at	string	false	A timestamp when the user accepted the terms of service. `null` if terms are not accepted yet.
feedback-avg	float	false	All time average for user feedback. Value range is 0.00 - 9.99.
feedback-avg-latest	float	false	Average feedback for the latest training. Value range is 0.00 - 9.99.
feedback-avg-latest-at	string	false	Datetime of latest feedback received.

Create a new user

Endpoint: /api/v2/users

Method	Action	Parameters
POST	Create user

You can add new user accounts to Skillhive by doing a POST request to the api endpoint. Here's an example request to post:

{
  "data": {
    "type": "users",
    "attributes": {     // User attributes
      "first-name": "Jaakko",
      "last-name": "Naakka",
      "email": "jaakko.naakka@intunex.fi",
    }
  }
}

The API endpoint will return a 201 Created response with all the data for the newly created user. The data includes all the same data you get when you're fetching a single user by id. If a non-admin user tries to create new user accounts, they will get a 403 Forbidden response instead.