Skip to main content

1. How it works

The Custom integration lets recruiters export talents from Collective to your ATS, individually or in bulk. Collective sends each profile to an endpoint you host. Your endpoint saves the candidate in your ATS and returns their ATS page URL, which Collective uses to open the candidate. You can also provide a jobs endpoint so recruiters can choose a job to associate with the candidate. Your developer can build these endpoints in your ATS or in a service that connects to its API.

2. Request activation

Collective activates the integration and configures the URLs manually. Contact support@collective.work or your account manager. These settings cannot be edited in the app.
Contact us before getting started, then send the final details when your endpoints are ready:
  • Organization name and recruiter account email.
  • Export URL — required, to receive profiles.
  • Jobs URL — optional, to enable job selection.
  • Bearer token and ATS logo — optional. The same token authenticates requests to both endpoints.
Wait for confirmation that the integration is active. It will appear as Live on your organization’s Integrations page.
Custom integration card showing Status: Live, I need help, and Documentation

The custom integration after activation.

3. Build the export endpoint

Request from Collective

Choose any URL on your service. The host and /collective/talents path below are examples; Collective sends requests to the exact full URL you provide during activation. Use a reachable HTTPS endpoint that accepts POST requests.
Bearer authentication is optional, but recommended. You define a secret token and share it with Collective during activation. Collective sends it in the Authorization header on requests to both endpoints. Your endpoints must check the token and reject requests with a missing or incorrect token, so only callers with your token can access them. If you do not configure a token, Collective omits this header. The request body contains: Example request body:
When a CV is present, decode cv.data from base64 and save it using fileName and contentType. Allow enough request-body capacity for the attachment. cv is null when absent or unavailable.

Save the candidate and return its URL

Create or update the candidate using profile.id as their stable external identifier. If jobId is specified and is a string, you should associate the candidate with that specified job. Once saved, respond within 15 seconds with 200 OK or 201 Created, Content-Type: application/json, and:
Return the candidate’s page URL even if the candidate already exists.
If your endpoint does not return a url, the export will FAIL, even with a 2xx status. Success requires a 2xx status and a valid absolute HTTP(S) url. An empty 204, invalid or relative URL, or unsuccessful status also fails the export. Redirects are not followed. Return the URL within 15 seconds; there is no later callback to complete an export.

4. Optionally enable job selection

Host a second endpoint that accepts GET requests and lists jobs from your ATS. Its URL is also your choice: /collective/jobs below is an example. Ask Collective to configure the full URL.
It uses the same optional bearer token, 15-second timeout, 2xx requirement, and no-redirect behavior as the export endpoint. Return 200 OK with JSON:
  • id: a stable, nonblank string, at most 512 characters. Convert numeric ATS IDs to strings.
  • name: a nonblank display name, at most 1,024 characters.
  • location: an optional location label, such as Paris, France or Remote. Collective trims surrounding whitespace. The result must be nonblank and at most 512 characters.
  • createdAt: an optional ISO 8601 timestamp with a timezone, such as 2026-11-01T10:00:00.000Z or 2026-11-01T11:00:00+01:00. Use the job’s posting date, or its creation date if no posting date is available. A date alone or a timestamp without a timezone is invalid.
You can omit location and createdAt or set either to null. Existing responses with only id and name remain valid. When provided, the location and date appear below the job name in search results and in the selected job card. Return {"jobs": []} when no jobs are available. Any invalid entry rejects the whole list, including a blank or overlong location or an invalid timestamp. Omit unavailable metadata or use null instead of an empty string. Return the complete list to display. Collective loads it when the recruiter focuses Job (optional) and searches it locally, without requesting additional pages or sending search text to your service.
Send to your ATS dialog with the optional job search and available jobs

Recruiters can search for a job before sending a talent.

The selected id becomes the export’s jobId; your export endpoint creates the job association. If no jobs URL is configured, the selector is hidden. An empty or cleared selection sends jobId: null. If jobs fail to load, recruiters can click Try again or export without a job.

5. Export talents

One talent

  1. Click the talent’s ATS button to open Send to your ATS.
  2. Optionally choose a job, then click Send.
  3. On success, Collective opens the returned ATS page. Future clicks on the ATS button open that saved page.

Several talents

Select talents, click Export, choose ATS as the export type, and optionally select a job. Collective sends one request per talent, with the same selected jobId for the entire export. You can also use this flow to send an already exported talent to another job.
Export profiles dialog with ATS selected, three profiles, and Product Designer as the job

Bulk export with an optional job selected.

Bulk exports run in the background. In Export history, hover over the status for success, failure, and pending counts; refresh or reopen the page for updates. Complete means processing has finished, even if some exports failed.

6. Timeouts and retries

The 15-second limit applies to each request to your endpoints, not the whole export operation: Collective prepares the profile and CV before sending it. A timeout or lost response can happen after your ATS has saved the candidate. Make repeated requests safe, including simultaneous deliveries:
  • Deduplicate candidates by profile.id and return the existing candidate URL.
  • Deduplicate job associations by (profile.id, jobId), while allowing the same candidate to be associated with another job.
For 429, set Retry-After to positive seconds (for example, 30) or a future HTTP date. Missing or unusable values fall back to 15 seconds. Bulk retries keep the selected jobId; rate-limit delays and repeated exports can cause more than five deliveries. Before going live, test exports with and without a job or CV, repeated requests, a timeout, an invalid response, unavailable jobs, and bulk retries. Confirm that candidates and job associations are saved correctly without duplicates.