Skip to main content
Search for Vacancies based on free text
curl --request POST \
  --url https://{tenant_name}.{region}.techwolf.ai/vacanies/search \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "text": "Software Engineer",
  "filters": [
    {
      "filter": "max_geo_distance",
      "max_geo_distance": 50
    },
    {
      "filter": "custom_property",
      "property_name": "direct_manager",
      "property_value": "John Doe"
    },
    {
      "filter": "custom_property_is_in_list",
      "property_name": "drivers_license",
      "possible_values": [
        "C",
        "CE"
      ]
    },
    {
      "filter": "custom_property_contains_element",
      "property_name": "industries",
      "property_value": "electronics"
    },
    {
      "filter": "external_id_is_in_list",
      "external_ids": [
        "external_id_1",
        "external_id_2",
        "external_id_3"
      ]
    },
    {
      "filter": "is_active",
      "is_active": true
    },
    {
      "filter": "exclude_match_feedback",
      "search_for": "employee_id",
      "exclude_match_feedback": "thumbs_up"
    }
  ],
  "weights": [
    {
      "weight": "max_geo_distance",
      "value": 0.1,
      "full_score_distance": 5,
      "zero_score_distance": 15
    },
    {
      "weight": "custom_property",
      "property_name": "direct_manager",
      "property_value": "John Doe",
      "operator": "eq",
      "value": 0.04
    },
    {
      "weight": "custom_property",
      "property_name": "yearly_salary",
      "property_value": 45000,
      "operator": "gte",
      "value": 0.04
    }
  ],
  "location": {
    "lat": 51.0216707,
    "lng": 3.6887328
  }
}
'
import requests

url = "https://{tenant_name}.{region}.techwolf.ai/vacanies/search"

payload = {
    "text": "Software Engineer",
    "filters": [
        {
            "filter": "max_geo_distance",
            "max_geo_distance": 50
        },
        {
            "filter": "custom_property",
            "property_name": "direct_manager",
            "property_value": "John Doe"
        },
        {
            "filter": "custom_property_is_in_list",
            "property_name": "drivers_license",
            "possible_values": ["C", "CE"]
        },
        {
            "filter": "custom_property_contains_element",
            "property_name": "industries",
            "property_value": "electronics"
        },
        {
            "filter": "external_id_is_in_list",
            "external_ids": ["external_id_1", "external_id_2", "external_id_3"]
        },
        {
            "filter": "is_active",
            "is_active": True
        },
        {
            "filter": "exclude_match_feedback",
            "search_for": "employee_id",
            "exclude_match_feedback": "thumbs_up"
        }
    ],
    "weights": [
        {
            "weight": "max_geo_distance",
            "value": 0.1,
            "full_score_distance": 5,
            "zero_score_distance": 15
        },
        {
            "weight": "custom_property",
            "property_name": "direct_manager",
            "property_value": "John Doe",
            "operator": "eq",
            "value": 0.04
        },
        {
            "weight": "custom_property",
            "property_name": "yearly_salary",
            "property_value": 45000,
            "operator": "gte",
            "value": 0.04
        }
    ],
    "location": {
        "lat": 51.0216707,
        "lng": 3.6887328
    }
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)
const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    text: 'Software Engineer',
    filters: [
      {filter: 'max_geo_distance', max_geo_distance: 50},
      {
        filter: 'custom_property',
        property_name: 'direct_manager',
        property_value: 'John Doe'
      },
      {
        filter: 'custom_property_is_in_list',
        property_name: 'drivers_license',
        possible_values: ['C', 'CE']
      },
      {
        filter: 'custom_property_contains_element',
        property_name: 'industries',
        property_value: 'electronics'
      },
      {
        filter: 'external_id_is_in_list',
        external_ids: ['external_id_1', 'external_id_2', 'external_id_3']
      },
      {filter: 'is_active', is_active: true},
      {
        filter: 'exclude_match_feedback',
        search_for: 'employee_id',
        exclude_match_feedback: 'thumbs_up'
      }
    ],
    weights: [
      {
        weight: 'max_geo_distance',
        value: 0.1,
        full_score_distance: 5,
        zero_score_distance: 15
      },
      {
        weight: 'custom_property',
        property_name: 'direct_manager',
        property_value: 'John Doe',
        operator: 'eq',
        value: 0.04
      },
      {
        weight: 'custom_property',
        property_name: 'yearly_salary',
        property_value: 45000,
        operator: 'gte',
        value: 0.04
      }
    ],
    location: {lat: 51.0216707, lng: 3.6887328}
  })
};

fetch('https://{tenant_name}.{region}.techwolf.ai/vacanies/search', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));
<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://{tenant_name}.{region}.techwolf.ai/vacanies/search",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'text' => 'Software Engineer',
    'filters' => [
        [
                'filter' => 'max_geo_distance',
                'max_geo_distance' => 50
        ],
        [
                'filter' => 'custom_property',
                'property_name' => 'direct_manager',
                'property_value' => 'John Doe'
        ],
        [
                'filter' => 'custom_property_is_in_list',
                'property_name' => 'drivers_license',
                'possible_values' => [
                                'C',
                                'CE'
                ]
        ],
        [
                'filter' => 'custom_property_contains_element',
                'property_name' => 'industries',
                'property_value' => 'electronics'
        ],
        [
                'filter' => 'external_id_is_in_list',
                'external_ids' => [
                                'external_id_1',
                                'external_id_2',
                                'external_id_3'
                ]
        ],
        [
                'filter' => 'is_active',
                'is_active' => true
        ],
        [
                'filter' => 'exclude_match_feedback',
                'search_for' => 'employee_id',
                'exclude_match_feedback' => 'thumbs_up'
        ]
    ],
    'weights' => [
        [
                'weight' => 'max_geo_distance',
                'value' => 0.1,
                'full_score_distance' => 5,
                'zero_score_distance' => 15
        ],
        [
                'weight' => 'custom_property',
                'property_name' => 'direct_manager',
                'property_value' => 'John Doe',
                'operator' => 'eq',
                'value' => 0.04
        ],
        [
                'weight' => 'custom_property',
                'property_name' => 'yearly_salary',
                'property_value' => 45000,
                'operator' => 'gte',
                'value' => 0.04
        ]
    ],
    'location' => [
        'lat' => 51.0216707,
        'lng' => 3.6887328
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://{tenant_name}.{region}.techwolf.ai/vacanies/search"

	payload := strings.NewReader("{\n  \"text\": \"Software Engineer\",\n  \"filters\": [\n    {\n      \"filter\": \"max_geo_distance\",\n      \"max_geo_distance\": 50\n    },\n    {\n      \"filter\": \"custom_property\",\n      \"property_name\": \"direct_manager\",\n      \"property_value\": \"John Doe\"\n    },\n    {\n      \"filter\": \"custom_property_is_in_list\",\n      \"property_name\": \"drivers_license\",\n      \"possible_values\": [\n        \"C\",\n        \"CE\"\n      ]\n    },\n    {\n      \"filter\": \"custom_property_contains_element\",\n      \"property_name\": \"industries\",\n      \"property_value\": \"electronics\"\n    },\n    {\n      \"filter\": \"external_id_is_in_list\",\n      \"external_ids\": [\n        \"external_id_1\",\n        \"external_id_2\",\n        \"external_id_3\"\n      ]\n    },\n    {\n      \"filter\": \"is_active\",\n      \"is_active\": true\n    },\n    {\n      \"filter\": \"exclude_match_feedback\",\n      \"search_for\": \"employee_id\",\n      \"exclude_match_feedback\": \"thumbs_up\"\n    }\n  ],\n  \"weights\": [\n    {\n      \"weight\": \"max_geo_distance\",\n      \"value\": 0.1,\n      \"full_score_distance\": 5,\n      \"zero_score_distance\": 15\n    },\n    {\n      \"weight\": \"custom_property\",\n      \"property_name\": \"direct_manager\",\n      \"property_value\": \"John Doe\",\n      \"operator\": \"eq\",\n      \"value\": 0.04\n    },\n    {\n      \"weight\": \"custom_property\",\n      \"property_name\": \"yearly_salary\",\n      \"property_value\": 45000,\n      \"operator\": \"gte\",\n      \"value\": 0.04\n    }\n  ],\n  \"location\": {\n    \"lat\": 51.0216707,\n    \"lng\": 3.6887328\n  }\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}
HttpResponse<String> response = Unirest.post("https://{tenant_name}.{region}.techwolf.ai/vacanies/search")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"text\": \"Software Engineer\",\n  \"filters\": [\n    {\n      \"filter\": \"max_geo_distance\",\n      \"max_geo_distance\": 50\n    },\n    {\n      \"filter\": \"custom_property\",\n      \"property_name\": \"direct_manager\",\n      \"property_value\": \"John Doe\"\n    },\n    {\n      \"filter\": \"custom_property_is_in_list\",\n      \"property_name\": \"drivers_license\",\n      \"possible_values\": [\n        \"C\",\n        \"CE\"\n      ]\n    },\n    {\n      \"filter\": \"custom_property_contains_element\",\n      \"property_name\": \"industries\",\n      \"property_value\": \"electronics\"\n    },\n    {\n      \"filter\": \"external_id_is_in_list\",\n      \"external_ids\": [\n        \"external_id_1\",\n        \"external_id_2\",\n        \"external_id_3\"\n      ]\n    },\n    {\n      \"filter\": \"is_active\",\n      \"is_active\": true\n    },\n    {\n      \"filter\": \"exclude_match_feedback\",\n      \"search_for\": \"employee_id\",\n      \"exclude_match_feedback\": \"thumbs_up\"\n    }\n  ],\n  \"weights\": [\n    {\n      \"weight\": \"max_geo_distance\",\n      \"value\": 0.1,\n      \"full_score_distance\": 5,\n      \"zero_score_distance\": 15\n    },\n    {\n      \"weight\": \"custom_property\",\n      \"property_name\": \"direct_manager\",\n      \"property_value\": \"John Doe\",\n      \"operator\": \"eq\",\n      \"value\": 0.04\n    },\n    {\n      \"weight\": \"custom_property\",\n      \"property_name\": \"yearly_salary\",\n      \"property_value\": 45000,\n      \"operator\": \"gte\",\n      \"value\": 0.04\n    }\n  ],\n  \"location\": {\n    \"lat\": 51.0216707,\n    \"lng\": 3.6887328\n  }\n}")
  .asString();
require 'uri'
require 'net/http'

url = URI("https://{tenant_name}.{region}.techwolf.ai/vacanies/search")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"text\": \"Software Engineer\",\n  \"filters\": [\n    {\n      \"filter\": \"max_geo_distance\",\n      \"max_geo_distance\": 50\n    },\n    {\n      \"filter\": \"custom_property\",\n      \"property_name\": \"direct_manager\",\n      \"property_value\": \"John Doe\"\n    },\n    {\n      \"filter\": \"custom_property_is_in_list\",\n      \"property_name\": \"drivers_license\",\n      \"possible_values\": [\n        \"C\",\n        \"CE\"\n      ]\n    },\n    {\n      \"filter\": \"custom_property_contains_element\",\n      \"property_name\": \"industries\",\n      \"property_value\": \"electronics\"\n    },\n    {\n      \"filter\": \"external_id_is_in_list\",\n      \"external_ids\": [\n        \"external_id_1\",\n        \"external_id_2\",\n        \"external_id_3\"\n      ]\n    },\n    {\n      \"filter\": \"is_active\",\n      \"is_active\": true\n    },\n    {\n      \"filter\": \"exclude_match_feedback\",\n      \"search_for\": \"employee_id\",\n      \"exclude_match_feedback\": \"thumbs_up\"\n    }\n  ],\n  \"weights\": [\n    {\n      \"weight\": \"max_geo_distance\",\n      \"value\": 0.1,\n      \"full_score_distance\": 5,\n      \"zero_score_distance\": 15\n    },\n    {\n      \"weight\": \"custom_property\",\n      \"property_name\": \"direct_manager\",\n      \"property_value\": \"John Doe\",\n      \"operator\": \"eq\",\n      \"value\": 0.04\n    },\n    {\n      \"weight\": \"custom_property\",\n      \"property_name\": \"yearly_salary\",\n      \"property_value\": 45000,\n      \"operator\": \"gte\",\n      \"value\": 0.04\n    }\n  ],\n  \"location\": {\n    \"lat\": 51.0216707,\n    \"lng\": 3.6887328\n  }\n}"

response = http.request(request)
puts response.read_body
{
  "results": [
    {
      "vacancy_id": "vuid-123",
      "score": 0.82
    },
    {
      "vacancy_id": "vuid-456",
      "score": 0.74
    },
    {
      "vacancy_id": "vuid-789",
      "score": 0.56
    }
  ]
}
[
  {
    "title": "400 Bad Request",
    "description": "The request body was not structured correctly."
  }
]
[
  {
    "title": "401 Unauthorized",
    "description": "OAuth access token is missing, invalid or expired."
  }
]
[
  {
    "title": "403 Forbidden",
    "description": "You don't have access to this resource."
  }
]
[
  {
    "title": "405 Method Not Allowed",
    "description": "This method is not allowed for the requested URL."
  }
]
[
  {
    "title": "413 Payload Too Large",
    "description": "Request payload is too large."
  }
]
[
  {
    "title": "415 Unsupported Media Type",
    "description": "Content-type must be one of: application/json"
  }
]
[
  {
    "title": "422 Unprocessable entity",
    "description": "The request body contains some fields with invalid data (e.g. invalid date, invalid enumeration value ..)"
  }
]
"max connections reached: <limit>"
[
  {
    "title": "503 Service Unavailable",
    "description": "The Skill Engine API is currently not available. Please contact TechWolf or try again later."
  }
]

Authorizations

​
Authorization
string
header
required

The access token received from the authorization server in the OAuth 2.0 flow.

Query Parameters

​
limit
integer
default:10

The maximal number of results returned.

Required range: 1 <= x <= 100
Example:

10

​
offset
integer
default:0

The rank offset for returned matches, return matches starting from rank offset up to rank offset+limit.

Required range: x >= 0
​
score_min_threshold
number<float>
default:0.5

The minimum score of the results. Due to approximations for fast result-delivery, there might be records with a score slightly lower than the minimum.

Required range: 0 <= x <= 1
Example:

0.7

​
language
enum<string>
default:auto

The language of the input text. auto will automatically detect the language used.

Available options:
auto,
nl,
fr,
en,
de
Example:

"en"

​
match_type
enum<string>
default:literal

The type of matching. literal will search text-based. skills will use the Skills extracted from the input to find the best-matching Vacancies.

Available options:
literal,
skills
Example:

"skills"

​
external_vendor
enum<string>
default:techwolf

The external vendor vocabulary you want to see the Skills displayed in. This will only work for vendors that are activated on your tenant.

Available options:
techwolf,
workday,
sap_attribute_library
Example:

"workday"

Body

application/json

Request structure for free text search.

​
text
string
required

Input text.

Example:

"Software Engineer"

​
filters
(max_geo_distance · object | custom_property · object | custom_property_is_in_list · object | custom_property_contains_element · object | external_id_is_in_list · object | is_active · object | exclude_match_feedback · object)[]
required
Example:
[
  {
    "filter": "max_geo_distance",
    "max_geo_distance": 50
  },
  {
    "filter": "custom_property",
    "property_name": "direct_manager",
    "property_value": "John Doe"
  },
  {
    "filter": "custom_property_is_in_list",
    "property_name": "drivers_license",
    "possible_values": ["C", "CE"]
  },
  {
    "filter": "custom_property_contains_element",
    "property_name": "industries",
    "property_value": "electronics"
  },
  {
    "filter": "external_id_is_in_list",
    "external_ids": [
      "external_id_1",
      "external_id_2",
      "external_id_3"
    ]
  },
  { "filter": "is_active", "is_active": true },
  {
    "filter": "exclude_match_feedback",
    "search_for": "employee_id",
    "exclude_match_feedback": "thumbs_up"
  }
]
​
weights
(geo_distance · object | custom_property · object | skills_match · object)[]
required
Example:
[
  {
    "weight": "max_geo_distance",
    "value": 0.1,
    "full_score_distance": 5,
    "zero_score_distance": 15
  },
  {
    "weight": "custom_property",
    "property_name": "direct_manager",
    "property_value": "John Doe",
    "operator": "eq",
    "value": 0.04
  },
  {
    "weight": "custom_property",
    "property_name": "yearly_salary",
    "property_value": 45000,
    "operator": "gte",
    "value": 0.04
  }
]
​
location
Location · object

A geographic location, expressed in latitude and longitude. This can represent a home address, an office location... Each entity is limited to having a single location. To get the latitude and longitude for a given address, you can use the Google Maps Geocoding API or a predefined lookup table (for example by zip code). If location is present in matching or filters, it will act as an override for geo-distance calculations.

Response

OK

​
results
object[]
required

List of search results.