Skip to main content
FreshTalent’s REST API lets you find people, organize them into Lists, run Targets, and consume profile-change events. Start with Build your first integration for a complete search → List → events workflow.

​
Base URL and authentication

Send a server-side API key in Authorization: Bearer YOUR_API_KEY. X-Api-Key is also accepted; send only one authentication method. Organization-owned resources are scoped to the key’s organization. Most data endpoints also require active organization access; Get account reports access and quotas.
Use Content-Type: application/json for JSON request bodies. Keep keys out of browser bundles, URLs, logs, and source control. See Authentication.

​
Requests and responses

Endpoint pages define their exact request and response shapes. Most successful reads return data; collection endpoints may add meta. A successful delete returns 204 with no body, so do not call response.json() on it. People search also returns the effective structured query. For example, an empty result can look like this:
Persist that query with Save query and reuse it on people search. Target discovery uses a different schema and is not an exact replay of the graph search. See Search query compatibility. Neither Target app_query nor its provider-oriented query accepts the echoed graph-search object unchanged.
  • Full versus compact: people search defaults to view=full. view=compact changes field names and structure, not just payload size. See Person response shapes.
  • Null versus omitted: null means a field has no value; optional fields can be absent. Neither implies false, zero, or an empty string. Tolerate additional response fields.
  • Identifiers: person routes use a LinkedIn slug. Lists resolve by UUID or case-insensitive name; use the returned UUID after resolution. Targets use UUIDs. URL-encode path values.
  • Pagination: follow the contract on each endpoint. People search uses offsets; events use older-page cursors. Not every collection is paginated, and counts are not interchangeable with totals.
  • Examples: cURL, JavaScript, and Python snippets are direct HTTP calls, not SDKs. Set FRESHTALENT_API_KEY; replace sample identifiers with values returned by your account. JavaScript examples use Node.js 22+; Python examples use the standard library.

​
Errors, limits, and safe retries

Branch on HTTP status first. Application errors usually return { "error": { "type": "…", "message": "…" } }, while framework validation and rate limiting can return { "statusCode": 429, "error": "Too Many Requests", "message": "…" }.
  • The Gateway currently allows 300 requests per minute per client IP as it sees it, not per key. See Rate limits and quotas.
  • Retry transient read failures with bounded backoff and jitter. Honor Retry-After on 429.
  • A timed-out mutation may already have succeeded. Reconcile the resource before replaying it; repeated List-member writes can overwrite stage and notes.
  • Event polling needs overlap windows and event-ID deduplication. A page cursor is not the checkpoint for the next poll.
See Errors for handling both error shapes and List events for the polling contract.

​
Endpoint map

​
Account and discovery

​
Lists and saved queries

​
Targets, events, and notifications

This map covers the operations documented in this reference, not every dashboard route. In particular, the dashboard’s /monitoring and filtered /signals feeds are not interchangeable with the integration event stream.

​
Other integration surfaces

  • MCP: connect compatible assistants at https://api.freshtalent.ai/mcp.
  • ATS and CRM architecture: turn events into idempotent downstream updates.
  • Machine-readable product guidance: https://freshtalent.ai/llms.txt.