> ## Documentation Index
> Fetch the complete documentation index at: https://docs.collective.work/llms.txt
> Use this file to discover all available pages before exploring further.

# Export talents to your ATS

> Connect your ATS to receive talent profiles from Collective, with optional job selection

## 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

> [!NOTE]
>
> **Collective activates the integration and configures the URLs manually.** Contact
> [support@collective.work](mailto: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](https://mintcdn.com/collective/F0fOZzeVFdKu6Whm/images/ats-custom-integration.png?fit=max\&auto=format\&n=F0fOZzeVFdKu6Whm\&q=85\&s=bb22c0c033cbb5557894085f263adb8c)

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.

```http theme={null}
POST /collective/talents HTTP/1.1
Host: integration.example.com
Content-Type: application/json
Authorization: Bearer YOUR_SHARED_TOKEN
```

**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:

| Field | Meaning |
| - | - |
| `profile` | The complete talent profile, with exactly the same structure as the **[Get Profile response](https://docs.collective.work/api-reference/endpoint/profile/get.md)**. Use that reference for all fields and types. |
| `jobId` | The selected job ID from your jobs endpoint, or **`null`** when none is selected. This field is always present. |

Example request body:

```json theme={null}
{
  "profile": {
    "id": "cm71yqftr00000ck0bpz3hpg1",
    "firstname": "Jane",
    "lastname": "Doe",
    "pictureUrl": "https://images.example.com/jane-doe.jpg",
    "linkedinUrl": "https://www.linkedin.com/in/jane-doe",
    "collectiveUrl": "https://app.collective.work/recruiter/search?profileId=cm71yqftr00000ck0bpz3hpg1",
    "title": "Senior Frontend Engineer",
    "dailyRate": 650,
    "yearlySalaryMin": null,
    "yearlySalaryMax": null,
    "availability": "AVAILABLE",
    "workPreference": "REMOTE_ONLY",
    "desiredContractType": "FREELANCER",
    "location": {
      "googleMapsPlaceId": null,
      "country": "France",
      "countryCode": "FR",
      "label": "Paris, France",
      "shortLabel": "Paris",
      "latitude": 48.8566,
      "longitude": 2.3522
    },
    "mobilities": [
      {
        "googleMapsPlaceId": null,
        "country": "France",
        "countryCode": "FR",
        "label": "Lyon, France",
        "shortLabel": "Lyon",
        "latitude": 45.764,
        "longitude": 4.8357
      }
    ],
    "skills": ["TypeScript", "React", "GraphQL"],
    "featuredSkills": ["React"],
    "workExperiences": [
      {
        "title": "Frontend Engineer",
        "company": "Example Company",
        "companyLogoUrl": "https://images.example.com/company-logo.png",
        "startDate": "2022-01-01T00:00:00.000Z",
        "endDate": null,
        "description": "Built and maintained web applications.",
        "location": {
          "googleMapsPlaceId": null,
          "country": null,
          "countryCode": null,
          "label": "Paris, France",
          "shortLabel": null,
          "latitude": null,
          "longitude": null
        }
      }
    ],
    "intro": "Frontend engineer specialising in design systems.",
    "educations": [
      {
        "school": "Example University",
        "degreeName": "MSc Computer Science",
        "field": "Computer Science",
        "description": "Specialised in software engineering.",
        "startDate": "2014-09-01T00:00:00.000Z",
        "endDate": "2017-06-30T00:00:00.000Z"
      }
    ],
    "languages": [{ "language": "English" }],
    "certifications": [
      {
        "name": "AWS Certified Solutions Architect",
        "companyName": "Amazon Web Services",
        "issueDate": "2022-03-01T00:00:00.000Z"
      }
    ],
    "links": [{ "name": "Portfolio", "url": "https://portfolio.example.com/jane" }],
    "emails": [{ "email": "jane.doe@example.com" }],
    "phones": [
      { "phoneNumber": "+33612345678", "whatsappValidity": "UNKNOWN" }
    ],
    "cv": {
      "fileName": "resume.pdf",
      "contentType": "application/pdf",
      "data": "<base64-encoded file contents>"
    }
  },
  "jobId": "job-123"
}
```

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:

```json theme={null}
{
  "url": "https://ats.example.com/candidates/123"
}
```

Return the candidate's page URL even if the candidate already exists.

> [!WARNING]
>
> **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.

```http theme={null}
GET /collective/jobs HTTP/1.1
Host: integration.example.com
Content-Type: application/json
Authorization: Bearer YOUR_SHARED_TOKEN
```

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:

```json theme={null}
{
  "jobs": [
    {
      "id": "job-123",
      "name": "Développeur frontend React",
      "location": "Paris, France",
      "createdAt": "2026-11-01T10:00:00.000Z"
    },
    { "id": "job-456", "name": "Product Designer" }
  ]
}
```

* **`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](https://mintcdn.com/collective/F0fOZzeVFdKu6Whm/images/ats-export-job-selection.png?fit=max\&auto=format\&n=F0fOZzeVFdKu6Whm\&q=85\&s=90baef59fcbf3301ee6311e1466232fd)

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](https://mintcdn.com/collective/F0fOZzeVFdKu6Whm/images/ats-bulk-export.png?fit=max\&auto=format\&n=F0fOZzeVFdKu6Whm\&q=85\&s=2afc243e7c922d0b5ec677ec93113c1b)

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.

| Operation | Retry behavior |
| - | - |
| Single export or loading jobs | Manual retry. If jobs cannot be loaded, exporting without a job remains possible. |
| Bulk export: ordinary failures | **Five total attempts** per talent: the initial request and four retries after **5, 10, 20, and 40 seconds**. |
| Bulk export: HTTP `429` | Delayed according to `Retry-After`, without consuming the ordinary retry budget. |

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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.