Example use-case of Claned API: Integrating Claned to external signup system

This documentation was last updated: 19.10.2022

This is a short explanation of how you, as a Claned partner or customer, can integrate your systems to Claned in order to automate the flow of adding and removing users that should have access to learning areas.

Please note that depending on your organization active location the API address will be different. In general, it will be either api.claned.com, api-germany.claned.com or api-asia.claned.com. So you need to modify the example calls in provided in this document accordingly. You can find each documentation with the correct formatting in the following locations:

App

Germany

Asia

Some key terminology:

• Here, your system (such as an e-commerce platform, employee portal, CRM or course signup system) will be called ‘P’ for clarity.
• P is the non-Claned system has the information about what learning areas a learner should have access to and when.
• The Claned API will be called API for clarity.
• In Claned’s terms, a board means a learning area, such as a course, group work area or learning community.

Prerequisites

API Key
In order to access the API, you will need an API Key that is specific to your Claned organization. You can find this directly from the user interface by logging in to Claned (app.claned.com) with an account that has admin rights for your organization and navigating to Admin -> Advanced -> API Access.

Organization ID
Many of the requests require you to pass your organization’s id as a parameter. You can get the ID of your organization by making the request below. This will return a list of organizations you have access to and their ID’s. The list usually only has one item.

Endpoint address	https://api.claned.com/external/v1/Organizations
Endpoint documentation	https://api.claned.com/apidocs/index.html#/Organizations/GetOrganizations
Method type	GET
Query	curl -X GET "https://api.claned.com/external/v1/Organizations" -H "accept: text/plain"
Example response	{ "id": "1", "name": "Claned Group" }

General API Response codes:
Code 200: Success
Code 401: Unauthorized
Code 200: Forbidden
General API methods headers:
“Content-Type": “application/json"
“authorization": “"

Getting started with the Claned API

To get started, you can experiment with the API by getting your API Key from the UI (see “API Key”
above) and navigating to Swagger (https://api.claned.com/apidocs/index.html) and selecting Authorize. After that, you can use any endpoint by selecting ‘Try it out’. This will allow you to see the requests and responses without doing any actual coding.

Note that any calls to the endpoint will affect your organization. So if you e.g. call the endpoint
https://api.claned.com/external/v1/Organizations/id/users to remove a user from your organization,
they will be removed from that organization in the production environment.

Add a user to one or more learning areas when they sign up or make a purchase

1. A user signs up for or purchases access one or more boards on P
2. P calls the API for Claned to invite the user

Note: Only the email is a mandatory parameter here. You can, if you want, add the user directly to a group (which boards are shared to in the Claned admin section), add an expiration time for their access, add custom labels for analytics purposes or an external ID so that you can track their progress.

Make sure that the board is shared to the corresponding group id (you can check the group id, if you need to, with this method https://api.claned.com/apidocs/index.html#/Groups/GetGroupByOrganization)

Endpoint address	https://api.claned.com/Users/invite
Endpoint documentation	https://api.claned.com/apidocs/index.html#/User/SendUserInvitation
Method type	POST
Example body parameters	{ "group_id": 1, "email": "[e-mail]","expires_at": "2019-04-25T10:42:45.174Z", "labels": { "customer id": "123", "customer type": "corporate" }, "external_id": "C1235" }

3. The user receives an automatic email with instructions for how to register an account.
4. After the registration, the user logs in to Claned and immediately sees the boards they signed up for or purchased.

Note 3: If an expiration date was set for the learner’s access in step 2. They will automatically lose access to the learning areas at this step and receive a Claned notification about this change. Their Claned account will not be automatically deleted, at it is the property of the user. Any existing assessment submissions and progress data will still be stored, even when they lose access.

 

Remove a user’s access to one or more learning areas

1. A user’s access to one or more learning areas is canceled on P. This can be caused by e.g. their
access time running out or them cancelling their purchase.
2. P sends a request to the API that the user should be removed from the relevant group

Endpoint address	https://api.claned.com/Groups/{id}/organizations/{organizationId}/users
Endpoint documentation	https://api.claned.com/apidocs/index.html#/Groups/RemoveGroupUserFromGroup
Method type	DELETE
Example query	curl -X DELETE "https://api.claned.com/external/v1/Groups/1/organizations/1 /users?Email=example%2B3%40claned.com" -H "accept: application/json" -H "Authorization: 1234567890abcdefghijklmnop"

Note: the "Authorization" needs to be your unique API key

3. If the user needs to be removed from the organization as a whole, P will request the removal of
the user from the organization

Endpoint address	https://api.claned.com/Groups/{id}/organizations/{organizationId}/users
Endpoint documentation	https://api.claned.com/apidocs/index.html#/Organizations/RemoveOrganizationUser
Method type	DELETE
Example query	curl -X DELETE "https://api.claned.com/external/v1/Organizations/1/users?Em ail=example%2B3%40claned.com" -H "accept: application/json" -H "Authorization: 1234567890abcdefghijklmnop"

4. Claned sends a notification to the user, that they no longer have access to the group(s) and/or
organization.

5. Note, that the user’s Claned account is not deleted when you remove them from the
organization or a group, as it is their property.

 

Further assistance

If you have any ideas, feedback or questions about the API, please contact [e-mail]