An API connector can be used to connect to a job board or career site.
Introduction
Context
Distribution of job offers on a jobboard by “API” or similar to a webhook: the API is created on the jobboard and will be called by Beetween.
Job offers are written on Beetween and broadcast on the destination job board thanks to a customized “connector” system integrated into the Beetween software’s job offer multicasting system.
The connector described here is an API connector, in which Beetween sends HTTP REST requests to the job board, according to a predefined format, for each job publication/offline operation. The jobboard must therefore develop an API that complies with the specifications in this documentation.
Compared with XML feeds, this system offers the advantage of near real-time publication, as well as better feedback to the recruiter. It is also much less resource-intensive.
In return, it requires specific development on the part of the jobboard.
Prerequisites
Setting up an API distribution connector requires the job board to develop an API entry point for feeding job offers. Before any development of specific job content to be sent by Beetween via API, the person in charge of development on the jobboard side must have read this document.
The job board must integrate an application form for each job offer, enabling candidates to apply: a specific e-mail address will be associated with each job offer to send applications via this form (or redirect to the URL present for each offer in the JSON file).
If necessary, we can also send applications by API, so ask your Beetween contact if you’re interested.
THE API CONNECTOR
General principle
Each job offer is identified by its Beetween public ID, which is a sequence of lower-case ascii letters and numbers, between 10 and 20 characters long. This ID is automatically generated by Beetween when an offer is placed online, and cannot be modified. It will be noted as $ID in the description of HTTP requests.
HTTP requests sent from Beetween to the job board enable the job to be published and taken offline. Data will be formatted in JSON.
When a job offer is published on the destination site, an HTTP POST request containing the job offer information is sent to the ENDPOINT. The call for creation or update is identical: it’s up to the destination site to check the presence of the offer using the ID supplied as a parameter.
When an offer is withdrawn from publication on the Beetween side, an HTTP DELETE request is sent, containing the offer ID.
HTTP requests
The root of the entry point is defined by the jobboard, and will hereafter be referred to as $ENDPOINT.
For example:
ENDPOINT = https://entry-point-chosen-by-jobboard.com/api/jobs
An HTTPS (not plain HTTP) entry point is strongly recommended.
This entry point must be accessible to Beetween via the Internet, without VPN or other configuration.
To avoid abusive calls, see the “Authentication” chapter.
Create or update a job offer
Here are the fields present in JSON :
To update an offer, the request is similar to putting an offer online: it’s a POST request with an existing ad ID.
Send request (Beetween -> ENDPOINT jobboard)
You’ll find a sample API request here.
For application_email, this value is the e-mail address for receiving applications. By default, this is an address generated by Beetween and specific to this offer, enabling applications to be integrated directly into Beetween. See the “Integration of applications in Beetween”, including the format of the e-mails to be sent for optimum retrieval of applicant information.
For details of the possible values for each field, see the appendix of this article.
Expected return request (Jobboard -> ENDPOINT Beetween)
- Status 200 in case of success
- All other statuses will be interpreted as error status.
- Body :
{
url:"",
userMessage:"",
developerMessage:""
}
Explanation of expected return attributes :
- url (required): displays the URL of the job offer on the job board in Beetween, so that the recruiter can consult it.
- userMessage message to the user (recruiter), for example to indicate a reason for failure (“Title too long”)
- developerMessage similar to userMessage, but for Beetween support in charge of monitoring publication operations. Provides more technical information than userMessage. Note: Beetween support also has access to userMessage.
Take an offer offline
DELETE $ENDPOINT/$ID
ex: DELETE https://entry-point-chosen-by-jobboard.com/api/jobs/a1b2v3d4e5f6
Return expected :
- no body
- if successful: status 204 (200 also accepted)
- if the offer was not online or did not exist, the operation is considered a success
- all other statuses will be interpreted as a failure of depublication
A Authorization: Basic xxxxx header will be included in each request, containing a token supplied by the jobboard and used to restrict access to the publishing APIs it sets up. This constraint is not mandatory, but is strongly recommended to avoid potential abuse.
The token will be encoded in base64 UTF-8. The size of the base64-encoded token must not exceed 64 characters.
For example, if the token is login:password, the authentication header will be :
Authorization: Basic bG9naW46cGFzc3dvcmQ=
You must use the login:password format, making sure not to use the “:” character in the login or password.
We can also support a Bearer token, which must be communicated to us when the API is set up.
Authorization: Bearer bG9naW46cGdsljksmkdFzc3dvcmQ=
Appendix
Description of an offer
| Element | Description | Type | Specific | Values |
| id | 10-character alpha-numeric field imposed by Beetween as a reference and generated automatically | Text | Autogenerated | – |
| clientId | Customer login on target job board | Text | Optional | – |
| title | Job title | Text | Required | – |
| recruiter | Name of recruiting company | Text | Required | – |
| creationDate | Date of first publication | Datetime | Autogenerated | – |
| LastModificationDate | Date of last publication (modification, republication…) | Datetime | Autogenerated | – |
| applicationEmail | Email address for applications | Text | Autogenerated | – |
| applicationUrl | Url of a Beetween application page for the ad with integrated application form | Text | Autogenerated | – |
| jobDescription | Includes offer content tags | – | – | – |
| ― company | Company description | HTML | Required | – |
| ― mission | Mission description | HTML | Required | – |
| ― profile | Profile description | HTML | Required | – |
| location | Includes job location tags, generated from the address selected by the user | – | – | – |
| ― display | Displayable value for location | Text | Required | – |
| ― city | City | Text | Required | – |
| ― post_code | Postal code | Text | Required | – |
| ― region2Code | Department code | Text | Required | – |
| ― region2 | Department name | Text | Required | – |
| ― region1 | Region name | Text | Required | – |
| ― countryCode | Country code | Text | Required | – |
| ― countryNameFr | Country name in French | Text | Required | – |
| ― longitude | GPS coordinates: longitude | Number | Required | – |
| ― latitude | GPS coordinates: latitude | Number | Required | – |
| logoUrl | URL of the logo linked to the registered company name and configured in Beetween | Text | Autogenerated | – |
| contract | Includes tags related to the proposed employment contract | – | – | – |
| ― type | Type of contract proposed, fixed values proposed in a drop-down list | – | Required | List of values |
| ― ― code | Contract type code | Text | Required | – |
| ― ― displayValue | Displayable value for contract type | Text | Required | – |
| ― duration | Contract duration for fixed-term contracts | – | Required for internships, fixed-term and temporary contracts | List of values |
| ― ― value | Value of contract duration for fixed-term contracts | Number | Required for internships, fixed-term and temporary contracts | – |
| ― ― unit | Unit of duration (months, weeks…) | Text | Required for internships, fixed-term and temporary contracts | – |
| ― ― displayValue | Concatenation of the two previous elements, displayable value | Text | Required for internships, fixed-term and temporary contracts | – |
| ― rhythm | Number of hours per week selected Contains attributes hours_per_weekdisplay_value (type Text) |
– | – | List of values |
| ― ― hoursPerWeek | Number of hours worked per week | Number | Required | – |
| ― ― fullTime | Full-time or part-time (true or false) | Text | Required | true or false |
| ― ― displayValue | Number of hours per week | Text | Required | – |
| ― starting_date | Mission start date | – | – | List of values |
| ― ― asap | Start date as soon as possible | Boolean | Required | true or false |
| ― ― value | Mission start date | Date | Required si asap = « false » | – |
| job_language | Ad language (drop-down list) | Text | – | List of values |
| salary | Proposed salary – 2 types of display: salary, and salary range Contains attributes value, currency, unit; and for range display min and max |
– | – | List of values |
| ― min | Minimum salary range | Number | – | – |
| ― max | Maximum salary range | Number | – | – |
| ― value | Fixed salary value | Number | – | – |
| ― currency | Currency of salary (EUR, USD …) | Text | Valeurs multiples | – |
| ― unit | Time value of salary (monthly, annual, etc.) | Text | Valeurs multiples | – |
| ― displayValue | Concatenation of previous fields | Text | Autogenerated | – |
| skills | Skills required for the position (free text) | [ Text1, Text2,…] | – | – |
| jobTitle | Area of activity corresponding to the position | – | – | List of values |
| ― code | Business area code | Text | – | – |
| ― displayValue | Displayable business area value | Text | – | – |
| mainActivityArea | Primary sector | – | Required | List of values |
| ― code | Code associated with primary activity sector | Text | Required | – |
| ― displayValue | Displayable value of primary activity sector | Text | Required | – |
| secondaryActivityArea | Secondary activity sector | – | – | List of values |
| ― code | Code associated with secondary activity sector | Text | – | – |
| ― displayValue | Displayable value of secondary activity sector | Text | – | – |
| qualification | Qualification level | – | – | List of values |
| ― code | Code associated with qualification level | Text | – | – |
| ― displayValue | Displayable value of qualification level | Text | – | – |
| experience | Required experience: number of years of experience required and number of years in management. | – | Required | Détails |
| ― experienceYear | Years of experience required | Number | – | – |
| ― includingManagementYears | Years of management experience required | Number | – | – |
| ― displayValue | Displayable experience level value | Text | – | – |
| studyLevels | Accepted level of qualification an element is added for each qualification level entered |
Tableau d’objet | Valeurs multiples | List of values |
| ― code | Diploma code | Text | – | – |
| ― displayValue | Displayable study level value | Text | – | – |
| school_types | Type of school, an element is added for each school type entered | Tableau d’objet | Valeurs multiples | List of values |
| ― code | Code associated with type of school requested | Text | – | – |
| ― displayValue | Displayable value of requested school type | Text | – | – |
| educationDomain | Field of study | Text | – | – |
The possible values for the contract “type” object are shown in the following table:
It is preferable to use “code” values for mapping, to avoid any updating problems.
| Code | displayValue |
| PERMANENT | CDI |
| TEMPORARY | CDD |
| INTERIM | Interim |
| INTERNSHIP | Internship |
| APPRENTICESHIP | Apprenticeship contract |
| CONTRAT_DE_PROFESIONNALISATION | Professionalization contract |
| FRANCHISE | Franchise |
| FREELANCE | Freelance |
| COLLABORATION_AGREEMENT | Collaboration contract |
| SUMMER_JOB | Summer job |
| FAMILY | Family employment |
The possible values for the “unit” element of the contract duration object are shown in the following table:
In the same way, it’s best to use unit values for mapping, to avoid any updating problems.
| Attribut Unit | Value |
| YEAR | year(s) |
| MONTH | month |
| WEEK | week(s) |
| DAY | day(s) |
| HOUR | hour(s) |
The rhythm object (rhythm and not rythm) contains 3 elements: "hoursPerWeek" which contains the number of hours worked per week, fullTime which contains "true" or "false" and displayValue which contains the number of hours worked in the form xx.xh/week.
For example:
"rhythm": {
"hoursPerWeek": "35.0",
"fullTime": "true",
"displayValue": "35.0h/semaine"
},
The startingDate object indicates the contract start date. When a date is chosen for the start of the contract, the asap="false" element and the value in the “value” element are equal to the date entered by the user.
If the user chooses “as soon as possible”, the asap="true" attribute and the date in “value” correspond to the date of publication of the advert.
Language
JobLanguage can take two values: “English” or “French”.
The salary object can be presented in 2 different ways (range or fixed value) depending on the user’s choice:
Fixed value :
"salary": {
"value": "100000.0",
"currency": "EUR",
"unit": "YEAR",
"displayValue": "100000 € (Euros) par an"
}
Range:
"salary": {
"min": "100000.0",
"max": "150000.0",
"currency": "EUR",
"unit": "YEAR",
"displayValue": "De 100000 à 150000 € (Euros) par an"
}
The possible values for the “unit” and “currency” elements are shown in the tables below:
| Unit | Value |
| YEAR | per year |
| MONTH | per month |
| WEEK | per week |
| DAY | per day |
| HOUR | per hour |
| Currency | Value |
| EUR | € (Euros) |
| GBP | £ (British Pound) |
| MAD | DH (Moroccan dirham) |
| USD | $ (U.S. Dollar) |
| CAD | $ (Canadian Dollar) |
| JPY | ¥ (Japanese yen) |
| CHF | CHF (Swiss Franc) |
Job title
| code | displayValue |
| Craft / Worker | Craftsman/Worker |
| Craft / Shop | Craftsman / Local shop |
| Worker | Construction worker |
| Technician | Technician |
| Hospitality / Travel | Hotels / Restaurants / Tourism / Leisure |
| Sales | Trade / Sales |
| MLM Commission | VDI |
| Computer | IT / Internet / Telecom |
| Marketing / Communication | Marketing / Communication |
| House help | Home services |
| Cleaning / Help | Housekeeping / Maintenance |
| Nurse / Babysitting / School help | Personal services |
| Management | Management / Supervision |
| Entity management | General management / Profit center manager |
| Project management | Project management |
| Engineering | Studies / Research / Engineering |
| HR / Training / Teaching | HR / Training / Education |
| HR | Human Resources / Training |
| Formation / Teaching | Education / Teaching |
| Health Care | Health / Medicine / Social |
| Multi services | General services |
| Administration | Administration |
| Assistant | Assistants / Secretaries / Receptionists |
| Accounting / Finance | Accounting / Management / Finance |
| Legal / Tax | Legal / Tax |
| Security / Help | Security / Defense / Guarding |
| Logistic | Transport / Logistics / Purchasing |
Activity area
| code | displayValue |
| Bank | Bank |
| Finance | Finance |
| Assurance | Insurance |
| Accounting | Accounting |
| Gestion | Management |
| Legal | Legal |
| Tax | Fiscal |
| Agriculture | Agriculture / Fishing |
| Agri | Food industry |
| Building | Building & civil engineering |
| Building / infrastucture | BTP Plants / Roads / Pipelines |
| Installation / Maintenance / Repair | Installation / Maintenance / Repair |
| Architecture | Architecture |
| Design | Design |
| Town planning | Urban planning |
| Real estate | Real estate |
| Craft | Trade / Crafts |
| Retail | Retail / Sales |
| Distribution | Retail |
| Export | International trade / Export |
| Customer service | Customer service / after-sales |
| Call center | Call center |
| Hostelry | Hotels |
| Food | Catering |
| Tourism | Tourism |
| Hobbies | Leisure |
| Sport | Sport |
| Equipment manufacturer | Automotive / Aerospace / Transportation |
| Metallurgy | Metallurgy |
| Mechanical / Robotics | Mechanics / Automation / Robotics |
| Materials processing | Materials processing |
| Electrical and electronic equipment | Electrical and electronic equipment |
| Quality | Quality / Inspection |
| High technologies | High-tech |
| Raw materials | Extraction and processing of raw materials |
| Chemicals | Chemicals – Rubber – Plastics |
| Pharmaceutical | Pharmaceuticals / Biotechnology |
| Manufacturing / Production | Industry / Manufacturing, other (furniture, textiles, printing) |
| Health | Health |
| Social | Social |
| Veterinary | Veterinarian |
| Web | Websites / SEO / Webdesign |
| Software | Software development |
| Telecom | Telecommunications |
| E-business | E-business |
| IT Services | IT Engineering Services Company |
| ConsultingProject management | ConsultingProject management |
| Cleaning | Cleaning / maintenance |
| Other company services | Other business services |
| Individual services | Personal services |
| Public service | Public services / Administrations |
| Fashion | Mode |
| Luxury | Luxury |
| Beauty | Beauty |
| Transport | Transport |
| Logistic | Logistics |
| Handling | Handling |
| HR | RH |
| Recruitment firm | Recruitment agency |
| Interim firm | Temporary employment agency |
| Marketing | Marketing |
| Communication | Communication / Media / Press |
| Advertising | Advertising |
| Journalism | Journalism |
| Edition | Editing and writing |
| Engineering | Engineering |
| RnD | R&D / High-tech |
| Consultancy | Design office |
| Private research | Private search |
| Public research | Public research |
| Security | Security / Defense |
| Art | Art / Entertainment / Culture |
| Teaching | Teaching |
| Public teaching | Public education |
| Private teaching | Private education |
| Formation | Vocational training |
| Apprenticeship Formation | Work-linked training |
| Water | Water |
| Electricity | Electricity |
| Oil and gas | Oil & Gas |
| Nuclear | Nuclear |
| Environment | Environment / Nature |
| Waste | Waste management |
| Humanitarian | Humanitarian |
Qualification
| Code | displayValue |
| MANOEUVRE | Maneuver |
| SPECIALIZED_WORKER | Skilled worker |
| P1_P2 | Skilled worker (P1,P2) |
| P3_P4_OHQ | Skilled worker (P3,P4,OHQ) |
| ENQ | Unskilled employee |
| EQ | Qualified employee |
| TECHNICIAN | Technician |
| AGENT_DE_MAITRISE | Supervisor |
| PRIVATE_FRAME | Private sector executive |
| PUBLIC_FRAMEWORK | Public sector executive / Armed forces |
Experience
The experience object contains 3 elements:
- experienceYear: contains the number of years of experience required.
- includingManagementYears: number of years of managerial experience required.
- displayValue, displayable values.
Example :
"experience": {
"experienceYear": "-2",
"includingManagementYears": "10.0",
"displayValue": "Tous niveaux d'expérience"
},
| experienceYear | displayValue |
| <0 | All levels of experience |
| 0.0 | Beginner |
| <6 | Experienced |
| >=6 | Project Manager |
Study levels
| Code | displayValue |
| ALL | No |
| BEP_CAP | BEP/CAP |
| BAC | Bin |
| BAC_1_2 | Bac+1/Bac+2 |
| BAC_3 | Bac+3 |
| BAC_4 | Bac+4 |
| BAC_5 | Bac+5 |
| BAC_6_PLUS | Bac+6 and above |
Example :
"studyLevels": [
{
"code": "BEP_CAP",
"displayValue": "BEP/CAP"
},
{
"code": "BAC",
"displayValue": "Bac"
}
]
School Types
| Code | displayValue |
| ALL | It doesn’t matter |
| UNI | University |
| RESEARCH_LAB | Research laboratory |
| BUSINESS_SCHOOL | Business school |
| ENGINEER_SCHOOL | Engineering school |
| A | A |
| A_PLUS | A+ |
Example :
"schoolTypes": [
{
"code": "UNI",
"displayValue": "Université"
},
{
"code": "ENGINEER_SCHOOL",
"displayValue": "École d'ingénieur"
}
]