Estimate talent pool

POST

talents

estimation

curl --request POST \
  --url https://app.kalent.ai/api/v1/search/talents/estimation \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "filters": [
    {}
  ],
  "mode": "<string>"
}
'

import requests

url = "https://app.kalent.ai/api/v1/search/talents/estimation"

payload = {
    "filters": [{}],
    "mode": "<string>"
}
headers = {
    "x-api-key": "<api-key>",
    "Content-Type": "application/json"
}

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

print(response.text)

const options = {
  method: 'POST',
  headers: {'x-api-key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({filters: [{}], mode: '<string>'})
};

fetch('https://app.kalent.ai/api/v1/search/talents/estimation', 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://app.kalent.ai/api/v1/search/talents/estimation",
  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([
    'filters' => [
        [
                
        ]
    ],
    'mode' => '<string>'
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "x-api-key: <api-key>"
  ],
]);

$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://app.kalent.ai/api/v1/search/talents/estimation"

	payload := strings.NewReader("{\n  \"filters\": [\n    {}\n  ],\n  \"mode\": \"<string>\"\n}")

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

	req.Header.Add("x-api-key", "<api-key>")
	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://app.kalent.ai/api/v1/search/talents/estimation")
  .header("x-api-key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"filters\": [\n    {}\n  ],\n  \"mode\": \"<string>\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://app.kalent.ai/api/v1/search/talents/estimation")

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

request = Net::HTTP::Post.new(url)
request["x-api-key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"filters\": [\n    {}\n  ],\n  \"mode\": \"<string>\"\n}"

response = http.request(request)
puts response.read_body

{
  "success": true,
  "data": {
    "estimationCount": 123,
    "mode": "<string>"
  },
  "error": {
    "code": "<string>",
    "message": "<string>",
    "debugTrackingCode": "<string>",
    "available": 123,
    "required": 123,
    "issues": [
      {}
    ],
    "details": {
      "window": "<string>",
      "limit": 123,
      "current": 123
    }
  }
}

First time? Set up Authentication

Learn how to authenticate your API requests with your API key.

Count the profiles that match a filters array. The response is a number and the mode that produced it. No profile, talent id, or searchTransactionId is returned, and no profile is saved. You can post the data object from extract search from prompt directly. qualificationCriterias is ignored. The same prompt can yield slightly different filters, so store data if you need a stable search.

Request body

object[]

required

Same filter objects as POST /v1/search/talents. At least one filter is required. See accepted filter values.

string

default:"gate"

Optional. One of gate or rank. Defaults to gate when omitted. See Search modes. Qualified search always runs in gate mode, so the gate estimate is the one that matches the qualified search pool.

Fields other than filters and mode are ignored, so the extraction data object, which also carries qualificationCriterias, is accepted as-is.

Limits

Item	Limit
`filters`	At least one filter. Each filter follows the rules of `POST /v1/search/talents`, for example `YEARS_OF_EXPERIENCE` as `"min-max"` with both bounds between 0 and 100 and min ≤ max.
`mode`	Optional. `gate` or `rank`. Defaults to `gate`.
`estimationCount`	Capped at 10,000.
Balance	At least 1 API credit, even though nothing is debited.
Rate limits	Each call counts against the API key’s request windows. See Rate limits.

Response

Successful responses carry two headers:

Header	Value
`X-Api-Credits-Used`	Always `0`.
`X-Api-Credits-Remaining`	Your workspace balance, read before the count.

Error responses do not send these headers.

boolean

Whether the request completed without errors.

object

Present when success is true.

Show data fields

number

Estimated number of profiles matching the filters in the requested mode. The estimate is capped at 10,000: a value of 10,000 means “10,000 or more”.

string

The mode that produced estimationCount: gate or rank. gate when the request omitted mode.

object

Error details, present when success is false.

Show error fields

string

Machine-readable error code. One of: validation_error, insufficient_api_credits, unsupported_location, missing_connected_linkedin_account, search_engine_timeout, missing_api_key, invalid_api_key, expired_token, plan_upgrade_required, rate_limit_exceeded, internal_error.

string

Human-readable error description.

string

Unique tracking code for this request. Include it when contacting support.

number

API credits available. Only present when code is insufficient_api_credits.

number

Minimum balance required, always 1. Only present when code is insufficient_api_credits.

object[]

Zod validation details. Only present when code is validation_error.

object

Present when code is plan_upgrade_required (billing remediation, see Authentication) or when code is rate_limit_exceeded on an API-key window.

Show rate limit details fields

string

The time window that was exceeded. One of: second, minute, hour, day, month.

number

Maximum number of requests allowed in this window.

number

Number of requests made in this window, including the rejected one.

Credits

The call debits 0 API credits, in gate and in rank mode. Nothing is reserved or consumed. It is still rejected with 402 insufficient_api_credits unless the balance is at least 1. required is 1 and available is the balance that was read. A successful response sends X-Api-Credits-Used: 0 and X-Api-Credits-Remaining equal to that balance. See Credits.

Errors

Status	`error.code`	When
400	`validation_error`	Missing or empty `filters`, an invalid filter, a `mode` other than `gate` or `rank`, or a body that is not a JSON object.
400	`missing_connected_linkedin_account`	A LinkedIn-relationship filter was sent and no LinkedIn account is connected.
401	`missing_api_key`	No API key was sent.
401	`invalid_api_key`	The API key or OAuth access token is not valid.
401	`expired_token`	The OAuth access token has expired. Re-authorize.
402	`insufficient_api_credits`	Balance is below 1. `required` is `1`.
402	`plan_upgrade_required`	The workspace must subscribe or upgrade its plan before using the API. Search routes, including this one, do not require a subscription today.
422	`unsupported_location`	A location filter cannot be resolved.
429	`rate_limit_exceeded`	An API-key request window, or the per-IP limit on failed authentication, was exceeded. See Rate limits.
500	`internal_error`	The count failed.
504	`search_engine_timeout`	The count timed out. Retry.

Response examples

200 — Success

Request

curl -X POST https://app.kalent.ai/api/v1/search/talents/estimation \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "mode": "gate",
    "filters": [
      {
        "filterType": "JOB_TITLE",
        "value": "Data Engineer",
        "isRequired": true,
        "isExcluded": false,
        "isExactMatch": false,
        "history": "CURRENT"
      },
      {
        "filterType": "LOCATION",
        "value": "Paris",
        "isRequired": true,
        "isExcluded": false,
        "isExactMatch": false
      },
      {
        "filterType": "YEARS_OF_EXPERIENCE",
        "value": "5-100",
        "isRequired": false,
        "isExcluded": false,
        "isExactMatch": false
      }
    ]
  }'

Response headers

X-Api-Credits-Used: 0
X-Api-Credits-Remaining: 41

Response

{
  "success": true,
  "data": {
    "estimationCount": 1840,
    "mode": "gate"
  }
}

400 — Validation error

Returned when the body does not match the schema. Here filters is empty.

Request

curl -X POST https://app.kalent.ai/api/v1/search/talents/estimation \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "filters": []
  }'

Response

{
  "success": false,
  "error": {
    "code": "validation_error",
    "message": "Validation failed",
    "debugTrackingCode": "V1StGXR8_Z5jdHi6B-myT",
    "issues": [
      {
        "code": "too_small",
        "minimum": 1,
        "type": "array",
        "inclusive": true,
        "exact": false,
        "message": "filters must not be empty",
        "path": ["filters"]
      }
    ]
  }
}

An unknown mode returns the same envelope with this issue:

{
  "received": "fast",
  "code": "invalid_enum_value",
  "options": ["gate", "rank"],
  "path": ["mode"],
  "message": "Invalid enum value. Expected 'gate' | 'rank', received 'fast'"
}

A YEARS_OF_EXPERIENCE value such as "5+", "150-100", or "10-5" returns:

{
  "code": "custom",
  "message": "Years of experience must be one string \"min-max\" with both bounds between 0 and 100 and min ≤ max",
  "path": ["filters", 0, "value"]
}

400 — Missing connected LinkedIn account

Returned when a LINKEDIN_RELATIONS_DEGREE filter is sent and the workspace has no connected LinkedIn account.

Response

{
  "success": false,
  "error": {
    "code": "missing_connected_linkedin_account",
    "message": "No LinkedIn account is connected. Connect LinkedIn in your Kalent settings to filter results by LinkedIn connections.",
    "debugTrackingCode": "V1StGXR8_Z5jdHi6B-myT"
  }
}

401 — Authentication error

Returned when the API key is missing or invalid, or when an OAuth access token has expired.

Response (missing key)

{
  "success": false,
  "error": {
    "code": "missing_api_key",
    "message": "Missing API key",
    "debugTrackingCode": "V1StGXR8_Z5jdHi6B-myT"
  }
}

Response (invalid key)

{
  "success": false,
  "error": {
    "code": "invalid_api_key",
    "message": "Invalid API key",
    "debugTrackingCode": "V1StGXR8_Z5jdHi6B-myT"
  }
}

Response (expired OAuth token)

{
  "success": false,
  "error": {
    "code": "expired_token",
    "message": "Access token has expired. Please re-authorize.",
    "debugTrackingCode": "V1StGXR8_Z5jdHi6B-myT"
  }
}

402 — Insufficient API credits

Returned when the balance is below 1. Nothing is counted. Top up your credits and retry.

Response

{
  "success": false,
  "error": {
    "code": "insufficient_api_credits",
    "message": "Insufficient API credits: 0 available, 1 required.",
    "available": 0,
    "required": 1,
    "debugTrackingCode": "V1StGXR8_Z5jdHi6B-myT"
  }
}

402 — Plan upgrade required

Returned by authentication when the workspace must subscribe or upgrade its plan. Search routes, including this one, do not require a subscription today.

Response

{
  "success": false,
  "error": {
    "code": "plan_upgrade_required",
    "message": "A Kalent subscription or plan upgrade is required to use the Kalent API. Please subscribe or upgrade your plan in Kalent billing: https://app.kalent.ai/settings/billing",
    "debugTrackingCode": "V1StGXR8_Z5jdHi6B-myT",
    "details": {
      "code": "subscription_or_plan_upgrade_required",
      "action": "subscribe_or_upgrade",
      "capability": "use_kalent_api",
      "billingUrl": "https://app.kalent.ai/settings/billing"
    }
  }
}

422 — Unsupported location

Returned when a LOCATION filter cannot be resolved. Remove that location or change it. Retrying the same value will not succeed.

Response

{
  "success": false,
  "error": {
    "code": "unsupported_location",
    "message": "Unsupported location: Singapore",
    "debugTrackingCode": "V1StGXR8_Z5jdHi6B-myT"
  }
}

429 — Rate limit exceeded

Returned when an API-key request window is exceeded. A per-IP limit on failed authentication returns the same code with the message Too many requests, please try again later and no details. See Rate limits.

Response

{
  "success": false,
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Rate limit exceeded: too many requests per minute",
    "debugTrackingCode": "V1StGXR8_Z5jdHi6B-myT",
    "details": {
      "window": "minute",
      "limit": 30,
      "current": 31
    }
  }
}

500 — Internal error

Returned when the count fails unexpectedly. Retry, and include debugTrackingCode if you contact support.

Response

{
  "success": false,
  "error": {
    "code": "internal_error",
    "message": "An error occurred during talent pool estimation",
    "debugTrackingCode": "V1StGXR8_Z5jdHi6B-myT"
  }
}

504 — Search timeout

Returned when the count takes too long. Retry, or narrow the filters.

Response

{
  "success": false,
  "error": {
    "code": "search_engine_timeout",
    "message": "The search request timed out. Please try again.",
    "debugTrackingCode": "V1StGXR8_Z5jdHi6B-myT"
  }
}

Estimate talent pool

curl --request POST \
  --url https://app.kalent.ai/api/v1/search/talents/estimation \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "filters": [
    {}
  ],
  "mode": "<string>"
}
'

import requests

url = "https://app.kalent.ai/api/v1/search/talents/estimation"

payload = {
    "filters": [{}],
    "mode": "<string>"
}
headers = {
    "x-api-key": "<api-key>",
    "Content-Type": "application/json"
}

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

print(response.text)

const options = {
  method: 'POST',
  headers: {'x-api-key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({filters: [{}], mode: '<string>'})
};

fetch('https://app.kalent.ai/api/v1/search/talents/estimation', 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://app.kalent.ai/api/v1/search/talents/estimation",
  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([
    'filters' => [
        [
                
        ]
    ],
    'mode' => '<string>'
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "x-api-key: <api-key>"
  ],
]);

$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://app.kalent.ai/api/v1/search/talents/estimation"

	payload := strings.NewReader("{\n  \"filters\": [\n    {}\n  ],\n  \"mode\": \"<string>\"\n}")

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

	req.Header.Add("x-api-key", "<api-key>")
	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://app.kalent.ai/api/v1/search/talents/estimation")
  .header("x-api-key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"filters\": [\n    {}\n  ],\n  \"mode\": \"<string>\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://app.kalent.ai/api/v1/search/talents/estimation")

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

request = Net::HTTP::Post.new(url)
request["x-api-key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"filters\": [\n    {}\n  ],\n  \"mode\": \"<string>\"\n}"

response = http.request(request)
puts response.read_body

{
  "success": true,
  "data": {
    "estimationCount": 123,
    "mode": "<string>"
  },
  "error": {
    "code": "<string>",
    "message": "<string>",
    "debugTrackingCode": "<string>",
    "available": 123,
    "required": 123,
    "issues": [
      {}
    ],
    "details": {
      "window": "<string>",
      "limit": 123,
      "current": 123
    }
  }
}

Getting Started

Search preparation

Talent search (L1)

Qualified search (L2)

LinkedIn contact enrichment

Estimate talent pool

First time? Set up Authentication

Request body

Limits

Response

Credits

Errors

Response examples

First time? Set up Authentication

​Request body

​Limits

​Response

​Credits

​Errors

​Response examples

Request body

Limits

Response

Credits

Errors

Response examples