DataVertex Candidate Search API

Overview

The DataVertex Candidate Search API allows you to discover and filter professional profiles by criteria such as job title, company, location, skills, and more. Search across 800M+ professional profiles to find candidates that match your specific requirements.

“Schedule a quick call to get API access and explore how DataVertex can support your recruiting product development.”

Endpoint: POST https://api.data-vertex.com/v1/search

Credit Cost: 1 credit per search (up to 100 profiles per page)

Billing: Success-based - you're only charged if results are returned

Authentication

All API requests must include your API key in the request headers:

x-api-key: YOUR_API_KEY

You can obtain your API key from DataVertex directly.

Request Format

Headers

Header	Value	Required
`x-api-key`	Your API key	Yes
`Content-Type`	`application/json`	Yes

Body Parameters

Parameter	Type	Description	Required
`search_criteria`	object	Search filters and criteria. Required unless `free_text_search` is provided.	Conditional
`free_text_search`	string	Natural language search request (max 300 characters). The API parses this into structured search criteria automatically. Required unless `search_criteria` is provided.	Conditional
`page_size`	integer	Number of profiles per page (1-100)	No (default: 50)
`start`	integer	Starting position for pagination	No (default: 1)
`include_similar_titles`	boolean	Automatically expand `current_title` with similar titles	No (default: false)

Note: At least one of search_criteria or free_text_search must be provided. Both can be used together — see the free_text_search section below for merge behavior.

Extended Title Search - include_similar_titles

When set to true at the top level of the request, the API automatically expands your current_title array with similar, titles before executing the search. This broadens your candidate pool without requiring you to manually list every relevant title variation.

Only applies when current_title is provided with fewer than 10 titles
Titles are added up to a maximum of 10 total
If current_title is not present in your request, this parameter has no effect
Default: false

{
  "search_criteria": {
    "current_title": ["software engineer"],
    "location": ["Austin::~30mi"]
  },
  "page_size": 50,
  "start": 1,
  "include_similar_titles": true
}

Semantic Candidate Search - free_text_search

Write a natural language description of the candidates you are looking for — up to 300 characters. The API will parse your request into structured search criteria.

Supported fields parsed from free text:

Free Text Concept	Mapped To
Job titles	`current_title`
Skills	`skills`
Location	`location`
Years of experience	`years_experience`
Current or previous employer	`current_employer` / `previous_employer`
School, degree, major	`school` / `degree` / `major`
Industry / sector / domain / market	`company_industry`

Behavior when combined with search_criteria: - Fields parsed from free_text_search are merged into any existing search_criteria — array values are combined - Exception: years_experience always overrides any value already in search_criteria rather than merging - free_text_search can be used as the sole input — search_criteria is not required when it is provided

Compatibility with include_similar_titles: Fully supported. The current_title values parsed from free_text_search are populated first, and then include_similar_titles expands them as normal.

Limit: 300 characters. Requests exceeding this return a 400 error.

{
  "free_text_search": "Software engineers with 5+ years of Python experience in Chicago",
  "page_size": 50,
  "start": 1
}

The response includes a free_text_searched field showing exactly what is mapped:

{
  "free_text_searched": {
    "current_title": ["Software Engineer"],
    "skills": ["Python"],
    "location": ["Chicago"],
    "years_experience": ["5+"]
  }
}

Search Criteria Parameters

The search_criteria object supports 60+ parameters organized into logical categories:

Profile Identification

Parameter	Type	Description	Example
`id`	array of strings	DataVertex Profile IDs	`["123456"]`
`name`	array of strings	Profile names	`["John Doe"]`
`email`	array of strings	Email addresses	`["john.doe@data-vertex.com"]`
`phone`	array of strings	Phone numbers	`["+15555555555"]`
`handle`	array of strings	Social media handles	`["johndoe"]`
`link`	array of strings	Profile URLs	`["https://linkedin.com/in/johndoe"]`

Job Title & Role

Parameter	Type	Description	Example
`current_title`	array of strings	Current job titles	`["Product Manager", "VP of Product"]`
`previous_title`	array of strings	Previous job titles	`["Software Engineer", "Software Developer"]`
`current_or_previous_title`	array of strings	Current or previous titles	`["VP of Sales", "Director of Sales"]`
`department`	array of strings	Company departments	`["Product Management", "Engineering"]`
`management_levels`	array of strings	Management levels	`["Director", "VP", "C-Level"]`

Employer

Parameter	Type	Description	Example
`current_employer`	array of strings	Current company names	`["DataVertex"]`
`previous_employer`	array of strings	Previous company names	`["Google", "Microsoft"]`
`company_name`	array of strings	Company names	`["DataVertex"]`
`company_domain`	array of strings	Company domains	`["data-vertex.com"]`
`company_email`	array of strings	Company email addresses	`["info@data-vertex.com"]`
`company_website_url`	array of strings	Company website URLs	`["data-vertex.com"]`

Company Attributes

Parameter	Type	Description	Example
`company_size`	array of strings	Company size ranges	`["51-200", "201-500"]`
`employees`	array of strings	Employee count ranges	`["100-500"]`
`company_revenue`	array of strings	Revenue ranges	`["10000000-50000000"]`
`company_funding_min`	array of strings	Minimum funding amount	`["1000000"]`
`company_funding_max`	array of strings	Maximum funding amount	`["50000000"]`
`total_funding`	array of strings	Total capital raised	`["10000000"]`
`company_publicly_traded`	array of strings	Public trading status	`["true"]`

Company Location

Parameter	Type	Description	Example
`company_country_code`	array of strings	Company country codes	`["US"]`
`geo`	array of strings	Geographic regions	`["North America"]`
`state`	array of strings	US states	`["MA", "CA"]`
`postal_code`	array of strings	Postal codes	`["02110"]`
`location`	array of strings	Location with optional radius	`["San Francisco::~50mi"]`

Location with Radius: Add a radius to location searches using the format "City::~Nmi" or "City::~Nkm": - Example: "location": ["San Francisco::~50mi"] - Example: "location": ["Boston::~25km"]

Industry & Sector

Parameter	Type	Description	Example
`company_industry`	array of strings	Company industries	`["Software Engineering"]`
`company_industry_keywords`	array of strings	Industry keywords	`["SaaS", "B2B"]`
`industry_keywords`	array of strings	Industry keywords	`["AI", "Machine Learning"]`
`company_naics_code`	array of strings	NAICS codes	`["541330", "541512"]`
`company_sic_code`	array of strings	SIC codes	`["7372"]`

Company Intelligence

Parameter	Type	Description	Example
`company_competitors`	array of strings	Competitor domains	`["competitor.com"]`

Education

Parameter	Type	Description	Example
`school`	array of strings	Schools attended	`["Stanford University", "MIT"]`
`degree`	array of strings	Degree types	`["Bachelors", "Masters", "PhD"]`
`major`	array of strings	Academic majors	`["Computer Science", "Biology"]`

Skills & Experience

Parameter	Type	Description	Example
`skills`	array of strings	Listed skills (any match)	`["Python", "SQL", "Machine Learning"]`
`all_skills`	array of strings	Required skills (must match all)	`["python", "sql", "machine learning"]`
`years_experience`	array of strings	Years of experience	`["1","2,","3"]` or ["1-3"]

Parameter	Type	Description	Example
`connections`	array of strings	LinkedIn connection counts	`["500+"]`

Healthcare (for healthcare professionals)

Parameter	Type	Description	Example
`health_credentials`	array of strings	Healthcare credentials	`["MD", "RN", "PhD"]`
`health_license`	array of strings	Healthcare licenses	`["MA12345"]`
`health_npi`	array of strings	National Provider Identifiers	`["1234567890"]`
`health_specialization`	array of strings	Medical specializations	`["Cardiology Technician", "Clinical Psychologist"]`

Metadata & Filters

Parameter	Type	Description	Example
`keywords`	array of strings	Multiple keywords (comma-separated)	`["Consulting", "Staffing"]`

Advanced Search Features

Exact Match

Add quotes around search terms to specify exact matches:

{
  "search_criteria": {
    "name": ["\"Marc Benioff\""],
    "current_employer": ["\"IBM\""]
  }
}

Without quotes, "Marc Benioff" matches "Marc Benioff", "Benioff Marc", "Marc Anthony Benioff", and ignores typos. With quotes, only exact matches are returned.

Exclude Terms

Prepend - to filter values to exclude results matching those terms:

{
  "search_criteria": {
    "current_title": ["Software Engineer", "Software Developer", "-Senior", "-Sr"]
  }
}

This matches Software Engineers and Software Developers that don't have "Senior" or "Sr" in their title.

Numeric Operators

company_funding_min, company_funding_max, employees, and company_size support mathematical operators:

{
  "search_criteria": {
    "company_funding_min": ["1000000+"],
    "company_funding_max": ["<90000000"],
    "company_revenue": ["1000000-90000000"]
  }
}

Valid operators: +, <, >=, <=, - (range)

Response Format

Success Response (200 OK)

{
  "success": true,
  "data": {
    "profiles": [
      {
        "id": "12345",
        "name": "Jane Smith",
        "current_title": "Software Engineer",
        "current_employer": "TechCorp",
        "location": "San Francisco, CA",
        "linkedin_url": "https://linkedin.com/in/janesmith"
      }
    ],
    "pagination": {
      "current_page": 1,
      "page_size": 50,
      "start": 1,
      "total": 1500,
      "has_next": true,
      "next_start": 51
    }
  },
  "credits": {
    "used": 1,
    "remaining": 999
  }
}

When free_text_search is used, the response also includes a free_text_searched field:

{
  "success": true,
  "data": { "..." },
  "credits": {
    "used": 1,
    "remaining": 999
  },
  "free_text_searched": {
    "current_title": ["Software Engineer"],
    "skills": ["Python"],
    "location": ["Chicago"],
    "years_experience": ["5+"]
  }
}

Response Fields

Profile Object

Each profile in the profiles array contains:

Field	Type	Description
`id`	string	Unique candidate ID (use for a lookup)
`name`	string	Full name
`current_title`	string	Current job title
`current_employer`	string	Current company name
`location`	string	Current location
`linkedin_url`	string	LinkedIn profile URL

Note: Search results do not include contact information (email/phone). Use the Lookup API with the candidate id to retrieve contact details.

Pagination Object

Field	Type	Description
`current_page`	integer	Current page number
`page_size`	integer	Profiles per page
`start`	integer	Starting position
`total`	integer	Total matching profiles
`has_next`	boolean	Whether more results exist
`next_start`	integer or null	Starting position for next page

Credits Object

Field	Type	Description
`used`	integer	Credits charged for this request
`remaining`	integer	Your remaining credit balance

Top-level Fields

Field	Type	Description
`similar_titles`	array or null	Expanded titles used for the search (only present when `include_similar_titles: true` and `current_title` was provided)
`free_text_searched`	object	The structured criteria the AI parsed from your `free_text_search` input (only present when `free_text_search` was used)

Code Examples

cURL

curl -X POST https://api.data-vertex.com/v1/search \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "search_criteria": {
      "current_title": ["Software Engineer", "Senior Software Engineer"],
      "location": ["San Francisco::~50mi"],
      "skills": ["Python", "React"]
    },
    "page_size": 50,
    "start": 1,
    "include_similar_titles": false
  }'

Python

import requests
import json

url = "https://api.data-vertex.com/v1/search"

headers = {
    "x-api-key": "YOUR_API_KEY",
    "Content-Type": "application/json"
}

payload = {
    "search_criteria": {
        "current_title": ["Software Engineer", "Senior Software Engineer"],
        "location": ["San Francisco::~50mi"],
        "skills": ["Python", "React"]
    },
    "page_size": 50,
    "start": 1,
    "include_similar_titles": False
}

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

if response.status_code == 200:
    data = response.json()
    print(f"Found {len(data['data']['profiles'])} profiles")
    print(f"Credits used: {data['credits']['used']}")
    print(f"Credits remaining: {data['credits']['remaining']}")
else:
    print(f"Error: {response.status_code}")
    print(response.text)

JavaScript (Node.js)

const axios = require('axios');

const searchCandidates = async () => {
  try {
    const response = await axios.post(
      'https://api.data-vertex.com/v1/search',
      {
        search_criteria: {
          current_title: ['Software Engineer', 'Senior Software Engineer'],
          location: ['San Francisco::~50mi'],
          skills: ['Python', 'React']
        },
        page_size: 50,
        start: 1,
        include_similar_titles: false
      },
      {
        headers: {
          'x-api-key': 'YOUR_API_KEY',
          'Content-Type': 'application/json'
        }
      }
    );

    console.log(`Found ${response.data.data.profiles.length} profiles`);
    console.log(`Credits used: ${response.data.credits.used}`);
    console.log(`Credits remaining: ${response.data.credits.remaining}`);

    return response.data;
  } catch (error) {
    console.error('Error:', error.response?.data || error.message);
  }
};

searchCandidates();

Pagination Example

To retrieve the next page of results:

import requests

url = "https://api.data-vertex.com/v1/search"
headers = {
    "x-api-key": "YOUR_API_KEY",
    "Content-Type": "application/json"
}

# First page
payload = {
    "search_criteria": {
        "current_title": ["Software Engineer"]
    },
    "page_size": 100,
    "start": 1,
    "include_similar_titles": False
}

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

# Check if there's a next page
if data['data']['pagination']['has_next']:
    next_start = data['data']['pagination']['next_start']

    # Get next page
    payload['start'] = next_start
    next_response = requests.post(url, headers=headers, json=payload)
    next_data = next_response.json()

Error Responses

400 Bad Request

Missing or invalid parameters:

{
  "success": false,
  "message": "search criteria was not provided or not formed correctly."
}

403 Forbidden

Authentication or authorization error:

{
  "success": false,
  "message": "Invalid or inactive API key."
}

Or insufficient credits:

{
  "success": false,
  "message": "Insufficient credits. Required: 1, Available: 0",
  "credits_info": {
    "required": 1,
    "available": 0
  }
}

500 Internal Server Error

Server error:

{
  "success": false,
  "message": "Internal server error occurred."
}

Error Codes Summary

Status Code	Meaning	Common Causes
200	OK	Request successful, data returned
400	Bad Request	Malformed request, missing required parameters, invalid page_size
403	Forbidden	Missing/invalid API key, insufficient credits
500	Internal Server Error	Unexpected server error

Best Practices

1. Use Specific Search Criteria

The more specific your search criteria, the better your results:

{
  "search_criteria": {
    "current_title": ["Software Engineer"],
    "location": ["San Francisco::~25mi"],
    "skills": ["Python", "Django"],
    "years_experience": ["5"]
  },
  "include_similar_titles": false
}

2. Optimize Page Size

Use page_size: 100 for maximum profiles per request
Smaller page sizes (10-20) for testing or incremental processing
Balance between API calls and processing time

3. Handle Pagination Efficiently

all_profiles = []
start = 1

while True:
    response = search_candidates(start=start)
    profiles = response['data']['profiles']
    all_profiles.extend(profiles)

    if not response['data']['pagination']['has_next']:
        break

    start = response['data']['pagination']['next_start']

4. Store Candidate IDs

Search results don't include contact information. Store the id field from each profile to use with the Lookup API:

candidate_ids = [profile['id'] for profile in response['data']['profiles']]

5. Monitor Your Credits

Check your remaining credits in each response to avoid interruptions:

if response['credits']['remaining'] < 100:
    print("Warning: Low credit balance!")

Common Use Cases

Example 1: Find Software Engineers in Bay Area

{
  "search_criteria": {
    "current_title": ["Software Engineer", "Senior Software Engineer", "Staff Engineer"],
    "location": ["San Francisco::~50mi"],
    "skills": ["Python", "JavaScript", "React"]
  },
  "page_size": 100,
  "include_similar_titles": false
}

Example 2: Find Healthcare Professionals

{
  "search_criteria": {
    "current_title": ["Registered Nurse", "RN"],
    "health_credentials": ["RN"],
    "location": ["Boston::~30mi"],
    "years_experience": ["3"]
  },
  "page_size": 50,
  "include_similar_titles": false
}

Example 3: Find Sales Leaders at Tech Companies

{
  "search_criteria": {
    "current_title": ["VP of Sales", "Director of Sales", "Sales Manager"],
    "company_industry": ["Software", "SaaS"],
    "company_size": ["51-200", "201-500"],
    "management_levels": ["Director", "VP"]
  },
  "page_size": 100,
  "include_similar_titles": false
}

Example 4: Find Recent Job Changers

{
  "search_criteria": {
    "current_title": ["Product Manager"],
    "location": ["New York::~40mi"],
    "job_change_range_days": ["30"]
  },
  "page_size": 50,
  "include_similar_titles": false
}

Example 5: Free Text Search

Use free_text_search to describe candidates in plain English instead of building structured criteria manually. The API maps your input to the appropriate fields and executes the search.

{
  "free_text_search": "Nurses with at least 3 years of experience in Boston",
  "page_size": 50,
  "start": 1
}

You can also combine free_text_search with explicit search_criteria — the parsed fields are merged in. The exception is years_experience, which is always overridden by the free text value rather than merged:

{
  "free_text_search": "Python engineers with 5+ years experience",
  "search_criteria": {
    "location": ["Austin::~30mi"],
    "company_size": ["51-200"]
  },
  "page_size": 50,
  "start": 1
}

Use free_text_search with include_similar_titles to both describe your candidates naturally and broaden the title match:

{
  "free_text_search": "Data engineers with Spark experience in Seattle",
  "include_similar_titles": true,
  "page_size": 100,
  "start": 1
}

Example 6: Expand a Single Title with include_similar_titles

When you only have one or a few titles in mind, use include_similar_titles to automatically broaden your search to related roles. The API will add up to 10 total titles before executing the search.

Page 1 — send your title and let the API expand it:

{
  "search_criteria": {
    "current_title": ["data engineer"],
    "location": ["Chicago::~40mi"]
  },
  "page_size": 100,
  "start": 1,
  "include_similar_titles": true
}

The response includes a similar_titles field containing the exact titles that were searched. Save this array — you will need it for all subsequent pages:

{
  "success": true,
  "data": {
    "profiles": [...],
    "pagination": {
      "current_page": 1,
      "page_size": 100,
      "start": 1,
      "total": 4800,
      "has_next": true,
      "next_start": 101
    }
  },
  "credits": {
    "used": 1,
    "remaining": 997
  },
  "similar_titles": [
    "data engineer",
    "analytics engineer",
    "data architect",
    "etl developer",
    "data pipeline engineer",
    "big data engineer",
    "data infrastructure engineer"
  ]
}

Page 2 onward — pass similar_titles back as current_title and set include_similar_titles to false:

{
  "search_criteria": {
    "current_title": [
      "data engineer",
      "analytics engineer",
      "data architect",
      "etl developer",
      "data pipeline engineer",
      "big data engineer",
      "data infrastructure engineer"
    ],
    "location": ["Chicago::~40mi"]
  },
  "page_size": 100,
  "start": 101,
  "include_similar_titles": false
}

This ensures every page is searched against the same set of titles, giving you consistent and complete results across your entire pagination sequence.

Need Help?

Support: dev@data-vertex.com
Website: https://www.data-vertex.com