Articles in this section

For Job Boards

Avatar
Elizaveta Shevchenko
Updated
Follow

Our Search product allows our clients to seek candidates on various job boards/platforms from a single interface. More information about this product can be found here.

This article provides an API guideline you (a job board) should follow in order for Broadbean to integrate with your CV/Résumé search.

 

Requirements for Your CV/Résumé API

Your API must:

  • Support the following calls:
  • Respond in real-time; connections with no data flow will be terminated and marked as failed after 20 seconds
  • Be multi-threaded as we will make concurrent requests
  • In the event of a failure/error, send a meaningful response, eg. "Username/Password not recognised", "Insufficient credit" etc.
  • Support pagination
  • Be able to mirror searching directly on the job board as much as possible

 

Authentication

Authentication can be done as a separate request or be included in the keyword/criteria search call.

We support various types of authentication, eg. Basic Auth, OAuth, Bearer Token etc.

 

Keyword/Criteria Search

To make a request we need to know:

  • HTTPS end-point
  • Supported fields:
    • mandatory, optional
    • possible values if a drop-down, any mappings
    • validations/exceptions
  • How the pagination works
  • Request example. We support the following formats: XML, JSON, URL encoded

The response has to include:

  • A total number of results
  • A list of candidates' snippets/previews with a unique ID for each of them

Request example

{
   "Account": {
      "Username": "recruiter@company.com",
      "Password": "Password!$#"
   },
   "Search_Query": {
      "Keywords": "IT manager OR Project manager",
      "Location": "London",
      "Radius": "10",
      "Contract_Type": "Permanent",
      "Salary_Cur": "GBP",
      "Salary_Min": "30000",
      "Salary_Max": "40000",
      "Salary_Rate": "annum",
      "Updated_within": "90",
      "Results_per_page": "25",
      "Page": "1"
   }

Response example

{
   "Search_Response": {
      "Total_Results": "150",
      "Results": [
         {
            "Record_Id": "12345",
            "Name": "John Smith",
            "Email": "john_smith@email.com",
            "Snippet": "Candidate description....",
            "Last_updated": "10.05.2019"
         },
         {...},
         {...},
         {...},
         {...}
      ]
   }
}

 

Candidate Profile View

To make a request we need to know:

  • HTTPS end-point
  • Whether it is chargeable or not
  • How we pass a candidate ID
  • Request example. We support the following formats: XML, JSON, URL encoded

The response has to include:

  • The candidate profile including name and email address
  • Sometimes includes the CV text
Request example 
{
   "Account": {
      "Username": "recruiter@company.com",  
      "Password": "Password!$#"
   },
   "Candidate_Profile_Query": {
      "Record_Id": "1234"
   }
}
Response example
{
   "Candidate_Profile_Response": {
      "Address": "...",
      "Education": [...],
      "Experience": [...],
      "Skills": [...],
      "CV_text": "...",
      ...
    }
}

 

CV Download

To make a request we need to know:

  • HTTPS end-point
  • Whether it is chargeable or not
  • How we pass a candidate ID
  • Request example. We support the following formats: XML, JSON, URL encoded

The response has to include:

  • 1 CV file
  • In one of these supported formats: .doc, .docx, .pdf, .txt, .rtf, .html
  • Maximum size 10MB

Request example

{
   "Account": {
      "Username": "recruiter@company.com",  
      "Password": "Password!$#"
   },
   "Candidate_CV_Query": {
      "Record_Id": "1234"
   }
}

Response example

{
   "Candidate_CV_Response": {
      "File": {
         "Transform": "base64",
         "Filename": "1234.doc",
         "Content-type": "application/msword",
         "File": "Base64 encoded file"
      }
   }
}

Related articles