(715) 203-0276 | Contact Us | FAQ

Home Candidate Search API
Recent Posts
Most Popular

Candidate Search API

Feb 10, 2021 HiringOpps Job Board Software API Documentation 0 Share

Candidate Search API allows to search candidates, view their profiles and download their resumes.

Searches, candidate views and resume downloads will spend subscription limitations accordingly, identically to user doing the same via the site. All examples here are for demo.hiringopps.com, but the same will work for other job boards using HiringOpps.

Request and Response format

All requests to any of the API endpoints should be GET requests.

Response will always contain JSON, with the exception of Resume download endpoint, which will return file contents.

Authorization

Authorization in the API is user-based. Each user gets a unique API token.

To authorize, add token to the GET request.

All endpoints which have URL starting with /api/v1/company require a token.

Example:
https://demo.hiringopps.com/api/v1/company/candidate/search?occupation=117&specialties[]=973&token=daei2598


Data Structure

Countries

Countries of the world

https://demo.hiringopps.com/api/country/get-all


States

Regions of the country

https://demo.hiringopps.com/api/state/country/228

228 is id of the country.

Occupations

Occupation is a general area of candidate's specialization. Each site has some occupations. All the other data is based on occupations. To get a list of occupations, use https://demo.hiringopps.com/api/occupation/all

Specialties

Specialties specify more exactly in which area of an occupation the candidate specializes.

To get a list of specialties, use:

https://demo.hiringopps.com/api/specialty/by-occupations?occupations=117

Where 117 is id of occupation

Degrees

Degrees are qualifications awarded to the candidates. They are specific to the occupation. Not all occupations have degrees. Job board might not have a degrees.

https://demo.hiringopps.com/api/degree/by-occupations?occupations=117


Work Environments

Work Environments are types of environments where candidate is willing to work. They are specific to the occupation. Not all occupations have them. Job board might not have work environments.

https://demo.hiringopps.com/api/work-environment/by-occupations?occupations=117


Position Types

Position types specify a type of job a candidate is ready to take. They are specific to the occupation. Not all occupations have them. Job board might not have position types.

https://demo.hiringopps.com/api/position-type/by-occupations?occupations=117



The criteria can be used to filter search results is not static, but it's not changed often either.

Itt can be cached for performance, but in case the job board updates job categories, the data might get stale and will get errors, so in case you are caching this data, it's recommended to re-request the search criteria.


Candidate Search Endpoint


To access candidate search functionality, make requests to

https://demo.hiringopps.com/api/v1/company/candidate/search

The search endpoint mimics the search functionality of the site. It's using the same URL structure, so to get an idea of what is possible, you can try to search the site and then replace https://demo.hiringopps.com/company/candidate/search with 

https://demo.hiringopps.com/api/v1/company/candidate/search in the URL and also change the token parameter.


Possible Filter Parameters

Specialties should belong to an occupation with the id specified in occupation parameter (1 in the example URL).

  • keywords takes space-separated list of keywords. Candidates' profiles and resumes are searched for these keywords. All words have to be present in the profile for it to match.

Board Certifications should belong to an occupation with the id specified in occupation parameter (1 in the example URL).

Position Types should belong to an occupation with the id specified in occupation parameter (1 in the example URL).

Degrees should belong to an occupation with the id specified in occupation parameter (1 in the example URL).

  • radius takes radius in miles of cities that should also need to be included in search results. Allowed values are integers between 0 and 250. Default is 0. This parameter can not be used without specifying any cities in cities[].
  • minExperience takes a minimal number of work experience in years the candidate is required to have. Allowed values are integers between 0 and 20. Default is 0.
  • maxExperience takes a maximal number of work experience in years the candidate is required to have. Allowed values are integers between 0 and 20. Default is no upper limit
  • dateAvailable takes a date when candidate is available for work in MM/DD/YYYY format, e.g. 08/13/2018.
  • registeredWithinType takes either range or preformatted. 
  • When it is set to range, registeredWithinTo and registeredWithinFrom should be specified, set to dates in MM/DD/YYYY format, e.g. 08/13/2018.
  • When it is set to preformatted, registeredWithin parameter should be one of the following values:
      • 1d
      • 7d
      • 14d
      • 30d
      • 60d
      • 90d
      • 6m
      • 1y
      • 2y
      • 3y

It filters candidates by registration date.

  • sponsorshipStatus takes one of 
  • visa_sponsorship_exclude  - exclude candidates requiring visa sponsorship
  • visa_sponsorship_only - only show candidates requiring visa sponsorship

If it is not specified, all candidates are shown.



Parameters that end with [] can be added to the URL more than once, to add multiple values for the filter, e.g. specialties[]=166&specialties[]=427

Pagination

    • parameter resultsPerPage takes integers between 1 and 50. Default is 10. It controls how many results are return per page
    • In the response, field total shows the total number of results.
  • parameter page takes integers between 1 and total results/results per page. Default is 1. Incrementing it by 1 loads next page of results


To provide the search results, the system requires at least one of the following:


Response structure

Response contains array profiles. Each profile has summary information about the candidate

    • id is an internal id, can be used to request more information about the candidate by viewing their profile. This corresponds to the profile ID in admin
    • name field may contain initial or full name of the candidate, depending on their privacy settings.
    • updatedAt is a date in a format MM/DD/YY when profile was last updated.
  • profilePicture is a URL of the user's profile picture or default profile picture if a user doesn't have a profile picture uploaded.
  • address contains a string in the format "State, Country" or "Country". More exact location if provided by candidate is available is when viewing candidate profile.
  • viewed is a boolean, shows whether current company user viewed this profile before.
  • contacted is a boolean, shows whether this candidate was contacted by current company user before.
  • appliedForCompanyJob is a boolean, shows whether this candidate applied for company jobs before.
  • willingToRelocate is a boolean, shows whether candidate is considering relocation for good job opportunities.
    • hasResume returns one of 3 values: "true", "false" and "confidential". "true" means candidate has a resume uploaded and it's available for download. "false" means candidate doesn't have a resume uploaded. "confidential" means candidate has a resume uploaded but candidate's privacy settings won't allow to view the resume unless candidate applies for one of the company's jobs.
  • occupation, specialties, degrees, positionTypes, boardCertifications, workEnvironments contain corresponding data about the candidate


View Candidate Endpoint

To get more information about candidate, you need to view their profile. This action consumes limitations from "Profile Views" part of the subscription, even if candidate doesn't have a resume uploaded. If candidate profile was viewed by the current user before, the action doesn't use up a limitation again.


To view a candidate, pass a get request to

https://demo.hiringopps.com/api/v1/company/candidate/view/{profile_id}

Example:

https://demo.hiringopps.com/api/v1/company/candidate/view/503131?token=daei2598


The response contains all the information about the candidate available:


    • name field may contain initial or full name of the candidate, depending on their privacy settings.
    • updateAt is a date in a format MM/DD/YY when profile was last updated
  • profilePicture is a URL of the user's profile picture or default profile picture if a user doesn't have a profile picture uploaded.
    • willingToRelocate is a boolean, shows whether candidate is considering relocation for good job opportunities
  • occupation, specialties, degrees, positionTypes, boardCertifications, workEnvironments contain corresponding data about the candidate
  • dateAvailable is a date candidate is available for work in a format MM/DD/YY
  • locationPreferences is an array of locations (countries, states, cities) where candidate is willing to work
  • stateLicenses is an array of States where candidates has a license 
  • state is the name of the state, 
  • licenseNumber is an optional field containing the number of the state license.
  • certifications is an array of various certifications candidate has
  • name has a name of certification
  • dateObtained is an optional field contains a date when candidate obtained the certification in a format MM/DD/YY
  • mobileNumber is candidate's mobile phone number 
  • phoneNumber is candidate's another phone number
  • address contains a string representation of candidate's location up to city
  • zipCode is candidate's ZIP code
  • resumes contains an array of all resumes candidate has uploaded.
      • uid is a parameter that can be used to download resume
  • filename is how the resume was named during upload
    • email is an email that can be used to contact the candidate
  • experience is a text explaining how many years of experience candidate has
  • educations contains a list of school candidate went to
      • school is a name of the school
  • level is an optional field showing education level achieved
  • startYear is a year education was or will be started
  • endYear is a year education was or will be ended
  • workExperiences contains an array of places the candidate worked
  • jobTitle is name of a title candidate held
  • organizationName is the name of the company
  • startDate is the date the work on this position was started by the candidate in the format MMM YYYY, where MMM is first 3 letter of an English name of the month
      • endDate is the date the candidate left the position. If not specified, work, candidate is still working on this position
  • occupation is an area of position that candidate held
  • description is a textual description of this work experience provided by the candidate
  • publications contains an array of candidate's published works
  • publicationName is a name of publication
  • articleName is a name of the article
  • publicationDate is a date when publication was made in a format MM/DD/YY
  • description is a textual description of publication provided by the candidate
  • organizations is an array containing a list of organizations which candidate is a member of.
      • name is organization name
  • joinDate is a date candidate joined organization in a format MMMM YYYY, where MMMM is full English month name
  • noteworthyInformation is a textual description of information candidate found noteworthy about themselves
  • missionStatement is a textual mission statement provided by the candidate
  • professionalMemberships is an array of professional organizations candidate is a member of

The fields that exist for every candidate:
name,  updatedAt, profilePicture, willingToRelocate, occupation, specialties, degrees, positionTypes, workEnvironments, locationPreferences, email


Resume Download Endpoint

To download CV/Resume uploaded by the candidate, send request to 


https://demo.hiringopps.com/api/v1/company/candidate/resume/{id}/{uid}. Where {id} is candidate id and {uid} is id of resume. UID is returned when viewing candidate's profile in resumes array.

API response JSON


 Resumes array is not present when the candidate doesn't have a resume uploaded.


Example:

https://demo.hiringopps.com/api/v1/company/candidate/resume/503131/KEVvrR8O9n97gBxy?token=daei2598


The response will contain the contents of the resume uploaded by the candidate.

Candidate Search API
HiringOpps Job Board Software

Comments