External Job Api

we have a new wiki, with a swagger documentation / api definitions and more
go to: NEW DEV WIKI 


OLD:

There are 3 general endpoints for:
1. add a job / unpublish a job
2. transfer applications
3. chat / communcation afterwards


API Endpoints:
 Test Environmenthttp://test.hokify.com
 Produktion Environmenthttps://api.hokify.com

Unless specified otherwise, all parameters are optional!

Authentification + General Notes
To authenticate against the API, you have to get a  mandator-Id and a token. To request access please write an email to: simon.tretter@hokify.com including: 1. technical contact email, 2. company name, 3. how many jobs published / month (estimated)
After you got the credentials, you have to exchange it with a session-token. This session-token has to be passed as a HTTP header "x-session-token" to all further API calls. The session token is valid up to 24hours.

The API checks the "accept-language" header in all requests, if it's missing it assumes "de" for German. 

Endpoint: /api/api-login
Method: POST
Input: JSON or multipart/form-data
Output: JSON

Following fields are valid:
 Field Description Type 
 mandatorAPI Mandator Stringrequired
 token API Token Stringrequired


If a session token has been issued, "success" returns true. and the field "sessionToken" contains the exchanged token.
{
    "success": true, 
    "sessionToken": "XYZ.-...", 
    "info": ""
}

On error success is false, and further information about the error can be found in "info".

Example in PHP to retrieve a sessin Token.

// LOGIN
$ch = curl_init();
$url = 'http://test.hokify.com/api/api-login';
$fields = array('mandator' => '....', 'token' => '....');

$headers[] = 'Accept: application/json';
$headers[] = 'Accept-Language: de'; // or "en" for english,..

$headers[] = 'Content-Type: application/json';
curl_setopt($ch,CURLOPT_HTTPHEADER, $headers);
curl_setopt($ch,CURLOPT_URL, $url);
curl_setopt($ch,CURLOPT_POSTFIELDS, json_encode($fields));
curl_setopt($ch,CURLOPT_POST, 1);
$result = curl_exec($ch);

$requestArr = json_decode($result, true);


$sessionToken = $requestArr['sessionToken'];

1. add/publish job

1.1 publish a job

Endpoint: /api/add-job-extern
Method: POST
Input: JSON or multipart/form-data
Output: JSON

this endpoitn can be used to publish a new job or update an existing one. To update an existing job specify "jobId" (the _id which is returned when creating the job on hokify) or "sourceId" (your own unique job id) in the request.
Following fields are valid:
 Field Description Type 
 name Job Titel Stringrequired
 wage Wage Stringrequired if region "at"
 type type of workID or language specific valuerequired
55d74e5d365315e629446d54: Vollzeit   
55d74e7d365315e629446d55: Teilzeit/Aushilfskraft   
55d74f6c365315e629446d56: Lehrstelle      
55d74f96365315e629446d58: Geringfügig     
56a90202c0b1e4ea4ede1a58: Freiberuflich
56b352dcb5c5f2a71436dc51: Praktikum/Ferialjob
 fields job categoryArray of IDsrequired
e.g.:
55d6369f365315e629446bf3: Kellner
(see chapter  1.1.3 to retrieve all possible job fields)
 questions list of questionsArray of IDse.g.:
55d6f6a7365315e629446c62: Pflichtschulabschluss
55d6f93a365315e629446c67: Sehr gute Deutsch Kenntnisse
55d6f9d6365315e629446cb4: Gültige Arbeitserlaubnis
(see chapter 1.1.2 to retrieve all yes/no questions)
 company Company name String 
 contactPhone Contact phone E164 
 contactEmail Contact email Email 
 address Geocodeable AddressString required
 addressText hides the address and shows this text instead String
 region Region Region-Code (at,de,..), default: at default: country of requestor's ip
 isPublished Job published Boolean default: false
 sourceId external ID     String an unique value to identify the job on your side
 descriptionHTML Job Description String 
 language Language lang-code (en,de,..) default: de or uses HTTP header settings
 employmenttype form of employmentjobsID or language specific valuee.g. Direktanstellung, Zeitarbeit, Interim (Zeitarbeit, wird nicht übernommen), - Projekteinsätze)
570ff1bf056b57087012f9f8: Direktanstellung
570ff242056b57087012f9fb: Zeitarbeit
570ff247056b57087012f9fc: Interim
570ff24d056b57087012f9fd: Projekteinsätze
 requiredFieldsadditional fields to ask for List of Strings or ObjectsBeware: specifying additonal documents or additonal questions can reduce the number of applications drastically!
There are 3 different types of possible values:
1. you can specify any document types available in "get-documenttypes-extern", by specifing:
<type>:<key> (e.g: document:wp or certificate:high)
2. furthermore you can specify following strings for other required fields/documents:
cv: CV
education: ask for last/mentionable education
job:  ask for last/metionable job
email: requires an email
phone: required a phone number
pic: required a profil picture
birthday: required birthday
nationality: requires nationality

3. by specifing an object like this, you can add an open question to the job interview:
 {
            "type": "OPEN_QUESTION",
            "question": "Willst du mein neues Auto kaufen?",
            "questiontype": "string-ohne-sonderzeichen",// z.b. "motivational" - nur für interne zuordnung - sieht der user nicht
            "answerMaxLength": 300 // maximal zeichen der antwort
            "answerMinLength": 0 // oder höher wenn es required ist
        }
Custom Job Image: to add  a custom job pic, you need to send a multipart document with a file "media" included.

If everything worked out, a job object is returned. E.g.:
{
    "success": true, 
    "job": {
        "__v": 0, 
        "jobNr": 4453, 
        "alias": "barkeeperin-raimundgasse--1020-wien---sterreich", 
        "_location": {
            "_id": "55e5d722205fef73534e8bfc", 
            "name": "Raimundgasse, 1020 Wien, Österreich", 
            "street": "Raimundgasse", 
            "city": "Wien", 
            "county": "Wien", 
            "country": "Österreich", 
            "code": "1020", 
            "longitude": 16.3753348, 
            "latitude": 48.2195626, 
            "__v": 0
        }, 
        "image": "http://localhost:3002/pub/jobfield/55d63657365315e629446bf0_1457471259245.jpg", 
        "_company": {
            "_id": "568e93732b6088d0a18a7882", 
            "name": "asdf", 
            "defaultNotification": 0
        }, 
        "description": "", 
        "wage": "Gehalt", 
        "name": "BarkeeperIn", 
        "r": {
            "coordinates": [
                0.8118031604681164, 
                0.7540901494212449
            ], 
            "type": "Point"
        }, 
        "_id": "56f03ebd3c634f1d0071b7b0", 
        "rounds": [ ], 
        "specificFields": [ ], 
        "timeFrame": [ ], 
        "_owner": [
            {
                "_id": "55e48c00a23cfa794b83bb9c", 
                "image": "http://test.hokify.com/pub/user/pic_55e48c00a23cfa794b83bb9c_1457365125384.jpeg", 
                "displayName": "Simon Tretter", 
                "general": {
                    "email": "s.tretter@szene1.at"
                }
            }
        ], 
        "_tags": [ ], 
        "date": "2016-03-21T18:34:37.702Z", 
        "requiredFields": [ ], 
        "yourTask": [ ], 
        "weOffer": [ ], 
        "weWant": [ ], 
        "travelNeeded": false, 
        "remoteWork": false, 
        "descriptionBlocks": [
            {
                "language": "de", 
                "block1": "", 
                "_id": "56f03ebd3c634f1d0071b7b1"
            }
        ], 
        "defaultLanguage": "de", 
        "internal": {
            "location": [
                16.3753348, 
                48.2195626
            ], 
            "jobCode": "cJCq5M9k", 
            "stats": {
                "smslink": 0, 
                "applied": 0, 
                "saved": 0, 
                "discarded": 0
            }, 
            "offline": false, 
            "isPublished": true, 
            "source": 0
        }, 
        "questions": [ ], 
        "type": "Vollzeit", 
        "fields": [
            {
                "name": "BarkeeperIn", 
                "id": "55d63657365315e629446bf0"
            }
        ], 
        "openRecruiterTodos": 0
    }
}


To verify if a request was succesful, check if "success": true is returned. Otherwise a "code" and a "error" is returned. E.g.:
{
    "success": false, 
    "code": "MISSING_LOCATION", 
    "error": "location must not be empty"
}


codes:
  • INVALID_LOCATION
  • MISSING_LOCATION
  • GENERIC_ERROR (
  • MISSING_JOB_FIELD
  • EMPTY_FIELDS
  • MISSING_CONTACTS
  • NO_CREDIT
more codes (mostly only relevant during developing): BROKEN_DESCRIPION_BLOCK, BROKEN_FIELDS, BROKEN_QUESTIONS, BROKEN_REQUIRED_FIELDS,BROKEN_SPECIFIC_FIELDS,


Note: Remember the "job._id" (here it is 56f03ebd3c634f1d0071b7b0). This unique ID identifies your newly created job. Otherwise you can use your specified source id (which must be unqiue to your use case!).

Example Code in PHP to add a job:
$url = 'http://test.hokify.com/api/add-job-extern';
$fields = array(
'name' => '',
'wage' => '',
'type' => '',
'fields' => '["..."]',
'company' => '',
'contactPhone' => '',
'contactEmail' => '',
'address' => '',
'region' => 'at',
'isPublished' => "true",
'sourceId' => '',
'descriptionHTML' => ''
);


$headers[] = "X-Session-Token:".$sessionToken;
$headers[] = 'Accept: application/json';

$headers[] = 'Content-Type: application/json';
curl_setopt($ch,CURLOPT_HTTPHEADER, $headers);
curl_setopt($ch,CURLOPT_URL, $url);
curl_setopt($ch,CURLOPT_POSTFIELDS, json_encode($fields));
curl_setopt($ch,CURLOPT_POST, 1);
$result = curl_exec($ch);

$res = json_decode($result, true);

1.1.1 retrieve possible document types

Endpoint: /api/get-documenttypes-extern
Method: GET
Input: -
Output: JSON

This endpoint returns a list of possible document types in a list form with objects lke this:
{name: "Arbeitserlaubnus", key: "wp", type: "document"}
for the requiredFields you have to combine type and key with a ":" ..e.g "document:wp" for Arbeitserlaubnis.

1.1.2 retrieve yes/no questions

Endpoint: /api/get-question-list-extern
Method: GET
Input: -
Output: JSON

1.1.3 retrieve all possible job fields

Endpoint: /api/get-fields-extern
Method: GET
Input: -
Output: JSON

1.2 remove a job

Endpoint: /api/disable-job-extern
Method: POST
Input: JSON or multipart/form-data
Output: JSON

Following fields are valid:

 Field Description Type
 jobIdjob ID Stringone of it is required
 sourceId source ID Stringone of it is required
Note: only specify ONE parameter!

If the request was fine, the API returns:
{
    "success": true, 
    "msg": "job unpublished"
}

on error, success is false.if the job is already unpublished, success returns true, but the msg shows "job was already unpublished".

Example Code in PHP to unpublish a job:
$url = 'http://test.hokify.com/api/disable-job-extern';
$fields = array('jobId' => '...');

$headers[] = "X-Session-Token:".$sessionToken;
$headers[] = 'Accept: application/json';

$headers[] = 'Content-Type: application/json';
curl_setopt($ch,CURLOPT_HTTPHEADER, $headers);
curl_setopt($ch,CURLOPT_URL, $url);
curl_setopt($ch,CURLOPT_POSTFIELDS, json_encode($fields));
curl_setopt($ch,CURLOPT_POST, 1);
$result = curl_exec($ch);

$res = json_decode($result, true);
 
2. Transfer applications
To retrieve current applications for your mandator, you can call get-all-applications-extern.
Endpoint: /api/get-all-applications-extern
Method: GET
Input: query parameters
Output: JSON or CSV (add query parameter ?csv=true 

Following fields are valid:
 Field Description Type
 startTimeLimit applications to a time range (Start) Date
 endTimeLimit applications to a time range (End) Date

 limit Maximum Results Number not available yet
 offset Offset Number  not available yet

Returns following fields:
  • job id
  • source id (if specified)
  • user id
  • unique application id (Match id)
  • name
  • original mail
  • hokify mail
  • phone
  • PDF (Answers) URL
  • birthday (if available)
  • gender (if available)
  • nationality (if available)
  • date/ time of the application

Example Code in PHP for retrieving all applications for authorized mandator:
$url = 'http://test.hokify.com/api/get-all-applications-extern';

$headers[] = "X-Session-Token:".$sessionToken;
$headers[] = 'Accept: application/json';

$headers[] = 'Content-Type: application/json';
curl_setopt($ch,CURLOPT_HTTPHEADER, $headers);
curl_setopt($ch,CURLOPT_URL, $url);
curl_setopt($ch,CURLOPT_POST, 0);
$result = curl_exec($ch);

$res = json_decode($result, true);
Note: see "apitest.php" attached to this website for a more detailed example.

more examples:
CSV with start and end time: /api/get-all-applications-extern?csv=true&startTime=1.1.2016&endTime=1.1.2017
JSON with start and end time: /api/get-all-applications-extern?startTime=1.1.2016&endTime=1.1.2017

Don't forget the x-session-token header!

If all went good, it returns something like this for json:
[
{  ..application-data...
},{  ..application-data...
},{  ..application-data...
},...]

and something like this for CSV:

Note: We have some APIs already covered (e.g. e-recruiter) which we can serve directly from our servers. Everytime a new application is happening,the API is triggered immediately. Please contact our sales team in case you believe we have your API already implemented (info@hokify.com and refer to Covered APIs).

3. Communication / Chat
All applications have a unique email to enable the chat communication seamlessly. All messages throguh this mail are delievered by mail and also directly to the phone of the applicant or company.

Usally it is enough to specify a contactMail when adding jobs. All communication on company side is then delivered to this specified email. For more complex use cases it is possible to leave the contactMail field empty and retrieve the messages through the /get-conversations-extern API.

Endpoint: /api/get-conversations-extern
Method: POST
Input: JSON or multipart/form-data
Output: JSON

Following fields are valid:
 Field Description Type
 startTimeLimit messages to a time range (Start) Date
 endTimeLimit messages to a time range (End) Date

 limit Maximum Results Number not available yet
 offset Offset Number 
not available yet

Returns following fields:
* JobIds (interene hokify ID und die source Id die durch den mandanten definiert wurde)
* Match Id (interne hokify id pro bewerbung)
* Name des senders
* user id (Eindeutieg ID des Senders (jeder User hat eine ID))
* E-mail wie man dem sender antworten kann
* Name des Jobs um den es geht
* Company Name der für diesen Job definiert wurde
* Nachrichten Zeit
* Nachricht

Example Code in PHP for retrieving all applications for authorized mandator:
$url = 'http://test.hokify.com/api/get-conversations-extern';

$headers[] = "X-Session-Token:".$sessionToken;
$headers[] = 'Accept: application/json';

$headers[] = 'Content-Type: application/json'; 
curl_setopt($ch,CURLOPT_HTTPHEADER, $headers);
curl_setopt($ch,CURLOPT_URL, $url);
curl_setopt($ch,CURLOPT_POST, 0);
$result = curl_exec($ch);

$res = json_decode($result, true);
Note: see "apitest.php" attached to this website for a more detailed example.

If all went good, it returns something like this for json:
[
   {
      "msgId": "5669f3ee5bd00e037a571560",
      "jobId": "565965e1cb39c7e3605e305a",
      "jobSourceId": "123",
      "sender": "user",
      "matchId": "565d8ae9e1f2e501791b6327",
      "userId": "55e48c00a23cfa794b83bb9c",
      "name": "Simon Tretter",
      "hokifyMail": "565d8ae9e1f2e501791b6327-from@local.hokify.com",
      "jobName": "Küchengehilf(e)in",
      "companyName": "JobSwipr GmbH",
      "msgTime": "Thu Dec 10 2015 22:51:42 GMT+0100 (Mitteleuropäische Zeit)",
      "msg": "Hallo. Textnachricht."
   
},
   {
      "msgId": "5669f466e7930ecf7bb11ae1",
      "jobId": "565965e1cb39c7e3605e305a",
      "jobSourceId": "345",
      "sender": "user",
      "matchId": "565d8ae9e1f2e501791b6327",
      "userId": "55e48c00a23cfa794b83bb9c",
      "name": "Simon Tretter",
      "hokifyMail": "565d8ae9e1f2e501791b6327-to@local.hokify.com",
      "jobName": "Küchengehilf(e)in",
      "companyName": "Miau Company",
      "msgTime": "Thu Dec 10 2015 22:53:42 GMT+0100 (Mitteleuropäische Zeit)",
      "msg": "Es gibt hier viel zu essen."
   
}
]

ċ
Simon Tretter,
Apr 15, 2016, 2:09 AM
Comments