# Export the records behind a placement (/workflows/agency-export)

Alex wants to see how Sam’s placement fits into the rest of your desk. You can export the jobs and the people who applied, then join the records in your reporting tool. The interview stays attached to Sam’s application for Alex’s job, even if Sam interviewed somewhere else that week.

## 1. Read the records [#1-read-the-records]

Download the [Python exporter](/examples/agency-export.py) and the [GraphQL queries](/examples/agency-export.graphql) into the same directory. Set `KITH_ATS_API_KEY` to your workspace key. This command writes one JSON record per line and moves the completed file into place when all the pages have arrived. [Get a workspace key](/api#authentication)

```sh
python3 agency-export.py https://api.authin.ai/api/graphql > agency.jsonl.part && mv agency.jsonl.part agency.jsonl
```

The script pages through team members, companies, contacts, candidates, jobs, applications and notes. For each job, candidate, application and interview it also follows the relevant document or history pages. A workspace with a long interview history can have several pages for one appointment. Every list has its own cursor. [Read interview changes](/api/reference/objects/interview#changes)

## 2. Join Sam to the right job [#2-join-sam-to-the-right-job]

Find Sam’s `application` row. Its `record.candidate.id` points to the candidate, and `record.job.id` points to the job. The job’s `client.id` takes you to Alex’s company. An interview row names the application in `parent.id`. Its changes in turn name that interview. Use the record type with its ID when joining. A candidate and a job can have the same numeric ID.

The application carries the current offer salary, fee and currency. Money stays in decimal strings, an acceptance or start day stays a calendar date, and interview times keep their UTC timestamps. [Add up placement fees](/workflows/placement-fees)

To check the export, count application IDs by job and stage, then compare each count with that job’s `pipelineSummary.stages`. The API applies the workspace’s visibility rules to both. Each page reads the data available at the time of the request. If the desk changes a stage while the export runs, a fresh run after the edit gives you a new comparison. [Read the job’s pipeline summary](/api/reference/objects/job#pipeline-summary)

### Catch up after a missed stage change [#catch-up-after-a-missed-stage-change]

Suppose your dashboard still shows Sam at interview after Alex has hired them. Run the download’s `StageHistory` query with Alex’s job ID, starting with `after: null`. It returns the newest entries first. While `hasNextPage` is true, pass `endCursor` to the next call. Match entries to Sam by `jobCandidate.id`. [Read the job’s history](/api/reference/objects/job#audit-trail)

Save each entry under its workspace, job and entry ID so a second pass can fill a gap without counting the same move twice. Read Sam’s application again for the stage to display now. You can do this on a schedule or when your integration receives a `candidate.stage.changed` notification. [Read the current application](/api/reference/queries/job-candidate)

## 3. Get a file when you need it [#3-get-a-file-when-you-need-it]

A document row carries its ID, filename and parent. To get a CV, request its `downloadPath` on the API host with your workspace credentials. Read the redirect and fetch its signed URL without the workspace key. For a job brief, read the job’s documents again and ask for `downloadUrl` when you need the file. That URL lasts two minutes. The export keeps the document reference so you can fetch a fresh link later. [Candidate files](/api/reference/objects/candidate-document#download-path) · [Job files](/api/reference/objects/job-document#download-url)

## Bring candidates in from another system [#bring-candidates-in-from-another-system]

To bring a list of people into the workspace, call `addCandidates` with up to 200 per request. Send a stable LinkedIn URL or email for each person. If you repeat a matched entry, the API returns its existing ID and `wasCreated: false`. A name alone doesn’t identify someone reliably. Use the returned candidate IDs with `addCandidatesToJob` to create applications on the right opening. [Add candidates](/api/reference/mutations/add-candidates) · [Add them to a job](/api/reference/mutations/add-candidates-to-job)

```graphql
mutation ImportCandidates($people: [NewCandidateInput!]!) {
  addCandidates(input: { candidates: $people }) {
    results { wasCreated candidate { id name } }
  }
}
```

For Sam, the variables would be `{"people":[{"name":"Sam Lindqvist","email":"sam@example.com"}]}`. Keep the returned ID alongside your source record when you import the next batch.