Partner search

Overview

On top of the full synchronization (GET /freelances), partners can query the Pylote pool on demand, in 2 stages:

Stage 1 — Anonymized search (POST /partners/search): your query is ranked by our matching engine. You receive partial, anonymized profiles: enough to assess relevance, nothing to identify or contact.
Stage 2 — Reveal (POST /partners/reveal): given the id of a result, you receive the full profile (JSON Resume format, identical to GET /freelances). This is when the freelancer is notified of the view (a profile_view event is emitted automatically on Pylote’s side).

This separation lets you implement your own credit logic: consumption only happens at Stage 2.

Stage 1 — Search

const response = await axios.post(
  'https://client-p.pylote.io/partners/search',
  {
    keywords: 'react "design system" -wordpress',
    skills: ['react_js', 'typescript'],                    // AND: all required (slug from the Skills referential)
    workAreas: ['ile-de-france'],                          // OR (slug from the Regions referential)
    seniority: ['senior_6-10_ans', 'master_10_ans'],       // OR (slug from the Seniority referential)
    available: true,
    page: 1,
    limit: 50,
  },
  { headers: { 'x-api-key': API_KEY } },
);
// response.data.freelances : anonymized profiles ranked by relevance
// response.data.infos      : { total, page, limit, totalPages }

`keywords` semantics

Syntax	Effect
`react node`	Implicit AND: both terms must match
`"design system"`	Exact phrase
`-wordpress`	Exclusion
`react OR vue`	OR between groups (uppercase `OR`; lowercase `or` is a normal word)

OR separates groups: each group keeps its implicit AND, exact phrases and exclusions (senior react OR senior vue -wordpress). Limits: at most 10 OR groups per query, no parentheses, and for OR queries the total is capped at 1000 profiles per group.

Filters and referential

Filters are exact matches (no typo tolerance), though case and accent insensitive. An out-of-referential value does not raise an error: it simply matches no profile. Fetch the accepted values from the public POST /referential endpoint:

const { data } = await axios.post('https://client-p.pylote.io/referential', {
  action: 'list:all',
  field: 'Seniority',   // or 'Skills', 'Regions'
});
// -> [{ name: 'Senior 6-10 ans', slug: 'senior_6-10_ans', ... }, ...]

Single rule: send the slug of the referential item, for all three filters:

Filter	Referential table	Field to send	Example
`skills`	`Skills`	`slug`	`react_js`
`workAreas`	`Regions`	`slug`	`ile-de-france`
`seniority`	`Seniority`	`slug`	`senior_6-10_ans`

This is also the format you will see in the skills[].name and seniority fields of the returned profiles. Geography is filtered by mobility areas (regions, countries), not by zip code

radius: map your target areas to our regions.

What a result contains

Each Stage 1 profile contains: id (the Stage 2 key), headline, summary, location (city/region/country/zip), skills, languages, seniority, professions, availability, work preferences, work history (titles, durations and descriptions, without an employer field), and matchRank. All free text (profile and mission summary) is redacted: emails, phone numbers, URLs and the freelancer’s own name are removed. These are texts written by the freelancer: a company name may occasionally appear in the prose. matchRank is the profile’s absolute rank in the relevance ranking (1 = best match). It is a real rank, not a percentage score. What Stage 1 never contains: name, email (even proxied), phone, profile links (resume, LinkedIn), structured employer field.

Stage 2 — Reveal a profile

const response = await axios.post(
  'https://client-p.pylote.io/partners/reveal',
  {
    freelanceId: 'a1b2c3d4-e5f6-7890-abcd-ef1234567890', // id from Stage 1
    recruiterEmail: 'marie.gilles@lutessa.com',           // must be whitelisted
  },
  { headers: { 'x-api-key': API_KEY } },
);
// response.data : full profile in JSON Resume format

Good to know:

recruiterEmail must be in your whitelist. Otherwise: 404. This is what feeds the ” via ” line the freelancer sees in their stats.
The profile_view event is emitted automatically: do not call POST /partners/events for the view itself. Keep it for granular actions (click_cv, click_linkedin, add_favorite…).
Contact goes through the Pylote proxy email and the tracked LinkedIn link of the revealed profile. Phone numbers are not exposed through the partner channel.
An opt_out recruiter cannot reveal a profile (403): a reveal exposes contact details, which requires tracking.

Rate limiting

120 requests/minute per API key, across all routes. Beyond that: 429. One search = one request, whatever the limit.

Getting started

Guides

Reference

Overview

Stage 1 — Search

`keywords` semantics

Filters and referential

What a result contains

Stage 2 — Reveal a profile

Rate limiting

​Overview

​Stage 1 — Search

​keywords semantics

​Filters and referential

​What a result contains

​Stage 2 — Reveal a profile

​Rate limiting

Overview

Stage 1 — Search

`keywords` semantics

Filters and referential

What a result contains

Stage 2 — Reveal a profile

Rate limiting