Skip to content
TK Portal Documentation
User API
latest

User Management API🔗

The User Management API is a REST API comprised of various endpoints to facilitate managing users and their corresponding access rights (by means of Search Policies).

For testing purposes, the REST services can be called using tools, such as Curl or Postman. Examples for requests and responses are provided for most functions.

Basic functions🔗

List and/or add users🔗

/portal/config/user

GET, PUT /portal/config/user

Method Media Type Description
GET application/json Lists all users of an account when authenticated as user manager
PUT application/json Adds users when authenticated as user manager

Request GET🔗

      curl -X GET -u <account name>:<account password> "https://home.textkernel.nl/portal/config/user" -H 'Content-Type: application/json'

Response GET🔗

[
    {
        "uuid":"8a33910179c30deb0179f0cc45394401",
        "name":"recruiter0",
        "displayName":"Recruiter 0",
        "emailAddress":"recruiterzero@invalidmail.com",
        "status":"ENABLED",
        "accountId":"8a33918679c30d710179f0cc40f3441c",
        "externalId":"recruiter0",
        "configuration":{
            "searchConfigs":[

            ]
        },
        "configurationAsString":"{}",
        "portalRoles":"recruiter",
        "activeRole":"recruiter",
        "created":"2021-06-01T14:43:09+02",
        "updated":"2021-06-01T14:43:09+02",
        "matchQuery":null,
        "profilePresent":false,
        "firstLogin":"2021-06-01T14:45:01+02",
        "lastLogin":null
    }
]

Request PUT🔗

Important

  • The method returns the listing for the newly added users.
  • If a user already exists, an exception is thrown and no changes are executed.

Warning

  • When creating users via the API, each user's name and password must be specified. If not, an exception is thrown and no changes are executed. This is not necessary for users created automatically via SSO.
  • If no status is specified, the user's status will be set to "DISABLED".
  • If no portal roles are sent for a user in the PUT request, the user will be assigned the default portal roles as configured in the account configuration. If a portal role is specified that is not configured in the account configuration an exception will be thrown, and no mutations are executed.
  • If no active role is specified it will default to the first role in the portal roles of the user.
[
    {
        "name":"user1",
        "password":"<password>",
        "displayName":"Textkernel User 1",
        "emailAddress":"user1@invalidmail.com",
        "status":"ENABLED",
        "externalId":"user1",
        "portalRoles":"recruiter",
        "activeRole":"recruiter"
    },
    {
        "name":"user2",
        "password":"<password>",
        "displayName":"Textkernel User 2",
        "emailAddress":"user2@invalidmail.com",
        "status":"ENABLED",
        "externalId":"user2",
        "portalRoles":"recruiter",
        "activeRole":"recruiter",
        "searchPolicyIds":[
            "aa8081814e0ad12b014e0ad136000004"
        ]
    }
]

Where:

Name Description
name Username
password Password. Only needed for users created via the API
displayName The name to be displayed in the UI (when used)
emailAddress Email address of the user
status Status of the user
externalId Unique identifier used in another system, e.g. ATS, CRM, etc
portalRoles Internal role used across Textkernel applications. A Textkernel consultant will provide the correct value specific for each use case
activeRole The active portal role. A Textkernel consultant will provide the correct value specific for each use case

Response PUT🔗

[
    {
        "uuid":"8a33918679f7513b017a134d1dfb2c30",
        "name":"user1",
        "displayName":"Textkernel User 1",
        "emailAddress":"user1@invalidmail.com",
        "status":"ENABLED",
        "accountId":"8a33918679c30d710178f0cc40f3445c",
        "externalId":"user1",
        "configuration":{
            "searchConfigs":[

            ]
        },
        "configurationAsString":"{}",
        "portalRoles":"recruiter",
        "activeRole":"recruiter",
        "created":"2021-06-02T16:50:13+02",
        "updated":"2021-06-02T16:50:13+02",
        "matchQuery":null,
        "profilePresent":false,
        "firstLogin":null,
        "lastLogin":null
    },
    {
        "uuid":"8a33918679f7513b017b154d1e562c31",
        "name":"user2",
        "displayName":"Textkernel User 2",
        "emailAddress":"user2@invalidmail.com",
        "status":"ENABLED",
        "accountId":"8a33918679c31d710179f0cc40f3445c",
        "externalId":"user2",
        "configuration":{
            "searchConfigs":[

            ]
        },
        "configurationAsString":"{}",
        "portalRoles":"recruiter",
        "activeRole":"recruiter",
        "created":"2021-06-02T16:50:13+02",
        "updated":"2021-06-02T16:50:13+02",
        "matchQuery":null,
        "profilePresent":false,
        "firstLogin":null,
        "lastLogin":null
    }
]

Retrieve, change or delete a user🔗

/portal/config/user/<name>

GET, PUT, DELETE /portal/config/user/<name>

Warning

When the username is an email address, a slash '/' must be added at the end. Otherwise, every character after the @ is ignored, and will cause a 'User not found' exception.

Method Media Type Description
GET application/json Get user
PUT application/json Update user
DELETE application/json Delete user

Request GET🔗

      curl --user <account name>:<account password> "https://home.textkernel.nl/portal/config/user/<username>" --header 'Content-Type: application/json'

Response GET🔗

{
    "uuid":"8a33918679f7513b017a134d1dfb2c30",
    "name":"user1",
    "displayName":"Textkernel User",
    "emailAddress":"user1@invalidmail.com",
    "status":"ENABLED",
    "accountId":"8a33918679c30d710178f0cc40f3445c",
    "externalId":"user1",
    "configuration":{
        "searchConfigs":[

        ]
    },
    "configurationAsString":"{}",
    "portalRoles":"recruiter",
    "activeRole":"recruiter",
    "created":"2021-06-03T10:40:48+02",
    "updated":"2021-06-03T10:40:48+02",
    "matchQuery":null,
    "profilePresent":false,
    "firstLogin":null,
    "lastLogin":null
}

Request PUT🔗

Warning

  • If no status is sent in the request, it will be set to DISABLED.
  • If no portal roles are included in the PUT request, the user will be assigned the default portal roles as configured in the account.
  • If a portal role is specified, which is not configured in the account configuration, an exception will be thrown and no changes are executed.
  • If the active role is blank, the original active role will be used.
  • If the original active role is no longer associated to the user, the active role will default to the first role in the portal roles for the user.
    curl -X PUT --user <account name>:<account password> "https://home.textkernel.nl/portal/config/user/<username>" --header 'Content-Type: application/json' --data '{"name": "recruiter1","displayName": "Changed Recruiter 1 name","portalRoles": "recruiter","status": "ENABLED"}'

{
    "name":"recruiter1",
    "displayName":"Changed Recruiter 1 name",
    "portalRoles":"recruiter",
    "status":"ENABLED"
}

Where:

Name Description
name Username
displayName The name to be displayed in the UI (when used)
portalRoles Internal role used across Textkernel applications. A Textkernel consultant will provide the correct value specific for each use case
status Status of the user

Response PUT🔗

{
    "uuid":"8a33918679f7513b017a154d1dfb2c30",
    "name":"recruiter1",
    "displayName":"Changed Recruiter 1 name",
    "emailAddress":null,
    "status":"ENABLED",
    "accountId":"8a33918679c30d710179f0cc40f3445c",
    "externalId":null,
    "configuration":{
        "searchConfigs":[

        ]
    },
    "configurationAsString":"{}",
    "portalRoles":"recruiter",
    "activeRole":"recruiter",
    "created":"2021-06-01T16:50:13+02",
    "updated":"2021-06-01T17:27:38+02",
    "matchQuery":null,
    "profilePresent":false,
    "firstLogin":null,
    "lastLogin":null
}

Request DELETE🔗

      curl -X DELETE -u <account name>:<account password> "https://home.textkernel.nl/portal/config/user/<username>"

Response DELETE🔗

200 OK or HTTP error, e.g. 404 Not Found 

{
    "message":"User <username> does not exist in account <account name>",
    "cause":"No Details available"
}

Search policies🔗

List or update the Search policies associated to a user🔗

/portal/config/user/<user name>/searchPolicies

GET, PUT /portal/config/user/<user name>/searchPolicies

Method Media Type Description
GET application/json List the Search policies associated to a user
PUT application/json Replace the Search policies associated to a user

/portal/config/user/id/<user id>/searchPolicies

GET, PUT /portal/config/user/id/<user id>/searchPolicies

Method Media Type Description
GET application/json List the Search policies associated to a user
PUT application/json Replace the Search policies associated to a user

Request🔗

[
    {
        "name":"aSearchPolicy",
        "shareableAsRole":true,
        "sharesWith":[
            "otherPolicy"
        ]
    }
]

Where:

Name Description
name The name assigned to the Search policy
shareableAsRole Adds a new Search role to the Search policy with the same name. Default: false
sharesWith The name(s) of (an)other existing Search policies to enable users that are members of these policies to share projects in Search!

Response🔗

[
    {
        "uuid":"8a3382a5602c481601602c4848430017",
        "name":"aSearchPolicy",
        "searchRoles":[

        ],
        "members":[
            {
                "name":"user1",
                "uuid":"8a3382a5602c481601602c482ba7000c"
            }
        ],
        "portalRoles":[

        ],
        "sharesWith":[
            {
                "name":"otherPolicy",
                "shareableAsRole":true,
                "uuid":"8a3382a5602c481601602c4848430018"
            }
        ],
        "receivesFrom":[
            {
                "name":"otherPolicy",
                "uuid":"8a3382a5602c481601602c4848430018"
            }
        ],
        "shareableAsRole":true,
        "defaultSearchPolicy":false,
        "created":"2021-12-06T15:43:42+01",
        "updated":"2021-12-06T15:43:42+01"
    }
]

User configuration🔗

Retrieve or change the user configuration🔗

/portal/config/user/<name>/config

GET, PUT /portal/config/user/<name>/config

Method Media Type Description
GET application/json, application/octet-stream Retrieve the user configuration
PUT application/json, application/octet-stream Update the user configuration

Request and Response🔗

Available settings

  1. Interface locale
  2. Search and Indexing roles
  3. Extra Info (the data will automatically be added when a user creates their profile in TKPortal)
{
    "searchConfigs":[
        {
            "searchRef":"jobSearch",
            "indexingRoles":[
                "ei1",
                "ei2"
            ],
            "searchRoles":[
                "es1",
                "es2"
            ]
        }
    ],
    "locale":"en"
}

Where:

Name Description
searchRef Defines to which Search! environment the roles should be applied. A Textkernel consultant will provide the correct value specific for each use case
indexingRoles A list of Search! roles to be added to the list of user roles for searching
searchRoles A list of Search! roles to be added to the list of user roles for indexing
locale The available locales are configured on a per-account basis

Retrieve or change the user status🔗

/portal/config/user/<name>/status

PUT /portal/config/user/<name>/status

Possible status values: ENABLED, DISABLED, DELETED.

Method Media Type Description
PUT text/plain Change user status

Request🔗

      curl -X PUT -u <account name>:<account password> "https://home.textkernel.nl/portal/config/user/<user>/status" -H 'Content-Type: text/plain' --data 'ENABLED'

Note that the content type is 'text/plain' and not 'application/json'.

Response🔗

This method returns the status of the user after the change has been made.