Categories are named "Sections" and "Topics" in the Exceed admin UI.

There are 2 different types of Category records:

  1. those named "Section" in the Exceed admin UI. They can't be mapped to activities. Their parent_category_id attribute value is empty.

  2. those named "Topic" in the Exceed admin UI. They can be mapped to activities. They are nested under a Section. Their parent_category_id attribute value is the id value of the Section Category record under which they are nested.

There is only one level of nesting, i.e. a topic can be nested only under a section, a topic cannot be nested under another topic.

Description of the Category Attributes


Attribute Name Description Is required or has a default value Can be updated
id (integer) Unique identifier of the record n/a (automatically set) no
name (string) Name required yes
is_active (boolean) "status" in the UI default value is true yes
description (text) Description not required yes
picture_file_name (string) Optional picture file name not required yes
parent_category_id (integer) The id of the Category record not required for sections;
required for topics		 no
locale (string) The locale of the recored. The locale of a topic must be equal to the locale of its section the default value is en no
subcategories (array) An array of Category records corresponding to the topics nested under the section always empty for topics
code (string) A client defined identifier not required no (can only be set on create)



List

Resource: /api/v2/categories

HTTPS Request Method: GET

Description: The list of Category records of the account. This endpoint is paginated and returns 50 results per page.

Required parameter:

  • api_key (string): the account API key

Optional parameters:

  • page (integer): the page you want to request. Every page is 50 records long at most. If not present, page 1 is assumed.
  • you can filter the results on the following Category attributes: id, is_active, is visible, updated_on, locale and parent_category_id
  • You can retrieve the full URLs of the picture associated with a category in the List endpoint, passing the parameter include_picture_urls with the value 1. This parameter will only work for JSON responses. Example request:

Description of the Category attributes for Picture URLs:


Field in the UI Attribute
Picture picture_url_full
Picture picture_url_thumbnail

Response:

  • on success: a 200 HTTP code and an array of the found records in the body
  • on failure: a 422 HTTP code and an array of the errors in the body

Example requests:

  • Get 50 first Category records of the account: curl -H "Content-type: application/json" -H "Accept: application/json" https://my-account-subdomain.exceedlms-staging.com/api/v2/categories?api_key=my-account-subdomain-api-key-value
  • Get only the active Category records: curl -H "Content-type: application/json" -H "Accept: application/json" "https://my-account-subdomain.exceedlms-staging.com/api/v2/categories?api_key=my-account-subdomain-api-key-value&category\[is_active\]=true"
  • Get the full urls of the picture associated with each Category record: curl -X "GET" "https://my-account-subdomain.exceedlms-staging.com/api/v2/categories?api_key=my-account-subdomain-api-key-value&include_picture_urls=1" \ -H "Content-Type: application/json" \ -H "Accept: application/json"



Read

Resource: /api/v2/categories/id_of_resource

HTTPS Request Method: GET

Description: A single category that matches the id passed in or the code passed in.

Required Parameters:

  • api_key
  • id of resource at end of url or category[code]

Optional parameters:

  • category[code]: when this parameter is passed, Exceed looks up the category using the code, and ignores the id parameter.

Example Request:

  • Get Category with id 5: curl -H "Content-type: application/json" -H "Accept: application/json" https://my-account-subdomain.exceedlms-staging.com/api/v2/categories/5?api_key=my-account-subdomain-api-key-value
  • Get Category with code "green": curl -H "Content-type: application/json" -H "Accept: application/json" https://my-account-subdomain.exceedlms-staging.com/api/v2/categories?api_key=my-account-subdomain-api-key-value&category\[code\]=green

Example Response:

{
    "id": 5,
    "is_active": true,
    "name": "tree",
    "picture_file_name": null,
    "parent_category_id": null,
    "description": null,
    "updated_on": "2019-02-05T19:17:16.591-05:00",
    "code": "green",
    "locale": "en",
    "subcategories": []
  }



Create

Resource: /api/v2/categories

HTTPS Request Method: POST

Description: create a new Category record. To create a section don't pass the parent_category_id parameter. To create a topic pass in the parent_category_id parameter the id value of the section record under which you want to nest the topic. See examples below.

Required parameter:

  • api_key (string): the account API key
  • name (string): the category name

Optional parameters:

The following optional parameters must be within the category key:

All the parameters listed in "Description of the Category attributes", except the picture_file_name and subcategories attributes, which can't be set

  • picture_url (text): the URL from where the picture will be fetched by the Create or Update endpoint in order to create or update the category picture. For performance reasons please store the File in a Google Cloud Storage bucket. Maximum file size is 10 megabytes.
  • hero_picture_url (text): the URL from where the image will be fetched by the Create endpoint in order to create the hero image. For performance reasons please store the File in a Google Cloud Storage bucket. Maximum file size is 10 megabytes.
  • hero_mobile_picture_url (text): the URL from where the image will be fetched by the Create endpoint in order to create the mobile version of the hero image. A hero_picture_url must be present or the hero image must already exist. For performance reasons please store the File in a Google Cloud Storage bucket. Maximum file size is 3 megabytes.

Note: The following parameters are limited to 255 characters:

  • name
  • code

Response:

  • on success: a 200 HTTP code and the created record in the body
  • on failure: a 422 HTTP code and an array of the errors in the body

Example requests:

  • Create a section named "My Section" with description "My Description" and with code "My Code": curl -H "Content-type: application/json" -H "Accept: application/json" -X POST -d '{ "category": {"name": "My Section", "description": "My Description", "code": "My Code" } }' https://my-account-subdomain.exceedlms-staging.com/api/v2/categories?api_key=my-account-subdomain-api-key-value
  • Create a topic named "My Topic", nested in the section with id 24: curl -H "Content-type: application/json" -H "Accept: application/json" -X POST -d '{ "category": {"name": "My Topic", parent_category_id: 24} }' https://my-account-subdomain.exceedlms-staging.com/api/v2/categories?api_key=my-account-subdomain-api-key-value
  • Create a category named "My Category" with a picture: curl -H "Content-type: application/json" -H "Accept: application/json" -X POST -d '{ "category": {"name": "My Category", "picture_url": "https://storage.googleapis.com/path/to/picture.png" } }' https://your-domain.exceedlms-staging.com/api/v2/categories?api_key=your-domain-api-key-value
  • Create a category named "My Category" with a hero picture and mobile hero picture: curl -H "Content-type: application/json" -H "Accept: application/json" -X POST -d '{ "category": {"name": "My Category", "hero_picture_url": "https://storage.googleapis.com/path/to/picture.png", "hero_mobile_picture_url": "https://storage.googleapis.com/path/to/image.png" } }' https://your-domain.exceedlms-staging.com/api/v2/categories?api_key=your-domain-api-key-value



Update

Resource: /api/v2/categories (id being the id attribute of the Category record to update)

HTTPS Request Method: PUT or PATCH (we handle PUT and PATCH requests in the same exact way)

Description: update an existing Category record

Required parameter:

  • api_key (string): the account API key
  • id (integer): the id attribute value of the Category record to update

Optional parameters:

  • see the list of required and optional parameters of the Create endpoint, minus the attributes which can not be updated (listed in the "Description of the Category attributes" section)
  • category[code]: when this parameter is passed, Exceed looks up the category using the code, and ignores the id parameter. The code value cannot be updated.

Response:

  • on success: a 200 HTTP code and the updated record in the body
  • on failure: a 422 HTTP code and an array of the errors in the body

Example requests:

  • Update the name of category with id 2 to "My New Category Name" : curl -H "Content-type: application/json" -H "Accept: application/json" -X PUT -d '{ "category": { "name": "My New Category Name" } }' https://my-account-subdomain.exceedlms-staging.com/api/v2/categories/2?api_key=my-account-subdomain-api-key-value



Destroy

Resource: /api/v2/categories/ (id being the id attribute of the Category record to destroy)

HTTPS Request Method: DELETE

Description: destroy an existing Category record. Destroying a parent category will also destroy all its subcategories.

Required parameters:
api_key (string): the account API key
id (integer): the id of the Category record to destroy

Optional parameters:

  • category[code]: when this parameter is passed, Exceed looks up the category using the code, and ignores the id parameter

Response:

  • on success: a 200 HTTP code and an empty body
  • on failure: a 422 HTTP code and an array of the errors in the body

Example requests:

  • Destroy the record with id 20: curl -H "Content-type: application/json" -H "Accept: application/json" -X DELETE https://my-account-subdomain.exceedlms-staging.com/api/v2/categories/20?api_key=my-account-subdomain-api-key-value