JANZZ API¶
list¶
API endpoint to display all JANZZs in account.
URL¶
https://www.janzz.jobs/japi/janzz
parameters¶
- start_at
- format: integer
- default value: 0
- effect: start at for pagination
- num_results
- format: integer between 0 and 1000
- default value: 100
- effect: maximum number of results to return
- janzz_type
- format: one of 10, 11
- default value: empty
- effect: if set, filter only janzzes of this type
- status
- format: 0:draft 1:published 3:withdrawn 4:paused
- default value: empty
- multiple: repeat parameter for multiple status values
- effect: if set, filter only janzzes having this status
- include_tag
- format: string
- multiple: repeating parameter will OR all tags together
- effect: if set, filter only janzzes having any of these tags
- include_tag_all
- format: string
- multiple: repeating parameter will AND all tags together
- effect: if set, filter only janzzes having ALL of these tags
- exclude_tag
- format: string
- multiple: repeating parameter will OR all tags together
- effect: if set, filter only janzzes not having any of these tags
returns¶
list of janzz objects
retrieve / modify¶
API endpoint to retrive, create, modify or delete a JANZZ from the current account.
URL¶
using JANZZ.jobs janzz id:
https://www.janzz.jobs/japi/janzz/{id}
using an externally managed ID:
https://www.janzz.jobs/japi/janzz_internal/{id}
ALLOWABLE METHODS¶
GET, PUT, POST, PATCH, DELETE
parameters¶
- noindex
- format: 1, true to indicate true
- default value: empty
- effect: optional parameter to disable indexing on the saved JANZZ for performance reasons. Indexing will have to be called explicitly with an index call either on the newly returned JANZZ or on all or new JANZZs.
janzz format¶
The JANZZ contents has the following format:
{
"id": 584156,
"internal_id": "123-1",
"group_key": 123,
"status": 1,
"internal_comments": "these are the internal comments\nmultiline",
"description": "the description of the JANZZ",
"janzz_type": 11,
"language_captured": "en",
"title": "test",
"match_factor": 10,
"occupation": "Engineer",
"occupation_list": [],
"specialization_list": [{
"specialization": "printed circuit technology",
"must": false
}, {
"specialization": "Multimedia",
"must": true
}],
"function_list": ["Junior Developer"],
"skill_list": [{
"skill": "Soil and plants",
"must": false,
"level": 3
}, {
"skill": "Gardening",
"must": true,
"level": 5
}],
"softskill_list": [{
"skill": "Friendliness",
"must": false,
"level": 3
}, {
"skill": "Punctuality",
"must": false,
"level": 3
}],
"custom_list": [{
"text": "custom_concept_1",
"weight": 1.5
}, {
"text": "custom_concept_2",
"weight": 0.1
}],
"contract_type_list": ["Full-time"],
"language_list": [{
"proficiency": 1,
"name": "English",
"proficiency2": 1
}, {
"proficiency": 5,
"name": "French",
"proficiency2": 5
}],
"industry_list": ["Banking, financial services and financial management"],
"location_list": [{
"lat": 47.424482,
"r": 30.0,
"name": "St Gallen, Switzerland",
"cc": "ch",
"type": "locality",
"lon": 9.376717
}, {
"lat": 46.227638,
"r": 0.0,
"name": "France",
"cc": "fr",
"type": "country",
"lon": 2.213749
}],
"slocation_list": [{
"code": "NO06.0633",
"label": "Nore og Uvdal"
}, {
"code": "NO18",
"label": "Nordland"
}],
"education_list": [{
"profession": null,
"degree": null,
"level": "Bachelor's degree/University primary qualification"
}, {
"profession": "Mechanic",
"degree": "Mathematics with Management",
"level": "On-the-job training"
}],
"experience_list": [{
"position": "experience description",
"value": 5.0,
"unit": 1
}],
"keyword_list": [{
"text": "kw1",
"has": true
}, {
"text": "kw2",
"has": false
}],
"tag_list": [{
"tag": "tag1"
}, {
"tag": "tag2"
}],
"occupation_exclude_list": [{
"text": "test engineer",
"cor": 0.8
}, {
"text": "painter",
"cor": 0.5
}],
"concept_filter_list": [
{
"branch": "location_no",
"text": "Hedmark",
"include_up": true,
"include_down": true
}
],
"authorization_list": [
{
"text": "Authorization Animal Health",
"must": false
}
]
}
Minimal JANZZ¶
A new JANZZ must have the following minimal set of fields:
{
"janzz_type": 11,
"language_captured": "en",
"match_factor": 10,
"contract_type_list": ["Full-time"]
}
Description of the fields¶
id:
7197- Assigned by JANZZ, used in the URL to access JANZZ
internal_id:
"123"- Assigned externally, can be used in the URL to access JANZZ
group_key:
123- format: bigint or null
- Advanced feature - use very carefully!
- When multiple janzzes are created for a single profile, use the group_key to group search results by this key.
- example: profile 123-1, 123-2, 123-3. group_key: 123. Then use ?grouped=true in the search to return only the janzz having the highest score from this group.
status:
1- Status of a the janzz. 0:draft 1:published 3:withdrawn 4:paused
- can be used for filtering search results
- default when not provided is 0
description:
"the description of the JANZZ"janzz_type:
11- 10=candidate profile, 11=job offer
- required when creating a JANZZ
title:
"test"- the title of the janzz
language_captured:
"en"- the language of the janzz
- certain fields like contract type, education, language must be in this language. This is required when creating a new JANZZ and cannot be changed after.
- required when creating a JANZZ
match_factor:
10- don’t show results lower than 10%
- required when creating a JANZZ
occupation:
"Engineer"- the occupation - most important field in the janzz
occupation_list:
[]- not used at the moment, possibility to have multiple occupations
occupation_exclude_list:
[{ "text": "test engineer", "cor": 0.8 }, { "text": "painter", "cor": 0.5 }]
- list of occupations to exclude from search results.
- cor refers to the minimum correlation for other related concepts to be excluded. For example, painter with cor 0.5 will also exclude “vehicle painter” because it has a correlation higher than 0.5. Cor 1.0 means only exclude this occupation and all others which are identical to this one.
- any JANZZ in the results having any of these concepts will be excluded.
specialization_list:
[{ "specialization": "printed circuit technology", "must": false }, { "specialization": "Multimedia", "must": true }]
- list of terms in the specialization branch
- must denotes that this value is very important
function_list:
[ "Junior Developer" ]
- list of terms in the function branch
skill_list:
[{ "skill": "Soil and plants", "must": false, "level": 3 }, { "skill": "Gardening", "must": true, "level": 5 }]
- skill term from skills branch
- level from 1(beginner) to 5(expert)
- must denotes that this value is very important
softskill_list:
[{ "skill": "Friendliness", "must": false, "level": 3 }, { "skill": "Punctuality", "must": false, "level": 3 }]
- skill term from softskills branch
- level from 1(beginner) to 5(expert)
- must denotes that this value is very important
contract_type_list:
[ "Full-time" ]
- term from contract types branch
- required when creating a JANZZ
language_list:
[ { "proficiency": 1, "name": "English", "proficiency2": 1 }, { "proficiency": 3, "name": "French", "proficiency2": 4 } ]
- proficiency: oral proficiency from 1 (perfect) to 5 (basic)
- proficiency2: written proficiency from 1 (perfect) to 5 (basic)
- name: name of language, must be in the language of the janzz
industry_list:
["Banking, financial services and financial management"]
- list of terms from the industries branch, must be in language of the janzz
location_list:
[ { "lat": 47.424482, "r": 30.0, "name": "St Gallen, Switzerland", "cc": "ch", "type": "locality", "lon": 9.376717 } ]
- lat: latitude
- lon: longitude
- r: radius in km, use 0.0 or 0.3 for a point without a radius.
- name: name of location (for display only)
- cc: country code (ch, de, no, etc.)
- type: one of locality, country
slocation_list:
[{ "code": "NO06.0633", "label": "Nore og Uvdal" }, { "code": "NO18", "label": "Nordland" }],
- slocation, or “simple location” is a simple code-based substring location matching tool. It filters janzzes matching more specific and more general codes. For example, NO18 will match all janzzes having NO, NO18, NO18*.
- code: the code to be matched, must be spelled correctly, case sensitive
- label: the label, only for displaying purposes, not used for filtering
education_list:
[{ "profession": null, "degree": null, "level": "Bachelor's degree/University primary qualification" }, { "profession": "Mechanic", "degree": "Mathematics with Management", "level": "On-the-job training" }]
list of objects with the following fields:
level: must be in language of janzz, must exist in education branch. Example URL for list of all education levels
https://www.janzz.jobs/japi/concepts?branch=education&lang=en&q=*
degree: Optional, the degree of the education object, using typeahead from branch education2, but new values can be entered. This will be indexed and it affects matching.
profession: Optional, a description of this education or a profession related to the education. This does not affect matching.
experience_list:
[{ "position": "experience description", "value": 5.0, "unit": 1 }]
- position: description of experience, free text
- value: number of years/months/days/hours
- unit: one of 1:years, 2:months, 3:days, 4:hours
- Experience is aggregated into a single experience_level concept in the matching engine
keyword_list:
[{ "text": "kw1", "has": true }, { "text": "kw2", "has": false }]
- can be used to filter results by keywords, either having or not having certain keywords. These keywords affect janzz matching.
tag_list:
[{ "tag": "tag1" }, { "tag": "tag2" }]
- can be used to filter results by tags. Unlike keywords, tags do not affect janzz matching and they can be provided in a janzz search query as GET parameters are query time.
custom_list:
[{ "text": "custom_concept_1", "weight": 1.5 }, { "text": "custom_concept_2", "weight": 0.1 }]
- custom concepts, these will generate a concept in the custom branch, if it does not already exist.
- examples can be things like a classification code+value, like ISCO-08:123
concept_filter_list:
[{ "branch": "location_no", "text": "Hedmark", "include_up": true, "include_down": true }]
- used to apply filters on janzz results using concepts without influencing matching scores.
- For example, location_no contains a structured list of all regions and cities in Norway.
- include_up: also include results having concepts within the same branch which are ancestors of provided filter
- include_down: also include results having concepts within the same branch which are descendants of provided filter
authorization_list:
[{ "text": "Authorization Animal Health", "must": false }]
- text term from authorization branch
- must denotes that this value is very important
The following need to match labels exactly as in the concept graph for the JANZZ to work: - contract_type_list - language_list - education_list - industry_list
bulk update¶
API endpoint to create and modify janzzes in batches of up to 500.
URL¶
https://www.janzz.jobs/japi/janzz_bulk_update_internal/
ALLOWABLE METHODS¶
POST
parameters¶
- noindex
- format: 1, true to indicate true
- default value: empty
- effect: optional parameter to disable indexing on the saved JANZZ for performance reasons. Indexing will have to be called explicitly with an index call either on the newly returned JANZZ or on all or new JANZZs.
- want_internal_id
- format: 1, true to indicate true
- default value: empty
- effect: optional parameter to return the provided internal_id with every record in the response.
batch format¶
The batch has the following format:
[
{
"internal_id": "123-1",
"group_key": 123,
"janzz_type": 11,
...
},
{
...
}, ...
]
Mandatory JANZZ fields¶
- internal_id: Besides the usual mandatory fields of a JANZZ, internal_id is required for each janzz
Return format¶
{
"indexed": false,
"updated": 423,
"created": 30,
"skipped": 20,
"results": [
{
"action": "UPDATE",
"errors": {
"education_list": [
"Invalid education level"
]
},
"janzz_id": 1747,
"success": false
},
{
"action": "CREATE",
"errors": {
"contract_type_list": [
"Invalid contract type"
]
},
"janzz_id": null,
"success": false
},
{
"action": "SKIP_DUPLICATE",
"errors": {},
"janzz_id": null,
"success": true
},
{
"action": "UPDATE",
"errors": {},
"janzz_id": 1748,
"success": true
},
{
"action": "UPDATE",
"errors": {},
"janzz_id": 1749,
"success": true
},
.....
- results: One entry for each submitted row in the batch with success true/false and the errors encountered.
- If there are duplicate internal_id values in the batch, only the last one will be processed. The previous ones are skipped, even if the processing of the last one returns an error.
bulk delete¶
API endpoint to delete janzzes in batches of up to 500.
URL¶
https://www.janzz.jobs/japi/janzz_bulk_delete_internal/
ALLOWABLE METHODS¶
POST
batch format¶
The batch has the following format:
[
{
"internal_id": "123-1",
},
{
"group_key": 101010,
}, ...
]
Mandatory fields¶
- either internal_id or group_key can be provided for each item in the list
Return format¶
{
"deleted": [
{
"group_key": 101010,
"internal_id": "100batch_create1",
"id": 4552
},
],
"internal_ids_not_found": [
"100batch_create5"
],
"skipped": [
{
"group_key": 101010,
"msg": "Janzz is being updated/deleted in another batch, will skip",
"id": 4629,
"internal_id": "100batch_create2"
},
{
"group_key": 101010,
"msg": "Janzz is being updated/deleted in another batch, will skip",
"id": 4630,
"internal_id": "100batch_create3"
}
],
"group_keys_not_found": [
"group-key-123",
]
}
- results: object containing lists of deleted, skipped, and not-found. JANZZs may be skipped if they are locked by another process.