Before you start using the Talent API, ensure that you have the following prerequisites in place:

• User credentials: To access the Talent API, you'll need a valid access token generated using your user credentials. If you don't have one, please contact our support team to obtain your user credentials.

• Development Environment: Set up your development environment with the required tools and libraries to make API calls. The Talent API is compatible with a variety of programming languages and frameworks, allowing you flexibility in your implementation.

• Understanding of REST APIs: Familiarize yourself with the fundamentals of REST APIs. This will help you understand how to structure your requests and handle responses effectively.

The Talent API documentation is divided into several sections, each addressing different aspects of API usage. Here's a brief overview of each section:

• Authorization: This section provides detailed information about the authentication process and guides you on how to get and use the access token in requests to authorize your access to the Talent API.

• Use-cases: The Use-cases section provides depth look at of how the Talent APIs capabilities and functionalities can be applied. It details key use-cases such as Users, Recruiting, and Upskilling. This section serves as a comprehensive guide to understanding the APIs core functionalities.

• Error Handling: The Error Handling section describes the different types of error responses that can be returned by the Talent API. It offers guidance on how to interpret and handle these errors in your application, ensuring that you can gracefully handle any unexpected situations that may arise during API interactions.

• Rate Limiting: The Rate Limiting section explains the rate limits imposed on API calls to ensure fair usage and optimal performance. It provides you with details on the number of requests allowed within a specific timeframe, helping you understand how to manage and handle rate limit-related scenarios effectively.

• Support: In the Support section, you will find valuable information on how to seek assistance and get the support you need. Whether you have questions, encounter difficulties, or require clarifications related to the Talent API, our team is readily available to provide prompt assistance and help you overcome any challenges you may face.

• API Reference: The API Reference section contains detailed information about each API endpoint supported by the Talent API. It includes comprehensive documentation on the request/response structure, required parameters, and possible responses for each endpoint. This section serves as a comprehensive guide for developers who are implementing the Talent API in their applications.

The Cobrainer REST APIs encompass several principles aimed at implementing standard RESTful practices on a large scale, ensuring consistent data modeling, and delivering a structured developer experience from start to finish.

Data Formats

Only the JSON format is supported for input and output. For all requests, the corresponding HTTP header should be set: Content-Type: application/json. Responses also contain this header.

All endpoints allow control over the language of the returned result. The HTTP Header Accept-Language: en-US or Accept-Language: de-DE should be set for this purpose.

Typical endpoints

For most entities, a set of typical endpoints is supported with some generic conventions.

• OPTIONS: /<entity> - returns a list of possible operations for the given entity. The response contains a list of available methods with path, attributes, and additional metadata. The response considers tenant configuration and requesting user permissions.

• GET: /<entity> - returns a list of all objects for the given entity. The response can be sorted and paginated. In this case, query parameters sort, page, size, and countOnly are accepted.

• POST: /<entity> - creates a new object for the given entity. The request accepts all fields for the entity. The response contains the created entity with ID. Field values in the response may differ from the request if the backend uses some defaults and validations.

• GET: /<entity>/{id} - reads a single object for the given entity. The response data may contain more values (including nested objects) than the responses returning a list of objects.

• PATCH: /<entity>/{id} - modifies a single object for the given entity. All request fields are optional; only values present in the request are replaced. To set an empty value for some attribute, null can be passed. The response contains the updated entity with ID.

• DELETE: /<entity>/{id} - deletes a single object for the given entity. No request body is required. The operation returns HTTP status 204 (NO-CONTENT) in case of successful deletion.

• GET: /<entity>/filter - returns a list of allowed filter fields with possible values for these fields.

• POST: /<entity>/filter - reads a list of objects for the given entity filtered by provided criteria. The request body has the following structure:

  {
     "paged": {
        "page": 0, // page number
        "size": 20, // page size,
        "countOnly": false // flag showing that only count is needed, not the real data
     },
     "sorted": {
        "fields": [
           // array of fields with sorting direction
        ]
     },
     "filter": {
        // filter fields and conditions are here
     }
  }
  

Talent API utilizes a Bearer JSON Web Token (JWT) authentication mechanism and alternatively API-Keys to secure access to its resources and services. The JWTs and API-Keys are tied to and only grant permissions for accessing functionality of a specific customer.

If both JWT and API-Key authentication is provided on API requests, only the API-Key authentication gets evaluated.

• User Authentication: To access the Talent API endpoint, users or services must first authenticate themselves using their credentials (e.g., username and password) in Cognito.
• Token Generation: Upon successful authentication, the application generates a Bearer JWT token. This token is associated with the authenticated user and contains relevant information, such as the user's ID, customer ID, roles, and any additional claims needed for authorization.
• Token Inclusion: To include the Bearer JWT token in a request, users must set the "Authorization" header with the value "Bearer" followed by the token itself.
• Authorization: Talent API verifies the token's authenticity and integrity. Once the token is successfully validated, the application checks the user's permissions and roles encoded within the token's payload. It verifies whether the user is authorized to access the requested resource or perform the desired action.
• Token Expiration and Renewal: Bearer JWT tokens have a limited lifespan defined by their expiration time claim. Once a token expires, the user must request a new token from the Cognito User Pool. This can be done through either re-authentication or by using a refresh token.

JWT Authentication code examples

Below, you can find code examples that support the described authentication flow.

Java

package com.cobrainer.authexample;

import org.springframework.http.HttpEntity;
import org.springframework.http.HttpHeaders;
import org.springframework.http.HttpMethod;
import org.springframework.http.ResponseEntity;
import org.springframework.web.client.RestTemplate;
import software.amazon.awssdk.regions.Region;
import software.amazon.awssdk.services.cognitoidentityprovider.CognitoIdentityProviderClient;
import software.amazon.awssdk.services.cognitoidentityprovider.model.*;

import java.time.LocalDateTime;
import java.util.Map;

public class TalentClient {

    private final String clientId;
    private final String userName;
    private final String password;
    private final CognitoIdentityProviderClient client;

    private String token;
    private String tokenType;
    private LocalDateTime expiration;
    private String refreshToken;

    // client id assigned to the customer, username and password are required for authentication. 
    public TalentClient(String clientId, String userName, String password) {
        this.client = CognitoIdentityProviderClient.builder().region(Region.EU_CENTRAL_1).build();
        this.clientId = clientId;
        this.userName = userName;
        this.password = password;
        setToken(initiateAuth());
    }

    // Example method demonstrating using token for GET requests.
    public <T> T call(String uri, Class<T> clazz) {
        RestTemplate template = new RestTemplate();
        HttpEntity<String> entity = new HttpEntity<String>("parameters", authHeader());
        // Using exchange to set headers with GET request.
        ResponseEntity<T> response = template.exchange(uri, HttpMethod.GET, entity, clazz);
        return response.getBody();
    }

    // Generate Authorization header for the request.
    private HttpHeaders authHeader() {
        if (expiration.isBefore(LocalDateTime.now())) {
            // Refresh the token if it's expired.
            refresh();
        }
        HttpHeaders headers = new HttpHeaders();
        headers.add("Authorization", tokenType + " " + token);
        return headers;
    }

    // Authenticate and obtain the token.
    private AuthenticationResultType initiateAuth() {
        InitiateAuthResponse authResponse = client.initiateAuth(
                InitiateAuthRequest.builder()
                        .authFlow(AuthFlowType.USER_PASSWORD_AUTH)
                        .authParameters(Map.of("USERNAME", userName, "PASSWORD", password))
                        .clientId(clientId)
                        .build());
        if (authResponse.challengeName() == ChallengeNameType.NEW_PASSWORD_REQUIRED) {
            // For new user the password change may be requested.
            return client.respondToAuthChallenge(
                    RespondToAuthChallengeRequest.builder()
                            .clientId(clientId)
                            .challengeName(authResponse.challengeName())
                            .session(authResponse.session())
                            .challengeResponses(Map.of("USERNAME", userName, "NEW_PASSWORD", password))
                            .build()).authenticationResult();
        } else {
            // Processing of other challenges maybe required if they set for user pool. Skipping it in this example.
            return authResponse.authenticationResult();
        }
    }

    // Refresh ID token based on refreshToken.
    private void refresh() {
        setToken(client.initiateAuth(InitiateAuthRequest.builder()
                .authFlow(AuthFlowType.REFRESH_TOKEN_AUTH)
                .authParameters(Map.of("REFRESH_TOKEN", refreshToken))
                .clientId(clientId)
                .build()).authenticationResult());
    }

    private void setToken(AuthenticationResultType authResult) {
        token = authResult.idToken();
        tokenType = authResult.tokenType();
        expiration = LocalDateTime.now().plusSeconds(authResult.expiresIn());
        refreshToken = authResult.refreshToken();
    }
}

Python

import datetime as dt

import boto3
import requests
from requests.auth import AuthBase


class AWSTenantAuthV2(AuthBase):
    _session_info = {
        "expiration_date": "",
        "token_type": "",
        "id_token": "",
        "refresh_token": ""
    }

    # client id assigned to the customer, username and password are required for authentication. 
    def __init__(self, client_id, username, password):
        self._username = username
        self._password = password
        self._client_id = client_id
        self._client = boto3.client("cognito-idp", "eu-central-1")
        self._start_session()

    # Example method demonstrating using token for requests.
    def __call__(self, req: requests.Request, *args, **kwargs):
        if self._session_info["expiration_date"] < dt.datetime.now():
            self._refresh_id_token()
        req.headers["Authorization"] = f"{self._session_info['token_type']} {self._session_info['id_token']}"

    # Authenticate and obtain the token.
    def _start_session(self):
        response = self._client.initiate_auth(
            AuthFlow="USER_PASSWORD_AUTH",
            AuthParameters={
                "USERNAME": self._username,
                "PASSWORD": self._password,
            },
            ClientId=self._client_id
        )

        self._session_info = {
            "expiration_date": dt.datetime.now() + dt.timedelta(0, response["AuthenticationResult"]["ExpiresIn"]),
            "id_token": response["AuthenticationResult"]["IdToken"],
            "token_type": response["AuthenticationResult"]["TokenType"],
            "refresh_token": response["AuthenticationResult"]["RefreshToken"]
        }

    # Refresh ID token based on refreshToken.
    def _refresh_id_token(self):
        response = self._client.initiate_auth(
            AuthFlow="REFRESH_TOKEN_AUTH",
            AuthParameters={
                "REFRESH_TOKEN": self._session_info["refresh_token"]
            },
            ClientId=self._client_id
        )
        self._session_info.update({
            "expiration_date": dt.datetime.now() + dt.timedelta(0, response["AuthenticationResult"]["ExpiresIn"]),
            "id_token": response["AuthenticationResult"]["IdToken"],
            "token_type": response["AuthenticationResult"]["TokenType"]
        })

• API-Key Creation: To access the Talent API endpoint, a key needs to be created at the developer portal at (tbd). Keys are created with a specific expiry date/time and a specific set of permissions.
• API-Key Usage: The API-Key is transmitted as HTTP header X-API-Key on every request, e.g. the full HTTP header would look like X-API-Key: cb-ab12cd34ef56.... If the API-Key is invalid, expired or disabled, an appropriate status code 401 response is returned.
• API-Key Rotation: To rotate keys that are close to expiry, simply create a new API-Key in the developer portal and update your systems to use the new key, before the old key expires. After rotation is finished, the old key can be disabled or deleted.
• API-Key Deprecation: At any time, existing API-Keys may be disabled (with the option to enable them again) or deleted. Keys that are deleted are irrecoverably lost and can't be recreated, therefore it's reasonable to first disable and only later delete them when confident, that they are no longer used.

API-Key Authentication code examples

Below, you can find code examples that support the described API-Key authentication.

Java

package com.cobrainer.authexample;

import org.springframework.http.HttpEntity;
import org.springframework.http.HttpHeaders;
import org.springframework.http.HttpMethod;
import org.springframework.http.ResponseEntity;
import org.springframework.web.client.RestTemplate;

import java.time.LocalDateTime;
import java.util.Map;

public class TalentClient {
    private final String apiKey;

    // apiKey must be propagated to the client from a secure location. Never hard-code API-Keys!
    public TalentClient(String apiKey) {
        this.apiKey = apiKey;
    }

    // Example method demonstrating using token for GET requests.
    public <T> T call(String uri, Class<T> clazz) {
        RestTemplate template = new RestTemplate();
        HttpEntity<String> entity = new HttpEntity<String>("parameters", apiKeyHeader());
        // Using exchange to set headers with GET request.
        ResponseEntity<T> response = template.exchange(uri, HttpMethod.GET, entity, clazz);
        return response.getBody();
    }

    // Generate X-API-Key header for the request.
    private HttpHeaders apiKeyHeader() {
        HttpHeaders headers = new HttpHeaders();
        headers.add("X-API-Key", apiKey);
        return headers;
    }
}

The Talent API incorporates a range of key features that enhance the application's functionality and usability. These key features have been thoughtfully integrated into the API, ensuring a comprehensive talent management solution that caters to our users' distinct requirements. The following features are at the core of the Talent API, providing an exceptional user experience and empowering seamless talent management processes.

The Skills API offers various capabilities to cater to your skill-related needs. With this API, you can conduct skill searches using specific criteria, accurately detect skills from textual content, and seamlessly retrieve skills-related information. At the heart of the skill API lies a skill data model that governs how skills are represented within the system. This comprehensive data model comprises various essential attributes, including:

Attributes	Description
ID	Unique identifier associated with a specific skill.
Name	Name of the Skill
Type	Type of the Skill (hard, soft, and language)

This comprehensive documentation is a valuable resource, providing detailed insights into the purpose and functionality of endpoints within the Skills API.

1. Skill Search

You can use the GET /skills endpoint to explore and find specific skills. This endpoint allows you to search by incorporating the following parameters within the request:

• searchTerm : This parameter enables you to filter skills based on a specific search term of your choice. It helps narrow down the results to match your desired criteria.

• limit: By including this parameter, you can specify the maximum number of skills you wish to retrieve. It allows you to control the number of skills returned to the search results.

• type: This parameter allows you to refine your search further by specifying the skills you want to retrieve. For instance, you can select from hard, soft, and language skills categories, tailoring the search to your specific requirements.

2. Skill Detection

If you need to identify skills from different types of textual content, such as CVs, job descriptions, or any other document type, you can use the POST /skills/detection endpoint. This robust endpoint provides the ability to detect skills by leveraging a range of parameters, including:

Skills Limit: By setting a skills limit parameter by type, you can control the maximum number of skills to be detected. This ensures that the skill detection process returns a manageable number of results that meet your requirements.

Document Type: The endpoint also enables you to customize the skill detection based on the type of document being analyzed. Whether it's a CV, job description, or any other type of textual content, considering the document type helps tailor the skill detection process to the specific context and needs of the document.

3. Skill Information

Our API provides multiple endpoints to facilitate access to skill-related information. You can utilize the GET /skills/{skillId} endpoint to obtain details about a specific skill. This endpoint will return essential information about the skill you specify.

If you require comprehensive details about a skill, including all its details and related skills, you can use the GET /skills/{skillId}/details endpoint. This endpoint provides a comprehensive overview of the skill, ensuring you have access to all the relevant information.

You can use the GET /skills/{skillId}/jobs endpoint to determine which jobs in your system require a specific skill. This endpoint allows you to retrieve a list of jobs that necessitate the particular skill you specify.

In cases where you require information about a group of skills rather than a single skill, you can employ the GET /skills/info endpoint. This endpoint enables you to retrieve comprehensive information about multiple skills simultaneously, streamlining the process of obtaining a holistic understanding of various skills.

You can utilize the POST /skills/related endpoint to find related skills to a particular skill. This endpoint facilitates the identification of skills that are closely associated with the skill you specify.

Users

The Users API provides a comprehensive set of functionalities for managing user information and data within the application.With this API, users can create, retrieve, update, delete, and filter user data to streamline user management processes. This documentation aims to provide developers with a detailed understanding of the User data model, its lifecycle, and the available endpoints for interacting with user information.

At the core of the Users API is the User data model, which serves as a structured representation of user information within the application. The User data model encompasses various attributes and fields that store essential information related to each user.

Here is an overview of the attributes included in our User data model:

Attributes	Description
ID	Unique identifier associated with a specific User.
externalId	To store the ID of a User from different system.
firstName	User first name.
lastName	User last name.
aboutMe	A brief description or biography of the user.
jobTitle	Current job title of the user.
department	Department where the user is employed.
location	Location of the user.
emailAddress	User email address.
phoneNumber	User contact phone number.
seniorityLevel	Seniority level of the user(0-6).
relocationPreference	User preference for relocation("not open". "open", "relocation only").
jobSeeking	Indicates if the user is currently seeking a job("not open", "open").
roles	Indicates the roles of the user

The Users use-case lifecycle encompasses multiple stages, starting from creation and extending to deletion and filtering. This comprehensive overview will outline the distinct stages that constitute the user lifecycle.

1. Create a User

The initial stage of the user lifecycle involves the creation of a new user. This can be accomplished by utilizing the POST /users endpoint, which allows for the creation of users by providing the necessary attributes from the user data model. While it is not obligatory to populate all attributes, there are a couple of mandatory fields that must be included when creating a user. These include firstName and lastName.

If there is limited information available about the user at the time of creation, users have the option to set some attributes as default values. This allows for the creation of a preliminary user profile, which can be further refined and supplemented with additional details later.

2. Retrieve a User

After a user has been successfully created, it becomes possible to retrieve the specific user by utilizing its userId. To retrieve a particular user, make use of the GET /users/{userId} endpoint. In the endpoint URL, substitute the placeholder {userId} with the actual user ID assigned during creation. This will allow you to access the detailed information and attributes associated with that specific user.

However, in the event that you do not have the user ID readily available, there is an alternative approach. By employing the GET /users endpoint, it is possible to retrieve a comprehensive list of all users present within the system. This endpoint provides an overview of all users, enabling you to browse through the available options and locate the desired user if the specific user ID is unknown.

3. Update a User

As users progress, it is often necessary to make updates to different fields associated with them. To facilitate these updates, the API offers the PATCH /users/{userId} endpoint, which allows for the modification of specific user attributes.

When utilizing the PATCH /users/{userId} endpoint, it is important to include the userId in the endpoint URL to specify the exact user that requires updating. Additionally, provide the updated fields within the request to reflect the desired changes. It is worth noting that all attributes are optional for updating, meaning that you can choose to modify one or more specific fields without the need to update every attribute.

4. Delete a User

Once a user's profile is no longer needed or should be removed, you have the option to delete it from the system. To achieve this, the API provides the DELETE /users/{userId} endpoint specifically designed for deleting users.

By utilizing the DELETE /users/{userId} endpoint, you can initiate the deletion process for a specific user. To indicate which user should be deleted, substitute the {userId} placeholder in the endpoint URL with the actual ID of the user you wish to remove.

Deleting a user through this endpoint permanently removes the user from the system, including all associated data and attributes. It is important to exercise caution when using this endpoint, as deleted users cannot be recovered. Therefore, it is recommended to ensure that the user truly needs to be deleted before invoking this endpoint.

5. User Filtering

The API offers a comprehensive user filtering feature, allowing you to refine your user search based on specific criteria. To explore the available filtering options, you can utilize the GET /users/filter endpoint, which provides a detailed list of fields that can be used to filter users. This endpoint returns a comprehensive set of filterable fields, enabling you to fine-tune your search based on desired attributes.

Once you have identified the relevant filter criteria, you can proceed to retrieve users that match those filters. The POST /users/filter endpoint serves this purpose, allowing you to submit your filter criteria within the request body. By specifying the desired filters in the request, the endpoint will return a list of users that align with your specified criteria.

With the combination of the GET /users/filter and POST /users/filter endpoints, you can efficiently navigate and retrieve users that meet your specific requirements.

User Skills

This section provides a guide to managing user skills. It covers adding and updating hard and soft skills, retrieving hard and soft skills, adding language skills, and retrieving language skills. It emphasizes using specific endpoints for each task and the importance of effective skill management.

1. Add Hard-Soft skills to a user profile

After a user has been successfully created, you can add or update hard and soft skills for that user by utilizing their user ID. To manage skills for a particular user, use the POST /users/{userId}/hard-soft-skills endpoint. Substitute the placeholder {userId} in the endpoint URL with the assigned user ID. This endpoint allows you to add a new list of skills, overriding a user's existing skills. Along with the skillId, you can also specify the level to describe the user's proficiency in each skill.

2. Retrieve Hard-Soft skills from a user profile

The GET /users/{userId}/hard-soft-skills endpoint is your go-to for a comprehensive understanding of a user's hard and soft skills. This endpoint provides detailed information about the user's hard and soft skills, including the skill id, skill name, skill type, and proficiency level. This information lets you to deeply understand the user's competencies and strengths.

3. Add Language skills to a user profile

Adding language skills to a user profile is as simple as adding hard-soft skills. Like before, you can use the POST /users/{userId}/languages endpoint. This endpoint allows you to add a new list of language skills, overriding a user's existing skills. Just like hard-soft skills, you can specify the level to describe the user's proficiency in each language. The process is straightforward and familiar, making managing a user's language skills easy.

4. Retrieve Language skills from a user profile

You can utilize the GET /users/{userId}/languages endpoint to fetch comprehensive details about a particular user's language skills. This includes the skill ID, name, type, and proficiency level associated with each language skill.

Jobs

The Jobs API provides a comprehensive set of functionalities for users to effectively manage job postings within the application. With this API, users can create, retrieve, update, delete, and filter job postings to streamline their job management processes. This documentation aims to provide developers with a detailed understanding of the Job data model, its lifecycle, and the available endpoints for interacting with job postings.

At the core of the Jobs API is the Job data model, which serves as a structured representation of job postings within the application. The Job data model encompasses various attributes and fields that store essential information related to each job posting.

Here is an overview of the attributes included in our Job data model:

Attributes	Description
ID	Unique identifier associated with a specific job.
externalId	To store the ID of a job from a different system.
translations	Contains title and description for the job in various languages.
creator	User who created the job.
owner	User who is the primary contact for the job.
hiringManager	Assigned hiring manager for the job.
duration	Specifies whether the job is "permanent" or "fixed-term".
locations	An array of location IDs where the job is located.
workPlace	Indicates whether the job is "remote" or "on-site".
startDate	Start date of the job.
applicationUrl	URL of the job application.
state	Indicates the current state of the job (draft, published, hired, or archived).
seniorityLevel	Seniority level of the job.
skills	An array of skills (id and level) required for the job.
updatedAt	Time when the job was last updated.
publishedAt	Time when the job was published.

The Job lifecycle encompasses multiple stages, starting from creation and extending to deletion and filtering. This comprehensive overview will outline the distinct stages that constitute the job lifecycle.

1. Create a Job

The initial stage of the job lifecycle involves the creation of a new job. This can be accomplished by utilizing the POST /jobs endpoint, which allows for the creation of jobs by providing the necessary attributes from the job data model. While it is not obligatory to populate all attributes, there are several mandatory fields that must be included when creating a job. These include translations, location, workplace, state, and seniority level.

If there is limited information available about the job at the time of creation, users have the option to set the job's state to "Draft" using the state attribute. This allows for the creation of a preliminary job posting, which can be further refined and supplemented with additional details before transitioning to the "Published" state.

2. Retrieve a Job

After a job has been successfully created, it becomes possible to retrieve the specific job by utilizing its jobId. To retrieve a particular job, make use of the GET /jobs/{jobId} endpoint. In the endpoint URL, substitute the placeholder {jobId} with the actual job ID assigned during creation. This will allow you to access the detailed information and attributes associated with that specific job.

However, in the event that you do not have the job ID readily available, there is an alternative approach. By employing the GET /jobs endpoint, it is possible to retrieve a comprehensive list of all jobs present within the system. This endpoint provides an overview of all jobs, enabling you to browse through the available options and locate the desired job if the specific job ID is unknown.

3. Update a Job

As jobs evolve and progress, it is often necessary to make updates to different fields associated with them. To facilitate these updates, the API offers the PATCH /jobs/{jobId} endpoint, which allows for the modification of specific job attributes.

When utilizing the PATCH /jobs/{jobId} endpoint, it is important to include the jobId in the endpoint URL to specify the exact job that requires updating. Additionally, provide the updated fields within the request to reflect the desired changes. It is worth noting that all attributes are optional for updating, meaning that you can choose to modify one or more specific fields without the need to update every attribute.

However, there are certain attributes that cannot be set to null during the update process. These attributes include translations, locations, workPlace, state, seniority level, and skills. It is crucial to ensure that these attributes are provided with valid values and not left empty or null.

4. Delete a Job

Once the hiring process for a job is complete or when there is no longer a need for a job posting, you have the option to remove it from the system. To achieve this, the API provides the DELETE /jobs/{jobId} endpoint specifically designed for deleting jobs.

By utilizing the DELETE /jobs/{jobId} endpoint, you can initiate the deletion process for a specific job. To indicate which job should be deleted, substitute the {jobId} placeholder in the endpoint URL with the actual ID of the job you wish to remove.

Deleting a job through this endpoint permanently removes the job from the system, including all associated data and attributes. It is important to exercise caution when using this endpoint, as deleted jobs cannot be recovered. Therefore, it is recommended to ensure that the job truly needs to be deleted before invoking this endpoint.

5. Job filtering

The API offers a comprehensive job filtering feature, allowing you to refine your job search based on specific criteria. To explore the available filtering options, you can utilize the GET /jobs/filter endpoint, which provides a detailed list of fields that can be used to filter jobs. This endpoint returns a comprehensive set of filterable fields, enabling you to fine-tune your search based on desired attributes.

Once you have identified the relevant filter criteria, you can proceed to retrieve jobs that match those filters. The POST /jobs/filter endpoint serves this purpose, allowing you to submit your filter criteria within the request body. By specifying the desired filters in the request, the endpoint will return a list of jobs that align with your specified criteria.

With the combination of the GET /jobs/filter and POST /jobs/filter endpoints, you can efficiently navigate and retrieve jobs that meet your specific requirements.

6. Job Description generation

In addition to its robust filtering capabilities, the Jobs API presents a seamless and highly efficient solution for generating comprehensive job descriptions using a job title. This feature is accomplished by harnessing the advanced capabilities of the OpenAI.

At the core of the Jobs API, the POST /jobs/generation endpoint serves as a remarkable tool for recruiters, empowering them to effortlessly create detailed job descriptions. Leveraging this endpoint, recruiters can input the job title and rely on the APIs sophisticated mechanisms to automatically generate comprehensive and accurate job descriptions.

7. Add users to Job Shortlist

The Shortlist feature allows recruiters to manage a list of candidates who have been shortlisted for a specific job. This feature helps in organizing and tracking potential candidates for a job role, making the recruitment process more efficient.

To get the current list of candidates who have been shortlisted for a specific job, use the GET /jobs/{jobId}/shortlist endpoint. This endpoint helps recruiters view the list of candidates who have been identified as potential fits for the job role, facilitating better tracking and management of the recruitment process.

8. Update users in Job Shortlist

To update the list of shortlisted candidates for a specific job, use the PATCH /jobs/{jobId}/shortlist endpoint. This endpoint provides flexibility in managing the shortlist by allowing recruiters to update the list of potential candidates dynamically, ensuring that the most suitable candidates are considered for the role.

9. Delete users from Job Shortlist

To delete one or more candidates from the shortlist for a specific job, use the DELETE /jobs/{jobId}/shortlist endpoint. This endpoint allows recruiters to clean up the shortlist by removing candidates who are no longer being considered for the job, ensuring that only relevant candidates remain in the list.

10. Add Notes to Shortlisted Candidate

To add notes to a specific candidate in the shortlist for a particular job, use the PATCH /jobs/{jobId}/shortlist endpoint with the candidateID query parameter. This endpoint helps recruiters keep detailed records of their observations and interactions with candidates, making it easier to review and decide on the suitability of each candidate during the recruitment process.

Job profiles

At the core of our job management system are the Job Profiles, the most detailed and specific component within an organization's job structure. Job Profiles precisely define the responsibilities, duties, required skills, and knowledge for particular positions. By providing detailed classifications, Job Profiles ensure clarity and consistency in role expectations, facilitating targeted recruitment, performance evaluation, and professional development within the organization. This documentation aims to provide developers with a comprehensive understanding of Job Profiles, their attributes, and the available endpoints for interacting with them.

Here is an overview of the attributes included in our Job profile data model:

Attributes	Description
ID	Unique identifier associated with a specific job profile.
externalId	To store the ID of a job profile from a different system.
translations	Contains title and description for the job profile in various languages.
creator	User who created the job profile.
owner	User who is the primary contact for the job profile.
state	Indicates the current state of the job profile (draft, active, or archived).
skills	An array of skills (id and level) required for the job profile.
updatedAt	Time when the job profile was last updated.

1. Create a Job Profile

To start the job profile lifecycle, you need to create a new job profile. You can do this by using the POST /job-profiles endpoint. This endpoint allows you to create job profiles by providing the required attributes from the job profile data model. While it's not mandatory to fill in all the attributes, you must include certain essential fields when creating a job profile, such as state and translations.

If you have limited information about the job profile when creating it, you can set the profile's state to "draft" using the state attribute. This will allow the creation of a preliminary job profile, which can be refined and updated with more details before changing its state to "Active."

2. Retrieve a Job Profile

Once you have successfully created a job profile, you can retrieve the specific profile by using its ID. Use the GET /job-profiles/{jobProfileId} endpoint to retrieve a particular job profile. In the endpoint URL, replace {jobProfileId} with the actual ID assigned during creation. This will allow you to access detailed information and attributes associated with that specific job profile, providing a comprehensive understanding of its characteristics.

If the profile ID is not readily available, there is an alternative approach. You can retrieve a comprehensive list of all job profiles present within the system by using the GET /job-profiles endpoint. This endpoint provides an overview of all profiles, allowing you to browse the options and locate the desired profile if the specific profile ID is unknown.

3. Update a Job Profile

As job profiles evolve and progress, the need to update different associated fields arises. The API offers the flexible PATCH /job-profiles/{jobProfileId} endpoint to empower you with control over these updates. This endpoint allows you to make specific modifications to job profile attributes, without the need to update every attribute. When utilizing the PATCH /job-profiles/{jobProfileId} endpoint, it is essential to include the profileId in the endpoint URL to specify the exact job profile that requires updating. Additionally, provide the updated fields within the request to reflect the desired changes. It is worth noting that all attributes are optional for updating, meaning that you can modify one or more specific fields without updating every attribute.

However, specific attributes cannot be null during the update process. These attributes include state and translations. It is crucial to ensure these attributes are met.

4. Delete a Job Profile

When a job profile is no longer needed or should be removed from the system, you can delete it using the API. The API provides the DELETE /job-profiles/{jobProfileId} endpoint, specifically designed for this purpose. This endpoint will delete the job profile and all associated data and attributes from the system. It's crucial to be cautious when using this endpoint, as deleted profiles cannot be recovered. Therefore, ensuring that the profile truly needs to be deleted before using this endpoint is essential.

5. Job Profile Filtering

The API offers a comprehensive job profile filtering feature, allowing you to refine your job profile search based on specific criteria. To explore the available filtering options, you can utilize the GET /job-profiles/filter endpoint, which provides a detailed list of fields that can be used to filter job profiles. This endpoint returns a comprehensive set of filterable fields, enabling you to fine-tune your search based on desired attributes.

Once you have identified the relevant filter criteria, you can retrieve job profiles matching those filters. The POST /job-profiles/filter endpoint allows you to submit your filter criteria within the request body. By specifying the desired filters in the request, the endpoint will return a list of job profiles that align with your criteria.

With the combination of the GET /job-profiles/filter and POST /job-profiles/filter endpoints, you can efficiently navigate and retrieve job profiles that meet your specific requirements.

User recommendations

User Recommendations leverage user skills and job requirements to identify suitable job opportunities for users. This feature allows for a more targeted job search process by matching users to jobs based on their skill sets and recommending relevant job openings. This documentation aims to provide developers with a comprehensive understanding of User Recommendations and the available endpoints for interacting with them.

1. Job Recommendations for a User

To identify potential job opportunities that are a good fit for a user based on their skill sets, use the GET /users/{userId}/jobs endpoint. This functionality supports the job search process by providing a curated list of job openings, making it easier for users to find roles that match their qualifications and career aspirations.

2. Matching Skills and Score for a Job

To get detailed information on the matching skills, missing skills, and the overall matching score between the user and the job, use the GET /users/{userId}/jobs/{jobId}/matching endpoint. It helps in evaluating how well a user's skills align with the job requirements, identifying areas for improvement, and making informed decisions in the job application process.

Job recommendations

Job Recommendations leverage job and user skills to identify suitable job candidates. This feature allows for a more targeted recruitment process by matching users to jobs based on their skill sets and recommending upskilling where necessary. This documentation aims to provide developers with a comprehensive understanding of Job Recommendations and the available endpoints for interacting with them.

1. Candidate Recommendations for a Job

To identify potential candidates who are a good fit for the job based on their skill sets, use the GET /jobs/{jobId}/candidates endpoint. This functionality supports the recruitment process by providing a curated list of candidates, making it easier to find the right person for the role.

2. Single Candidate Information

To get detailed information about the specified candidate, such as their skills, experience, and any other relevant attributes, use the GET /jobs/{jobId}/candidates/{candidateId} endpoint. This detailed view helps recruiters and managers understand a candidate's qualifications and suitability for the job.

3. Learning Opportunities for Candidate Upskilling

To get a list of learning opportunities that can help a candidate address missing skills for a job, use the GET /jobs/{jobId}/candidates/{candidateId}/learning-opportunities endpoint. This endpoint identifies gaps in the candidate's skills and provides relevant learning opportunities to fill those gaps.

4. Matching Skills and Score for a Candidate

To get detailed information on the matching skills, missing skills, and the overall matching score between the candidate and the job, use the GET /jobs/{jobId}/candidates/{candidateId}/matching endpoint. It helps in evaluating how well a candidate's skills align with the job requirements, identifying areas for improvement, and making informed decisions in the recruitment process.

5. Filter Candidate Recommendations

The API also offers candidate filtering feature, allowing you to refine your recommended candidate list based on specific criteria. To explore the available filtering options, you can utilize the GET /jobs/{jobId}/candidates/filter endpoint, which provides a detailed list of fields that can be used to filter candidates.

Once you have identified the relevant filter criteria, you can proceed to retrieve candidates that match those filters. The POST /jobs/{jobId}/candidates/filter endpoint serves this purpose, allowing you to submit your filter criteria within the request body. By specifying the desired filters in the request, the endpoint will return a list of candidates that align with your specified criteria.

The Upskilling section is designed to manage learning opportunities within the organization. It offers various functions for creating, retrieving, updating, deleting, filtering, and recommending learning opportunities. Additionally, users can be assigned learning opportunities to support their professional development.

Learning opportunities

Learning Opportunities form a crucial part of our job management system, providing a structured approach for employees to enhance their skills and knowledge. These opportunities can include courses, books and other educational activities. This documentation aims to provide developers with a comprehensive understanding of Learning Opportunities, their attributes, and the available endpoints for interacting with them.

Here is an overview of the attributes included in our Learning Opportunity data model:

Attributes	Description
ID	Unique identifier associated with a specific learning opportunity.
externalId	To store the ID of a learning opportunity from a different system.
translations	Contains title and description for the learning opportunity in various languages.
type	Indicates what type of learning opportunity (course).
ownerName	User who created the learning opportunity.
state	Indicates the current state of the learning opportunity (draft, published, or archived).
url	To store the url address of the learning opportunity
learningLanguage	To store in which language the learning opportunity is in.
provider	To store who is the provider of the learning opportunity.
skills	An array of skills at are associated with the learning opportunity.
createdAt	Time when the learning opportunity is created.
updatedAt	Time when the learning opportunity was last updated.

1. Create a Learning Opportunity

You need to create a new learning opportunity to initiate the learning opportunity lifecycle. You can do this by using the POST /learning-opportunities endpoint. This endpoint allows you to create learning opportunities by providing the required attributes from the learning opportunity data model. While filling in all the attributes is not mandatory, you must include specific essential fields when creating a learning opportunity, such as title, translations, state, and skills.

When creating the learning opportunity, you can set the profile's state to "draft" using the state attribute if you have limited information about it. This will allow a preliminary learning opportunity to be refined and updated with more details before changing its state to "Active."

2. Retrieve a Learning Opportunity

Once you have successfully created a learning opportunity, you can retrieve the specific opportunity by using its ID. Use the GET /learning-opportunities/{learningOpportunityId} endpoint to retrieve a particular learning opportunity. In the endpoint URL, replace {learningOpportunityId} with the ID assigned during creation. This will allow you to access detailed information and attributes associated with that specific learning opportunity, providing a comprehensive understanding of its characteristics.

If the opportunity ID is not readily available, there is an alternative approach. You can retrieve a comprehensive list of all learning opportunities present within the system by using the GET /learning-opportunities endpoint. This endpoint provides an overview of all opportunities, giving you the flexibility to browse the options and locate the desired opportunity if the specific opportunity ID is unknown.

3. Update a Learning Opportunity

As learning opportunities evolve and progress, the need to update different associated fields arises. The API offers the flexible PATCH /learning-opportunities/{learningOpportunityId} endpoint to empower you with control over these updates. This endpoint allows you to make specific modifications to learning opportunity attributes without the need to update every attribute. When utilizing this endpoint, it is essential to include the opportunityId in the endpoint URL to specify the exact learning opportunity that requires updating.

Additionally, provide the updated fields within the request to reflect the desired changes. It is worth noting that all attributes are optional for updating, meaning that you can modify one or more specific fields without updating every attribute. However, specific attributes cannot be null during the update process. These attributes include translations, type, state, and skills, and it is crucial to ensure they are met.

4. Delete a Learning Opportunity

When a learning opportunity is no longer needed or should be removed from the system, you can delete it using the API. The API provides the DELETE /learning-opportunities/{learningOpportunityId} endpoint, specifically designed for this purpose. This endpoint will delete the learning opportunity and all associated data and attributes from the system. It's crucial to be cautious when using this endpoint, as deleted opportunities cannot be recovered. Therefore, it is essential to delete the opportunity before using this endpoint.

5. Learning Opportunity Filtering

The API offers a comprehensive learning opportunity filtering feature, allowing you to refine your learning opportunity search based on specific criteria. To explore the available filtering options, you can utilize the GET /learning-opportunities/filter endpoint, which provides a detailed list of fields that can be used to filter learning opportunities. This endpoint returns a comprehensive set of filterable fields, enabling you to fine-tune your search based on desired attributes.

Once you have identified the relevant filter criteria, you can retrieve learning opportunities matching those filters. The POST /learning-opportunities/filter endpoint allows you to submit your filter criteria within the request body. By specifying the desired filters in the request, the endpoint will return a list of learning opportunities that align with your criteria.

With the combination of the GET /learning-opportunities/filter and POST /learning-opportunities/filter endpoints, you can efficiently navigate and retrieve learning opportunities that meet your specific requirements.

6. Learning Opportunity Recommendations

Learning Opportunity Recommendations are designed to help users find relevant learning opportunities based on specific skills they wish to develop. This feature leverages the skillId to provide tailored recommendations, ensuring users can easily discover opportunities that align with their professional development goals.

To get personalized learning opportunity recommendations based on a specific skill, use the GET /learning-opportunities/recommendations endpoint. This endpoint requires the skillId as a query parameter to generate relevant recommendations.

Featured Opportunities

Featured Opportunities are specially highlighted learning opportunities assigned to specific users to promote their professional growth. These opportunities are curated based on the user’s role, skills, and career aspirations. This documentation aims to provide developers with a comprehensive understanding of Featured Opportunities, their attributes, and the available endpoints for interacting with them.

1. Set featured opportunity

To assign a learning opportunity to a user as a featured opportunity, you can do this by using the POST /featured-opportunities/{learningOpportunityId} endpoint. This endpoint allows you to assign learning opportunities to multiple users simultaneously.

2. Get users for featured opportunity

Once you assign a featured opportunity to users, you can retrieve the specific user's list using the learningOpportunityID. Use the GET /featured-opportunities/{learningOpportunityID} endpoint to get a particular user list. In the endpoint URL, replace {learningOpportunityID} with the ID assigned during creation. This will allow you to access detailed information which includes user ID, featured at what time, and who assigned it to the user.

3. Delete featured opportunity

When a featured opportunity is no longer needed or should be removed for a user, you can delete it using the DELETE /featured-opportunities/{learningOpportunity} endpoint. This endpoint will remove the featured opportunity and all associated data assigned to a user. It's crucial to be cautious when using this endpoint, as removed featured opportunities cannot be recovered. Therefore, ensuring that the user's opportunity is removed before using this endpoint is essential.

4. Get featured Opportunities for user

On the other hand, if a user wants to know which learning opportunities are assigned to them, they can utilize the GET /users/{userId}/featured-opportunities endpoint. By replacing the userId in the endpoint URL, this endpoint will provide a comprehensive list of all learning opportunities assigned to that particular user, including who assigned it to them and at what time.

The API has comprehensive error handling to provide clear and informative responses when issues occur. This section provides details for the error handling approach and explains how error responses are structured.

All endpoints in the API have error responses that provide detailed information about encountered issues. These responses are designed to help developers understand and resolve problems effectively. Error responses include the following elements:

HTTP Status Codes

Error responses are accompanied by appropriate HTTP status codes to indicate the nature of the error. Some of the status codes for error responses are:

• 400 Bad Request: The request is invalid or malformed.
• 401 Unauthorized: The request requires user authentication.
• 403 Forbidden: The authenticated user does not have permission to access the requested resource.
• 404 Not Found: The requested resource was not found.
• 500 Internal Server Error: An unexpected error occurred on the server.

Error Message Structure

Error responses contain a structured message that provides information about the issue. The message typically includes the following elements:

• error code: A code that can be used for programmatic error handling.
• message: A human-readable description of the error, providing additional context, such as validation errors or specific error details

For more details about the specific error responses for each endpoint, please refer to the API Reference section. The API Reference provides comprehensive documentation for each endpoint, including the possible error scenarios, associated status codes, and detailed error messages.

To ensure fair usage and prevent abuse, rate limiting mechanisms have been implemented on the application endpoints. The following information outlines the specific rate limits that are enforced and describes how they are applied.

Rate Limiting Rules

The application endpoints adhere to the following rate limits:

• Each user ID is allowed to send a maximum of 500 requests per minute.

• Once the limit of 500 requests per minute is reached, the user ID will be restricted to 50 requests per 10 minutes.

These rate limits serve to maintain a balanced and equitable usage of the API, preventing any individual user from overwhelming the system with excessive requests. By carefully controlling the rate at which requests are accepted, the API ensures a smooth and reliable experience for all users.

This section is dedicated to helping you resolve any issues or challenges you may encounter while working with the Talent API. Our support team is committed to providing timely assistance and ensuring a smooth experience throughout your integration process.

If you require support or have any questions regarding the Talent API, there are several ways to seek assistance:

• Documentation: First and foremost, make sure to thoroughly review the API documentation. It contains comprehensive information about the APIs features, endpoints, request/response structures, and common use cases. Frequently, the documentation will answer many of your questions and provide guidance on proper API usage.

• Support Ticket: If you have exhausted the available resources and still require assistance, you can submit a support ticket. Our support team will promptly review your request and provide personalized assistance to address your specific needs. When submitting a support ticket, please provide detailed information about the issue you are facing, including any relevant error messages, request/response examples, and steps to reproduce the problem. The more information you provide, the faster we can diagnose and resolve the issue.

• Contacting Support: For urgent matters or critical issues, you can contact our support team directly. We prioritize such cases and will respond as quickly as possible to minimize any disruption to your application. You can find the contact details for our support team in your contract.

The API Reference section serves as a comprehensive guide, offering detailed information about the various endpoints available within the Talent API. Within this section, you will find distinct sections dedicated to jobs, skills, and locations, each providing an exhaustive list of endpoints specific to that area.

For every endpoint, the API reference provides in-depth details about the request and response structures, including any mandatory parameters that need to be supplied and the expected data formats for successful interaction with the API.

Operations to work with users

Operations to work with job postings

Operations to generate content with assistance of AI

Operations to read data from the Skills graph