Talent network
Read recruiter-entered preferences for many candidates at once
curl -X POST "https://external-api.paraform.com/api/external/v1/talent-network/candidates/preferences/lookup" \
-H "Authorization: Bearer $PARAFORM_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"candidates": [
{
"candidateUserId": "string"
}
]
}'
{
"results": [
{
"index": 0,
"ok": true,
"status": "found"
}
]
}
Required scopes:
Rate limit:
talent_network:readRate limit:
default tier, 120 requests per minute per keyGET /talent-network/candidates/{candidateUserId}/preferences, for CRMs that mirror a whole list rather than one candidate at a time. These are the same values a recruiter manages in-app, and the source that always wins for ParaAI matching.
Each item references a candidate by candidateUserId (from GET /talent-network/candidates or POST /talent-network/candidates/lookup), or by email / linkedinUrl. candidateUserId wins when both are given; otherwise linkedinUrl beats email, the same precedence lookup documents. Any candidate owned by an approved member of your agency is addressable — deliberately wider than the membership list, so off-market or expired candidates are readable too.
An identity reference resolves to EVERY membership row your agency holds for that person, so candidates can carry more than one entry: a candidate two of your recruiters own has a separate, independently editable preferences row per owner, each listed with its own candidateUserId. Entries are ordered by ParaAI eligibility expiry, latest first, with rows that have no expiry last. Do not assume a single entry — read them all, or pick by candidateUserId.
results is index-aligned with candidates and the request answers 200, so branch on per-item ok. status is found (candidates lists one entry per owning membership row) or not_found (no candidate owned by an approved member of your agency matches this reference, indistinguishable from a candidate that does not exist). Values are never rejected: an unparseable linkedinUrl, an unknown email, or an item naming no candidate at all — null fields read as omitted — answers not_found at its own index, so one bad value never costs you the rest of the batch. Only schema violations fail the whole request with 400, as on every endpoint: fields must carry their documented JSON types, and candidateUserId, when present, must be a non-empty string. Statuses are never renamed but new ones may be added — branch on ok and treat an unknown status as informational.
An entry’s preferences is null when that membership row has no recruiter-entered preferences yet (possible for candidates who entered the network via a role submission) — exactly what the single-candidate GET returns for it. Candidates predating today’s validation may read back null numbers or empty arrays.
This endpoint only reads; it never creates or modifies anything and takes no Idempotency-Key. Duplicate references in one request get the same answer at every index.
Body
object[]
required
Response
object[]
required
Show results properties
Show results properties
integer
required
Constraints: minimum 0.
object[]
Show candidates properties
Show candidates properties
string
required
object | null
required
Show preferences properties
Show preferences properties
string[]
required
Show 21 allowed values
Show 21 allowed values
new_york, san_francisco, south_bay_area, los_angeles, boston, seattle, texas, chicago, europe, latam, korea, canada, australia, india, uk, washington_dc, asia, denver, florida, minnesota, sacramentostring[]
required
Allowed values:
REMOTE, ON_SITE, HYBRID.integer | null
required
integer | null
required
integer | null
required
string[]
required
Allowed values:
PRE_SEED, SEED, SERIES_A, SERIES_B, SERIES_C, SERIES_D_PLUS, UNKNOWN.string | null
required
Allowed values:
NO_VISA_AUTHORIZATION_NEEDED, HAS_VISA_AUTHORIZATION, NEEDS_NEW_VISA_AUTHORIZATION.string[]
required
Show 83 allowed values
Show 83 allowed values
backend_engineer, frontend_engineer, full_stack_engineer, mobile_engineer, infrastructure_devops_sre, security_engineer, forward_deployed_engineer_solutions_support, robotics_software_engineer, robotics_platform_engineer, sales_solutions_engineer, qa_test_engineering, blockchain_protocol_engineer, developer_relations_advocacy, founding_engineer, product_engineer, embedded_firmware_engineer, mechanical_engineer, electrical_engineer, robotics_hardware_engineer, aerospace_flight_engineer, machine_learning_engineer, robotics_ml_engineer, data_engineer, data_science_analytics, computer_vision_engineer, research_scientist_applied_research, ai_ml_researcher, research_engineer_applied_research, data_scientist_applied_scientist, machine_learning_infrastructure, machine_learning_ops_platform, research_scientist, research_engineer, ai_engineer, product_management, product_design_ux_ui, brand_visual_design, marketing_growth, growth_engineer, growth_marketing, demand_generation, performance_paid_media, lifecycle_crm_email, seo_organic_growth, marketing_ops_analytics, product_marketing, customer_marketing, content_marketing, brand_marketing, social_media_influencer, communications_pr, events_field_marketing, marketing_leadership, founding_marketer_generalist, account_executives_sales, account_management_customer_success, business_development, sales_development_rep, customer_technical_support, content_copywriting, sales_gtm_leadership, partnerships, operations_strategy, robotics_operations_engineer, revenue_operations, finance_accounting, people_talent, chief_of_staff, program_project_management, executive_assistant, data_analyst, engineering_leadership, executive_leadership, clinical_healthcare, legal_compliance_officer, legal_operations, legal_compliance, legal_partner, legal_counsel, legal_associate, legal_in_house_counsel, legal_paralegal, legal_adminstring[]
required
Show 39 allowed values
Show 39 allowed values
venture_capital, logistics, real_estate, marketplace, healthcare, life_sciences, hardware, ai, gaming, fintech, finance, education, ecommerce, devtools, defense, cybersecurity, crypto, data, enterprise, financial_services, government, insurance, law, marketing, media, transportation, environment, robotics, security, construction, manufacturing, consumer, ad_tech, b2b, api_sdk, software_development, creator_economy, edtech, autonomous_vehiclesstring[]
required
Allowed values:
< 10 employees, 10 - 50 employees, 50 - 200 employees, 200 - 1000 employees, > 1000 employees.boolean
required
string
required
Allowed values:
found, not_found.string
curl -X POST "https://external-api.paraform.com/api/external/v1/talent-network/candidates/preferences/lookup" \
-H "Authorization: Bearer $PARAFORM_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"candidates": [
{
"candidateUserId": "string"
}
]
}'
{
"results": [
{
"index": 0,
"ok": true,
"status": "found"
}
]
}
⌘I
curl -X POST "https://external-api.paraform.com/api/external/v1/talent-network/candidates/preferences/lookup" \
-H "Authorization: Bearer $PARAFORM_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"candidates": [
{
"candidateUserId": "string"
}
]
}'
{
"results": [
{
"index": 0,
"ok": true,
"status": "found"
}
]
}