Nobl.ai

Nobl.ai

Menu
Book a demo

JOB MATCHING
API DOCUMENTATION

Nobl Job Matching API
API docs by Redocly

Nobl Job Matching API (0.0.1)

Download OpenAPI specification:

The HR Software linking vacancy 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 candidate profiles, vacancy descriptions, profile-vacancy matches, and CV parsing requests. As outputs it can provide:

  • vacancy_id recommendations for a given candidate_id
  • candidate_id recommendations for a given vacancy_id
  • Structured parsed profiles from CVs uploaded as file_bytes (pdf, docx, doc, txt), including extracted plaintext, warnings, and parser metadata
  • Top-N ESCO tags returned in vacancy create/update responses to support tagging integrated with the recommender API
  • Bias and model metrics for fairness and performance monitoring via analytics endpoints

The quality of recommendations depends on the completeness of the candidate_ids and vacancy_ids as well as the amount of candidate-vacancy interactions. In general, candidates with complete CV and many interactions will receive better recommendations. Similarly, vacancies for which more information is available will receive better candidate profile recommendations. Recommendations for new candidate_ids and vacancy_ids are immediately available upon processing the corresponding post request. These recommendations are also dynamically updated based on candidate-vacancy 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 Nobl API

Authenticates with the Nobl API using client_id and client_secret.

Returns a time-limited access token that can be used to authorize subsequent requests by including the header Authorization: Bearer {access_token}.

  • client_id: Client ID provided by the Nobl support team
  • client_secret: Client secret provided by the Nobl support team
Request Body schema: application/json
required
client_id
required
string (Client Id)

Client ID provided by Nobl support team

client_secret
required
string (Client Secret)

Client secret provided by Nobl support team

Responses

Request samples

Content type
application/json
{
  • "client_id": "string",
  • "client_secret": "string"
}

Response samples

Content type
application/json
{
  • "access_token": "string",
  • "token_type": "bearer",
  • "expires_at": "string"
}

Candidates

The API exposes a number of calls that allow for the addition or updating of candidates. Next, each of these API calls are described in detailed including their required parameters, data formats, possible responses and examples.

Create a new candidate

Creates a new candidate. Recommendations for new candidates are available immediately after processing this request.

Authorizations:
HTTPBearer
Request Body schema: application/json
required
candidate_id
required
string (Candidate Id)

The id of the candidate.

given_name
string (Given Name)

The given name of the candidate.

family_name
string (Family Name)

The family name of the candidate.

additional_name
string (Additional Name)

An additional name for a Person, can be used for a middle name.

email
string <email> (Email)

The email of the candidate.

phone
string (Phone)

The phone number of the candidate.

gender
string (Gender)
Enum: "MALE" "FEMALE" "NON_BINARY" "PREFER_NOT_TO_SAY"

The gender of the candidate. For fairness auditing only.

birth_date
string <date-time> (Birth Date)

The birth date of the candidate.

object (PostalAddress)

The address of the candidate.

Array of objects (Work Experiences)

The work experience of the candidate.

highest_education_level
string (EducationLevel)
Enum: "EARLY_CHILDHOOD_EDUCATION" "PRIMARY_EDUCATION" "LOWER_SECONDARY_EDUCATION" "UPPER_SECONDARY_EDUCATION" "POST_SECONDARY_NON_TERTIARY_EDUCATION" "SHORT_CYCLE_TERTIARY_EDUCATION" "BACHELOR_OR_EQUIVALENT_LEVEL" "MASTER_OR_EQUIVALENT_LEVEL" "DOCTORAL_OR_EQUIVALENT_LEVEL" "OTHER"

Requested education levels as defined in ISCED 2011 levels (https://en.wikipedia.org/wiki/International_Standard_Classification_of_Education). Preferably as granular as possible.

Array of objects (Languages)

The languages of the candidate.

Array of objects (Certificates)

The certificates of the candidate.

Array of objects (Trainings)

The training of the candidate.

Array of objects (Skills)

The skills of the candidate.

Array of objects (Interests)

The interests of the candidate, e.g. 'reading', 'sports', 'cooking', etc.

Array of objects (Degrees)

The degrees of the candidate.

object (MonetaryAmount)

The recent salary of the candidate.

object (CandidatePreferences)

The preferences of the candidate.

Array of objects (Social Media Profiles)

The social media profile of the candidate. e.g. LinkedIn, X, etc.

personal_statement
string (Personal Statement)

A personal statement of the candidate.

bio
string (Bio)

A bio of the candidate.

creation_datetime
required
string <date-time> (Creation Datetime)

The creation datetime of the candidate.

publication_datetime
required
string <date-time> (Publication Datetime)

The publication datetime of the candidate.

expiration_datetime
required
string <date-time> (Expiration Datetime)

The expiration datetime of the candidate.

last_updated_datetime
required
string <date-time> (Last Updated Datetime)

The last updated datetime of the candidate.

is_active
required
boolean (Is Active)

Whether the candidate is active.

Responses

Request samples

Content type
application/json
{
  • "candidate_id": "string",
  • "given_name": "string",
  • "family_name": "string",
  • "additional_name": "string",
  • "email": "user@example.com",
  • "phone": "string",
  • "gender": "MALE",
  • "birth_date": "2019-08-24T14:15:22Z",
  • "address": {
    },
  • "work_experiences": [
    ],
  • "highest_education_level": "EARLY_CHILDHOOD_EDUCATION",
  • "languages": [
    ],
  • "certificates": [
    ],
  • "trainings": [
    ],
  • "skills": [
    ],
  • "interests": [
    ],
  • "degrees": [
    ],
  • "recent_salary": {
    },
  • "preferences": {
    },
  • "social_media_profiles": [],
  • "personal_statement": "string",
  • "bio": "string",
  • "creation_datetime": "2019-08-24T14:15:22Z",
  • "publication_datetime": "2019-08-24T14:15:22Z",
  • "expiration_datetime": "2019-08-24T14:15:22Z",
  • "last_updated_datetime": "2019-08-24T14:15:22Z",
  • "is_active": true
}

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "string",
  • "timestamp": "2019-08-24T14:15:22Z"
}

Update candidate

Updates a candidate. Recommendations for updated candidates are available immediately after processing this request.

Authorizations:
HTTPBearer
path Parameters
candidate_id
required
string (Candidate Id)
Request Body schema: application/json
required
candidate_id
required
string (Candidate Id)

The id of the candidate.

given_name
string (Given Name)

The given name of the candidate.

family_name
string (Family Name)

The family name of the candidate.

additional_name
string (Additional Name)

An additional name for a Person, can be used for a middle name.

email
string <email> (Email)

The email of the candidate.

phone
string (Phone)

The phone number of the candidate.

gender
string (Gender)
Enum: "MALE" "FEMALE" "NON_BINARY" "PREFER_NOT_TO_SAY"

The gender of the candidate. For fairness auditing only.

birth_date
string <date-time> (Birth Date)

The birth date of the candidate.

object (PostalAddress)

The address of the candidate.

Array of objects (Work Experiences)

The work experience of the candidate.

highest_education_level
string (EducationLevel)
Enum: "EARLY_CHILDHOOD_EDUCATION" "PRIMARY_EDUCATION" "LOWER_SECONDARY_EDUCATION" "UPPER_SECONDARY_EDUCATION" "POST_SECONDARY_NON_TERTIARY_EDUCATION" "SHORT_CYCLE_TERTIARY_EDUCATION" "BACHELOR_OR_EQUIVALENT_LEVEL" "MASTER_OR_EQUIVALENT_LEVEL" "DOCTORAL_OR_EQUIVALENT_LEVEL" "OTHER"

Requested education levels as defined in ISCED 2011 levels (https://en.wikipedia.org/wiki/International_Standard_Classification_of_Education). Preferably as granular as possible.

Array of objects (Languages)

The languages of the candidate.

Array of objects (Certificates)

The certificates of the candidate.

Array of objects (Trainings)

The training of the candidate.

Array of objects (Skills)

The skills of the candidate.

Array of objects (Interests)

The interests of the candidate, e.g. 'reading', 'sports', 'cooking', etc.

Array of objects (Degrees)

The degrees of the candidate.

object (MonetaryAmount)

The recent salary of the candidate.

object (CandidatePreferences)

The preferences of the candidate.

Array of objects (Social Media Profiles)

The social media profile of the candidate. e.g. LinkedIn, X, etc.

personal_statement
string (Personal Statement)

A personal statement of the candidate.

bio
string (Bio)

A bio of the candidate.

creation_datetime
required
string <date-time> (Creation Datetime)

The creation datetime of the candidate.

publication_datetime
required
string <date-time> (Publication Datetime)

The publication datetime of the candidate.

expiration_datetime
required
string <date-time> (Expiration Datetime)

The expiration datetime of the candidate.

last_updated_datetime
required
string <date-time> (Last Updated Datetime)

The last updated datetime of the candidate.

is_active
required
boolean (Is Active)

Whether the candidate is active.

Responses

Request samples

Content type
application/json
{
  • "candidate_id": "string",
  • "given_name": "string",
  • "family_name": "string",
  • "additional_name": "string",
  • "email": "user@example.com",
  • "phone": "string",
  • "gender": "MALE",
  • "birth_date": "2019-08-24T14:15:22Z",
  • "address": {
    },
  • "work_experiences": [
    ],
  • "highest_education_level": "EARLY_CHILDHOOD_EDUCATION",
  • "languages": [
    ],
  • "certificates": [
    ],
  • "trainings": [
    ],
  • "skills": [
    ],
  • "interests": [
    ],
  • "degrees": [
    ],
  • "recent_salary": {
    },
  • "preferences": {
    },
  • "social_media_profiles": [],
  • "personal_statement": "string",
  • "bio": "string",
  • "creation_datetime": "2019-08-24T14:15:22Z",
  • "publication_datetime": "2019-08-24T14:15:22Z",
  • "expiration_datetime": "2019-08-24T14:15:22Z",
  • "last_updated_datetime": "2019-08-24T14:15:22Z",
  • "is_active": true
}

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "string",
  • "timestamp": "2019-08-24T14:15:22Z"
}

Delete candidate

Deletes the candidate with the given candidate_id

Authorizations:
HTTPBearer
path Parameters
candidate_id
required
string (Candidate Id)

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "string",
  • "timestamp": "2019-08-24T14:15:22Z"
}

Vacancies

The API exposes a number of calls that allow for the addition or updating of vacancies. Next, each of these API calls are described in detailed including their required parameters, data formats, possible responses and examples.

Create a new vacancy

Creates a new vacancy. Recommendations for new vacancies are available immediately after processing this request.

Authorizations:
HTTPBearer
Request Body schema: application/json
required
vacancy_id
required
string (Vacancy Id)

The unique identifier for the vacancy.

title
required
string (Title)

The title of the vacancy.

description
required
string (Description)

A description of the vacancy.

object (Place)

The address of the vacancy.

object (Industry)

The industry associated with the vacancy position. Use the ISIC 2008 classification (https://en.wikipedia.org/wiki/International_Standard_Industrial_Classification).

required_qualifications
Array of strings (Required Qualifications)

Specific qualifications required for this role or Occupation.

benefits
Array of strings (Benefits)

Description of benefits associated with the vacancy. Each benefit is a string.

Array of objects (Required Skills)

The skills required for the vacancy.

Array of objects (Required Languages)

The languages required for the vacancy.

minimum_education_level
string (EducationLevel)
Enum: "EARLY_CHILDHOOD_EDUCATION" "PRIMARY_EDUCATION" "LOWER_SECONDARY_EDUCATION" "UPPER_SECONDARY_EDUCATION" "POST_SECONDARY_NON_TERTIARY_EDUCATION" "SHORT_CYCLE_TERTIARY_EDUCATION" "BACHELOR_OR_EQUIVALENT_LEVEL" "MASTER_OR_EQUIVALENT_LEVEL" "DOCTORAL_OR_EQUIVALENT_LEVEL" "OTHER"

The minimum education level required for the vacancy.

object (VacancyPreferences)

The preferences of the vacancy.

object (OccupationCode)

A category describing the vacancy, preferably using a term from a taxonomy such as ESCO or similar, with the property repeated for each applicable value. Ideally the taxonomy should be identified, and both the textual label and formal code for the category should be provided.

object (MonetaryAmount)

An estimated salary for a vacancy posting or occupation, based on a variety of variables including, but not limited to industry, vacancy title, and location. Estimated salaries are often computed by outside organizations rather than the hiring organization, who may not have committed to the estimated value.

object (Organization-Input)

The organization that is publishing the vacancy.

object (Organization-Input)

The organization offering the vacancy.

total_vacancy_openings
integer (Total Vacancy Openings)

The number of positions open for this vacancy posting. Use a positive integer. Do not use if the number of positions is unclear or not known.

url
string <uri> (Url) [ 1 .. 2083 ] characters

The URL of the vacancy posting.

object (ContactPoint)

Contact details for further information relevant to this vacancy posting.

application_deadline
string <date-time> (Application Deadline)

The date and time the application deadline for the vacancy.

vacancy_start_datetime
string <date-time> (Vacancy Start Datetime)

The date on which a successful applicant for this vacancy would be expected to start work. Choose a specific date in the future or use the vacancyImmediateStart property to indicate the position is to be filled as soon as possible.

vacancy_end_datetime
string <date-time> (Vacancy End Datetime)

The date on which a successful applicant for this vacancy would be expected to end work. Choose a specific date in the future or use the vacancyImmediateStart property to indicate the position is to be filled as soon as possible.

creation_datetime
required
string <date-time> (Creation Datetime)

The creation datetime of the vacancy.

publication_datetime
required
string <date-time> (Publication Datetime)

The publication datetime of the vacancy.

expiration_datetime
required
string <date-time> (Expiration Datetime)

The expiration datetime of the vacancy.

last_updated_datetime
required
string <date-time> (Last Updated Datetime)

The last updated datetime of the vacancy.

is_active
required
boolean (Is Active)

Whether the vacancy is active.

Responses

Request samples

Content type
application/json
{
  • "vacancy_id": "string",
  • "title": "string",
  • "description": "string",
  • "address": {
    },
  • "industry": {
    },
  • "required_qualifications": [
    ],
  • "benefits": [
    ],
  • "required_skills": [
    ],
  • "required_languages": [
    ],
  • "minimum_education_level": "EARLY_CHILDHOOD_EDUCATION",
  • "preferences": {
    },
  • "occupational_category": {
    },
  • "estimated_salary": {
    },
  • "publisher": {
    },
  • "employer": {
    },
  • "total_vacancy_openings": 0,
  • "url": "http://example.com",
  • "application_contact": {
    },
  • "application_deadline": "2019-08-24T14:15:22Z",
  • "vacancy_start_datetime": "2019-08-24T14:15:22Z",
  • "vacancy_end_datetime": "2019-08-24T14:15:22Z",
  • "creation_datetime": "2019-08-24T14:15:22Z",
  • "publication_datetime": "2019-08-24T14:15:22Z",
  • "expiration_datetime": "2019-08-24T14:15:22Z",
  • "last_updated_datetime": "2019-08-24T14:15:22Z",
  • "is_active": true
}

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "string",
  • "timestamp": "2019-08-24T14:15:22Z"
}

Update vacancy

Updates a vacancy. Recommendations for updated vacancies are available immediately after processing this request.

Authorizations:
HTTPBearer
path Parameters
vacancy_id
required
string (Vacancy Id)
Request Body schema: application/json
required
vacancy_id
required
string (Vacancy Id)

The unique identifier for the vacancy.

title
required
string (Title)

The title of the vacancy.

description
required
string (Description)

A description of the vacancy.

object (Place)

The address of the vacancy.

object (Industry)

The industry associated with the vacancy position. Use the ISIC 2008 classification (https://en.wikipedia.org/wiki/International_Standard_Industrial_Classification).

required_qualifications
Array of strings (Required Qualifications)

Specific qualifications required for this role or Occupation.

benefits
Array of strings (Benefits)

Description of benefits associated with the vacancy. Each benefit is a string.

Array of objects (Required Skills)

The skills required for the vacancy.

Array of objects (Required Languages)

The languages required for the vacancy.

minimum_education_level
string (EducationLevel)
Enum: "EARLY_CHILDHOOD_EDUCATION" "PRIMARY_EDUCATION" "LOWER_SECONDARY_EDUCATION" "UPPER_SECONDARY_EDUCATION" "POST_SECONDARY_NON_TERTIARY_EDUCATION" "SHORT_CYCLE_TERTIARY_EDUCATION" "BACHELOR_OR_EQUIVALENT_LEVEL" "MASTER_OR_EQUIVALENT_LEVEL" "DOCTORAL_OR_EQUIVALENT_LEVEL" "OTHER"

The minimum education level required for the vacancy.

object (VacancyPreferences)

The preferences of the vacancy.

object (OccupationCode)

A category describing the vacancy, preferably using a term from a taxonomy such as ESCO or similar, with the property repeated for each applicable value. Ideally the taxonomy should be identified, and both the textual label and formal code for the category should be provided.

object (MonetaryAmount)

An estimated salary for a vacancy posting or occupation, based on a variety of variables including, but not limited to industry, vacancy title, and location. Estimated salaries are often computed by outside organizations rather than the hiring organization, who may not have committed to the estimated value.

object (Organization-Input)

The organization that is publishing the vacancy.

object (Organization-Input)

The organization offering the vacancy.

total_vacancy_openings
integer (Total Vacancy Openings)

The number of positions open for this vacancy posting. Use a positive integer. Do not use if the number of positions is unclear or not known.

url
string <uri> (Url) [ 1 .. 2083 ] characters

The URL of the vacancy posting.

object (ContactPoint)

Contact details for further information relevant to this vacancy posting.

application_deadline
string <date-time> (Application Deadline)

The date and time the application deadline for the vacancy.

vacancy_start_datetime
string <date-time> (Vacancy Start Datetime)

The date on which a successful applicant for this vacancy would be expected to start work. Choose a specific date in the future or use the vacancyImmediateStart property to indicate the position is to be filled as soon as possible.

vacancy_end_datetime
string <date-time> (Vacancy End Datetime)

The date on which a successful applicant for this vacancy would be expected to end work. Choose a specific date in the future or use the vacancyImmediateStart property to indicate the position is to be filled as soon as possible.

creation_datetime
required
string <date-time> (Creation Datetime)

The creation datetime of the vacancy.

publication_datetime
required
string <date-time> (Publication Datetime)

The publication datetime of the vacancy.

expiration_datetime
required
string <date-time> (Expiration Datetime)

The expiration datetime of the vacancy.

last_updated_datetime
required
string <date-time> (Last Updated Datetime)

The last updated datetime of the vacancy.

is_active
required
boolean (Is Active)

Whether the vacancy is active.

Responses

Request samples

Content type
application/json
{
  • "vacancy_id": "string",
  • "title": "string",
  • "description": "string",
  • "address": {
    },
  • "industry": {
    },
  • "required_qualifications": [
    ],
  • "benefits": [
    ],
  • "required_skills": [
    ],
  • "required_languages": [
    ],
  • "minimum_education_level": "EARLY_CHILDHOOD_EDUCATION",
  • "preferences": {
    },
  • "occupational_category": {
    },
  • "estimated_salary": {
    },
  • "publisher": {
    },
  • "employer": {
    },
  • "total_vacancy_openings": 0,
  • "url": "http://example.com",
  • "application_contact": {
    },
  • "application_deadline": "2019-08-24T14:15:22Z",
  • "vacancy_start_datetime": "2019-08-24T14:15:22Z",
  • "vacancy_end_datetime": "2019-08-24T14:15:22Z",
  • "creation_datetime": "2019-08-24T14:15:22Z",
  • "publication_datetime": "2019-08-24T14:15:22Z",
  • "expiration_datetime": "2019-08-24T14:15:22Z",
  • "last_updated_datetime": "2019-08-24T14:15:22Z",
  • "is_active": true
}

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "string",
  • "timestamp": "2019-08-24T14:15:22Z"
}

Delete vacancy

Deletes the vacancy with the given vacancy_id

Authorizations:
HTTPBearer
path Parameters
vacancy_id
required
string (Vacancy Id)

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "string",
  • "timestamp": "2019-08-24T14:15:22Z"
}

Get vacancy occupation category

Returns the occupational_category field for the vacancy with the given vacancy_id.

Authorizations:
HTTPBearer
path Parameters
vacancy_id
required
string (Vacancy Id)

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "string",
  • "timestamp": "2019-08-24T14:15:22Z",
  • "occupational_category": {
    }
}

Interactions

The API exposes a number of calls that allow for the addition or updating of interactions. Next, each of these API calls are described in detailed including their required parameters, data formats, possible responses and examples.

Create a new interaction

Creates a new interaction. Both candidate_id and vacancy_id have to be provided.

Authorizations:
HTTPBearer
Request Body schema: application/json
required
candidate_id
required
string (Candidate Id)

The id of the candidate.

vacancy_id
required
string (Vacancy Id)

The id of the vacancy.

timestamp
required
string <date-time> (Timestamp)

The timestamp (including timezone) of the interaction.

interaction_actor
required
string (InteractionActor)
Enum: "CANDIDATE" "EMPLOYER" "INTERMEDIARY"

The actor of the interaction.

interaction_type
required
string (InteractionType)
Enum: "VIEW" "SAVE" "LIKE" "DISLIKE" "FORWARD" "APPLY_INTEREST" "APPLY" "REJECT" "INTERVIEW" "HIRE"

The type of interaction.

session_id
required
string (Session Id)

The id of the session.

recommendation_id
string (Recommendation Id)

The id of the recommendation.

recommendation_position
integer (Recommendation Position)

Position in recommendation list

query
string (Query)

Raw search query if applicable, e.g., 'data scientist remote'

object (Context)

Additional context for the interaction, e.g., {'source': 'search'}

object (Filters)

Applied filters/facets for the interaction, e.g., {'location': 'NYC', 'experience': {'gte': 3}}

object (Sort)

Sorting parameters used, e.g., {'field': 'posted_at', 'order': 'desc'}

page
integer (Page)

Page number for paginated results, e.g., 2

page_size
integer (Page Size)

Page size for paginated results, e.g., 20

query_id
string (Query Id)

Identifier linking events to the originating query, e.g., 'q_123abc'

device_type
string (Device Type)

Device used (mobile/desktop/tablet)

source_page
string (Source Page)

Page where interaction originated

dwell_time_ms
integer (Dwell Time Ms)

Dwell time in milliseconds

Responses

Request samples

Content type
application/json
{
  • "candidate_id": "string",
  • "vacancy_id": "string",
  • "timestamp": "2019-08-24T14:15:22Z",
  • "interaction_actor": "CANDIDATE",
  • "interaction_type": "VIEW",
  • "session_id": "string",
  • "recommendation_id": "string",
  • "recommendation_position": 0,
  • "query": "string",
  • "context": { },
  • "filters": { },
  • "sort": { },
  • "page": 0,
  • "page_size": 0,
  • "query_id": "string",
  • "device_type": "string",
  • "source_page": "string",
  • "dwell_time_ms": 0
}

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "string",
  • "timestamp": "2019-08-24T14:15:22Z"
}

Recommendations

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 recommendations given a single candidate_id or a batch of candidate_ids. Conversely, calls for retrieving profile recommendations given a single vacancy_id or a batch of vacancy_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 vacancies/candidates for a candidate/vacancy

Recommend vacancies or candidates for a given user or vacancy. Return either candidate_ids or vacancy_ids depending on the parameter provided in the recommendation_type. If vacancy_id is provided, the returned recommendations will be candidate_ids. If candidate_id is provided, the returned recommendations will be vacancy_ids. Optionally, a limit parameter can be provided to limit the number of recommendations returned.

Authorizations:
HTTPBearer
Request Body schema: application/json
required
entity_id
required
string (Entity Id)

The id of the entity.

entity_type
required
string (RecommendationEntityType)
Enum: "CANDIDATE" "VACANCY"

The type of the entity.

limit
integer (Limit)
Default: 10

The number of recommendations to return.

include_explanation
boolean (Include Explanation)
Default: false

Whether to include explanations

object (Context)

The context of the recommendation.

object (Filters)

The filters for the recommendation.

Responses

Request samples

Content type
application/json
{
  • "entity_id": "string",
  • "entity_type": "CANDIDATE",
  • "limit": 10,
  • "include_explanation": false,
  • "context": { },
  • "filters": { }
}

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "string",
  • "timestamp": "2019-08-24T14:15:22Z",
  • "recommendation_id": "string",
  • "recommendations": [
    ],
  • "model_version": "string"
}

Recommend vacancies/users for a batch of users/vacancies

Recommend vacancies or users for a batch of users or vacancies. Return either candidate_ids or vacancy_ids depending on the parameter provided in the recommendation_type. If vacancy_id is provided, the returned recommendations will be candidate_ids. If candidate_id is provided, the returned recommendations will be vacancy_ids. Optionally, a limit parameter can be provided to limit the number of recommendations returned.

Authorizations:
HTTPBearer
Request Body schema: application/json
required
Array
entity_id
required
string (Entity Id)

The id of the entity.

entity_type
required
string (RecommendationEntityType)
Enum: "CANDIDATE" "VACANCY"

The type of the entity.

limit
integer (Limit)
Default: 10

The number of recommendations to return.

include_explanation
boolean (Include Explanation)
Default: false

Whether to include explanations

object (Context)

The context of the recommendation.

object (Filters)

The filters for the recommendation.

Responses

Request samples

Content type
application/json
[
  • {
    }
]

Response samples

Content type
application/json
[
  • {
    }
]

Parser

The API exposes a number of calls that allow for the parsing of CVs. Next, each of these API calls are described in detailed including their required parameters, data formats, possible responses and examples.

Parse a CV

Parses a text and returns the entities, relations, events, and entities with relations.

Authorizations:
HTTPBearer
Request Body schema: application/json
required
candidate_id
required
string (Candidate Id)

The id of the candidate.

file_bytes
required
string <binary> (File Bytes)

Binary contents of an uploaded file sent via API.

file_type
required
string (FileType)
Enum: "pdf" "docx" "doc" "txt"

File type of uploaded document. Allowed: pdf, docx, doc, txt.

filename
string (Filename)

Original filename (optional), used for heuristics and logging.

Responses

Request samples

Content type
application/json
{
  • "candidate_id": "string",
  • "file_bytes": "string",
  • "file_type": "pdf",
  • "filename": "string"
}

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "string",
  • "timestamp": "2019-08-24T14:15:22Z",
  • "data": {
    },
  • "raw_text": "string",
  • "warnings": [
    ],
  • "parser_metadata": { }
}

Analytics

The API exposes a number of calls that allow for the retrieval of bias and model metrics. Next, each of these API calls are described in detailed including their required parameters, data formats, possible responses and examples.

Get bias metrics

Get bias metrics for the current model.

Authorizations:
HTTPBearer

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "string",
  • "timestamp": "2019-08-24T14:15:22Z",
  • "bias_metrics": {
    }
}

Get model metrics

Get model metrics for the current model.

Authorizations:
HTTPBearer

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "string",
  • "timestamp": "2019-08-24T14:15:22Z",
  • "model_metrics": {
    }
}

Health

The API exposes a number of calls that allow for the health check of the system. Next, each of these API calls are described in detailed including their required parameters, data formats, possible responses and examples.

Check health of Nobl API

Checks the health of the Nobl API.

Returns a JSON object with a status field set to ok if the API is healthy.

Authorizations:
HTTPBearer

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "string",
  • "timestamp": "2019-08-24T14:15:22Z",
  • "health": {
    }
}
Scroll to Top