Nobl.ai

JOB RECOMMENDER
API DOCUMENTATION

Job Recommender - API Reference

Job Recommender - API Reference

Download OpenAPI specification:Download

The HR Software linking job and applicant without ifs, buts, or maybes.

API Support: support@nobl.ai | Website: www.nobl.ai.

Introduction

The Nobl API follows the principles of REST, providing a straightforward and efficient way to interact with various resources. The API has predictable resource-oriented URLs, accepts form-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs.

The API accepts JSON encoded user profiles, job descriptions and profile-job matches as inputs. As outputs it can provide:

  • job_id recommendations for a given profile_id
  • job_id recommendations for a given batch of profile_ids
  • profile_id recommendations for a given job_id
  • profile_id recommendations for a given batch of job_ids

Additionally, the existance of specfic profile_ids and job_ids can be checked and these resources can also be deleted on request.

The quality of recommendations depends on the completeness of the profile_ids and job_ids as well as the amount of profile-job interactions. In general, users with complete CV and many interactions will receive better job recommendations. Similarly, jobs for which more information is available will receive better candidate profile recommendations. Recommendations for new profile_ids and job_ids are inmediately available upon processing the corresponding post request. These recommendations are also dynamically updated based on profile-job interactions.

Authentication

The Nobl API uses API Keys to authenticate requests. A client_id and client_secret will be provided by the Nobl support team allowing for authentication at the /auth endpoint. Upon successful authentication, a time-limited Access Token will be received and can be used to authorize subsequent requests by including the header Authorization: {access_token}. The complete documentation of the authentication POST call is summarized below including required parameters, data formats, possible responses, and examples.

Authenticate with the nobl API.

Authenticates with the Nobl API using client_id and client_secret.

header Parameters
Content-Type
required
string
X-Amz-Target
required
string
Request Body schema: application/json
required
client_id
required
string

The client ID. Example: "client-company-env@nobl.ai" .

client_secret
required
string

The client secret.

scope
string
Default: "api/ALL"

The authentication scope.

type
string (TypeEnum)
Default: "client"
Enum: "client" "user"

The type of user being authenticated (AuthClientType).

Responses

Request samples

Content type
application/json
{
  • "client_id": "string",
  • "client_secret": "string",
  • "scope": "api/ALL",
  • "type": "client"
}

Add or Update

The API exposes a number of calls that allow for the addition or updating of resources such as user profiles, jobs and user-job interactions (or matches). Next, each of these POST API calls are described in detailed including their required parameters, data formats, possible responses and examples.

Add or update a profile.

Adds or updates a user profile. If the profile_id exists, its informations is updated, otherwise a new user profile is created. Recommendations for new users are inmediately available after processing this request.

Authorizations:
cognito-auth
Request Body schema: application/json
required
external_id
required
string

The unique entity identifier. In this case, the profile_id.

client_data
object (ClientData)

Other optional job-seeker-specific data.

addresses
required
Array of strings

The array of addresses closest to which the job seeker is looking for work, at post-code level granularity only and including the city and country names. Note this is not the same as the addresses where the job seeker is looking for work. Example: ["Zwijnaarde, 9052 Gent, Belgium"].

gender
string (Gender)
Enum: "F" "M" "X"

The gender of the job seeker.

year_of_birth
integer [ 1900 .. 2100 ]

The year of birth of the job seeker.

description
string <= 100000 characters

The profile description of the job seeker. Should not include identifiable personal information.

highest_educational_level
string^[0-9]{1,3}$

The highest level of education attained by the job seeker, as defined in ISCED 2011 levels (https://en.wikipedia.org/wiki/International_Standard_Classification_of_Education, http://uis.unesco.org/sites/default/files/documents/international-standard-classification-of-education-isced-2011-en.pdf). Preferably as granular as possible. Example: "65".

Array of objects (Language)

The array of languages and proficiencies of the job seeker.

certificates
Array of strings

The array of descriptions of the certificates held by the job seeker.

skills
Array of strings

The array of skills of the job seeker.

Array of objects (SkillTag)

The array of skill tags of the job seeker.

interests
Array of strings

The array of descriptions of the job seeker's interests.

desired_jobs
Array of strings

The array of desired job titles or short job descriptions.

undesired_jobs
Array of strings

The array of undesired job titles or short job descriptions.

desired_job_seniority_levels
Array of strings (ExperienceLevel)
Items Enum: "JUNIOR" "MEDIOR" "SENIOR"

The array of desired job seniority levels.

Array of objects (Degree)

The array of attained or in-progress degrees of the job seeker. If the degree is in-progress, leave the attendanceEndDateTime blank. Only include degrees that are not attained or in-progress!

Array of objects (Experience)

The array of work experiences of the job seeker. If the job is in-progress, leave the job_end_datetime blank.

relationship_preferences
Array of strings (RelationshipType)
Items Enum: "EMPLOYEE" "CONTRACTOR" "CONTRACT_TO_HIRE" "INTERN" "JOB_STUDENT" "VOLUNTEER" "FREELANCE" "STARTER" "INTERIM" "INTERIM_TO_HIRE" "FLEXI_JOB"

The array of employment relationship types prefered.

location_preferences
Array of strings (LocationType)
Items Enum: "LOCAL" "REMOTE" "RELOCATE" "FLY_IN_FLY_OUT"

The array of employment location types prefered.

employment_term_preferences
Array of strings (TermType)
Items Enum: "INDEFINITE" "TEMPORARY"

The array of employment term types prefered.

capacity_preferences
Array of strings (CapacityType)
Items Enum: "FULL_TIME" "PART_TIME" "PER_DIEM"

The array of employment capacity types prefered.

workday_preferences
Array of strings (DaysType)
Items Enum: "WEEKDAYS" "WEEKENDS" "HOLIDAYS"

The array of employment day types prefered.

hours_preferences
Array of strings (HoursType)
Items Enum: "DAY" "MORNING" "AFTERNOON" "EVENING" "NIGHT"

The array of employment hour types prefered.

string or string

The localized timestamp (including timezone) when the job seeker profile was last updated in ISO 8601 (https://en.wikipedia.org/wiki/ISO_8601). Example: "2020-01-01T00:00:00+01:00".

string or string

The most recent localized timestamp (including timezone) when this job seeker profile was published in ISO 8601 (https://en.wikipedia.org/wiki/ISO_8601). Example: "2020-01-01T00:00:00+01:00".

string or string

The localized timestamp (including timezone) when this job seeker profile expires in ISO 8601 (https://en.wikipedia.org/wiki/ISO_8601). If null, this profile does not expire. Example: "2020-01-01T00:00:00+01:00".

may_be_recommended
boolean
Default: true

Whether this job seeker profile may be recommended (subject to the profile publish and expire times).

may_receive_recommendations
boolean
Default: true

Whether this job seeker may receive recommendations.

Responses

Request samples

Content type
application/json
{
  • "external_id": "string",
  • "client_data": { },
  • "addresses": [
    ],
  • "gender": "F",
  • "year_of_birth": 1900,
  • "description": "string",
  • "highest_educational_level": "string",
  • "languages": [
    ],
  • "certificates": [
    ],
  • "skills": [
    ],
  • "skill_tags": [
    ],
  • "interests": [
    ],
  • "desired_jobs": [
    ],
  • "undesired_jobs": [
    ],
  • "desired_job_seniority_levels": [
    ],
  • "degrees": [
    ],
  • "experiences": [
    ],
  • "relationship_preferences": [
    ],
  • "location_preferences": [
    ],
  • "employment_term_preferences": [
    ],
  • "capacity_preferences": [
    ],
  • "workday_preferences": [
    ],
  • "hours_preferences": [
    ],
  • "last_updated_datetime": "2019-08-24T14:15:22Z",
  • "publication_datetime": "2019-08-24T14:15:22Z",
  • "expiration_datetime": "2019-08-24T14:15:22Z",
  • "may_be_recommended": true,
  • "may_receive_recommendations": true
}

Add a match indicator.

Adds a profile-job match indicator. Both profile_id and job_id must already exist.

Authorizations:
cognito-auth
Request Body schema: application/json
required
profile_id
required
string

The id of the entity performing the match action.

job_id
required
string

The id of the entity receiving the match action.

match_actor
required
string (MatchActor)
Enum: "CANDIDATE" "EMPLOYER" "CANDIDATE_AND_EMPLOYER" "INTERMEDIARY"

The actor performing the match action.

match_datetime
required
string <date-time>

The localized timestamp (including timezone) at which the match occured in ISO 8601 (https://en.wikipedia.org/wiki/ISO_8601). Example: "2020-01-01T00:00:00+01:00".

match_type
required
string (MatchType)
Enum: "PAGEVIEW" "SAVE" "APPLY" "APPLY_INTENTION" "RECOMMEND" "INVITE" "GOOD_MATCH" "BAD_MATCH" "PREVIEW" "INTERVIEW" "HIRE"

The type of match action.

object (MatchMetadata)

The match metadata body.

Responses

Request samples

Content type
application/json
{
  • "profile_id": "string",
  • "job_id": "string",
  • "match_actor": "CANDIDATE",
  • "match_datetime": "2019-08-24T14:15:22Z",
  • "match_type": "PAGEVIEW",
  • "metadata": {
    }
}

Add or update a job.

Adds or updates a job. If the job_id exists, its informations is updated, otherwise a new job is created. Recommendations for new jobs are inmediately available after processing this request.

Authorizations:
cognito-auth
Request Body schema: application/json
required
external_id
required
string

The unique entity identifier. In this case, the job_id.

client_data
object (ClientData)

Other optional job-specific data.

title
required
string <= 500 characters

The title of the job ad.

addresses
required
Array of strings

The array of street addresses related to the job ad, at post-code level granularity only and including the city and country names. At least one address is requred. Example: ["Zwijnaarde, 9052 Gent, Belgium"].

publisher_name
string <= 255 characters

The name of the job ad publisher.

publisher_description
string <= 100000 characters

The description of the job ad publisher.

employer_name
string <= 255 characters

The name of the employer.

employer_description
string <= 100000 characters

The description of the employer.

department
string <= 255 characters

The name of the department or area within the company with the open position.

description
string <= 100000 characters

The description of the job.

required_qualifications
Array of strings

The array of descriptions of each qualification and skill required for the job.

Array of objects (SkillTag)

The array of skill tags of the job.

offers
Array of strings

The array of offers of the job.

benefits
Array of strings

The array of benefits offered by the job.

contains_video
boolean

Whether this job ad contains a video.

contains_header_image
boolean

Whether this job ad contains a header image.

is_top_job
boolean

Whether this job ad is a top job.

apply_method
string (ApplyMethod)
Enum: "EMAIL" "WEBSITE" "WHATSAPP"

The method of application for the job.

application_instructions_str
string <= 3000 characters

The instructions a candidate should follow to apply for the job.

object (Compensation)

The compensation offered by the job.

Array of objects (Language)

The array of languages and proficiencies required for the job.

degrees
Array of strings

The array of educational degrees required for the job.

education_levels
Array of strings

The array of education levels required, as defined in ISCED 2011 levels (https://en.wikipedia.org/wiki/International_Standard_Classification_of_Education, http://uis.unesco.org/sites/default/files/documents/international-standard-classification-of-education-isced-2011-en.pdf). Preferably as granular as possible. Example: ["65","75"].

seniority_preferences
Array of strings (ExperienceLevel)
Items Enum: "JUNIOR" "MEDIOR" "SENIOR"

The array of seniority levels prefered.

relationship_preferences
Array of strings (RelationshipType)
Items Enum: "EMPLOYEE" "CONTRACTOR" "CONTRACT_TO_HIRE" "INTERN" "JOB_STUDENT" "VOLUNTEER" "FREELANCE" "STARTER" "INTERIM" "INTERIM_TO_HIRE" "FLEXI_JOB"

The array of employment relationship types prefered.

location_preferences
Array of strings (LocationType)
Items Enum: "LOCAL" "REMOTE" "RELOCATE" "FLY_IN_FLY_OUT"

The array of employment location types prefered.

employment_term_preferences
Array of strings (TermType)
Items Enum: "INDEFINITE" "TEMPORARY"

The array of employment term types prefered.

capacity_preferences
Array of strings (CapacityType)
Items Enum: "FULL_TIME" "PART_TIME" "PER_DIEM"

The array of employment capacity types prefered.

workday_preferences
Array of strings (DaysType)
Items Enum: "WEEKDAYS" "WEEKENDS" "HOLIDAYS"

The array of employment day types prefered.

hours_preferences
Array of strings (HoursType)
Items Enum: "DAY" "MORNING" "AFTERNOON" "EVENING" "NIGHT"

The array of employment hour types prefered.

string or string

The localized start timestamp (including timezone) of the job ad in ISO 8601 (https://en.wikipedia.org/wiki/ISO_8601). If null, it is known that there is no start time. If this property is missing, the start time is unknown. Example: "2020-01-01T00:00:00+01:00".

string or string

The localized end timestamp (including timezone) of the job ad in ISO 8601 (https://en.wikipedia.org/wiki/ISO_8601). If null, it is known that there is no end time. If this property is missing, the end time is unknown. Example: "2020-01-01T00:00:00+01:00".

string or string

The localized timestamp (including timezone) when this job ad was last updated in ISO 8601 (https://en.wikipedia.org/wiki/ISO_8601). Example: "2020-01-01T00:00:00+01:00".

string or string

The most recent localized timestamp (including timezone) when this job ad was published in ISO 8601 (https://en.wikipedia.org/wiki/ISO_8601). Example: "2020-01-01T00:00:00+01:00".

string or string

The localized timestamp (including timezone) when this job ad expires in ISO 8601 (https://en.wikipedia.org/wiki/ISO_8601). If null, this job ad does not expire. Example: "2020-01-01T00:00:00+01:00".

may_be_recommended
boolean

Whether this job ad may be recommended (subject to the job ad publish and expire times).

may_receive_recommendations
boolean

Whether this job ad may receive recommendations.

Responses

Request samples

Content type
application/json
{
  • "external_id": "string",
  • "client_data": { },
  • "title": "string",
  • "addresses": [
    ],
  • "publisher_name": "string",
  • "publisher_description": "string",
  • "employer_name": "string",
  • "employer_description": "string",
  • "department": "string",
  • "description": "string",
  • "required_qualifications": [
    ],
  • "skill_tags": [
    ],
  • "offers": [
    ],
  • "benefits": [
    ],
  • "contains_video": true,
  • "contains_header_image": true,
  • "is_top_job": true,
  • "apply_method": "EMAIL",
  • "application_instructions_str": "string",
  • "compensation": {
    },
  • "languages": [
    ],
  • "degrees": [
    ],
  • "education_levels": [
    ],
  • "seniority_preferences": [
    ],
  • "relationship_preferences": [
    ],
  • "location_preferences": [
    ],
  • "employment_term_preferences": [
    ],
  • "capacity_preferences": [
    ],
  • "workday_preferences": [
    ],
  • "hours_preferences": [
    ],
  • "job_start_datetime": "2019-08-24T14:15:22Z",
  • "job_end_datetime": "2019-08-24T14:15:22Z",
  • "last_updated_datetime": "2019-08-24T14:15:22Z",
  • "publication_datetime": "2019-08-24T14:15:22Z",
  • "expiration_datetime": "2019-08-24T14:15:22Z",
  • "may_be_recommended": true,
  • "may_receive_recommendations": true
}

Delete

Resources such as user profiles and jobs can also be deleted from the system by using the appropriate API calls. The two HTTP DELETE-based calls available are describes below including their required parameters, data formats, possible responses and examples.

Delete a profile.

Deletes the user profile with the specified profile_id.

Authorizations:
cognito-auth
path Parameters
profile_id
required
string

Responses

Delete a job.

Deletes the job with the specified job_id.

Authorizations:
cognito-auth
path Parameters
job_id
required
string

Responses

Fetch

Functionalities for checking the existance of specific user profiles and jobs are also provided. The API exposes GET methods that accept a profile_id or job_id parameter and return a boolean response. These API calls are described in detail below including their required parameters, data formats, possible responses and examples.

Check profile existance.

Checks the existance of a user profile with the specified profile_id.

Authorizations:
cognito-auth
path Parameters
profile_id
required
string

Responses

Check job existance.

Checks the existance of a job with the specified job_id.

Authorizations:
cognito-auth
path Parameters
job_id
required
string

Responses

Recommend

The core functionality of the Nobl API is facilitated by the recommendation-related API calls. These calls are build around HTTP POST methods and can return a number of job recommendations given a single profile_id or a batch of profile_ids. Conversely, calls for retreiving profile recommendations given a single job_idor a batch of job_ids, are also implemented. Below, each of these API calls are described in detail including their required parameters, data formats, possible responses and examples.

Recommend jobs for a profile.

Returns job recommendations for the specified profile_id. Optional parameters control the number of recommendations and provide additional filters.

Authorizations:
cognito-auth
path Parameters
profile_id
required
string
Request Body schema: application/json
required
Array of objects (Filter)

The array of filters to filter results based on entity properties.

max_distance
integer

The maximum radius around the entity address in which to look for recommendations. This is not used if location_filters is specified.

Array of objects (LocationFilter)

The array of coordinates and distances, to replace the entity addresses. This takes precendence over the max_distance parameter.

continuation_token
string

The continuation token for getting the next page of recommendations. Example: "2023-09-16T17:28:54$5".

limit
integer <= 200
Default: 10

The number of results to return.

interactions_to_filter
Array of strings (InteractionType)
Items Enum: "PAGEVIEW" "SAVE" "APPLY" "APPLY_INTENTION" "RECOMMEND" "INVITE" "GOOD_MATCH" "BAD_MATCH" "PREVIEW" "INTERVIEW" "HIRE"

The array of interaction types to filter.

show_explanation
boolean
Default: false

Enables human readable explanations.

experimental
boolean
Default: false

Enables the latest experimental improvements.

Responses

Request samples

Content type
application/json
{
  • "filters": [
    ],
  • "max_distance": 0,
  • "location_filters": [
    ],
  • "continuation_token": "string",
  • "limit": 10,
  • "interactions_to_filter": [
    ],
  • "show_explanation": false,
  • "experimental": false
}

Recommend profiles for a batch of jobs.

Returns user profile recommendations for a batch of specified job_ids. Optional parameters control the number of recommendations and provide additional filters.

Authorizations:
cognito-auth
Request Body schema: application/json
required
external_ids
Array of strings

The array of unique entity ids for which to get recommendations.

object (MatchConfig)

The match config body.

Responses

Request samples

Content type
application/json
{
  • "external_ids": [
    ],
  • "match_config": {
    }
}

Recommend profiles for a job.

Returns user profile recommendations for the specified job_id. Optional parameters control the number of recommendations and provide additional filters.

Authorizations:
cognito-auth
path Parameters
job_id
required
string
Request Body schema: application/json
required
Array of objects (Filter)

The array of filters to filter results based on entity properties.

max_distance
integer

The maximum radius around the entity address in which to look for recommendations. This is not used if location_filters is specified.

Array of objects (LocationFilter)

The array of coordinates and distances, to replace the entity addresses. This takes precendence over the max_distance parameter.

continuation_token
string

The continuation token for getting the next page of recommendations. Example: "2023-09-16T17:28:54$5".

limit
integer <= 200
Default: 10

The number of results to return.

interactions_to_filter
Array of strings (InteractionType)
Items Enum: "PAGEVIEW" "SAVE" "APPLY" "APPLY_INTENTION" "RECOMMEND" "INVITE" "GOOD_MATCH" "BAD_MATCH" "PREVIEW" "INTERVIEW" "HIRE"

The array of interaction types to filter.

show_explanation
boolean
Default: false

Enables human readable explanations.

experimental
boolean
Default: false

Enables the latest experimental improvements.

Responses

Request samples

Content type
application/json
{
  • "filters": [
    ],
  • "max_distance": 0,
  • "location_filters": [
    ],
  • "continuation_token": "string",
  • "limit": 10,
  • "interactions_to_filter": [
    ],
  • "show_explanation": false,
  • "experimental": false
}

Recommend jobs for a batch of profiles.

Returns job recommendations for a batch of specified profile_ids. Optional parameters control the number of recommendations and provide additional filters.

Authorizations:
cognito-auth
Request Body schema: application/json
required
external_ids
Array of strings

The array of unique entity ids for which to get recommendations.

object (MatchConfig)

The match config body.

Responses

Request samples

Content type
application/json
{
  • "external_ids": [
    ],
  • "match_config": {
    }
}
Scroll to Top