Nobl.ai

Nobl.ai

Menu
Book a demo

JOB MATCHING
API DOCUMENTATION

Nobl Job Matching API
API docs by Redocly

Nobl Job Matching API (v0.0.5)

Download OpenAPI specification:

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 candidate profiles, vacancy descriptions and candidate-vacancy interactions as inputs. As outputs it can provide:

  • Recommendations for candidates based on various criteria
  • Batch recommendation processing for multiple candidates
  • CV parsing capabilities to extract structured data from resumes
  • Analytics including bias metrics and model performance metrics
  • Health monitoring and system status information

Additionally, the existence of specific candidates and vacancies can be managed through creation, updates, and deletion operations.

The quality of recommendations depends on the completeness of candidate profiles and vacancy descriptions as well as the amount of candidate-vacancy interactions. In general, candidates with complete profiles and many interactions will receive better recommendations. Similarly, vacancies with comprehensive information will yield better matching results. Recommendations are immediately available upon processing the corresponding requests and are dynamically updated based on interactions.

Authentication

The Nobl API uses API Keys to authenticate requests. A clientId and clientSecret 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: {accessToken}. 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 clientId and clientSecret.

header Parameters
Content-Type
required
string
X-Amz-Target
required
string
Request Body schema: application/json
required
clientId
required
string (Client Id)

Client ID provided by Nobl support team

clientSecret
required
string (Client Secret)

Client secret provided by Nobl support team

Responses

Request samples

Content type
application/json
{
  • "clientId": "string",
  • "clientSecret": "string"
}

Candidates

The API exposes calls that allow for the addition, updating, and deletion of candidate profiles. Candidate profiles contain structured information about job seekers including their skills, experience, education, and other relevant attributes. These endpoints enable full CRUD operations on candidate data which forms the foundation for the recommendation system.

Add or update a candidate.

Adds or updates a candidate profile. If the candidate already exists, its information is updated, otherwise a new candidate profile is created. Recommendations for new candidates are immediately available after processing this request.

Authorizations:
cognito-auth
Request Body schema: application/json
required
identifier
required
string (Candidate Id)

The id of the candidate.

gender
string (Gender)
Enum: "MALE" "FEMALE" "NON_BINARY" "PREFER_NOT_TO_SAY"
birthDate
string <date-time> (Birth Date)

The birth date of the candidate.

object (Place)
Array of objects (Work Experiences)

The work experience of the candidate.

highestEducationLevel
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 level of education or training received by the person.

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.

Array of objects (Degrees)

The degrees of the candidate.

object (MonetaryAmount)
object (CandidatePreferences)
personalStatement
string (Personal Statement)

A personal statement of the candidate.

bio
string (Bio)

A bio of the candidate.

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

The creation datetime of the candidate.

datePosted
required
string <date-time> (Date Posted)

The date posted of the candidate.

validThrough
required
string <date-time> (Valid Through)

The valid through of the candidate.

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

The last updated datetime of the candidate.

isActive
required
boolean (Is Active)

Whether the candidate is active.

Responses

Request samples

Content type
application/json
{
  • "identifier": "string",
  • "gender": "MALE",
  • "birthDate": "2019-08-24T14:15:22Z",
  • "address": {
    },
  • "workExperiences": [
    ],
  • "highestEducationLevel": "EARLY_CHILDHOOD_EDUCATION",
  • "languages": [
    ],
  • "certificates": [
    ],
  • "trainings": [
    ],
  • "skills": [
    ],
  • "interests": [
    ],
  • "degrees": [
    ],
  • "recentSalary": {
    },
  • "preferences": {
    },
  • "personalStatement": "string",
  • "bio": "string",
  • "creationDatetime": "2019-08-24T14:15:22Z",
  • "datePosted": "2019-08-24T14:15:22Z",
  • "validThrough": "2019-08-24T14:15:22Z",
  • "lastUpdatedDatetime": "2019-08-24T14:15:22Z",
  • "isActive": true
}

Delete a candidate.

Deletes the candidate profile with the specified candidateId.

Authorizations:
cognito-auth
path Parameters
candidateId
required
string

Responses

Vacancies

Vacancy management endpoints allow for the creation, updating, deletion, and querying of job positions. Vacancy data includes job descriptions, requirements, location information, and other relevant details. The system can also extract occupation categories from vacancy descriptions to improve matching accuracy.

Get vacancy occupation category.

Retrieves the occupation category for the specified vacancyId.

Authorizations:
cognito-auth
path Parameters
vacancyId
required
string

Responses

Add or update a vacancy.

Adds or updates a vacancy. If the vacancy already exists, its information is updated, otherwise a new vacancy is created. Recommendations for new vacancies are immediately available after processing this request.

Authorizations:
cognito-auth
Request Body schema: application/json
required
identifier
required
string (Identifier)

The identifier property represents any kind of identifier for any kind of Thing, such as ISBNs, GTIN codes, UUIDs etc.

title
required
string (Title)

The title of the job (not the title of the posting). For example, "Software Engineer" or "Barista".

description
required
string (Description)

A description of the item.

required
object (Organization)
datePosted
required
string <date-time> (Date Posted)

Publication date for the job posting.

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

The creation datetime of the vacancy.

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

The last updated datetime of the vacancy.

isActive
required
boolean (Is Active)

Whether the vacancy is active.

required
object (Place)
EmploymentType (string) or string

Type of employment.

MonetaryAmount (object) or number or PriceSpecification (object)

The base salary of the job or of an employee in an EmployeeRole.

MonetaryAmount (object) or MonetaryAmountDistribution (object) or number

An estimated salary for a job posting or occupation, based on a variety of variables including, but not limited to industry, job title, and location.

salaryCurrency
string (Salary Currency)

The currency (coded using ISO 4217) used for the main salary information in this job posting or for this employee.

validThrough
required
string <date-time> (Valid Through)

The date after when the item is not valid. For example the end of an offer, salary period, or a period of opening hours.

workHours
string (Work Hours)

The typical working hours for this job (e.g. 1st shift, night shift, 8am-5pm).

object (CategoryCode)
Array of objects (Industry)

The industries associated with the job position.

Array of objects (Skill)

A statement of knowledge, skill, ability, task or any other assertion expressing a competency that is desired or required to fulfill this role or to work in this occupation.

Array of objects (Languages)

The languages of the candidate.

EducationalOccupationalCredential (object) or string

Specific qualifications required for this role or Occupation.

EducationalOccupationalCredential (object) or EducationLevel (string)

Educational background needed for the position or Occupation.

OccupationalExperienceRequirements (object) or string

Description of skills and experience needed for the position or Occupation.

experienceInPlaceOfEducation
boolean (Experience In Place Of Education)

Indicates whether a Vacancy will accept experience (as indicated by OccupationalExperienceRequirements) in place of its formal educational qualifications (as indicated by educationRequirements).

responsibilities
string (Responsibilities)

Responsibilities associated with this role or Occupation.

jobBenefits
string (Job Benefits)

Description of benefits associated with the job.

incentiveCompensation
string (Incentive Compensation)

Description of bonus and commission compensation aspects of the job.

specialCommitments
string (Special Commitments)

Any special commitments associated with this job posting. Valid entries include VeteranCommit, for jobs that are specifically targeted towards Veterans.

totalJobOpenings
integer (Total Job Openings)

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

jobLocationType
string (WorkLocationType)
Enum: "LOCAL" "REMOTE" "HYBRID" "RELOCATE" "FLY_IN_FLY_OUT"
Job Start Date (string) or Job Start Date (string) (Job Start Date)

The date on which a successful applicant for this job would be expected to start work.

jobImmediateStart
boolean (Job Immediate Start)

An indicator as to whether a position is available for an immediate start.

directApply
boolean (Direct Apply)

Indicates whether an url that is associated with a Vacancy enables direct application for the job, via the posting website.

object (ContactPoint)
object (AdministrativeArea)
eligibilityToWorkRequirement
string (Eligibility To Work Requirement)

The legal requirements such as citizenship, visa and other documentation required for an applicant to this job.

employerOverview
string (Employer Overview)

A description of the employer, career opportunities and work environment for this position.

object (Organization)
physicalRequirement
string (Physical Requirement)

A description of the types of physical activity associated with the job.

sensoryRequirement
string (Sensory Requirement)

A description of any sensory requirements and levels necessary to function on the job, including hearing and vision.

string or string

A description of any security clearance requirements of the job.

object (CategoryCode)
image
string <uri> (Image)

An image of the item. This can be a URL.

name
string (Name)

The name of the item.

url
string <uri> (URL)

URL of the item.

alternateName
string (Alternate Name)

An alias for the item.

disambiguatingDescription
string (Disambiguating Description)

A sub property of description. A short description of the item used to disambiguate from other, similar items.

CreativeWork (object) or string

Indicates a page (or other CreativeWork) for which this thing is the main entity being described.

Responses

Request samples

Content type
application/json
{
  • "identifier": "string",
  • "title": "string",
  • "description": "string",
  • "hiringOrganization": {
    },
  • "datePosted": "2019-08-24T14:15:22Z",
  • "creationDatetime": "2019-08-24T14:15:22Z",
  • "lastUpdatedDatetime": "2019-08-24T14:15:22Z",
  • "isActive": true,
  • "jobLocation": {
    },
  • "employmentType": "EMPLOYEE",
  • "baseSalary": {
    },
  • "estimatedSalary": {
    },
  • "salaryCurrency": "string",
  • "validThrough": "2019-08-24T14:15:22Z",
  • "workHours": "string",
  • "occupationalCategory": {
    },
  • "industry": [
    ],
  • "skills": [
    ],
  • "languages": [
    ],
  • "qualifications": {
    },
  • "educationRequirements": {
    },
  • "experienceRequirements": {
    },
  • "experienceInPlaceOfEducation": true,
  • "responsibilities": "string",
  • "jobBenefits": "string",
  • "incentiveCompensation": "string",
  • "specialCommitments": "string",
  • "totalJobOpenings": 0,
  • "jobLocationType": "LOCAL",
  • "jobStartDate": "2019-08-24",
  • "jobImmediateStart": true,
  • "directApply": true,
  • "applicationContact": {
    },
  • "applicantLocationRequirements": {
    },
  • "eligibilityToWorkRequirement": "string",
  • "employerOverview": "string",
  • "employmentUnit": {
    },
  • "physicalRequirement": "string",
  • "sensoryRequirement": "string",
  • "securityClearanceRequirement": "string",
  • "relevantOccupation": {
    },
  • "image": "http://example.com",
  • "name": "string",
  • "url": "http://example.com",
  • "alternateName": "string",
  • "disambiguatingDescription": "string",
  • "mainEntityOfPage": {
    }
}

Delete a vacancy.

Deletes the vacancy with the specified vacancyId.

Authorizations:
cognito-auth
path Parameters
vacancyId
required
string

Responses

Interactions

Interaction endpoints capture the relationships and activities between candidates and vacancies. These interactions help train and improve the recommendation algorithms by providing feedback on matches, applications, and other candidate-vacancy engagements.

Add an interaction.

Adds a candidate-vacancy interaction. Both candidate and vacancy must already exist in the system.

Authorizations:
cognito-auth
Request Body schema: application/json
required
candidateId
required
string (Candidate Id)

The id of the candidate.

vacancyId
required
string (Vacancy Id)

The id of the vacancy.

timestamp
required
string <date-time> (Timestamp)

The timestamp (including timezone) of the interaction.

interactionActor
required
string (InteractionActor)
Enum: "CANDIDATE" "EMPLOYER" "INTERMEDIARY"
interactionType
required
string (InteractionType)
Enum: "VIEW" "SAVE" "LIKE" "DISLIKE" "FORWARD" "APPLY_INTEREST" "APPLY" "REJECT" "INTERVIEW" "HIRE"
sessionId
required
string (Session Id)

The id of the session.

recommendationId
string (Recommendation Id)

The id of the recommendation.

recommendationPosition
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

pageSize
integer (Page Size)

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

queryId
string (Query Id)

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

deviceType
string (Device Type)

Device used (mobile/desktop/tablet)

sourcePage
string (Source Page)

Page where interaction originated

dwellTimeMs
integer (Dwell Time Ms)

Dwell time in milliseconds

Responses

Request samples

Content type
application/json
{
  • "candidateId": "string",
  • "vacancyId": "string",
  • "timestamp": "2019-08-24T14:15:22Z",
  • "interactionActor": "CANDIDATE",
  • "interactionType": "VIEW",
  • "sessionId": "string",
  • "recommendationId": "string",
  • "recommendationPosition": 0,
  • "query": "string",
  • "context": { },
  • "filters": { },
  • "sort": { },
  • "page": 0,
  • "pageSize": 0,
  • "queryId": "string",
  • "deviceType": "string",
  • "sourcePage": "string",
  • "dwellTimeMs": 0
}

Recommendations

The core functionality of the Nobl API is facilitated by the recommendation endpoints. These endpoints provide intelligent matching between candidates and vacancies based on various factors including skills, experience, preferences, and historical interactions. Both single and batch processing options are available for efficient handling of recommendation requests.

Get batch recommendations.

Returns recommendations for multiple entities in a single request. This is more efficient for processing large numbers of recommendation requests.

Authorizations:
cognito-auth
Request Body schema: application/json
required
entityIds
required
Array of strings (Entity Ids)

The ids of the entities.

entityType
required
string (RecommendationEntityType)
Enum: "CANDIDATE" "VACANCY"
limit
integer (Limit)
Default: 10

The number of recommendations to return.

includeExplanation
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
{
  • "entityIds": [
    ],
  • "entityType": "CANDIDATE",
  • "limit": 10,
  • "includeExplanation": false,
  • "context": { },
  • "filters": { }
}

Get recommendations.

Returns personalized recommendations based on the provided criteria. Optional parameters control the number of recommendations and provide additional filters.

Authorizations:
cognito-auth
Request Body schema: application/json
required
entityId
required
string (Entity Id)

The id of the entity.

entityType
required
string (RecommendationEntityType)
Enum: "CANDIDATE" "VACANCY"
limit
integer (Limit)
Default: 10

The number of recommendations to return.

includeExplanation
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
{
  • "entityId": "string",
  • "entityType": "CANDIDATE",
  • "limit": 10,
  • "includeExplanation": false,
  • "context": { },
  • "filters": { }
}

Parse

CV parsing functionality allows for the extraction of structured information from resume documents. This service can process various document formats and extract key information such as personal details, work experience, education, and skills, converting unstructured resume data into structured candidate profiles.

Parse CV document.

Parses a CV document and extracts structured information including personal details, work experience, education, and skills.

Authorizations:
cognito-auth
Request Body schema: application/json
required
candidateId
required
string (Candidate Id)

The id of the candidate.

fileBytes
required
string <byte> (File Bytes)

Binary contents of an uploaded file sent via API.

fileType
required
string (FileType)
Enum: "pdf" "docx" "doc" "txt"
filename
string (Filename)

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

Responses

Request samples

Content type
application/json
{
  • "candidateId": "string",
  • "fileBytes": "string",
  • "fileType": "pdf",
  • "filename": "string"
}

Analytics

Analytics endpoints provide insights into system performance and potential biases in the recommendation algorithms. These endpoints offer bias metrics to ensure fair and equitable matching, as well as model performance metrics to monitor the effectiveness of the recommendation system. They also provide Labor Market Information (LMI) insights.

Get LMI metrics.

Retrieves Labor Market Information (LMI) metrics based on accumulated job data and ESCO taxonomy.

Query Parameters:

  • start_date (Required): Start date for the analysis period (YYYY-MM-DD).
  • end_date (Required): End date for the analysis period (YYYY-MM-DD).
  • top_k_occupations (Optional): Number of top occupations to return (default: 10, min: 1, max: 100).
  • top_k_skills (Optional): Number of top skills to return (default: 10, min: 1, max: 100).
Authorizations:
cognito-auth
query Parameters
top_k_skills
string
start_date
required
string
end_date
required
string
top_k_occupations
string

Responses

Get bias metrics.

Retrieves bias metrics to analyze fairness and equity in the recommendation system.

Authorizations:
cognito-auth

Responses

Get model metrics.

Retrieves model performance metrics to monitor the effectiveness of the recommendation algorithms.

Authorizations:
cognito-auth

Responses

Health

Health monitoring endpoints provide system status information and can be used to verify that the API services are operational and responding correctly. These endpoints are useful for monitoring and alerting systems.

Health check.

Returns the health status of the API and its dependencies.

Authorizations:
cognito-auth

Responses

Scroll to Top