JOB RECOMMENDER
API DOCUMENTATION
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.
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 givenprofile_id
job_id
recommendations for a given batch ofprofile_id
sprofile_id
recommendations for a givenjob_id
profile_id
recommendations for a given batch ofjob_id
s
Additionally, the existance of specfic profile_id
s and job_id
s can be checked and these resources can also be deleted on request.
The quality of recommendations depends on the completeness of the profile_id
s and job_id
s 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_id
s and job_id
s are inmediately available upon processing
the corresponding post request. These recommendations are also dynamically updated based on profile-job interactions.
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/jsonrequired
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
- Payload
{- "client_id": "string",
- "client_secret": "string",
- "scope": "api/ALL",
- "type": "client"
}
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:
Request Body schema: application/jsonrequired
external_id required | string The unique entity identifier. In this case, the |
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
- Payload
{- "external_id": "string",
- "client_data": { },
- "addresses": [
- "string"
], - "gender": "F",
- "year_of_birth": 1900,
- "description": "string",
- "highest_educational_level": "string",
- "languages": [
- {
- "language": "string",
- "proficiency": "ELEMENTARY"
}
], - "certificates": [
- "string"
], - "skills": [
- "string"
], - "skill_tags": [
- {
- "name": "string",
- "experience": "JUNIOR",
- "type": "GENERATED"
}
], - "interests": [
- "string"
], - "desired_jobs": [
- "string"
], - "undesired_jobs": [
- "string"
], - "desired_job_seniority_levels": [
- "JUNIOR"
], - "degrees": [
- {
- "title": "string",
- "institution": "string",
- "description": "string",
- "level": "string",
- "attendance_start_datetime": "2019-08-24T14:15:22Z",
- "attendance_end_datetime": "2019-08-24T14:15:22Z"
}
], - "experiences": [
- {
- "title": "string",
- "organization_name": "string",
- "organization_vatin": "string",
- "description": "string",
- "job_start_datetime": "2019-08-24T14:15:22Z",
- "job_end_datetime": "2019-08-24T14:15:22Z"
}
], - "relationship_preferences": [
- "EMPLOYEE"
], - "location_preferences": [
- "LOCAL"
], - "employment_term_preferences": [
- "INDEFINITE"
], - "capacity_preferences": [
- "FULL_TIME"
], - "workday_preferences": [
- "WEEKDAYS"
], - "hours_preferences": [
- "DAY"
], - "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:
Request Body schema: application/jsonrequired
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
- Payload
{- "profile_id": "string",
- "job_id": "string",
- "match_actor": "CANDIDATE",
- "match_datetime": "2019-08-24T14:15:22Z",
- "match_type": "PAGEVIEW",
- "metadata": {
- "origin": "LITTO_MATCHING",
- "direction": "JOB2JOB",
- "origin_id": "string",
- "client_data": { }
}
}
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:
Request Body schema: application/jsonrequired
external_id required | string The unique entity identifier. In this case, the |
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
- Payload
{- "external_id": "string",
- "client_data": { },
- "title": "string",
- "addresses": [
- "string"
], - "publisher_name": "string",
- "publisher_description": "string",
- "employer_name": "string",
- "employer_description": "string",
- "department": "string",
- "description": "string",
- "required_qualifications": [
- "string"
], - "skill_tags": [
- {
- "name": "string",
- "experience": "JUNIOR",
- "type": "GENERATED"
}
], - "offers": [
- "string"
], - "benefits": [
- "string"
], - "contains_video": true,
- "contains_header_image": true,
- "is_top_job": true,
- "apply_method": "EMAIL",
- "application_instructions_str": "string",
- "compensation": {
- "compensation_currency": "string",
- "from": 0,
- "to": 0,
- "type": "HOURLY"
}, - "languages": [
- {
- "language": "string",
- "proficiency": "ELEMENTARY"
}
], - "degrees": [
- "string"
], - "education_levels": [
- "string"
], - "seniority_preferences": [
- "JUNIOR"
], - "relationship_preferences": [
- "EMPLOYEE"
], - "location_preferences": [
- "LOCAL"
], - "employment_term_preferences": [
- "INDEFINITE"
], - "capacity_preferences": [
- "FULL_TIME"
], - "workday_preferences": [
- "WEEKDAYS"
], - "hours_preferences": [
- "DAY"
], - "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
}
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.
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.
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_id
s. Conversely, calls for retreiving
profile recommendations given a single job_id
or a batch of job_id
s, 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:
path Parameters
profile_id required | string |
Request Body schema: application/jsonrequired
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 |
Array of objects (LocationFilter) The array of coordinates and distances, to replace the entity addresses. This takes precendence over the | |
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
- Payload
{- "filters": [
- {
- "key": "string",
- "operator": "OVERLAP",
- "value": [
- { }
]
}
], - "max_distance": 0,
- "location_filters": [
- {
- "geopoint": {
- "lat": -90,
- "lon": -180
}, - "distance_in_km": 30
}
], - "continuation_token": "string",
- "limit": 10,
- "interactions_to_filter": [
- "PAGEVIEW"
], - "show_explanation": false,
- "experimental": false
}
Recommend profiles for a batch of jobs.
Returns user profile recommendations for a batch of specified job_id
s. Optional parameters control the number of recommendations and provide additional filters.
Authorizations:
Request Body schema: application/jsonrequired
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
- Payload
{- "external_ids": [
- "string"
], - "match_config": {
- "filters": [
- {
- "key": "string",
- "operator": "OVERLAP",
- "value": [
- { }
]
}
], - "max_distance": 0,
- "location_filters": [
- {
- "geopoint": {
- "lat": -90,
- "lon": -180
}, - "distance_in_km": 30
}
], - "continuation_token": "string",
- "limit": 10,
- "interactions_to_filter": [
- "PAGEVIEW"
], - "show_explanation": false,
- "experimental": false
}
}
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:
path Parameters
job_id required | string |
Request Body schema: application/jsonrequired
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 |
Array of objects (LocationFilter) The array of coordinates and distances, to replace the entity addresses. This takes precendence over the | |
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
- Payload
{- "filters": [
- {
- "key": "string",
- "operator": "OVERLAP",
- "value": [
- { }
]
}
], - "max_distance": 0,
- "location_filters": [
- {
- "geopoint": {
- "lat": -90,
- "lon": -180
}, - "distance_in_km": 30
}
], - "continuation_token": "string",
- "limit": 10,
- "interactions_to_filter": [
- "PAGEVIEW"
], - "show_explanation": false,
- "experimental": false
}
Recommend jobs for a batch of profiles.
Returns job recommendations for a batch of specified profile_id
s. Optional parameters control the number of recommendations and provide additional filters.
Authorizations:
Request Body schema: application/jsonrequired
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
- Payload
{- "external_ids": [
- "string"
], - "match_config": {
- "filters": [
- {
- "key": "string",
- "operator": "OVERLAP",
- "value": [
- { }
]
}
], - "max_distance": 0,
- "location_filters": [
- {
- "geopoint": {
- "lat": -90,
- "lon": -180
}, - "distance_in_km": 30
}
], - "continuation_token": "string",
- "limit": 10,
- "interactions_to_filter": [
- "PAGEVIEW"
], - "show_explanation": false,
- "experimental": false
}
}