NAV Navbar
  • Introduction
  • Authentication
  • Token Scopes
  • Rate limiting
  • Errors
  • User Management
  • Channel Management
  • Learning Records
  • Introduction

    Welcome to the SmartUp API! You can use our API to access SmartUp API endpoints, which can get information on various users, channels and learning records in our database.

    Authentication

    SmartUp uses standard OAuth2.0 Client Credentials flow to issue tokens for apps or 3rd party systems.

    Obtaining access token

    You can obtain an OAuth token by POSTing to the /oauth/token resource.

    In order to obtain a token send the following JSON to /oauth/token

    {
      "grant_type": "client_credentials",
      "client_id": "YOUR_CLIENT_ID",
      "client_secret": "YOUR_CLIENT_SECRET"
    }
    

    Response should look like the following

    {
      "access_token": "AN_ACCESS_TOKEN",
      "token_type": "bearer",
      "expires_in": 3600,
      "refresh_token": "A_REFRESH_TOKEN"
    }
    

    Using the access token

    On subsequent requests the caller must to provide a valid and non-expired access token otherwise HTTP 403 will be returned on each call. The access token has to be included in the standard HTTP Authorization header with type Bearer.

    The issued access token is a standard Json Web Token(JWT) signed with algorithm type RS256, using assymetric cryptography to provide the tokens integrity.

    Further information about standards:

    Refreshing the token

    Token Scopes

    Scopes define the actions that are available for a principal authenticating with a specific API token. Their purpose is to keep permissions on a "need-to-know" basis and to limit and separate responsibilities of 3rd party apps or systems.

    Scope Description
    users:read Read user profile
    users:write Write user profile
    channels:read Read channels
    lr:read Query learning record of users

    Rate limiting

    Errors

    The SmartUp API uses the following error codes:

    Error Code Meaning
    400 Bad Request -- Your request is invalid.
    401 Unauthorized -- Your API key is wrong.
    403 Forbidden -- The requested resource is not accessible for your security principal.
    404 Not Found -- The specified resource could not be found.
    405 Method Not Allowed -- You tried to access a resource with an invalid method.
    406 Not Acceptable -- You requested a format that isn't json.
    429 Too Many Requests -- You're requesting too many resources concurrently. We recommend an exponential backoff.
    500 Internal Server Error -- We had a problem with our server. Try again later.
    503 Service Unavailable -- We're temporarily offline for maintenance. Please try again later.

    User Management

    Get all users

    Retrieve all users from the community.

    The above command returns JSON structured like this:

    {
      "data": [
        {
          "id": 1,
          "first_name": "John",
          "last_name": "Smart",
          "username": "john.smart@acme.com",
          "email": "john.smart@acme.com",
          "member_type": "user",
          "enabled": true,
          "creation_timestamp": "2018-09-11T12:53:14",
          "reference": "WzFd"
        },
        {
          "id": 2,
          "first_name": "Jane",
          "last_name": "Smart",
          "username": "jane.smart@acme.com",
          "email": "jane.smart@acme.com",
          "member_type": "admin",
          "enabled": false,
          "creation_timestamp": "2018-09-11T12:53:14",
          "reference": "WzFd"
        }
      ],
      "has_more": false
    }
    

    This endpoint retrieves all users.

    HTTP Request

    GET https://api.smartup.io/api/v1/users

    Query Parameters

    Parameter Default Description
    enabled N/A If set to true, the result only includes enabled users. If set to false, the result only includes disabled users. If not set, returns both.
    starting_after N/A If set the result will contain elements after the reference.
    ending_before N/A If set the result will contain elements before the reference.
    limit 100 Number of records to retrieve.

    Get a specific user

    The above command returns JSON structured like this:

    {
      "id": 1,
      "first_name": "John",
      "last_name": "Smart",
      "username": "john.smart@acme.com",
      "email": "john.smart@acme.com",
      "member_type": "user",
      "enabled": true,
      "creation_timestamp": "2018-09-11T12:53:14"
    }
    

    This endpoint retrieves a specific user.

    HTTP Request

    GET https://api.smartup.io/api/v1/users/{id}

    URL Parameters

    Parameter Description
    id The id of the user to retrieve

    Get channels of a user

    The above command returns JSON structured like this:

    [
      {
        "id": 1,
        "name": "Compliance",
        "description": "This channel is all about compliance."
      },
      {
        "id": 2,
        "name": "Research",
        "description": "The place where the innovative things happen."
      }
    ]
    

    This endpoint retrieves all joined channels for a specific user.

    HTTP Request

    GET https://api.smartup.io/api/v1/users/{id}/channels

    URL Parameters

    Parameter Description
    id The id of the user

    Channel Management

    Get all channels

    Retrieve all channels from your community.

    The above command returns JSON structured like this:

    {
      "data": [
        {
          "id": 1,
          "name": "Compliance",
          "description": "This channel is all about compliance.",
          "privacy": "open",
          "auto_join": true,
          "auto_publish": true,
          "auto_join_toggleable": true,
          "status": "online",
          "channel_managers": [
            {
              "id": 1,
              "first_name": "John",
              "last_name": "Smart",
              "email": "john.smart@acme.com"
            },
            {
              "id": 2,
              "first_name": "Jane",
              "last_name": "Smart",
              "email": "jane.smart@acme.com"
            }
          ],
          "reference": "WzFd"
        },
        {
          "id": 2,
          "name": "Research",
          "description": "The place where the innovative things happen.",
          "privacy": "closed",
          "auto_join": false,
          "auto_publish": false,
          "auto_join_toggleable": true,
          "status": "offline",
          "channel_managers": [
            {
              "id": 3,
              "first_name": "Laura",
              "last_name": "Smart",
              "email": "laura.smart@acme.com"
            },
            {
              "id": 4,
              "first_name": "Rick",
              "last_name": "Smart",
              "email": "rick.smart@acme.com"
            }
          ],
          "reference": "WzFd"
        }
      ],
      "has_more": false
    }
    

    HTTP Request

    GET https://api.smartup.io/api/v1/channels

    Query Parameters

    Parameter Default Description
    status N/A If set to online, the result only includes online channels. If set to offline, the result only includes offline channels. If not set, returns both.
    starting_after N/A If specified the result will contain elements after the reference.
    ending_before N/A If specified the result will contain elements before the reference.
    limit 100 Number of records to retrieve.

    Get a specific channel

    The above command returns JSON structured like this:

    {
      "id": 1,
      "name": "Compliance",
      "description": "This channel is all about compliance.",
      "privacy": "open",
      "auto_join": true,
      "auto_publish": true,
      "auto_join_toggleable": true,
      "status": "online",
      "channel_managers": [
        {
          "id": 1,
          "first_name": "John",
          "last_name": "Smart",
          "email": "john.smart@acme.com"
        },
        {
          "id": 2,
          "first_name": "Jane",
          "last_name": "Smart",
          "email": "jane.smart@acme.com"
        }
      ]
    }
    

    HTTP Request

    GET https://api.smartup.io/api/v1/channels/{id}

    URL Parameters

    Parameter Description
    id The id of the channel to retrieve

    Get members of a channel

    The above command returns JSON structured like this:

    {
      "data": [
        {
          "id": 1,
          "first_name": "John",
          "last_name": "Smart",
          "email": "john.smart@acme.com",
          "member_type": "member",
          "reference": "WzFd"
        },
        {
          "id": 2,
          "first_name": "Jane",
          "last_name": "Smart",
          "email": "jane.smart@acme.com",
          "member_type": "manager",
          "reference": "WzFd"
        }
      ],
      "has_more": false
    }
    

    This endpoint retrieves all members of a specific channel.

    HTTP Request

    GET https://api.smartup.io/api/v1/channels/{id}/members

    URL Parameters

    Parameter Description
    id The id of the channel
    starting_after N/A
    ending_before N/A
    limit 100

    Learning Records

    Get learning records

    Retrieve all learning records from the community.

    The above command returns JSON structured like this:

    {
      "data": [
        {
          "content_id": "abcd123",
          "content_version_id": "dfgh123",
          "title": "An awesome content",
          "on_behalf_of": "An awesome team",
          "start_timestamp": "2018-09-11T12:53:14",
          "completion_timestamp": "2018-09-11T12:53:14",
          "channel_id": 123,
          "user_id": 123,
          "num_of_total_cards": 30,
          "num_of_completed_cards": 29,
          "completed": false,
          "reference": "WzFd"
        },
        {
          "content_id": "abcd123",
          "content_version_id": "dfgh123",
          "title": "An awesome content",
          "on_behalf_of": "An awesome team",
          "start_timestamp": "2018-09-11T12:53:14",
          "completion_timestamp": "2018-09-11T12:53:14",
          "channel_id": 123,
          "user_id": 250,
          "num_of_total_cards": 30,
          "num_of_completed_cards": 30,
          "completed": true,
          "reference": "WzFd"
        }
      ],
      "has_more": false
    }
    

    HTTP Request

    GET https://api.smartup.io/api/v1/learning-records

    Query Parameters

    Parameter Default Description
    user_id N/A Filter by user_id
    content_id 0 Filter by content_id
    start_timestamp_after N/A Show records started after start_timestamp_after
    start_timestamp_before N/A Show records started before start_timestamp_before
    completion_timestamp_after N/A Show records completed after completion_timestamp_after
    completion_timestamp_before N/A Show records completed before completion_timestamp_before
    starting_after N/A If set the result will contain elements after the reference.
    ending_before N/A If set the result will contain elements before the reference.
    limit 500 Number of records to retrieve.