{"openapi":"3.1.0","info":{"title":"Atlas API","version":"1.0.0","description":"## Introduction\n\nWelcome to the Atlas API. If you've never worked with an API before, don't worry - this page explains everything from scratch.\n\n### What is an API?\n\nAn API is a way for two different pieces of software to talk to each other. While we use the phone, emails or perhaps meet in person, software doesn't have that luxury (yet). Each software also speaks a completely different lanuage. So an API helps two pieces of software exchange datae in a common language\n\nHere's an analogy: imagine Atlas is a filing cabinet full of your recruitment data. Normally, you open the app, log in, and interact with that filing cabinet yourself - clicking through screens to find candidates, update projects, or pull reports. An API is like giving someone else (another piece of software) a set of keys and a rulebook, so they can access that same filing cabinet automatically, without a human needing to be involved.\n\nFor example:\n- When a candidate applies through your website, their details can be automatically added to Atlas as a new person record - no manual data entry needed.\n- A client portal you build could pull live project updates straight from Atlas, so clients always see the latest shortlist without you sending a single email.\n- If you use a job board or LinkedIn integration, candidate profiles can flow directly into Atlas the moment they express interest.\n\n### How does it work?\n\nEvery action in the API is called a **request**. A request is simply your software asking Atlas to do something - like \"give me a list of all candidates\" or \"create a new person record\".\n\nAtlas then sends back a **response** - the answer to that request. If you asked for a list of candidates, the response would contain that list of candidates and all their details, formatted in a way that software can easily read and process.\n\nRequests are sent to specific web addresses called **endpoints**. Each endpoint does one specific thing. This reference documents every endpoint available - what it does, what information you need to send along with your request, and exactly what the response will look like.\n\n> [!tip]\n> New to all of this? Watch our [quick walkthrough video](https://www.loom.com/share/7c71869c03274499a2a24c8cd422c32c) for a guided introduction before diving in.\n\n### Do I need to be a developer to use this?\n\nNot necessarily. There are several ways to build with an API today, depending on your comfort level:\n\n- **No-code tools** like Zapier or Make let you connect Atlas to other apps with a visual, drag-and-drop interface - no coding required.\n- **AI-assisted coding tools** like [Cursor](https://www.cursor.com), [Lovable](https://lovable.dev), or vibe coding tools mean you can describe what you want in plain English and have working code generated for you. Many non-developers are building real integrations this way.\n- **Traditional development** - if you have a developer on your team or work with an agency, hand them this reference and they'll know exactly what to build.\n\nHowever you approach it, this reference is written so that anyone can read through it, understand what's possible, and communicate it clearly to whoever is doing the building.\n\n## Authentication\n\nBefore the API will respond to any request, it needs to know who you are. This is done using an **API key** - a long string of characters that acts like a password, uniquely identifying your agency.\n\n### Getting your API key\n\nAPI keys are generated from the Atlas dashboard. Go to **Settings → Integrations → API Keys** and create a new key. Give it a name so you remember what it's for (e.g. \"Website integration\" or \"Zapier connection\").\n\n> [!warning]\n> Treat your API key like a password. Don't share it publicly, don't put it in a place others can see it, and don't commit it to a code repository. If a key is ever compromised, you can revoke it from the dashboard and generate a new one.\n\n### Using your API key\n\nEvery request you make to the API must include your key in the request headers. A **header** is just a piece of extra information sent alongside your request - think of it like writing your name on the outside of an envelope before sending it.\n\nThe header you need to include looks like this:\n\n```\nAuthorization: Bearer \n```\n\nReplace `` with the actual key you generated. For example, if your key was `abc123`, you would send:\n\n```\nAuthorization: Bearer abc123\n```\n\nDon't forget to add Bearer in front. If you're using a no-code tool like Zapier or Make, there will be a field where you paste your API key - you won't need to write this header yourself. If you're using an AI coding tool or working with a developer, share the key with them securely and they'll handle this for you.\n\n## Rate limits\n\nTo keep the platform fast for everyone, the API limits how many requests each agency can make per minute. Limits are counted per agency and per **tier** — reads, writes, and uploads each have an independent counter, so a burst of reads never eats into your write budget:\n\n| Tier | Applies to | Default limit |\n| --- | --- | --- |\n| `read` | All `GET` endpoints | 1200 requests / 60s |\n| `write` | `POST` / `PUT` / `PATCH` / `DELETE` endpoints | 400 requests / 60s |\n| `upload` | File uploads | 60 requests / 60s |\n\nPublic Jobs Portal endpoints (which need no API key) are limited per IP address using the same defaults. Higher limits can be arranged per agency — contact support if you need more.\n\n### Rate limit headers\n\n**Every** response — not just rejected ones — includes headers telling you where you stand:\n\n| Header | Meaning |\n| --- | --- |\n| `RateLimit-Limit` | Your quota for the current window on this endpoint's tier |\n| `RateLimit-Policy` | The quota policy as `;w=`, e.g. `1200;w=60` |\n| `RateLimit-Remaining` | Requests you have left in the current window |\n| `RateLimit-Reset` | Seconds until the window resets (a delta in seconds, not a Unix timestamp) |\n\n### What happens when you hit the limit\n\nOnce the quota is used up, further requests are rejected with **HTTP 429** and a JSON body:\n\n```json\n{\n \"status\": \"error\",\n \"error\": \"Rate limit exceeded\",\n \"tier\": \"read\",\n \"retryAfterSec\": 60\n}\n```\n\nWait `retryAfterSec` seconds (equivalently, the `RateLimit-Reset` header) before retrying. A `Retry-After` header may also be present on 429 responses, but it is not guaranteed — prefer `RateLimit-Reset` or `retryAfterSec`. If you are building a high-volume sync, watch `RateLimit-Remaining` and slow down before it reaches zero rather than retrying on 429s.\n\n## Company contacts and prospects\n\nA **company contact** is a person linked to a company in a business-development context. A **prospect** is a company contact attached to an opportunity. People can exist on their own, but to attach a person to an opportunity as a prospect they must first have a current company. This guide walks through the full sequence.\n\n### Step 1 - create the company\n\n`POST /api/v1/companies` with a `name` **and at least one of `websiteUrl` or `linkedinUrl`** - a name alone is rejected with **422**, because a company without a website or LinkedIn identity cannot be found again through the `GET /api/v1/companies` lookup. Keep the returned `data.id` - you will link the person to it in the next step.\n\nIf you don't have a website or LinkedIn URL for the company, skip this step and pass `headline.company` (the name) in step 2 instead - Atlas resolves it to an existing company by name, or creates one when none matches.\n\n### Step 2 - create the person as a company contact\n\n`POST /api/v1/people` with:\n\n- `isContact: true` - marks the person as a company contact.\n- `headline.companyId` - the company ID from step 1. This links the contact to that exact company; no new company is created and no name matching happens.\n- `identities` - at least one non-website contact detail (email, phone, or LinkedIn), as on any person create.\n\n```json\n{\n \"addedByEmail\": \"consultant@your-agency.com\",\n \"isContact\": true,\n \"headline\": { \"role\": \"Head of Engineering\", \"companyId\": \"\" },\n \"identities\": [{ \"type\": \"email\", \"value\": \"jane@example.com\" }]\n}\n```\n\nIf you only know the company by name, pass `headline.company` (the name) instead of `headline.companyId` - Atlas resolves it to an existing company by name, or creates one when none matches. Prefer `headline.companyId` whenever you created or looked up the company yourself, as name matching can create duplicate stub companies.\n\nThe company-contact link is created **synchronously**: the 201 response reports `queued.companyContact: 1` and the link is already present on an immediate read - there is no need to wait or poll before step 3.\n\nIf the create returns **409 Conflict**, the person already exists; take the returned `personId` and `PATCH /api/v1/people/{id}` with the same `headline` fields to link them, then continue. Note that `isContact` is not accepted on PATCH - if sent, it is silently ignored and no company-contact link is created. A headline company link is enough: step 3 accepts any prospect with one, and attaching the prospect creates the company-contact link itself.\n\n### Step 3 - create the opportunity with the person as prospect\n\n`POST /api/v1/opportunities` with `prospectIds: [\"\"]` (plus the opportunity's own required fields).\n\nEvery person in `prospectIds` must have a current company - a headline company link or an existing company-contact link. A person without one makes the request fail with **422** and a message listing the offending person IDs. To recover, `PATCH /api/v1/people/{id}` with `headline.companyId` (or `headline.company`) for each listed person, then retry the opportunity create - the fix is effective immediately.\n\n### Contact ID types\n\nThree different IDs relate a person to other records. They are all UUIDs, so they look identical — but they are not interchangeable:\n\n| ID | Where you get it | Where you use it |\n| --- | --- | --- |\n| **Person ID** | `id` on GET `/api/v1/people`; `personId` on other resources | Person endpoints; `prospectIds` on opportunity create/update |\n| **CompanyContact junction ID** (the person↔company link) | `companyContact.id` on GET `/api/v1/people/{id}` | `companyContactIds` on POST/PATCH `/api/v1/projects` |\n| **Opportunity-person row ID** (the person↔opportunity link) | `prospects[].id` (and its alias `contactId`) on opportunity endpoints | Identifying that prospect link only — never accepted as a person ID or `companyContactIds` value |\n\nPassing the wrong type returns a 404, since no record with that ID exists in the expected table.","x-logo":{"url":"https://berg-atlas-public.s3.eu-west-1.amazonaws.com/atlas/logo.png","altText":"Atlas"}},"servers":[{"url":"/"}],"tags":[{"name":"Companies","description":"Endpoints for retrieving company data within your agency."},{"name":"Contacts","description":"Endpoints for listing company contacts (the link between a person and a company) within your agency."},{"name":"People","description":"Endpoints for managing people and their data within your agency."},{"name":"Projects","description":"Endpoints for listing and filtering projects within your agency."},{"name":"Candidates","description":"Endpoints for listing candidates across all projects within your agency. A candidate is a person at a specific status within a project pipeline."},{"name":"Jobs Portal","description":"Public endpoints for powering career pages and job boards. These endpoints do not require authentication and only return projects marked as public. Each project includes the `owner` (the lead consultant on the role) with their name and email so contact details can be shown on external job pages."},{"name":"Users","description":"Endpoints for listing users within your agency."},{"name":"Opportunities","description":"Endpoints for creating and managing opportunities within your agency."},{"name":"Prospects","description":"Endpoints for listing prospects — people attached to opportunities — as a flat, agency-wide list. Includes prospects created by the Spec CV / float workflow (surfaced via `opportunityType=speculative`)."},{"name":"Opportunity stage events","description":"A keyset-paginated feed of opportunity (business-development) stage transitions for incremental sync. This is distinct from Candidate stage events: it tracks opportunity/BD pipeline moves, not candidate/job pipeline moves."},{"name":"Campaigns","description":"Outreach campaigns are multi-step sequences (email, LinkedIn InMail/request, phone call, to-do) sent to a person on behalf of a recruiter.\n\nThere are two resources. An **outreach campaign** is a reusable *template* — a named sequence of steps tied to one project or opportunity — created with `POST /api/v1/campaigns`. **Launching** a template at a specific person with `POST /api/v1/campaigns/{id}/launch` creates that person's individual campaign, with every variable resolved and the first step scheduled.\n\n### Variables\n\nA step's `subject` and `body` may contain `{{variable}}` placeholders. There are three families:\n\n- **Static** (e.g. `{{person_first_name}}`, `{{client_name}}`, `{{job_role}}`) — resolved automatically from the person and the campaign's project/opportunity when you launch. You may override any of them per-launch. If a static placeholder resolves to empty and you did not override it, the launch is rejected.\n- **Time-sensitive** (`{{today}}`, `{{tomorrow}}`, `{{one_working_day}}`, …) and **step-sensitive** (`{{previous_step_day}}`) — resolved automatically at the moment each step is sent, so dates stay accurate. These cannot be overridden.\n- **AI** (`{{ai:}}`) — a natural-language instruction you resolve yourself. The create and get-by-id responses list every distinct AI prompt under `aiVariables` as an array of `{ \"name\": \"\", \"value\": null }`. Supply a value for each at launch by echoing the same array with values filled — `aiVariables: [{ \"name\": \"\", \"value\": \"…\" }]` — matched by `name`.\n\n`{{manual:...}}` placeholders exist only in the in-app campaign editor and are **not supported over the API** — a template containing one is rejected on create (422) and cannot be launched.\n\n| Variable | Family | Resolved from | Overridable |\n| --- | --- | --- | --- |\n| `person_first_name` | static | Person's first name | yes |\n| `person_last_name` | static | Person's last name | yes |\n| `current_company` | static | Person's current employer | yes |\n| `client_name` | static | The project's company name | yes |\n| `job_role` | static | The project's job role | yes |\n| `job_link` | static | Public link to the project (the project must be public) | yes |\n| `target_company` | static | Person's company contact (business-development context) | yes |\n| `today` / `tomorrow` / `yesterday` | time-sensitive | The send date, as a weekday | no |\n| `time_of_day` | time-sensitive | `morning` / `afternoon` at send time | no |\n| `one_working_day` / `two_working_days` | time-sensitive | Working days after the send date | no |\n| `previous_step_day` | step-sensitive | Weekday the previous step completed | no |\n| `ai:` | ai | You resolve it; supply at launch via `aiVariables` | required |\n\n### Duplicate rules\n\nLaunching returns **409 Conflict** when the person already has a clashing campaign. What counts as clashing depends on the campaign type:\n\n- **candidate_outreach** (project-linked): a person can have at most one active campaign on the project — any active campaign blocks a new launch, even from a different template. A completed campaign from the same template also blocks relaunching that template.\n- **prospect_outreach** (opportunity-linked): multiple concurrent campaigns are allowed for the same person on the same opportunity — only relaunching a template that is still active for them returns 409.\n- **speculative** (opportunity-linked): scoped to the launched person, like the other types — a person can have at most one active campaign per speculative opportunity. Relaunching the same active template is blocked (as for prospect_outreach), and so is launching a different template from the same speculative opportunity for that person (all its templates share the speculative person). Campaigns launched for other people never block: the same speculative person can be pitched to any number of people concurrently.\n\nDraft campaigns never block; \"active\" covers the active and ready statuses.\n\n### Example flow\n\n1. **Create a template** — `POST /api/v1/campaigns` with a step body like `Hi {{person_first_name}}, {{ai:write a one-line hook about their experience}}`.\n2. **Read back the AI prompts** — the create response (and `GET /api/v1/campaigns/{id}`) lists each step’s distinct prompts as `aiVariables: [{ \"name\": \"write a one-line hook about their experience\", \"value\": null }]`.\n3. **Resolve each prompt yourself** with your own AI — person context from `GET /api/v1/people/{personId}`, job context from the project/opportunity — producing a value for that prompt `name`.\n4. **Launch** — `POST /api/v1/campaigns/{id}/launch` with `{ \"personId\": \"…\", \"aiVariables\": [{ \"name\": \"write a one-line hook about their experience\", \"value\": \"ex-Stripe engineer who scaled payments to 1M TPS\" }] }`. The response returns each step with every variable resolved."},{"name":"Interviews","description":"Endpoints for retrieving interviews and their participants within your agency."},{"name":"Meetings","description":"Endpoints for listing meetings (both general meetings and interviews) and their participants within your agency."},{"name":"Emails","description":"Endpoints for listing email activity within your agency. Each row links an email to a person and carries metadata plus a snippet (not the full body). Private and hidden emails are excluded."},{"name":"Files","description":"Endpoints for uploading files to your agency."},{"name":"Placements","description":"Endpoints for retrieving placements (hires) and their fees within your agency."},{"name":"Fees","description":"Endpoints for retrieving project fees and their splits."},{"name":"Contracts","description":"Endpoints for retrieving contracts — ongoing contractor engagements with their rates, contacts, and fee attributions."},{"name":"Tasks","description":"Endpoints for listing, creating and updating tasks — actionable items assigned to a user, optionally linked to a person or company."},{"name":"Custom Attributes","description":"Endpoints for discovering custom attribute definitions (the schema) configured for each entity type — person, company, project, user, candidate, meeting. Use these to find which custom fields exist and what values are valid before reading or writing attribute data."},{"name":"Webhooks","description":"Atlas can send real-time notifications to your system when events happen — for example, when a person is created, a candidate moves stage, or a placement is recorded. These are called **webhooks**.\n\nWebhooks are delivered via [Svix](https://www.svix.com). To start receiving webhooks, go to **Settings → Integrations → Webhooks** in your Atlas dashboard and add an endpoint URL.\n\nEach webhook is an HTTP POST request to your endpoint with a JSON body containing:\n- `event` — the event type (e.g. `person.created`)\n- `occurredAt` — ISO 8601 timestamp\n- `data` — the event payload\n\nReturn any 2xx status code to acknowledge receipt. If delivery fails, Svix will retry automatically with exponential backoff."}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT"}},"headers":{"RateLimitLimit":{"description":"Request quota for the current window on the tier this endpoint counts against (default per minute: 1200 read / 400 write / 60 upload). Agencies with a negotiated override see their own limit here.","schema":{"type":"integer","example":1200}},"RateLimitPolicy":{"description":"Quota policy for the tier in `;w=` form, e.g. `1200;w=60`.","schema":{"type":"string","example":"1200;w=60"}},"RateLimitRemaining":{"description":"Number of requests remaining in the current window. `0` means the next request will be rejected with a 429.","schema":{"type":"integer","example":1199}},"RateLimitReset":{"description":"Number of seconds until the current window resets and the quota is restored. This is a delta in seconds, not a Unix timestamp.","schema":{"type":"integer","example":60}},"RetryAfter":{"description":"Number of seconds to wait before retrying. This header is not guaranteed to be present on 429 responses — rely on `RateLimit-Reset` or the `retryAfterSec` field in the JSON body instead.","schema":{"type":"integer","example":60}}},"schemas":{"UpdateCompanyPayload":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":500,"description":"Company name (max 500 characters)","example":"Acme Corp"},"relationship":{"type":"string","enum":["client","target","none"],"description":"Company relationship","example":"client"},"type":{"type":["string","null"],"enum":["educational","government","nonprofit","private","public"],"description":"Company type. Send null to clear."},"size":{"type":["string","null"],"enum":["1-10","11-50","51-200","201-500","501-1000","1001-5000","5001-10000","10001+"],"description":"Company size bucket. Send null to clear.","example":"51-200"},"summary":{"type":["string","null"],"minLength":1,"maxLength":255,"description":"Short company summary. Empty strings are rejected — omit or send null to clear.","example":"B2B SaaS"},"overview":{"type":["string","null"],"minLength":1,"maxLength":16384,"description":"Long-form company description. Empty strings are rejected — omit or send null to clear."},"industry":{"type":["array","null"],"items":{"type":"string","minLength":1,"maxLength":80},"maxItems":100,"description":"Industry labels (overwrites the existing set). Each label must be a known industry from the Atlas industry dictionary — matched case-insensitively and stored in the dictionary’s canonical casing; unknown labels return 422. Duplicates are silently dropped. Send null (or []) to clear.","example":["Software"]},"employeeCount":{"type":["integer","null"],"minimum":1,"maximum":10000000,"description":"Number of employees (precise, integer). Send null to clear.","example":150},"ticker":{"type":["string","null"],"minLength":1,"maxLength":255,"description":"Stock ticker symbol. Empty strings are rejected — omit or send null to clear.","example":"AAPL"},"location":{"type":["object","null"],"properties":{"name":{"type":["string","null"],"minLength":1,"maxLength":255,"description":"Display name / formatted address (e.g. \"London, UK\")","example":"London, UK"},"locality":{"type":["string","null"],"minLength":1,"maxLength":255,"description":"City name","example":"London"},"region":{"type":["string","null"],"minLength":1,"maxLength":255,"description":"State or region","example":"England"},"metro":{"type":["string","null"],"minLength":1,"maxLength":255,"description":"Metro area (People Data Labs convention, e.g. \"new york, new york\")","example":"new york, new york"},"country":{"type":["string","null"],"minLength":1,"maxLength":255,"description":"Country name","example":"United Kingdom"},"streetAddress":{"type":["string","null"],"minLength":1,"maxLength":255,"description":"Street address line 1","example":"123 Baker Street"},"addressLine2":{"type":["string","null"],"minLength":1,"maxLength":255,"description":"Street address line 2 (apartment, suite, unit, etc.)","example":"Suite 200"},"postalCode":{"type":["string","null"],"minLength":1,"maxLength":255,"description":"Postal / ZIP code","example":"NW1 6XE"},"raw":{"type":["string","null"],"minLength":1,"maxLength":255,"description":"Raw unstructured address text (used for geocoding)","example":"123 Baker Street, London NW1 6XE, United Kingdom"},"latitude":{"type":["number","null"],"minimum":-90,"maximum":90,"description":"Latitude coordinate (-90..90)","example":51.523767},"longitude":{"type":["number","null"],"minimum":-180,"maximum":180,"description":"Longitude coordinate (-180..180)","example":-0.158519}},"description":"Company primary location (overwrites the entire location). Send null to clear."},"identities":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["linkedin","phone","website","aboutme","angellist","behance","crunchbase","dribbble","ello","facebook","flickr","foursquare","github","gitlab","google","gravatar","indeed","instagram","klout","meetup","myspace","pinterest","quora","reddit","soundcloud","stackoverflow","twitter","vimeo","wordpress","xing","youtube","medium","scholar","other"],"description":"Identity type. Any value except `email` (companies have no email identities).","example":"linkedin"},"value":{"type":"string","minLength":1,"maxLength":2048,"description":"Identity value (URL, handle, etc.). URL-like values are normalised before storage (protocol and `www.` stripped, lower-cased), matching how identities are stored on create.","example":"https://linkedin.com/company/acme"},"primary":{"type":"boolean","description":"Whether this is the primary identity of its type. Defaults to false.","example":true}},"required":["type","value"]},"maxItems":100,"description":"Replace-all: when provided, the company’s existing identities are removed and this set inserted. Omit to leave identities unchanged. An identity value already owned by another company in the agency returns 409.","example":[{"type":"linkedin","value":"https://linkedin.com/company/acme","primary":true}]},"customAttributes":{"type":"array","items":{"type":"object","properties":{"customAttributeId":{"type":"string","format":"uuid","description":"Custom attribute definition ID — must belong to the agency at the correct scope."},"optionId":{"type":["string","null"],"format":"uuid","description":"Required for `options`-type attributes — set to the chosen option's UUID. Mutually exclusive with `value`. For multi-select (`multipleValues: true`), repeat the entry once per chosen optionId."},"value":{"anyOf":[{"type":"string","minLength":1,"maxLength":16384},{"type":"number"},{"type":"null"}],"description":"Attribute value. Shape depends on the attribute `type`:\n- `text_line` / `text_block`: non-empty string (trimmed, max 16384 chars).\n- `integer` / `number_input`: JSON number, integer only, must fit Postgres int32 (-2147483648..2147483647).\n- `date`: string `YYYY-MM-DD`, calendar-validated.\n- `options`: do not send `value` — use `optionId` instead.\nMutually exclusive with `optionId`. Sending neither is rejected (422).","example":"Some text value"}},"required":["customAttributeId"],"description":"Custom attribute value"},"maxItems":100,"description":"Custom attribute values to set. Replace-per-attribute: for each customAttributeId present, the company’s existing values for that attribute are removed and these inserted. Attributes not listed are untouched. Same entry shape as POST /companies.","example":[{"customAttributeId":"550e8400-e29b-41d4-a716-446655440000","value":"Tier 1"},{"customAttributeId":"f47ac10b-58cc-4372-a567-0e02b2c3d479","optionId":"9b2e4d6a-1c3f-4a8b-9e7d-2f1a6c5b4d3e"}]},"ownerEmail":{"type":"string","maxLength":255,"format":"email","description":"Email of the Atlas user the update is attributed to (acting user). Optional — must match a user in the agency when supplied, otherwise 404.","example":"recruiter@agency.com"}},"description":"Partial update of a company"},"CreatePersonPayload":{"type":"object","properties":{"firstName":{"type":["string","null"],"minLength":1,"maxLength":80,"description":"First name","example":"Michael"},"lastName":{"type":["string","null"],"minLength":1,"maxLength":80,"description":"Last name","example":"Scott"},"isContact":{"type":"boolean","default":false,"description":"If true, creates a company contact","example":false},"gender":{"type":"string","enum":["male","female"],"description":"Gender","example":"male"},"addedByEmail":{"type":"string","maxLength":255,"format":"email","description":"Email of the user adding this person","example":"jordan@recruitwithatlas.com"},"source":{"type":"object","properties":{"system":{"type":"string","minLength":1,"maxLength":255,"description":"Source system name (sets people.sourced)","example":"api"},"externalId":{"type":["string","null"],"minLength":1,"maxLength":255,"description":"External ID from the source system. Unique per person within the agency: a (system, externalId) pair identifies at most one person and is the highest-priority conflict check on POST /api/v1/people. Supplying an externalId already stored on another person returns 409 (on POST and PATCH) with that person's id.","example":"124456"}},"required":["system"],"description":"Source system and external ID (defaults to api). The (system, externalId) pair is unique per person within the agency — supplying one that already belongs to a person returns 409."},"identities":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["email","phone","linkedin","linkedin_salesnav","linkedin_recruiter","website"],"description":"Identity type","example":"email"},"value":{"type":"string","minLength":1,"maxLength":255,"description":"Identity value","example":"mscott@gmail.com"},"isPersonal":{"type":"boolean","description":"Whether this is a personal identity","example":true},"isPrimary":{"type":"boolean","description":"Whether this is the primary/favourite identity","example":true}},"required":["type","value"]},"minItems":1,"maxItems":20,"description":"Person identities (at least one non-website identity required, max 20)"},"headline":{"type":"object","properties":{"role":{"type":["string","null"],"minLength":1,"maxLength":255,"description":"Current role/job title","example":"Regional Manager"},"company":{"type":["string","null"],"minLength":1,"maxLength":255,"description":"Current company name. Resolved to an existing company by name (or a new one is created when none matches) and linked to the person, unless `companyId` is also provided (which takes precedence) or explicitly set to null (which stores the name as text only, without a company link).","example":"Dunder Mifflin"},"companyId":{"type":["string","null"],"format":"uuid","description":"Atlas company ID to link this headline/contact to an existing company. When provided, no new company is created and name matching is skipped. Takes precedence over `company`: the stored company name is set to the linked company’s name, overwriting a contradictory `company` value. On PATCH, an existing company-contact link is re-pointed to this company; as when changing the contact’s company in the app, this detaches the contact from projects linked under the old company.","example":"550e8400-e29b-41d4-a716-446655440000"},"roleStartedAt":{"type":["string","null"],"pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"When the current role started (YYYY-MM-DD)","example":"2023-04-01"}},"description":"Current headline information"},"location":{"type":["object","null"],"properties":{"name":{"type":["string","null"],"minLength":1,"maxLength":255,"description":"Display name / formatted address (e.g. \"London, UK\")","example":"London, UK"},"locality":{"type":["string","null"],"minLength":1,"maxLength":255,"description":"City name","example":"London"},"region":{"type":["string","null"],"minLength":1,"maxLength":255,"description":"State or region","example":"England"},"metro":{"type":["string","null"],"minLength":1,"maxLength":255,"description":"Metro area (People Data Labs convention, e.g. \"new york, new york\")","example":"new york, new york"},"country":{"type":["string","null"],"minLength":1,"maxLength":255,"description":"Country name","example":"United Kingdom"},"streetAddress":{"type":["string","null"],"minLength":1,"maxLength":255,"description":"Street address line 1","example":"123 Baker Street"},"addressLine2":{"type":["string","null"],"minLength":1,"maxLength":255,"description":"Street address line 2 (apartment, suite, unit, etc.)","example":"Suite 200"},"postalCode":{"type":["string","null"],"minLength":1,"maxLength":255,"description":"Postal / ZIP code","example":"NW1 6XE"},"raw":{"type":["string","null"],"minLength":1,"maxLength":255,"description":"Raw unstructured address text (used for geocoding)","example":"123 Baker Street, London NW1 6XE, United Kingdom"},"latitude":{"type":["number","null"],"minimum":-90,"maximum":90,"description":"Latitude coordinate (-90..90)","example":51.523767},"longitude":{"type":["number","null"],"minimum":-180,"maximum":180,"description":"Longitude coordinate (-180..180)","example":-0.158519}},"description":"Person address/location"},"compensation":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["actual","expected"],"description":"Compensation type","example":"actual"},"basicSalary":{"type":"number","exclusiveMinimum":0,"description":"Base salary amount","example":120000},"totalSalary":{"type":"number","exclusiveMinimum":0,"description":"Total salary amount (base + bonus)","example":150000},"currency":{"type":"string","enum":["USD","EUR","JPY","GBP","AUD","CAD","CHF","CNY","HKD","NZD","SEK","NOK","MXN","SGD","RUB","ZAR","TRY","BRL","INR","KRW","DKK","PLN","ILS","HUF","CZK","RON","THB","MYR","IDR","VND","PHP","SAR","AED","QAR","KWD","JOD","CLP","COP","PEN","ARS","UYU","CRC","PKR","BDT","LKR","EGP","NGN","TWD","KES","GHS","UGX","TZS","MAD","BWP","BGN","UAH","KZT","GEL","ISK","BHD","OMR"],"description":"Currency code","example":"USD"},"basis":{"type":"string","enum":["gross","net"],"default":"gross","description":"Gross or net","example":"gross"},"date":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Date this compensation data is relevant to (YYYY-MM-DD)","example":"2024-06-01"}},"required":["type","currency","date"]},"maxItems":100,"description":"Compensation records"},"customAttributes":{"type":"array","items":{"type":"object","properties":{"customAttributeId":{"type":"string","format":"uuid","description":"Custom attribute definition ID — must belong to the agency at the correct scope."},"optionId":{"type":["string","null"],"format":"uuid","description":"Required for `options`-type attributes — set to the chosen option's UUID. Mutually exclusive with `value`. For multi-select (`multipleValues: true`), repeat the entry once per chosen optionId."},"value":{"anyOf":[{"type":"string","minLength":1,"maxLength":16384},{"type":"number"},{"type":"null"}],"description":"Attribute value. Shape depends on the attribute `type`:\n- `text_line` / `text_block`: non-empty string (trimmed, max 16384 chars).\n- `integer` / `number_input`: JSON number, integer only, must fit Postgres int32 (-2147483648..2147483647).\n- `date`: string `YYYY-MM-DD`, calendar-validated.\n- `options`: do not send `value` — use `optionId` instead.\nMutually exclusive with `optionId`. Sending neither is rejected (422).","example":"Some text value"}},"required":["customAttributeId"],"description":"Custom attribute value"},"maxItems":100,"default":[],"description":"Custom attribute values. Each entry sets `customAttributeId` plus either `value` (text/number/date) or `optionId` (options-type) — never both. For options-type attributes with multipleValues=true, repeat the same customAttributeId with distinct optionIds.\n\nDeprecated shape still accepted for backward compatibility: `{ attributeId, valueString | valueInt | valueDate }` is auto-mapped to `{ customAttributeId, value }`. Send the canonical shape below.","example":[{"customAttributeId":"550e8400-e29b-41d4-a716-446655440000","value":"Some text value"},{"customAttributeId":"6f9619ff-8b86-d011-b42d-00cf4fc964ff","value":42},{"customAttributeId":"c9bf9e57-1685-4c89-bafb-ff5af830be8a","value":"2025-06-01"},{"customAttributeId":"f47ac10b-58cc-4372-a567-0e02b2c3d479","optionId":"9b2e4d6a-1c3f-4a8b-9e7d-2f1a6c5b4d3e"}]},"experience":{"type":"array","items":{"type":"object","properties":{"companyName":{"type":"string","minLength":1,"maxLength":255,"description":"Company name","example":"Dunder Mifflin"},"companyId":{"type":["string","null"],"format":"uuid","description":"Atlas company ID to link this experience to an existing company. When provided, no new company is created and name/domain/LinkedIn matching is skipped. On update, an explicit `null` unlinks the company; when present (id or null) it takes precedence over `companyName` matching.","example":"550e8400-e29b-41d4-a716-446655440000"},"companyLinkedinId":{"type":["string","null"],"minLength":1,"maxLength":255,"description":"Company LinkedIn ID","example":"12345678"},"companyDomain":{"type":["string","null"],"minLength":1,"maxLength":255,"description":"Company website domain (bare domain; full URLs are accepted and normalized to their hostname)","example":"dundermifflin.com"},"role":{"type":"string","minLength":1,"maxLength":255,"description":"Job title/role","example":"Regional Manager"},"description":{"type":["string","null"],"minLength":1,"maxLength":16384,"description":"Role description","example":"Responsible for managing Scranton branch."},"startDate":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Start date (YYYY-MM-DD)","example":"2021-04-01"},"endDate":{"type":["string","null"],"pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"End date (YYYY-MM-DD, null = current)","example":null}},"required":["companyName","role","startDate"]},"maxItems":100,"description":"Work experience records"},"education":{"type":"array","items":{"type":"object","properties":{"institutionName":{"type":"string","minLength":1,"maxLength":255,"description":"Institution name","example":"University of Scranton"},"degree":{"type":["string","null"],"minLength":1,"maxLength":255,"description":"Degree name","example":"Bachelor of Science"},"fieldOfStudy":{"type":["string","null"],"minLength":1,"maxLength":255,"description":"Field of study","example":"Business Administration"},"grade":{"type":["string","null"],"minLength":1,"maxLength":255,"description":"Grade/GPA","example":"3.4 GPA"},"description":{"type":["string","null"],"minLength":1,"maxLength":16384,"description":"Description","example":"Focus on management and sales."},"startDate":{"type":["string","null"],"pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Start date (YYYY-MM-DD)","example":"2012-09-01"},"endDate":{"type":["string","null"],"pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"End date (YYYY-MM-DD)","example":"2016-06-30"}},"required":["institutionName"]},"maxItems":100,"description":"Education records"}},"required":["addedByEmail","identities"],"description":"Create a person from an external source. Strict create — if the payload matches an existing person the request returns 409 with that person's id; use PATCH /api/v1/people/{id} to update them."},"LookupPeoplePayload":{"type":"object","properties":{"identities":{"type":"array","items":{"type":"string","description":"Identity value (email, phone, or LinkedIn URL)","example":"candidate@example.com"},"minItems":1,"maxItems":100,"description":"List of identity strings to look up (max 100). Type is auto-detected from the value pattern.","example":["test@example.com","+380631817386","www.linkedin.com/in/pavel","/in/jshlosberg","in/jane-doe"]}},"required":["identities"]},"UpdatePersonPayload":{"type":"object","properties":{"firstName":{"type":["string","null"],"minLength":1,"maxLength":80,"description":"First name","example":"Michael"},"lastName":{"type":["string","null"],"minLength":1,"maxLength":80,"description":"Last name","example":"Scott"},"gender":{"type":"string","enum":["male","female"],"description":"Gender","example":"male"},"candidateStatus":{"type":"string","enum":["omitted","applied","sourced","regular"],"description":"Candidate status classification: omitted (outbound-only, unresponsive), applied (created from an application), sourced (created via sourcing, still in a sourcing stage), regular (everyone else).","example":"regular"},"overview":{"type":["string","null"],"minLength":1,"maxLength":16384,"description":"Free-text overview/summary of the person. `null` clears it.","example":"Senior backend engineer, 10 years in fintech, open to contract roles."},"addedByEmail":{"type":"string","maxLength":255,"format":"email","description":"Email of the Atlas user the update is attributed to. Optional — required only when updating identities. If omitted, the update is unattributed.","example":"jordan@recruitwithatlas.com"},"source":{"type":"object","properties":{"system":{"type":"string","minLength":1,"maxLength":255,"description":"Source system name (sets people.sourced)","example":"api"},"externalId":{"type":["string","null"],"minLength":1,"maxLength":255,"description":"External ID from the source system. Unique per person within the agency: a (system, externalId) pair identifies at most one person and is the highest-priority conflict check on POST /api/v1/people. Supplying an externalId already stored on another person returns 409 (on POST and PATCH) with that person's id.","example":"124456"}},"required":["system"],"description":"Source system and external ID"},"identities":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["email","phone","linkedin","linkedin_salesnav","linkedin_recruiter","website"],"description":"Identity type","example":"email"},"value":{"type":"string","minLength":1,"maxLength":255,"description":"Identity value","example":"mscott@gmail.com"},"isPersonal":{"type":"boolean","description":"Whether this is a personal identity","example":true},"isPrimary":{"type":"boolean","description":"Whether this is the primary/favourite identity","example":true}},"required":["type","value"]},"minItems":1,"maxItems":20,"description":"Identities to add (additive — existing identities are never removed; at least one non-website identity required, max 20). An identity already owned by another person returns 409. Requires addedByEmail."},"headline":{"type":"object","properties":{"role":{"type":["string","null"],"minLength":1,"maxLength":255,"description":"Current role/job title","example":"Regional Manager"},"company":{"type":["string","null"],"minLength":1,"maxLength":255,"description":"Current company name. Resolved to an existing company by name (or a new one is created when none matches) and linked to the person, unless `companyId` is also provided (which takes precedence) or explicitly set to null (which stores the name as text only, without a company link).","example":"Dunder Mifflin"},"companyId":{"type":["string","null"],"format":"uuid","description":"Atlas company ID to link this headline/contact to an existing company. When provided, no new company is created and name matching is skipped. Takes precedence over `company`: the stored company name is set to the linked company’s name, overwriting a contradictory `company` value. On PATCH, an existing company-contact link is re-pointed to this company; as when changing the contact’s company in the app, this detaches the contact from projects linked under the old company.","example":"550e8400-e29b-41d4-a716-446655440000"},"roleStartedAt":{"type":["string","null"],"pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"When the current role started (YYYY-MM-DD)","example":"2023-04-01"}},"description":"Current headline information"},"location":{"type":["object","null"],"properties":{"name":{"type":["string","null"],"minLength":1,"maxLength":255,"description":"Display name / formatted address (e.g. \"London, UK\")","example":"London, UK"},"locality":{"type":["string","null"],"minLength":1,"maxLength":255,"description":"City name","example":"London"},"region":{"type":["string","null"],"minLength":1,"maxLength":255,"description":"State or region","example":"England"},"metro":{"type":["string","null"],"minLength":1,"maxLength":255,"description":"Metro area (People Data Labs convention, e.g. \"new york, new york\")","example":"new york, new york"},"country":{"type":["string","null"],"minLength":1,"maxLength":255,"description":"Country name","example":"United Kingdom"},"streetAddress":{"type":["string","null"],"minLength":1,"maxLength":255,"description":"Street address line 1","example":"123 Baker Street"},"addressLine2":{"type":["string","null"],"minLength":1,"maxLength":255,"description":"Street address line 2 (apartment, suite, unit, etc.)","example":"Suite 200"},"postalCode":{"type":["string","null"],"minLength":1,"maxLength":255,"description":"Postal / ZIP code","example":"NW1 6XE"},"raw":{"type":["string","null"],"minLength":1,"maxLength":255,"description":"Raw unstructured address text (used for geocoding)","example":"123 Baker Street, London NW1 6XE, United Kingdom"},"latitude":{"type":["number","null"],"minimum":-90,"maximum":90,"description":"Latitude coordinate (-90..90)","example":51.523767},"longitude":{"type":["number","null"],"minimum":-180,"maximum":180,"description":"Longitude coordinate (-180..180)","example":-0.158519}},"description":"Person address/location"},"customAttributes":{"type":"array","items":{"type":"object","properties":{"customAttributeId":{"type":"string","format":"uuid","description":"Custom attribute definition ID — must belong to the agency at the correct scope."},"optionId":{"type":["string","null"],"format":"uuid","description":"Required for `options`-type attributes — set to the chosen option's UUID. Mutually exclusive with `value`. For multi-select (`multipleValues: true`), repeat the entry once per chosen optionId."},"value":{"anyOf":[{"type":"string","minLength":1,"maxLength":16384},{"type":"number"},{"type":"null"}],"description":"Attribute value. Shape depends on the attribute `type`:\n- `text_line` / `text_block`: non-empty string (trimmed, max 16384 chars).\n- `integer` / `number_input`: JSON number, integer only, must fit Postgres int32 (-2147483648..2147483647).\n- `date`: string `YYYY-MM-DD`, calendar-validated.\n- `options`: do not send `value` — use `optionId` instead.\nMutually exclusive with `optionId`. Sending neither is rejected (422).","example":"Some text value"}},"required":["customAttributeId"],"description":"Custom attribute value"},"maxItems":100,"description":"Custom attribute values to set. Replace-per-attribute: for each customAttributeId present, the person’s existing values for that attribute are removed and these inserted. Attributes not listed are untouched. Same entry shape as POST /people.","example":[{"customAttributeId":"550e8400-e29b-41d4-a716-446655440000","value":"Some text value"},{"customAttributeId":"f47ac10b-58cc-4372-a567-0e02b2c3d479","optionId":"9b2e4d6a-1c3f-4a8b-9e7d-2f1a6c5b4d3e"}]}},"description":"Synchronous partial update of a person"},"UpdateExperiencePayload":{"type":"object","properties":{"companyName":{"type":"string","minLength":1,"maxLength":255,"description":"Company name","example":"Dunder Mifflin"},"companyId":{"type":["string","null"],"format":"uuid","description":"Atlas company ID to link this experience to an existing company. When provided, no new company is created and name/domain/LinkedIn matching is skipped. On update, an explicit `null` unlinks the company; when present (id or null) it takes precedence over `companyName` matching.","example":"550e8400-e29b-41d4-a716-446655440000"},"companyLinkedinId":{"type":["string","null"],"minLength":1,"maxLength":255,"description":"Company LinkedIn ID","example":"12345678"},"companyDomain":{"type":["string","null"],"minLength":1,"maxLength":255,"description":"Company website domain (bare domain; full URLs are accepted and normalized to their hostname)","example":"dundermifflin.com"},"role":{"type":"string","minLength":1,"maxLength":255,"description":"Job title/role","example":"Regional Manager"},"description":{"type":["string","null"],"minLength":1,"maxLength":16384,"description":"Role description","example":"Responsible for managing Scranton branch."},"startDate":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Start date (YYYY-MM-DD)","example":"2021-04-01"},"endDate":{"type":["string","null"],"pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"End date (YYYY-MM-DD, null = current)","example":null}},"description":"Partial update of a single experience"},"CreateNotePayload":{"type":"object","properties":{"email":{"type":"string","maxLength":255,"format":"email","description":"Person's email address. Provide exactly one of `email`, `personId`, `linkedinUrl`, or `phone`.","example":"person@example.com"},"personId":{"type":"string","format":"uuid","description":"Atlas person ID. Provide exactly one of `email`, `personId`, `linkedinUrl`, or `phone`.","example":"123e4567-e89b-12d3-a456-426614174000"},"linkedinUrl":{"type":"string","minLength":1,"description":"Person's LinkedIn profile URL. Provide exactly one of `email`, `personId`, `linkedinUrl`, or `phone`.","example":"linkedin.com/in/john-doe"},"phone":{"type":"string","minLength":1,"description":"Person's phone number. Provide exactly one of `email`, `personId`, `linkedinUrl`, or `phone`.","example":"+14155551234"},"note":{"type":"string","minLength":1,"maxLength":16384,"description":"Note text to create","example":"Called and left a voicemail."},"ownerEmail":{"type":"string","maxLength":255,"format":"email","description":"Note owner's email address","example":"recruiter@agency.com"},"projectId":{"type":"string","format":"uuid","description":"Atlas project ID to scope the note to the person's candidacy on that project. Omit for a person-level note.","example":"9f8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d"}},"required":["note","ownerEmail"],"description":"Create a note attached to a person"},"CreateCandidatePayload":{"type":"object","properties":{"personId":{"type":"string","format":"uuid","description":"Person ID to add as candidate","example":"550e8400-e29b-41d4-a716-446655440001"},"statusId":{"type":"string","format":"uuid","description":"Target status ID. When provided, stageId is ignored","example":"550e8400-e29b-41d4-a716-446655440002"},"stageId":{"type":"string","format":"uuid","description":"Target stage ID — first status of this stage will be used. Ignored when statusId is provided","example":"550e8400-e29b-41d4-a716-446655440003"}},"required":["personId"]},"CreateOpportunityPayload":{"type":"object","properties":{"name":{"type":["string","null"],"description":"Opportunity name (max 500 chars)","example":"Acme Corp — Senior Engineer"},"notes":{"type":["string","null"],"description":"Free-text notes (max 10 000 chars). Stored on the opportunity itself and returned as the top-level `notes` string on GET — not as an entry in the `opportunityNotes` array, which holds individual note records added by users in Atlas.","example":"Warm intro via LinkedIn"},"aiSummary":{"type":["string","null"],"description":"AI-generated summary for the opportunity (max 10 000 chars)","example":"High-fit candidate based on past placements."},"value":{"type":["integer","null"],"minimum":0,"maximum":1000000000,"description":"Monetary value (integer, 0–1 000 000 000)","example":25000},"ownerId":{"type":["string","null"],"format":"uuid","description":"Owner user ID (defaults to authenticated user)","example":"550e8400-e29b-41d4-a716-446655440001"},"candidateId":{"type":["string","null"],"format":"uuid","description":"Person being specced out. Sets type to speculative","example":"550e8400-e29b-41d4-a716-446655440005"},"prospectIds":{"type":["array","null"],"items":{"type":"string","format":"uuid"},"maxItems":50,"description":"Person IDs to attach as prospects (max 50) — the `id` from GET /api/v1/people. NOT CompanyContact junction IDs (`companyContact.id`) and NOT the `prospects[].id` rows returned by opportunity endpoints. Merged IDs are resolved to their canonical person automatically."},"companyIds":{"type":["array","null"],"items":{"type":"string","format":"uuid"},"maxItems":50,"description":"Target companies (max 50)"},"jobLeadIds":{"type":["array","null"],"items":{"type":"string","format":"uuid"},"maxItems":50,"description":"Projects to link as job leads (max 50)"}},"additionalProperties":false},"UpdateOpportunityPayload":{"type":"object","properties":{"prospectIds":{"type":["array","null"],"items":{"type":"string","format":"uuid"},"maxItems":50,"description":"Person IDs to attach as prospects (max 50) — the `id` from GET /api/v1/people, not CompanyContact junction IDs or `prospects[].id` rows. Additive — already-linked people are skipped. Merged IDs are resolved to their canonical person automatically."},"companyIds":{"type":["array","null"],"items":{"type":"string","format":"uuid"},"maxItems":50,"description":"Target companies to add (max 50). Additive — already-linked companies are skipped."},"jobLeadIds":{"type":["array","null"],"items":{"type":"string","format":"uuid"},"maxItems":50,"description":"Projects to link as job leads (max 50). Additive — already-linked projects are skipped."}},"additionalProperties":false}},"parameters":{}},"paths":{"/api/v1/companies":{"get":{"summary":"List companies","description":"Returns a paginated list of companies under the caller's agency, newest first.\n\n**Filters:**\n- `relationship` — comma-separated relationships (`client`, `target`, `none`). **Defaults to `client,target` — `none` companies are excluded unless you request them explicitly** (e.g. `?relationship=none` or `?relationship=client,target,none`). `none` is the relationship of every company auto-created from a person’s experience, enrichment, or import, so they are omitted from the sync surface by default.\n- `name` — case-insensitive partial match on the company name.\n- `createdAfter` / `createdBefore` — only companies created within the range (inclusive).\n- `updatedAfter` / `updatedBefore` — only companies updated within the range (inclusive). Use `updatedAfter` as an incremental-sync cursor: persist the maximum `updatedAt` you receive and pass it back on the next poll to fetch only what changed (upsert by `id` to stay idempotent).\n\n**Deletions (tombstones):**\nSoft-deleted companies are excluded by default. Pass `includeDeleted=true` to also receive deleted companies as tombstones — each carries a populated `deletedAt` (live rows have `deletedAt: null`). Combine `includeDeleted=true` with `updatedAfter` to incrementally pick up deletions: a soft-delete bumps `updatedAt`, so the deleted row resurfaces in the next poll with `deletedAt` set.\n\n**Pagination:**\nBy default the list is offset-paginated (`page` / `pageSize`) and the response's `pagination` object carries `page`, `pageSize`, `total`, and `totalPages`.\n- For large agencies, full crawls, or incremental syncs, prefer **keyset (cursor) pagination**: set `paginate=cursor`. In this mode `page` is ignored, the expensive total `COUNT` is skipped, and paging stays stable while the list changes underneath a long sync. For the default newest-first crawl (live rows) it also stays fast at any depth; combining cursor mode with `includeDeleted=true` or a narrow `updatedAfter`/`updatedBefore` window can still be slow on very large agencies (those paths are not yet index-optimized). The response `pagination` object then carries `pageSize`, `hasMore`, and `nextCursor` (`total`/`totalPages` are omitted). Request page 1 with just `paginate=cursor` (no cursor), then replay `pagination.nextCursor.cursorDate` + `cursorId` on each subsequent request until `nextCursor` is `null` (equivalently `hasMore` is `false`). Both cursor halves must be sent together — a half-cursor is a `422`. When `paginate` is omitted, a `cursorDate` + `cursorId` pair activates cursor mode on its own; combining a cursor pair with an explicit `paginate=offset` is contradictory and is rejected with `422`.\n\nEach item has the same shape as `GET /api/v1/companies/{id}`, including location, identities, custom attributes, and owners.","tags":["Companies"],"security":[{"BearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"Comma-separated company relationships to filter by (`client`, `target`, `none`).\n\n**Default (when omitted): `client,target` — `none` companies are excluded.** `none` is the relationship of every company auto-created from a person’s work experience, enrichment, or import (the large majority of companies), so the sync surface excludes them by default. To include them, request `none` explicitly — e.g. `?relationship=none` or `?relationship=client,target,none`.","example":"client,target"},"required":false,"name":"relationship","in":"query"},{"schema":{"type":"string","minLength":1,"maxLength":500,"description":"Filter by company name (case-insensitive partial match)","example":"Acme"},"required":false,"name":"name","in":"query"},{"schema":{"anyOf":[{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},{"type":"string","format":"date-time"}],"description":"Only companies created after this point (inclusive). Accepts an ISO 8601 datetime or a date-only YYYY-MM-DD value (covering from the start of that UTC day)","example":"2025-01-01"},"required":false,"name":"createdAfter","in":"query"},{"schema":{"anyOf":[{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},{"type":"string","format":"date-time"}],"description":"Only companies created before this point (inclusive). Accepts an ISO 8601 datetime or a date-only YYYY-MM-DD value (covering through the end of that UTC day)","example":"2026-01-01"},"required":false,"name":"createdBefore","in":"query"},{"schema":{"anyOf":[{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},{"type":"string","format":"date-time"}],"description":"Only companies updated after this point (inclusive). Accepts an ISO 8601 datetime or a date-only YYYY-MM-DD value (covering from the start of that UTC day)","example":"2025-06-01"},"required":false,"name":"updatedAfter","in":"query"},{"schema":{"anyOf":[{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},{"type":"string","format":"date-time"}],"description":"Only companies updated before this point (inclusive). Accepts an ISO 8601 datetime or a date-only YYYY-MM-DD value (covering through the end of that UTC day)","example":"2026-06-01"},"required":false,"name":"updatedBefore","in":"query"},{"schema":{"type":"string","enum":["true","false"],"description":"Include soft-deleted companies as tombstones (with a populated `deletedAt`). Defaults to false. Pair with `updatedAfter` to incrementally sync deletions.","example":"false"},"required":false,"name":"includeDeleted","in":"query"},{"schema":{"type":"string","enum":["asc","desc"],"default":"desc","description":"Sort order by `createdAt` (record creation time) — `desc` (default, newest first) or `asc` (oldest first). `id` is used as a stable tie-breaker, applied in the same direction.","example":"desc"},"required":false,"name":"order","in":"query"},{"schema":{"type":"integer","minimum":1,"default":1,"description":"Page number (1-indexed)","example":1},"required":false,"name":"page","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":100,"description":"Items per page (max 100)","example":25},"required":false,"name":"pageSize","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":100,"description":"Alias for pageSize","deprecated":true},"required":false,"name":"perPage","in":"query"},{"schema":{"type":"string","enum":["offset","cursor"],"description":"Pagination strategy. `offset` (the default when omitted) uses `page`/`pageSize` and returns `total`/`totalPages`. `cursor` uses keyset pagination (`cursorDate` + `cursorId`) and skips the expensive total `COUNT` — recommended for full crawls and incremental syncs; it stays fast at any depth for the default newest-first crawl, though `includeDeleted=true` or a narrow `updatedAfter`/`updatedBefore` window can still be slow on very large agencies. When `paginate` is omitted, passing `cursorDate`/`cursorId` infers `cursor`; combining an explicit `paginate=offset` with a cursor pair is rejected with `422`.","example":"offset"},"required":false,"name":"paginate","in":"query"},{"schema":{"type":"string","format":"date-time","description":"Keyset pagination cursor (used with `paginate=cursor`): pass back the `pagination.nextCursor.cursorDate` from the previous response. Must be sent together with `cursorId`. Omit for the first page. When cursor mode is active `page` is ignored and `total`/`totalPages` are omitted from the response — walk pages until `nextCursor` is `null`.","example":"2026-01-05T12:00:00.123456Z"},"required":false,"name":"cursorDate","in":"query"},{"schema":{"type":"string","format":"uuid","description":"Keyset pagination cursor id (used with `paginate=cursor`): pass back the `pagination.nextCursor.cursorId` from the previous response. Must be sent together with `cursorDate`.","example":"550e8400-e29b-41d4-a716-446655440000"},"required":false,"name":"cursorId","in":"query"}],"responses":{"200":{"description":"Paginated list of companies","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["ok"]},"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string","description":"Company name","example":"Acme Corp"},"websiteUrl":{"type":["string","null"],"description":"The company's primary website as a canonical `https://…` URL, derived from the primary `website` identity (or the first one if none is flagged primary). `null` when the company has no website identity. Accepted verbatim by `GET /companies/find-one?website=`.","example":"https://acme.com"},"linkedinUrl":{"type":["string","null"],"description":"The company's primary LinkedIn page as a canonical `https://…` URL, derived from the primary `linkedin` identity (or the first one if none is flagged primary). `null` when the company has no linkedin identity. Accepted verbatim by `GET /companies/find-one?linkedin_url=`.","example":"https://linkedin.com/company/acme"},"relationship":{"type":"string","enum":["client","target","none"],"description":"Company relationship","example":"client"},"type":{"type":["string","null"],"enum":["educational","government","nonprofit","private","public"],"description":"Company type"},"size":{"type":["string","null"],"enum":["1-10","11-50","51-200","201-500","501-1000","1001-5000","5001-10000","10001+"],"description":"Company size"},"industry":{"type":["array","null"],"items":{"type":"string"},"description":"Array of industry labels","example":["Technology"]},"summary":{"type":["string","null"],"description":"Short company summary"},"overview":{"type":["string","null"],"description":"Long-form company description"},"logo":{"type":["string","null"],"description":"Logo image URL"},"employeeCount":{"type":["integer","null"],"description":"Number of employees","example":150},"ticker":{"type":["string","null"],"description":"Stock ticker symbol","example":"AAPL"},"location":{"type":["object","null"],"properties":{"formattedAddress":{"type":["string","null"],"description":"Provider-normalized \"city, region, country\" string","example":"San Francisco, California, United States"},"city":{"type":["string","null"],"description":"City","example":"San Francisco"},"region":{"type":["string","null"],"description":"State / province","example":"California"},"country":{"type":["string","null"],"description":"Country","example":"United States"},"metro":{"type":["string","null"],"description":"Metro area","example":"San Francisco Bay Area"},"streetAddress":{"type":["string","null"],"description":"Street address line 1"},"addressLine2":{"type":["string","null"],"description":"Street address line 2"},"postalCode":{"type":["string","null"],"description":"Postal / zip code"},"raw":{"type":["string","null"],"description":"Unstructured location string (e.g. provider-normalized address text)","example":"London, England, United Kingdom"},"latitude":{"type":["number","null"],"description":"Latitude in decimal degrees","example":37.7749},"longitude":{"type":["number","null"],"description":"Longitude in decimal degrees","example":-122.4194}},"required":["formattedAddress","city","region","country","metro","streetAddress","addressLine2","postalCode","raw","latitude","longitude"],"description":"Company primary location, or `null` when no usable location data is on file"},"identities":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","description":"Identity type","example":"linkedin"},"value":{"type":"string","description":"Normalised identity value, stored scheme-less (protocol and `www.` stripped) so duplicates collapse to one company. Use the top-level `websiteUrl` / `linkedinUrl` fields for ready-to-use `https://…` URLs.","example":"linkedin.com/company/acme"},"primary":{"type":"boolean","description":"Whether this is the primary identity of its type"}},"required":["type","value","primary"]},"description":"Company identities (linkedin, website, etc.)"},"customAttributes":{"type":"array","items":{"type":"object","properties":{"attributeId":{"type":"string","format":"uuid","description":"Custom attribute definition ID"},"attributeName":{"type":["string","null"],"description":"Attribute name"},"attributeType":{"type":["string","null"],"enum":["options","text_block","text_line","number_input","integer","date"],"description":"Attribute type — drives the shape of each entry in `values`."},"values":{"type":"array","items":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"object","properties":{"optionId":{"type":"string","format":"uuid","description":"Selected option ID"},"optionValue":{"type":["string","null"],"description":"Display value of the option"}},"required":["optionId","optionValue"]}],"description":"A single value entry. Shape depends on `attributeType`:\n- `text_line` / `text_block` → string\n- `integer` / `number_input` → number\n- `date` → ISO `YYYY-MM-DD` string\n- `options` → `{ optionId, optionValue }` object"},"description":"All values recorded for this attribute. For single-value attributes the array has one entry; for multi-select `options` attributes it may have several."}},"required":["attributeId","attributeName","attributeType","values"]},"description":"Custom attribute values"},"owners":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Atlas user id of the owner"},"name":{"type":"string","description":"Owner's full name","example":"Jane Smith"},"email":{"type":"string","description":"Owner's email address","example":"jane@agency.com"}},"required":["id","name","email"]},"description":"Atlas users who own this company relationship (its relationship managers). A company can have several owners; the array is empty when none are assigned. Read-only — owners are managed in the Atlas app."},"createdAt":{"type":"string","description":"ISO 8601 creation timestamp"},"updatedAt":{"type":"string","description":"ISO 8601 last modification timestamp"},"deletedAt":{"type":["string","null"],"description":"ISO 8601 soft-delete timestamp. `null` for live companies; populated for tombstones (only returned when `includeDeleted=true` on the list endpoint)"}},"required":["id","name","websiteUrl","linkedinUrl","relationship","type","size","industry","summary","overview","logo","employeeCount","ticker","location","identities","customAttributes","owners","createdAt","updatedAt","deletedAt"]}},"pagination":{"anyOf":[{"type":"object","properties":{"page":{"type":"integer","description":"Current page number","example":1},"pageSize":{"type":"integer","description":"Items per page","example":25},"total":{"type":"integer","description":"Total matching items","example":42},"totalPages":{"type":"integer","description":"Total number of pages","example":2}},"required":["page","pageSize","total","totalPages"]},{"type":"object","properties":{"pageSize":{"type":"integer","description":"Items per page","example":25},"hasMore":{"type":"boolean","description":"Whether another page is available after this one","example":true},"nextCursor":{"type":["object","null"],"properties":{"cursorDate":{"type":"string","description":"Pass back as `cursorDate` to fetch the next page"},"cursorId":{"type":"string","format":"uuid","description":"Pass back as `cursorId` to fetch the next page"}},"required":["cursorDate","cursorId"],"description":"Cursor for the next page. `null` when there are no more results (equivalently `hasMore` is `false`)."}},"required":["pageSize","hasMore","nextCursor"]}],"description":"Offset shape (`page`/`pageSize`/`total`/`totalPages`) by default, or the keyset shape (`pageSize`/`hasMore`/`nextCursor`) when cursor mode is active — i.e. `paginate=cursor` is set (the first page needs no cursor) or a `cursorDate` + `cursorId` pair is supplied."}},"required":["status","data","pagination"]}}}},"401":{"description":"Unauthorized - missing or invalid API key","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["error"]},"error":{"type":"string","description":"Human-readable error message"}},"required":["status","error"]},"example":{"status":"error","error":"Unauthorized"}}}},"422":{"description":"Validation error - the request body or query parameters failed validation","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["error"]},"errors":{"type":"object","properties":{"formErrors":{"type":"array","items":{"type":"string"},"description":"Top-level validation errors"},"fieldErrors":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Per-field validation errors keyed by field name"}},"required":["formErrors","fieldErrors"]}},"required":["status","errors"]},"example":{"status":"error","errors":{"formErrors":[],"fieldErrors":{"email":["Invalid email"]}}}}}},"429":{"description":"Too many requests - the caller has exceeded the per-agency rate limit for the tier this endpoint counts against (default per minute: 1200 read / 400 write / 60 upload). Inspect the `RateLimit-*` headers — returned on every response, not only on 429s — and back off until the window resets. See the \"Rate limits\" section of the introduction for details.","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}},"content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["error"]},"error":{"type":"string","description":"Human-readable error message"},"tier":{"type":"string","enum":["read","write","upload"],"description":"The rate-limit tier whose quota was exceeded. GET endpoints count against `read`, POST/PUT/PATCH/DELETE against `write`, and multipart file uploads against `upload` — each tier has an independent counter."},"retryAfterSec":{"type":"integer","description":"Number of seconds after which the rate-limit window resets and requests will be accepted again. Prefer this (or the `RateLimit-Reset` header) over the `Retry-After` header, which is not guaranteed to be present."}},"required":["status","error","tier","retryAfterSec"]},"example":{"status":"error","error":"Rate limit exceeded","tier":"read","retryAfterSec":60}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["error"]},"error":{"type":"string","description":"Human-readable error message"}},"required":["status","error"]},"example":{"status":"error","error":"Internal Server error"}}}}}},"post":{"summary":"Create a company","description":"Creates a new company under the caller's agency. The endpoint:\n\n- Requires **at least one of `websiteUrl` or `linkedinUrl`** — companies created without any identity become unreachable via `GET /companies` lookup. Submitting both is allowed; both are stored as separate identities.\n- Stores `websiteUrl` and `linkedinUrl` as CompanyIdentity rows of type `website` / `linkedin` (the `identities` array is read-only output).\n- Returns **409 Conflict** when an existing company in the same agency already owns the supplied `websiteUrl`, `linkedinUrl`, or LinkedIn id — the underlying create service silently dedups, REST surfaces the conflict.\n- Does **not** accept a caller-supplied `logo` URL — any `logo` field in the body is silently stripped. The logo is populated downstream by automated enrichment (the create endpoint does not dereference caller URLs to avoid SSRF risk). Triggers enrichment / geolocation jobs in the background; PDL-derived fields (`industry`, `ticker`, location subfields) may continue to populate after the response is returned.\n\nResponse shape matches `GET /api/v1/companies/{id}` minus `logo`. Read `logo` via `GET /companies/{id}` once enrichment finishes.","tags":["Companies"],"security":[{"BearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":500,"description":"Company name (max 500 characters)","example":"Acme Corp"},"websiteUrl":{"type":["string","null"],"minLength":1,"maxLength":2048,"description":"Company website URL. Stored as a CompanyIdentity of type `website`. Bare hostnames are normalised (`acme.com` → `https://acme.com`). At least one of `websiteUrl` or `linkedinUrl` is required.","example":"https://acme.com"},"linkedinUrl":{"type":["string","null"],"minLength":1,"maxLength":2048,"description":"LinkedIn company URL. Stored as a CompanyIdentity of type `linkedin`. At least one of `websiteUrl` or `linkedinUrl` is required.","example":"https://linkedin.com/company/acme"},"summary":{"type":["string","null"],"minLength":1,"maxLength":255,"description":"Short company summary. Empty strings are rejected — omit or send null to clear.","example":"B2B SaaS"},"overview":{"type":["string","null"],"minLength":1,"maxLength":16384,"description":"Long-form company description. Empty strings are rejected — omit or send null to clear."},"size":{"type":["string","null"],"enum":["1-10","11-50","51-200","201-500","501-1000","1001-5000","5001-10000","10001+"],"description":"Company size bucket","example":"51-200"},"industry":{"type":["array","null"],"items":{"type":"string","minLength":1,"maxLength":80},"maxItems":100,"description":"Industry labels. Duplicate entries are silently dropped (`[\"Tech\",\"Tech\"]` → `[\"Tech\"]`).","example":["Technology"]},"relationship":{"type":"string","enum":["client","target","none"],"default":"none","description":"Company relationship","example":"client"},"type":{"type":["string","null"],"enum":["educational","government","nonprofit","private","public"],"description":"Company type"},"employeeCount":{"type":["integer","null"],"minimum":1,"maximum":10000000,"description":"Number of employees (precise, integer)","example":150},"ticker":{"type":["string","null"],"minLength":1,"maxLength":255,"description":"Stock ticker symbol. Empty strings are rejected — omit or send null to clear.","example":"AAPL"},"location":{"type":["object","null"],"properties":{"name":{"type":["string","null"],"minLength":1,"maxLength":255,"description":"Display name / formatted address (e.g. \"London, UK\")","example":"London, UK"},"locality":{"type":["string","null"],"minLength":1,"maxLength":255,"description":"City name","example":"London"},"region":{"type":["string","null"],"minLength":1,"maxLength":255,"description":"State or region","example":"England"},"metro":{"type":["string","null"],"minLength":1,"maxLength":255,"description":"Metro area (People Data Labs convention, e.g. \"new york, new york\")","example":"new york, new york"},"country":{"type":["string","null"],"minLength":1,"maxLength":255,"description":"Country name","example":"United Kingdom"},"streetAddress":{"type":["string","null"],"minLength":1,"maxLength":255,"description":"Street address line 1","example":"123 Baker Street"},"addressLine2":{"type":["string","null"],"minLength":1,"maxLength":255,"description":"Street address line 2 (apartment, suite, unit, etc.)","example":"Suite 200"},"postalCode":{"type":["string","null"],"minLength":1,"maxLength":255,"description":"Postal / ZIP code","example":"NW1 6XE"},"raw":{"type":["string","null"],"minLength":1,"maxLength":255,"description":"Raw unstructured address text (used for geocoding)","example":"123 Baker Street, London NW1 6XE, United Kingdom"},"latitude":{"type":["number","null"],"minimum":-90,"maximum":90,"description":"Latitude coordinate (-90..90)","example":51.523767},"longitude":{"type":["number","null"],"minimum":-180,"maximum":180,"description":"Longitude coordinate (-180..180)","example":-0.158519}},"description":"Location"},"customAttributes":{"type":"array","items":{"type":"object","properties":{"customAttributeId":{"type":"string","format":"uuid","description":"Custom attribute definition ID — must belong to the agency at the correct scope."},"optionId":{"type":["string","null"],"format":"uuid","description":"Required for `options`-type attributes — set to the chosen option's UUID. Mutually exclusive with `value`. For multi-select (`multipleValues: true`), repeat the entry once per chosen optionId."},"value":{"anyOf":[{"type":"string","minLength":1,"maxLength":16384},{"type":"number"},{"type":"null"}],"description":"Attribute value. Shape depends on the attribute `type`:\n- `text_line` / `text_block`: non-empty string (trimmed, max 16384 chars).\n- `integer` / `number_input`: JSON number, integer only, must fit Postgres int32 (-2147483648..2147483647).\n- `date`: string `YYYY-MM-DD`, calendar-validated.\n- `options`: do not send `value` — use `optionId` instead.\nMutually exclusive with `optionId`. Sending neither is rejected (422).","example":"Some text value"}},"required":["customAttributeId"],"description":"Custom attribute value"},"maxItems":100,"default":[],"description":"Custom attribute values. For options-type attributes with multipleValues=true, repeat the same customAttributeId with distinct optionIds."}},"required":["name"]}}}},"responses":{"201":{"description":"Company created","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["ok"]},"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string","description":"Company name","example":"Acme Corp"},"websiteUrl":{"type":["string","null"],"description":"The company's primary website as a canonical `https://…` URL, derived from the primary `website` identity (or the first one if none is flagged primary). `null` when the company has no website identity. Accepted verbatim by `GET /companies/find-one?website=`.","example":"https://acme.com"},"linkedinUrl":{"type":["string","null"],"description":"The company's primary LinkedIn page as a canonical `https://…` URL, derived from the primary `linkedin` identity (or the first one if none is flagged primary). `null` when the company has no linkedin identity. Accepted verbatim by `GET /companies/find-one?linkedin_url=`.","example":"https://linkedin.com/company/acme"},"relationship":{"type":"string","enum":["client","target","none"],"description":"Company relationship","example":"client"},"type":{"type":["string","null"],"enum":["educational","government","nonprofit","private","public"],"description":"Company type"},"size":{"type":["string","null"],"enum":["1-10","11-50","51-200","201-500","501-1000","1001-5000","5001-10000","10001+"],"description":"Company size"},"industry":{"type":["array","null"],"items":{"type":"string"},"description":"Array of industry labels","example":["Technology"]},"summary":{"type":["string","null"],"description":"Short company summary"},"overview":{"type":["string","null"],"description":"Long-form company description"},"employeeCount":{"type":["integer","null"],"description":"Number of employees","example":150},"ticker":{"type":["string","null"],"description":"Stock ticker symbol","example":"AAPL"},"location":{"type":["object","null"],"properties":{"formattedAddress":{"type":["string","null"],"description":"Provider-normalized \"city, region, country\" string","example":"San Francisco, California, United States"},"city":{"type":["string","null"],"description":"City","example":"San Francisco"},"region":{"type":["string","null"],"description":"State / province","example":"California"},"country":{"type":["string","null"],"description":"Country","example":"United States"},"metro":{"type":["string","null"],"description":"Metro area","example":"San Francisco Bay Area"},"streetAddress":{"type":["string","null"],"description":"Street address line 1"},"addressLine2":{"type":["string","null"],"description":"Street address line 2"},"postalCode":{"type":["string","null"],"description":"Postal / zip code"},"raw":{"type":["string","null"],"description":"Unstructured location string (e.g. provider-normalized address text)","example":"London, England, United Kingdom"},"latitude":{"type":["number","null"],"description":"Latitude in decimal degrees","example":37.7749},"longitude":{"type":["number","null"],"description":"Longitude in decimal degrees","example":-122.4194}},"required":["formattedAddress","city","region","country","metro","streetAddress","addressLine2","postalCode","raw","latitude","longitude"],"description":"Company primary location, or `null` when no usable location data is on file"},"identities":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","description":"Identity type","example":"linkedin"},"value":{"type":"string","description":"Normalised identity value, stored scheme-less (protocol and `www.` stripped) so duplicates collapse to one company. Use the top-level `websiteUrl` / `linkedinUrl` fields for ready-to-use `https://…` URLs.","example":"linkedin.com/company/acme"},"primary":{"type":"boolean","description":"Whether this is the primary identity of its type"}},"required":["type","value","primary"]},"description":"Company identities (linkedin, website, etc.)"},"customAttributes":{"type":"array","items":{"type":"object","properties":{"attributeId":{"type":"string","format":"uuid","description":"Custom attribute definition ID"},"attributeName":{"type":["string","null"],"description":"Attribute name"},"attributeType":{"type":["string","null"],"enum":["options","text_block","text_line","number_input","integer","date"],"description":"Attribute type — drives the shape of each entry in `values`."},"values":{"type":"array","items":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"object","properties":{"optionId":{"type":"string","format":"uuid","description":"Selected option ID"},"optionValue":{"type":["string","null"],"description":"Display value of the option"}},"required":["optionId","optionValue"]}],"description":"A single value entry. Shape depends on `attributeType`:\n- `text_line` / `text_block` → string\n- `integer` / `number_input` → number\n- `date` → ISO `YYYY-MM-DD` string\n- `options` → `{ optionId, optionValue }` object"},"description":"All values recorded for this attribute. For single-value attributes the array has one entry; for multi-select `options` attributes it may have several."}},"required":["attributeId","attributeName","attributeType","values"]},"description":"Custom attribute values"},"owners":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Atlas user id of the owner"},"name":{"type":"string","description":"Owner's full name","example":"Jane Smith"},"email":{"type":"string","description":"Owner's email address","example":"jane@agency.com"}},"required":["id","name","email"]},"description":"Atlas users who own this company relationship (its relationship managers). A company can have several owners; the array is empty when none are assigned. Read-only — owners are managed in the Atlas app."},"createdAt":{"type":"string","description":"ISO 8601 creation timestamp"},"updatedAt":{"type":"string","description":"ISO 8601 last modification timestamp"},"deletedAt":{"type":["string","null"],"description":"ISO 8601 soft-delete timestamp. `null` for live companies; populated for tombstones (only returned when `includeDeleted=true` on the list endpoint)"}},"required":["id","name","websiteUrl","linkedinUrl","relationship","type","size","industry","summary","overview","employeeCount","ticker","location","identities","customAttributes","owners","createdAt","updatedAt","deletedAt"]}},"required":["status","data"]}}}},"401":{"description":"Unauthorized - missing or invalid API key","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["error"]},"error":{"type":"string","description":"Human-readable error message"}},"required":["status","error"]},"example":{"status":"error","error":"Unauthorized"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["error"]},"error":{"type":"string","description":"Human-readable error message"}},"required":["status","error"]},"example":{"status":"error","error":"Not found"}}}},"409":{"description":"Conflict - the request cannot be fulfilled because of a conflict with the current state of the resource","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["error"]},"error":{"type":"string","description":"Human-readable error message"}},"required":["status","error"]},"example":{"status":"error","error":"websiteUrl matches company but linkedinUrl matches company . Submit only one identity, or reconcile the companies first."}}}},"422":{"description":"Validation error - the request body or query parameters failed validation","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["error"]},"errors":{"type":"object","properties":{"formErrors":{"type":"array","items":{"type":"string"},"description":"Top-level validation errors"},"fieldErrors":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Per-field validation errors keyed by field name"}},"required":["formErrors","fieldErrors"]}},"required":["status","errors"]},"example":{"status":"error","errors":{"formErrors":[],"fieldErrors":{"email":["Invalid email"]}}}}}},"429":{"description":"Too many requests - the caller has exceeded the per-agency rate limit for the tier this endpoint counts against (default per minute: 1200 read / 400 write / 60 upload). Inspect the `RateLimit-*` headers — returned on every response, not only on 429s — and back off until the window resets. See the \"Rate limits\" section of the introduction for details.","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}},"content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["error"]},"error":{"type":"string","description":"Human-readable error message"},"tier":{"type":"string","enum":["read","write","upload"],"description":"The rate-limit tier whose quota was exceeded. GET endpoints count against `read`, POST/PUT/PATCH/DELETE against `write`, and multipart file uploads against `upload` — each tier has an independent counter."},"retryAfterSec":{"type":"integer","description":"Number of seconds after which the rate-limit window resets and requests will be accepted again. Prefer this (or the `RateLimit-Reset` header) over the `Retry-After` header, which is not guaranteed to be present."}},"required":["status","error","tier","retryAfterSec"]},"example":{"status":"error","error":"Rate limit exceeded","tier":"read","retryAfterSec":60}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["error"]},"error":{"type":"string","description":"Human-readable error message"}},"required":["status","error"]},"example":{"status":"error","error":"Internal Server error"}}}}}}},"/api/v1/companies/{id}":{"get":{"summary":"Get company by ID","description":"Returns full company details including location, identities, custom attributes, and owners (the Atlas users managing the company relationship).","tags":["Companies"],"security":[{"BearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid","description":"Company ID","example":"550e8400-e29b-41d4-a716-446655440000"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Company found","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["ok"]},"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string","description":"Company name","example":"Acme Corp"},"websiteUrl":{"type":["string","null"],"description":"The company's primary website as a canonical `https://…` URL, derived from the primary `website` identity (or the first one if none is flagged primary). `null` when the company has no website identity. Accepted verbatim by `GET /companies/find-one?website=`.","example":"https://acme.com"},"linkedinUrl":{"type":["string","null"],"description":"The company's primary LinkedIn page as a canonical `https://…` URL, derived from the primary `linkedin` identity (or the first one if none is flagged primary). `null` when the company has no linkedin identity. Accepted verbatim by `GET /companies/find-one?linkedin_url=`.","example":"https://linkedin.com/company/acme"},"relationship":{"type":"string","enum":["client","target","none"],"description":"Company relationship","example":"client"},"type":{"type":["string","null"],"enum":["educational","government","nonprofit","private","public"],"description":"Company type"},"size":{"type":["string","null"],"enum":["1-10","11-50","51-200","201-500","501-1000","1001-5000","5001-10000","10001+"],"description":"Company size"},"industry":{"type":["array","null"],"items":{"type":"string"},"description":"Array of industry labels","example":["Technology"]},"summary":{"type":["string","null"],"description":"Short company summary"},"overview":{"type":["string","null"],"description":"Long-form company description"},"logo":{"type":["string","null"],"description":"Logo image URL"},"employeeCount":{"type":["integer","null"],"description":"Number of employees","example":150},"ticker":{"type":["string","null"],"description":"Stock ticker symbol","example":"AAPL"},"location":{"type":["object","null"],"properties":{"formattedAddress":{"type":["string","null"],"description":"Provider-normalized \"city, region, country\" string","example":"San Francisco, California, United States"},"city":{"type":["string","null"],"description":"City","example":"San Francisco"},"region":{"type":["string","null"],"description":"State / province","example":"California"},"country":{"type":["string","null"],"description":"Country","example":"United States"},"metro":{"type":["string","null"],"description":"Metro area","example":"San Francisco Bay Area"},"streetAddress":{"type":["string","null"],"description":"Street address line 1"},"addressLine2":{"type":["string","null"],"description":"Street address line 2"},"postalCode":{"type":["string","null"],"description":"Postal / zip code"},"raw":{"type":["string","null"],"description":"Unstructured location string (e.g. provider-normalized address text)","example":"London, England, United Kingdom"},"latitude":{"type":["number","null"],"description":"Latitude in decimal degrees","example":37.7749},"longitude":{"type":["number","null"],"description":"Longitude in decimal degrees","example":-122.4194}},"required":["formattedAddress","city","region","country","metro","streetAddress","addressLine2","postalCode","raw","latitude","longitude"],"description":"Company primary location, or `null` when no usable location data is on file"},"identities":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","description":"Identity type","example":"linkedin"},"value":{"type":"string","description":"Normalised identity value, stored scheme-less (protocol and `www.` stripped) so duplicates collapse to one company. Use the top-level `websiteUrl` / `linkedinUrl` fields for ready-to-use `https://…` URLs.","example":"linkedin.com/company/acme"},"primary":{"type":"boolean","description":"Whether this is the primary identity of its type"}},"required":["type","value","primary"]},"description":"Company identities (linkedin, website, etc.)"},"customAttributes":{"type":"array","items":{"type":"object","properties":{"attributeId":{"type":"string","format":"uuid","description":"Custom attribute definition ID"},"attributeName":{"type":["string","null"],"description":"Attribute name"},"attributeType":{"type":["string","null"],"enum":["options","text_block","text_line","number_input","integer","date"],"description":"Attribute type — drives the shape of each entry in `values`."},"values":{"type":"array","items":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"object","properties":{"optionId":{"type":"string","format":"uuid","description":"Selected option ID"},"optionValue":{"type":["string","null"],"description":"Display value of the option"}},"required":["optionId","optionValue"]}],"description":"A single value entry. Shape depends on `attributeType`:\n- `text_line` / `text_block` → string\n- `integer` / `number_input` → number\n- `date` → ISO `YYYY-MM-DD` string\n- `options` → `{ optionId, optionValue }` object"},"description":"All values recorded for this attribute. For single-value attributes the array has one entry; for multi-select `options` attributes it may have several."}},"required":["attributeId","attributeName","attributeType","values"]},"description":"Custom attribute values"},"owners":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Atlas user id of the owner"},"name":{"type":"string","description":"Owner's full name","example":"Jane Smith"},"email":{"type":"string","description":"Owner's email address","example":"jane@agency.com"}},"required":["id","name","email"]},"description":"Atlas users who own this company relationship (its relationship managers). A company can have several owners; the array is empty when none are assigned. Read-only — owners are managed in the Atlas app."},"createdAt":{"type":"string","description":"ISO 8601 creation timestamp"},"updatedAt":{"type":"string","description":"ISO 8601 last modification timestamp"},"deletedAt":{"type":["string","null"],"description":"ISO 8601 soft-delete timestamp. `null` for live companies; populated for tombstones (only returned when `includeDeleted=true` on the list endpoint)"}},"required":["id","name","websiteUrl","linkedinUrl","relationship","type","size","industry","summary","overview","logo","employeeCount","ticker","location","identities","customAttributes","owners","createdAt","updatedAt","deletedAt"]}},"required":["status","data"]}}}},"401":{"description":"Unauthorized"},"404":{"description":"Company not found"},"422":{"description":"Validation error"},"429":{"description":"Too many requests - the caller has exceeded the per-agency rate limit for the tier this endpoint counts against (default per minute: 1200 read / 400 write / 60 upload). Inspect the `RateLimit-*` headers — returned on every response, not only on 429s — and back off until the window resets. See the \"Rate limits\" section of the introduction for details.","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}},"content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["error"]},"error":{"type":"string","description":"Human-readable error message"},"tier":{"type":"string","enum":["read","write","upload"],"description":"The rate-limit tier whose quota was exceeded. GET endpoints count against `read`, POST/PUT/PATCH/DELETE against `write`, and multipart file uploads against `upload` — each tier has an independent counter."},"retryAfterSec":{"type":"integer","description":"Number of seconds after which the rate-limit window resets and requests will be accepted again. Prefer this (or the `RateLimit-Reset` header) over the `Retry-After` header, which is not guaranteed to be present."}},"required":["status","error","tier","retryAfterSec"]},"example":{"status":"error","error":"Rate limit exceeded","tier":"read","retryAfterSec":60}}}}}},"patch":{"summary":"Update a company","description":"Use this endpoint to update an existing company in your Atlas account — refresh scalar fields, location, identities, and custom attributes (e.g. Tier, Employer Type, Headcount) without a manual CSV import.\n\nEvery field is optional — send only what you want to change. An omitted field is left untouched; sending `null` on a nullable field clears it. At least one updatable field must be present (otherwise 422).\n\n**Scalars & location.** `name`, `relationship`, `type`, `size`, `summary`, `overview`, `industry`, `employeeCount`, `ticker` and `location` overwrite the stored value. Changing `name` re-indexes the company for search and refreshes the cached company name on the people who work there.\n\n**Identities are replace-all.** When you send `identities`, the company’s existing identities are removed and the supplied set inserted. Omit the field to leave identities unchanged. URL-like values are normalised (protocol / `www.` stripped, lower-cased) before storage. An identity value already owned by a **different** company in your agency fails with **409 Conflict**.\n\n**Custom attributes are replaced per attribute.** For every `customAttributeId` you send, the company’s existing values for that attribute are removed and the supplied ones written. Attributes you don’t mention are left as-is.\n\n**Attribution.** `ownerEmail` is optional and records which Atlas user made the change; when supplied it must match a user in your agency (otherwise 404).\n\nReturns the full updated company — the same shape as `GET /api/v1/companies/{id}`.","tags":["Companies"],"security":[{"BearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid","description":"Company ID","example":"550e8400-e29b-41d4-a716-446655440000"},"required":true,"name":"id","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateCompanyPayload"}}}},"responses":{"200":{"description":"Company updated. All changes are applied synchronously.","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["ok"]},"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string","description":"Company name","example":"Acme Corp"},"websiteUrl":{"type":["string","null"],"description":"The company's primary website as a canonical `https://…` URL, derived from the primary `website` identity (or the first one if none is flagged primary). `null` when the company has no website identity. Accepted verbatim by `GET /companies/find-one?website=`.","example":"https://acme.com"},"linkedinUrl":{"type":["string","null"],"description":"The company's primary LinkedIn page as a canonical `https://…` URL, derived from the primary `linkedin` identity (or the first one if none is flagged primary). `null` when the company has no linkedin identity. Accepted verbatim by `GET /companies/find-one?linkedin_url=`.","example":"https://linkedin.com/company/acme"},"relationship":{"type":"string","enum":["client","target","none"],"description":"Company relationship","example":"client"},"type":{"type":["string","null"],"enum":["educational","government","nonprofit","private","public"],"description":"Company type"},"size":{"type":["string","null"],"enum":["1-10","11-50","51-200","201-500","501-1000","1001-5000","5001-10000","10001+"],"description":"Company size"},"industry":{"type":["array","null"],"items":{"type":"string"},"description":"Array of industry labels","example":["Technology"]},"summary":{"type":["string","null"],"description":"Short company summary"},"overview":{"type":["string","null"],"description":"Long-form company description"},"logo":{"type":["string","null"],"description":"Logo image URL"},"employeeCount":{"type":["integer","null"],"description":"Number of employees","example":150},"ticker":{"type":["string","null"],"description":"Stock ticker symbol","example":"AAPL"},"location":{"type":["object","null"],"properties":{"formattedAddress":{"type":["string","null"],"description":"Provider-normalized \"city, region, country\" string","example":"San Francisco, California, United States"},"city":{"type":["string","null"],"description":"City","example":"San Francisco"},"region":{"type":["string","null"],"description":"State / province","example":"California"},"country":{"type":["string","null"],"description":"Country","example":"United States"},"metro":{"type":["string","null"],"description":"Metro area","example":"San Francisco Bay Area"},"streetAddress":{"type":["string","null"],"description":"Street address line 1"},"addressLine2":{"type":["string","null"],"description":"Street address line 2"},"postalCode":{"type":["string","null"],"description":"Postal / zip code"},"raw":{"type":["string","null"],"description":"Unstructured location string (e.g. provider-normalized address text)","example":"London, England, United Kingdom"},"latitude":{"type":["number","null"],"description":"Latitude in decimal degrees","example":37.7749},"longitude":{"type":["number","null"],"description":"Longitude in decimal degrees","example":-122.4194}},"required":["formattedAddress","city","region","country","metro","streetAddress","addressLine2","postalCode","raw","latitude","longitude"],"description":"Company primary location, or `null` when no usable location data is on file"},"identities":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","description":"Identity type","example":"linkedin"},"value":{"type":"string","description":"Normalised identity value, stored scheme-less (protocol and `www.` stripped) so duplicates collapse to one company. Use the top-level `websiteUrl` / `linkedinUrl` fields for ready-to-use `https://…` URLs.","example":"linkedin.com/company/acme"},"primary":{"type":"boolean","description":"Whether this is the primary identity of its type"}},"required":["type","value","primary"]},"description":"Company identities (linkedin, website, etc.)"},"customAttributes":{"type":"array","items":{"type":"object","properties":{"attributeId":{"type":"string","format":"uuid","description":"Custom attribute definition ID"},"attributeName":{"type":["string","null"],"description":"Attribute name"},"attributeType":{"type":["string","null"],"enum":["options","text_block","text_line","number_input","integer","date"],"description":"Attribute type — drives the shape of each entry in `values`."},"values":{"type":"array","items":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"object","properties":{"optionId":{"type":"string","format":"uuid","description":"Selected option ID"},"optionValue":{"type":["string","null"],"description":"Display value of the option"}},"required":["optionId","optionValue"]}],"description":"A single value entry. Shape depends on `attributeType`:\n- `text_line` / `text_block` → string\n- `integer` / `number_input` → number\n- `date` → ISO `YYYY-MM-DD` string\n- `options` → `{ optionId, optionValue }` object"},"description":"All values recorded for this attribute. For single-value attributes the array has one entry; for multi-select `options` attributes it may have several."}},"required":["attributeId","attributeName","attributeType","values"]},"description":"Custom attribute values"},"owners":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Atlas user id of the owner"},"name":{"type":"string","description":"Owner's full name","example":"Jane Smith"},"email":{"type":"string","description":"Owner's email address","example":"jane@agency.com"}},"required":["id","name","email"]},"description":"Atlas users who own this company relationship (its relationship managers). A company can have several owners; the array is empty when none are assigned. Read-only — owners are managed in the Atlas app."},"createdAt":{"type":"string","description":"ISO 8601 creation timestamp"},"updatedAt":{"type":"string","description":"ISO 8601 last modification timestamp"},"deletedAt":{"type":["string","null"],"description":"ISO 8601 soft-delete timestamp. `null` for live companies; populated for tombstones (only returned when `includeDeleted=true` on the list endpoint)"}},"required":["id","name","websiteUrl","linkedinUrl","relationship","type","size","industry","summary","overview","logo","employeeCount","ticker","location","identities","customAttributes","owners","createdAt","updatedAt","deletedAt"]}},"required":["status","data"]}}}},"401":{"description":"Unauthorized - missing or invalid API key","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["error"]},"error":{"type":"string","description":"Human-readable error message"}},"required":["status","error"]},"example":{"status":"error","error":"Unauthorized"}}}},"404":{"description":"Company not found, the provided ownerEmail matches no user, or a referenced customAttribute / option does not exist.","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["error"]},"error":{"type":"string","description":"Human-readable error message"}},"required":["status","error"]},"example":{"status":"error","error":"Not found"}}}},"409":{"description":"Conflict - the request cannot be fulfilled because of a conflict with the current state of the resource","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["error"]},"error":{"type":"string","description":"Human-readable error message"}},"required":["status","error"]},"example":{"status":"error","error":"websiteUrl matches company but linkedinUrl matches company . Submit only one identity, or reconcile the companies first."}}}},"422":{"description":"Validation error - the request body or query parameters failed validation","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["error"]},"errors":{"type":"object","properties":{"formErrors":{"type":"array","items":{"type":"string"},"description":"Top-level validation errors"},"fieldErrors":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Per-field validation errors keyed by field name"}},"required":["formErrors","fieldErrors"]}},"required":["status","errors"]},"example":{"status":"error","errors":{"formErrors":[],"fieldErrors":{"email":["Invalid email"]}}}}}},"429":{"description":"Too many requests - the caller has exceeded the per-agency rate limit for the tier this endpoint counts against (default per minute: 1200 read / 400 write / 60 upload). Inspect the `RateLimit-*` headers — returned on every response, not only on 429s — and back off until the window resets. See the \"Rate limits\" section of the introduction for details.","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}},"content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["error"]},"error":{"type":"string","description":"Human-readable error message"},"tier":{"type":"string","enum":["read","write","upload"],"description":"The rate-limit tier whose quota was exceeded. GET endpoints count against `read`, POST/PUT/PATCH/DELETE against `write`, and multipart file uploads against `upload` — each tier has an independent counter."},"retryAfterSec":{"type":"integer","description":"Number of seconds after which the rate-limit window resets and requests will be accepted again. Prefer this (or the `RateLimit-Reset` header) over the `Retry-After` header, which is not guaranteed to be present."}},"required":["status","error","tier","retryAfterSec"]},"example":{"status":"error","error":"Rate limit exceeded","tier":"read","retryAfterSec":60}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["error"]},"error":{"type":"string","description":"Human-readable error message"}},"required":["status","error"]},"example":{"status":"error","error":"Internal Server error"}}}}}}},"/api/v1/companies/find-one":{"get":{"summary":"Find a single company by identifier","description":"Finds a single company in your agency matching one of the provided identifiers. At least one of `name`, `linkedin_url`, `website`, or `identity` must be provided. If multiple are provided they are evaluated as OR in this precedence order — `linkedin_url` → `website` → `identity` → `name` — and the first match wins. The `name` lookup matches case-insensitively with fuzzy tolerance: exact matches win, then case-insensitive substring, then typo-tolerant (trigram) similarity, and the single best-scoring company is returned. `linkedin_url` and `website` accept either a full `https://…` URL or the scheme-less value returned in a company’s `identities` / `linkedinUrl` / `websiteUrl` (e.g. `acme.com`), so a value read from `GET /companies/{id}` can be passed straight back. Returns full company details including location, identities, custom attributes, and owners.","tags":["Companies"],"security":[{"BearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1,"maxLength":500,"description":"Company name. Matched case-insensitively with typo-tolerant full-text ranking — the single best-scoring company in the caller's agency is returned.\n\nNote: name matching uses an asynchronous search index that is eventually consistent with the primary store. A company created via `POST /companies` may take a short interval (typically sub-second, occasionally longer under load) to become discoverable via `?name=`. Clients that need read-your-writes semantics should look the company up by `linkedin_url`, `website`, or the id returned from `POST /companies` instead.","example":"Acme Corp"},"required":false,"name":"name","in":"query"},{"schema":{"type":"string","minLength":1,"maxLength":2048,"description":"LinkedIn company URL. Bare hostnames / scheme-less slugs are accepted and normalised (`linkedin.com/company/acme` → `https://linkedin.com/company/acme`), so the value returned in a company’s `linkedin` identity can be passed back verbatim.","example":"https://linkedin.com/company/acme"},"required":false,"name":"linkedin_url","in":"query"},{"schema":{"type":"string","minLength":1,"maxLength":2048,"description":"Company website URL. Bare hostnames are accepted and normalised (`acme.com` → `https://acme.com`), so the value returned in a company’s `website` identity can be passed back verbatim.","example":"https://acme.com"},"required":false,"name":"website","in":"query"},{"schema":{"type":"string","minLength":1,"maxLength":2048,"description":"Any identity value — searches across all company identity types","example":"https://github.com/acme"},"required":false,"name":"identity","in":"query"}],"responses":{"200":{"description":"Lookup succeeded. `data` is the matched company, or `null` when no company matched the supplied identifiers.","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["ok"]},"data":{"type":["object","null"],"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string","description":"Company name","example":"Acme Corp"},"websiteUrl":{"type":["string","null"],"description":"The company's primary website as a canonical `https://…` URL, derived from the primary `website` identity (or the first one if none is flagged primary). `null` when the company has no website identity. Accepted verbatim by `GET /companies/find-one?website=`.","example":"https://acme.com"},"linkedinUrl":{"type":["string","null"],"description":"The company's primary LinkedIn page as a canonical `https://…` URL, derived from the primary `linkedin` identity (or the first one if none is flagged primary). `null` when the company has no linkedin identity. Accepted verbatim by `GET /companies/find-one?linkedin_url=`.","example":"https://linkedin.com/company/acme"},"relationship":{"type":"string","enum":["client","target","none"],"description":"Company relationship","example":"client"},"type":{"type":["string","null"],"enum":["educational","government","nonprofit","private","public"],"description":"Company type"},"size":{"type":["string","null"],"enum":["1-10","11-50","51-200","201-500","501-1000","1001-5000","5001-10000","10001+"],"description":"Company size"},"industry":{"type":["array","null"],"items":{"type":"string"},"description":"Array of industry labels","example":["Technology"]},"summary":{"type":["string","null"],"description":"Short company summary"},"overview":{"type":["string","null"],"description":"Long-form company description"},"logo":{"type":["string","null"],"description":"Logo image URL"},"employeeCount":{"type":["integer","null"],"description":"Number of employees","example":150},"ticker":{"type":["string","null"],"description":"Stock ticker symbol","example":"AAPL"},"location":{"type":["object","null"],"properties":{"formattedAddress":{"type":["string","null"],"description":"Provider-normalized \"city, region, country\" string","example":"San Francisco, California, United States"},"city":{"type":["string","null"],"description":"City","example":"San Francisco"},"region":{"type":["string","null"],"description":"State / province","example":"California"},"country":{"type":["string","null"],"description":"Country","example":"United States"},"metro":{"type":["string","null"],"description":"Metro area","example":"San Francisco Bay Area"},"streetAddress":{"type":["string","null"],"description":"Street address line 1"},"addressLine2":{"type":["string","null"],"description":"Street address line 2"},"postalCode":{"type":["string","null"],"description":"Postal / zip code"},"raw":{"type":["string","null"],"description":"Unstructured location string (e.g. provider-normalized address text)","example":"London, England, United Kingdom"},"latitude":{"type":["number","null"],"description":"Latitude in decimal degrees","example":37.7749},"longitude":{"type":["number","null"],"description":"Longitude in decimal degrees","example":-122.4194}},"required":["formattedAddress","city","region","country","metro","streetAddress","addressLine2","postalCode","raw","latitude","longitude"],"description":"Company primary location, or `null` when no usable location data is on file"},"identities":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","description":"Identity type","example":"linkedin"},"value":{"type":"string","description":"Normalised identity value, stored scheme-less (protocol and `www.` stripped) so duplicates collapse to one company. Use the top-level `websiteUrl` / `linkedinUrl` fields for ready-to-use `https://…` URLs.","example":"linkedin.com/company/acme"},"primary":{"type":"boolean","description":"Whether this is the primary identity of its type"}},"required":["type","value","primary"]},"description":"Company identities (linkedin, website, etc.)"},"customAttributes":{"type":"array","items":{"type":"object","properties":{"attributeId":{"type":"string","format":"uuid","description":"Custom attribute definition ID"},"attributeName":{"type":["string","null"],"description":"Attribute name"},"attributeType":{"type":["string","null"],"enum":["options","text_block","text_line","number_input","integer","date"],"description":"Attribute type — drives the shape of each entry in `values`."},"values":{"type":"array","items":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"object","properties":{"optionId":{"type":"string","format":"uuid","description":"Selected option ID"},"optionValue":{"type":["string","null"],"description":"Display value of the option"}},"required":["optionId","optionValue"]}],"description":"A single value entry. Shape depends on `attributeType`:\n- `text_line` / `text_block` → string\n- `integer` / `number_input` → number\n- `date` → ISO `YYYY-MM-DD` string\n- `options` → `{ optionId, optionValue }` object"},"description":"All values recorded for this attribute. For single-value attributes the array has one entry; for multi-select `options` attributes it may have several."}},"required":["attributeId","attributeName","attributeType","values"]},"description":"Custom attribute values"},"owners":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Atlas user id of the owner"},"name":{"type":"string","description":"Owner's full name","example":"Jane Smith"},"email":{"type":"string","description":"Owner's email address","example":"jane@agency.com"}},"required":["id","name","email"]},"description":"Atlas users who own this company relationship (its relationship managers). A company can have several owners; the array is empty when none are assigned. Read-only — owners are managed in the Atlas app."},"createdAt":{"type":"string","description":"ISO 8601 creation timestamp"},"updatedAt":{"type":"string","description":"ISO 8601 last modification timestamp"},"deletedAt":{"type":["string","null"],"description":"ISO 8601 soft-delete timestamp. `null` for live companies; populated for tombstones (only returned when `includeDeleted=true` on the list endpoint)"}},"required":["id","name","websiteUrl","linkedinUrl","relationship","type","size","industry","summary","overview","logo","employeeCount","ticker","location","identities","customAttributes","owners","createdAt","updatedAt","deletedAt"]}},"required":["status","data"]}}}},"401":{"description":"Unauthorized - missing or invalid API key","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["error"]},"error":{"type":"string","description":"Human-readable error message"}},"required":["status","error"]},"example":{"status":"error","error":"Unauthorized"}}}},"422":{"description":"Validation error - the request body or query parameters failed validation","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["error"]},"errors":{"type":"object","properties":{"formErrors":{"type":"array","items":{"type":"string"},"description":"Top-level validation errors"},"fieldErrors":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Per-field validation errors keyed by field name"}},"required":["formErrors","fieldErrors"]}},"required":["status","errors"]},"example":{"status":"error","errors":{"formErrors":[],"fieldErrors":{"email":["Invalid email"]}}}}}},"429":{"description":"Too many requests - the caller has exceeded the per-agency rate limit for the tier this endpoint counts against (default per minute: 1200 read / 400 write / 60 upload). Inspect the `RateLimit-*` headers — returned on every response, not only on 429s — and back off until the window resets. See the \"Rate limits\" section of the introduction for details.","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}},"content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["error"]},"error":{"type":"string","description":"Human-readable error message"},"tier":{"type":"string","enum":["read","write","upload"],"description":"The rate-limit tier whose quota was exceeded. GET endpoints count against `read`, POST/PUT/PATCH/DELETE against `write`, and multipart file uploads against `upload` — each tier has an independent counter."},"retryAfterSec":{"type":"integer","description":"Number of seconds after which the rate-limit window resets and requests will be accepted again. Prefer this (or the `RateLimit-Reset` header) over the `Retry-After` header, which is not guaranteed to be present."}},"required":["status","error","tier","retryAfterSec"]},"example":{"status":"error","error":"Rate limit exceeded","tier":"read","retryAfterSec":60}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["error"]},"error":{"type":"string","description":"Human-readable error message"}},"required":["status","error"]},"example":{"status":"error","error":"Internal Server error"}}}}}}},"/api/v1/contacts":{"get":{"summary":"List company contacts","description":"Returns a paginated list of company contacts under the caller's agency, newest first. A contact is the link between a person and a company (`company_contacts`); each person has at most one live contact.\n\n**Filters:**\n- `relationship` — comma-separated relationships (`client`, `prospect`, `none`). Every row is returned by default, including `none` links.\n- `personId` — return only the contact for a single person.\n- `companyId` — return only contacts linked to a single company.\n- `createdAfter` / `createdBefore` — only contacts created within the range (inclusive).\n- `updatedAfter` / `updatedBefore` — only contacts updated within the range (inclusive). Use `updatedAfter` as an incremental-sync cursor: persist the maximum `updatedAt` you receive and pass it back on the next poll to fetch only what changed (upsert by `id` to stay idempotent).\n\n**Deletions (tombstones):**\nSoft-deleted contacts are excluded by default. Pass `includeDeleted=true` to also receive deleted contacts as tombstones — each carries a populated `deletedAt` (live rows have `deletedAt: null`). Combine `includeDeleted=true` with `updatedAfter` to incrementally pick up deletions: a soft-delete bumps `updatedAt`, so the deleted row resurfaces in the next poll with `deletedAt` set.","tags":["Contacts"],"security":[{"BearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"Comma-separated company-contact relationships to filter by","example":"client,prospect"},"required":false,"name":"relationship","in":"query"},{"schema":{"type":"string","format":"uuid","description":"Filter to the contact row for a single person","example":"550e8400-e29b-41d4-a716-446655440000"},"required":false,"name":"personId","in":"query"},{"schema":{"type":"string","format":"uuid","description":"Filter to contacts linked to a single company","example":"550e8400-e29b-41d4-a716-446655440000"},"required":false,"name":"companyId","in":"query"},{"schema":{"anyOf":[{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},{"type":"string","format":"date-time"}],"description":"Only contacts created after this point (inclusive). Accepts an ISO 8601 datetime or a date-only YYYY-MM-DD value (covering from the start of that UTC day)","example":"2025-01-01"},"required":false,"name":"createdAfter","in":"query"},{"schema":{"anyOf":[{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},{"type":"string","format":"date-time"}],"description":"Only contacts created before this point (inclusive). Accepts an ISO 8601 datetime or a date-only YYYY-MM-DD value (covering through the end of that UTC day)","example":"2026-01-01"},"required":false,"name":"createdBefore","in":"query"},{"schema":{"anyOf":[{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},{"type":"string","format":"date-time"}],"description":"Only contacts updated after this point (inclusive). Accepts an ISO 8601 datetime or a date-only YYYY-MM-DD value (covering from the start of that UTC day)","example":"2025-06-01"},"required":false,"name":"updatedAfter","in":"query"},{"schema":{"anyOf":[{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},{"type":"string","format":"date-time"}],"description":"Only contacts updated before this point (inclusive). Accepts an ISO 8601 datetime or a date-only YYYY-MM-DD value (covering through the end of that UTC day)","example":"2026-06-01"},"required":false,"name":"updatedBefore","in":"query"},{"schema":{"type":"string","enum":["true","false"],"description":"Include soft-deleted contacts as tombstones (with a populated `deletedAt`). Defaults to false. Pair with `updatedAfter` to incrementally sync deletions.","example":"false"},"required":false,"name":"includeDeleted","in":"query"},{"schema":{"type":"string","enum":["asc","desc"],"default":"desc","description":"Sort order by `createdAt` (record creation time) — `desc` (default, newest first) or `asc` (oldest first). `id` is used as a stable tie-breaker, applied in the same direction.","example":"desc"},"required":false,"name":"order","in":"query"},{"schema":{"type":"integer","minimum":1,"default":1,"description":"Page number (1-indexed)","example":1},"required":false,"name":"page","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":100,"description":"Items per page (max 100)","example":25},"required":false,"name":"pageSize","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":100,"description":"Alias for pageSize","deprecated":true},"required":false,"name":"perPage","in":"query"}],"responses":{"200":{"description":"Paginated list of company contacts","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["ok"]},"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"personId":{"type":"string","format":"uuid","description":"ID of the linked person"},"companyId":{"type":"string","format":"uuid","description":"ID of the linked company"},"relationship":{"type":"string","enum":["client","prospect","none"],"description":"Contact relationship. `none` means the person is linked to a company but not (yet) an active client/prospect contact.","example":"client"},"title":{"type":["string","null"],"description":"Contact job title at the company","example":"Head of Talent"},"seniority":{"type":["string","null"],"enum":["Partner","Board","Founder","CXO","VP","Director","Manager","Senior","Middle","Junior","Training","Unpaid"],"description":"Derived work seniority"},"person":{"type":["object","null"],"properties":{"id":{"type":"string","format":"uuid"},"firstName":{"type":["string","null"],"description":"Person first name","example":"Michael"},"lastName":{"type":["string","null"],"description":"Person last name","example":"Scott"}},"required":["id","firstName","lastName"],"description":"Light reference to the linked person, or `null` when it could not be loaded"},"company":{"type":["object","null"],"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string","description":"Company name","example":"Acme Corp"}},"required":["id","name"],"description":"Light reference to the linked company, or `null` when it could not be loaded"},"createdBy":{"type":["object","null"],"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string","description":"User full name","example":"Jane Recruiter"},"email":{"type":["string","null"],"description":"User email","example":"jane@agency.com"}},"required":["id","name","email"],"description":"The user who created the contact. For contacts predating July 2026 this is backfilled from the creator of the linked person (best-effort), and `null` where no creator could be resolved."},"createdAt":{"type":"string","description":"ISO 8601 creation timestamp"},"updatedAt":{"type":"string","description":"ISO 8601 last modification timestamp"},"deletedAt":{"type":["string","null"],"description":"ISO 8601 soft-delete timestamp. `null` for live contacts; populated for tombstones (only returned when `includeDeleted=true`)"}},"required":["id","personId","companyId","relationship","title","seniority","person","company","createdBy","createdAt","updatedAt","deletedAt"]}},"pagination":{"type":"object","properties":{"page":{"type":"integer","description":"Current page number","example":1},"pageSize":{"type":"integer","description":"Items per page","example":25},"total":{"type":"integer","description":"Total matching items","example":42},"totalPages":{"type":"integer","description":"Total number of pages","example":2}},"required":["page","pageSize","total","totalPages"]}},"required":["status","data","pagination"]}}}},"401":{"description":"Unauthorized - missing or invalid API key","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["error"]},"error":{"type":"string","description":"Human-readable error message"}},"required":["status","error"]},"example":{"status":"error","error":"Unauthorized"}}}},"422":{"description":"Validation error - the request body or query parameters failed validation","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["error"]},"errors":{"type":"object","properties":{"formErrors":{"type":"array","items":{"type":"string"},"description":"Top-level validation errors"},"fieldErrors":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Per-field validation errors keyed by field name"}},"required":["formErrors","fieldErrors"]}},"required":["status","errors"]},"example":{"status":"error","errors":{"formErrors":[],"fieldErrors":{"email":["Invalid email"]}}}}}},"429":{"description":"Too many requests - the caller has exceeded the per-agency rate limit for the tier this endpoint counts against (default per minute: 1200 read / 400 write / 60 upload). Inspect the `RateLimit-*` headers — returned on every response, not only on 429s — and back off until the window resets. See the \"Rate limits\" section of the introduction for details.","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}},"content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["error"]},"error":{"type":"string","description":"Human-readable error message"},"tier":{"type":"string","enum":["read","write","upload"],"description":"The rate-limit tier whose quota was exceeded. GET endpoints count against `read`, POST/PUT/PATCH/DELETE against `write`, and multipart file uploads against `upload` — each tier has an independent counter."},"retryAfterSec":{"type":"integer","description":"Number of seconds after which the rate-limit window resets and requests will be accepted again. Prefer this (or the `RateLimit-Reset` header) over the `Retry-After` header, which is not guaranteed to be present."}},"required":["status","error","tier","retryAfterSec"]},"example":{"status":"error","error":"Rate limit exceeded","tier":"read","retryAfterSec":60}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["error"]},"error":{"type":"string","description":"Human-readable error message"}},"required":["status","error"]},"example":{"status":"error","error":"Internal Server error"}}}}}}},"/api/v1/people":{"get":{"summary":"List people","description":"Use this endpoint to retrieve a paginated list of people (contacts and candidates) across your **entire** agency.\n\nIt is the counterpart to **Get a person** (`GET /api/v1/people/{id}`) for bulk reads: sync every person into an external system, or count how many people each consultant added to the CRM over a period.\n\n**What you can filter by:**\n- `createdByIds` — comma-separated Atlas user UUIDs; return only people added by those consultants (matches `Person.createdById`). This is the filter to use for \"people/candidates added per consultant\".\n- `createdAfter` / `createdBefore` — only people added within a date range (inclusive). Accepts an ISO 8601 datetime or a date-only `YYYY-MM-DD` value.\n- `updatedAfter` / `updatedBefore` — only people last modified within a date range (inclusive). Use `updatedAfter` as an incremental-sync cursor.\n- `includeDeleted` — when `true`, soft-deleted people are included as tombstones (with a populated `deletedAt`) so you can sync deletions.\n\n**Ordering:**\nResults are ordered by creation date (`createdAt`, then `id` as a tiebreaker). Use `sortDirection=asc` or `sortDirection=desc` (default `desc`, newest first).\n\n**Pagination:**\nUse `page` (1-based) and `pageSize` (1–100, default 25). The response includes a `pagination` object with `page`, `pageSize`, `total`, and `totalPages`.\n\n**What you get back:**\nEach person includes `id`, `firstName`, `lastName`, headline (`headlineRole`, `headlineCompanyName`), `relationshipType` (`contact` vs `candidate`), the `company` they are a contact at (when applicable), the `createdBy` consultant, and `createdAt` / `updatedAt` / `deletedAt` timestamps. Use `id` with **Get a person** to fetch full details.","tags":["People"],"security":[{"BearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"Filter to people created by these Atlas users (the consultant who added them). Comma-separated user UUIDs — matches `Person.createdById`. Omit to return people added by anyone.","example":"550e8400-e29b-41d4-a716-446655440000,660e8400-e29b-41d4-a716-446655440001"},"required":false,"name":"createdByIds","in":"query"},{"schema":{"anyOf":[{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},{"type":"string","format":"date-time"}],"description":"Only people created after this point (inclusive). Accepts an ISO 8601 datetime or a date-only YYYY-MM-DD value (covering from the start of that UTC day)","example":"2025-01-01"},"required":false,"name":"createdAfter","in":"query"},{"schema":{"anyOf":[{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},{"type":"string","format":"date-time"}],"description":"Only people created before this point (inclusive). Accepts an ISO 8601 datetime or a date-only YYYY-MM-DD value (covering through the end of that UTC day)","example":"2026-01-01"},"required":false,"name":"createdBefore","in":"query"},{"schema":{"anyOf":[{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},{"type":"string","format":"date-time"}],"description":"Only people updated after this point (inclusive). Accepts an ISO 8601 datetime or a date-only YYYY-MM-DD value (covering from the start of that UTC day)","example":"2025-06-01"},"required":false,"name":"updatedAfter","in":"query"},{"schema":{"anyOf":[{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},{"type":"string","format":"date-time"}],"description":"Only people updated before this point (inclusive). Accepts an ISO 8601 datetime or a date-only YYYY-MM-DD value (covering through the end of that UTC day)","example":"2026-06-01"},"required":false,"name":"updatedBefore","in":"query"},{"schema":{"type":"string","enum":["true","false"],"description":"Include soft-deleted people as tombstones (with a populated `deletedAt`). Defaults to false. Pair with `updatedAfter` to incrementally sync deletions.","example":"false"},"required":false,"name":"includeDeleted","in":"query"},{"schema":{"type":"string","enum":["asc","desc"],"default":"desc","description":"Sort direction by creation date (createdAt, then id as a tiebreaker). Defaults to desc (newest first).","example":"desc"},"required":false,"name":"sortDirection","in":"query"},{"schema":{"type":"integer","minimum":1,"default":1,"description":"Page number (1-indexed)","example":1},"required":false,"name":"page","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":100,"description":"Items per page (max 100)","example":25},"required":false,"name":"pageSize","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":100,"description":"Alias for pageSize","deprecated":true},"required":false,"name":"perPage","in":"query"}],"responses":{"200":{"description":"Paginated list of people","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["ok"]},"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Person ID (people.id)"},"firstName":{"type":["string","null"],"description":"Person first name"},"lastName":{"type":["string","null"],"description":"Person last name"},"headlineRole":{"type":["string","null"],"description":"Current/most recent job title","example":"Regional Manager"},"headlineCompanyName":{"type":["string","null"],"description":"Current/most recent company name","example":"Dunder Mifflin"},"relationshipType":{"type":"string","enum":["contact","candidate"],"description":"Simplified split derived **solely** from company-contact links: `contact` when the person has at least one live company-contact link, otherwise `candidate`. Important: `candidate` here means only \"not a client contact\" — it does **NOT** indicate the person is (or ever was) a candidate linked to any project. A person who is both a client contact and an active candidate is reported as `contact`, and the candidacy is not reflected in this field. To count real candidates or pipeline candidacies, use `GET /api/v1/candidates` — not this field.","example":"candidate"},"company":{"type":["object","null"],"properties":{"id":{"type":"string","format":"uuid","description":"Company ID"},"name":{"type":"string","description":"Company name"}},"required":["id","name"],"description":"The company this person is a contact at (only when `relationshipType` is `contact`). May reference a company that is excluded from the default `GET /api/v1/companies` list (which returns only `client`/`target` by default) — resolve it via `GET /api/v1/companies/{id}`."},"createdBy":{"type":["object","null"],"properties":{"id":{"type":"string","format":"uuid","description":"Creating user ID"},"name":{"type":["string","null"],"description":"Creating user name"},"email":{"type":["string","null"],"description":"Creating user email"}},"required":["id","name","email"],"description":"The Atlas user (consultant) who added this person to the CRM"},"createdAt":{"type":["string","null"],"description":"ISO 8601 — when the person was added"},"updatedAt":{"type":["string","null"],"description":"ISO 8601 — when the person was last modified"},"deletedAt":{"type":["string","null"],"description":"ISO 8601 — when the person was soft-deleted, null unless returned as a tombstone"}},"required":["id","firstName","lastName","headlineRole","headlineCompanyName","relationshipType","company","createdBy","createdAt","updatedAt","deletedAt"]}},"pagination":{"type":"object","properties":{"page":{"type":"integer","description":"Current page number","example":1},"pageSize":{"type":"integer","description":"Results per page","example":25},"total":{"type":"integer","description":"Total number of matching people","example":42},"totalPages":{"type":"integer","description":"Total number of pages","example":2}},"required":["page","pageSize","total","totalPages"]}},"required":["status","data","pagination"]}}}},"401":{"description":"Unauthorized - missing or invalid API key","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["error"]},"error":{"type":"string","description":"Human-readable error message"}},"required":["status","error"]},"example":{"status":"error","error":"Unauthorized"}}}},"422":{"description":"Validation error - the request body or query parameters failed validation","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["error"]},"errors":{"type":"object","properties":{"formErrors":{"type":"array","items":{"type":"string"},"description":"Top-level validation errors"},"fieldErrors":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Per-field validation errors keyed by field name"}},"required":["formErrors","fieldErrors"]}},"required":["status","errors"]},"example":{"status":"error","errors":{"formErrors":[],"fieldErrors":{"email":["Invalid email"]}}}}}},"429":{"description":"Too many requests - the caller has exceeded the per-agency rate limit for the tier this endpoint counts against (default per minute: 1200 read / 400 write / 60 upload). Inspect the `RateLimit-*` headers — returned on every response, not only on 429s — and back off until the window resets. See the \"Rate limits\" section of the introduction for details.","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}},"content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["error"]},"error":{"type":"string","description":"Human-readable error message"},"tier":{"type":"string","enum":["read","write","upload"],"description":"The rate-limit tier whose quota was exceeded. GET endpoints count against `read`, POST/PUT/PATCH/DELETE against `write`, and multipart file uploads against `upload` — each tier has an independent counter."},"retryAfterSec":{"type":"integer","description":"Number of seconds after which the rate-limit window resets and requests will be accepted again. Prefer this (or the `RateLimit-Reset` header) over the `Retry-After` header, which is not guaranteed to be present."}},"required":["status","error","tier","retryAfterSec"]},"example":{"status":"error","error":"Rate limit exceeded","tier":"read","retryAfterSec":60}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["error"]},"error":{"type":"string","description":"Human-readable error message"}},"required":["status","error"]},"example":{"status":"error","error":"Internal Server error"}}}}}},"post":{"summary":"Create a person","description":"Use this endpoint to add a new person to your Atlas account.\n\nThis is the main endpoint for pushing contact data into Atlas from an external system - for example, from your website's application form, a spreadsheet import, or another tool in your tech stack.\n\n**Strict create — never updates an existing person.**\n\nIf any of the contact details (identities) you provide already point at a person in your agency, the request fails with **409 Conflict** and the response body includes the existing `personId`. To update an existing record, use **`PATCH /api/v1/people/{id}`** (fields, identities, custom attributes) and the dedicated experience / education endpoints — this endpoint will not merge data into an existing record under any circumstances. The typical integration flow is: POST, and on a 409 take the returned `personId` and PATCH it.\n\n**Conflict detection order:**\n\n1. `source.externalId` paired with `source.system` (high-confidence external-id match).\n2. Email address (normalized).\n3. LinkedIn URL (`linkedin`, `linkedin_salesnav`, `linkedin_recruiter`).\n4. Phone number (matched against all variations Atlas stores).\n\nThe first match wins; the returned `personId` is the conflicting person's id, and `conflictType` tells you which rule matched — `\"externalId\"` for rule 1, `\"identity\"` for rules 2–4 (each with a matching distinct `error` message).\n\n**Important fields:**\n- `identities` - you must provide at least one non-website contact detail (email, phone, or LinkedIn). This is how Atlas identifies the person and how the conflict check runs.\n- `addedByEmail` - the email address of an existing Atlas user in your agency. This is the team member the action will be attributed to. If no user exists with this email, the request fails with a 404.\n- `source` - optional. Tag where this data came from (e.g. `\"website\"`, `\"zapier\"`, `\"hubspot\"`).\n\n**`source.externalId` uniqueness.** A `(source.system, source.externalId)` pair is unique within your agency — it identifies at most one person and is the highest-priority conflict rule (rule 1 above). Re-pushing a record whose externalId is already stored on a person returns 409 with that person's `personId`, so it doubles as an idempotency key: on 409, switch to `PATCH /api/v1/people/{id}`.\n\n**Synchronous vs. asynchronous creation.**\n\nThe person record, its identities, headline, and any custom attribute values are created **synchronously** — once you receive the 201, the person exists and the conflict check above will match it.\n\nWork experience, education and compensation are created **asynchronously**: each is queued as an independent background job. They are validated synchronously (an invalid payload still returns 422 before anything is created), so anything accepted will be created — but it may take a short moment to appear, so they are **not guaranteed to be present on an immediate `GET /api/v1/people/{id}`**. The company-contact link (when `isContact: true`) is created **synchronously** and is present on that immediate read. A failure creating one of these extras (e.g. a transient database error) is retried automatically and never affects the person, the other extras, or the 201 you already received.\n\n**What you get back:**\n\nOn success (201), the response includes:\n- The Atlas person ID\n- `created: true`\n- `identitiesCreated` / `customAttributesCreated` — counts created synchronously\n- `queued` — counts of experience, education, compensation, and company-contact records accepted and enqueued for asynchronous creation","tags":["People"],"security":[{"BearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreatePersonPayload"}}}},"responses":{"201":{"description":"New person created. Identities, custom attributes and the company-contact link (when `isContact` is set) are created synchronously; experience, education and compensation are enqueued for asynchronous creation (see the `queued` counts).","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["ok"]},"data":{"type":"object","properties":{"personId":{"type":"string","format":"uuid"},"created":{"type":"boolean","enum":[true]},"identitiesCreated":{"type":"integer","description":"Identities created synchronously"},"customAttributesCreated":{"type":"integer","description":"Custom attribute values created synchronously"},"queued":{"type":"object","properties":{"experiences":{"type":"integer"},"educations":{"type":"integer"},"compensation":{"type":"integer"},"companyContact":{"type":"integer"}},"required":["experiences","educations","compensation","companyContact"],"description":"Counts of extra entities. `experiences`, `educations` and `compensation` are enqueued for asynchronous creation (not yet present when this response is returned). `companyContact` is created synchronously — `1` when the link was created, `0` otherwise."}},"required":["personId","created","identitiesCreated","customAttributesCreated","queued"]}},"required":["status","data"]}}}},"401":{"description":"Unauthorized - missing or invalid API key","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["error"]},"error":{"type":"string","description":"Human-readable error message"}},"required":["status","error"]},"example":{"status":"error","error":"Unauthorized"}}}},"404":{"description":"User not found for the provided addedByEmail, OR a referenced customAttribute / option does not exist in the agency.","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["error"]},"error":{"type":"string","description":"Human-readable error message"}},"required":["status","error"]},"example":{"status":"error","error":"Not found"}}}},"409":{"description":"A person with one of the supplied identities — or the same (source.system, source.externalId) pair — already exists in this agency. `conflictType` says which rule matched (`identity` vs `externalId`) and the `error` message differs accordingly. This endpoint never updates: take the returned personId and use PATCH /api/v1/people/{id} to update that person.","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["error"]},"error":{"type":"string","description":"Human-readable conflict explanation. Distinct per rule: identity conflicts return \"A person with one of the supplied identities already exists\"; (source.system, source.externalId) conflicts return \"A person with the same (source.system, source.externalId) pair already exists\".","example":"A person with one of the supplied identities already exists"},"conflictType":{"type":"string","enum":["identity","externalId"],"description":"Which uniqueness rule matched: `externalId` — the (source.system, source.externalId) pair already belongs to a person; `identity` — an email / LinkedIn URL / phone number already belongs to a person. When both would match, `externalId` wins (it is checked first).","example":"identity"},"personId":{"type":"string","format":"uuid","description":"ID of the existing person that conflicted. Use it with GET /api/v1/people/{id} or PATCH /api/v1/people/{id}."}},"required":["status","error","conflictType","personId"]}}}},"422":{"description":"Validation error - the request body or query parameters failed validation","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["error"]},"errors":{"type":"object","properties":{"formErrors":{"type":"array","items":{"type":"string"},"description":"Top-level validation errors"},"fieldErrors":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Per-field validation errors keyed by field name"}},"required":["formErrors","fieldErrors"]}},"required":["status","errors"]},"example":{"status":"error","errors":{"formErrors":[],"fieldErrors":{"email":["Invalid email"]}}}}}},"429":{"description":"Too many requests - the caller has exceeded the per-agency rate limit for the tier this endpoint counts against (default per minute: 1200 read / 400 write / 60 upload). Inspect the `RateLimit-*` headers — returned on every response, not only on 429s — and back off until the window resets. See the \"Rate limits\" section of the introduction for details.","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}},"content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["error"]},"error":{"type":"string","description":"Human-readable error message"},"tier":{"type":"string","enum":["read","write","upload"],"description":"The rate-limit tier whose quota was exceeded. GET endpoints count against `read`, POST/PUT/PATCH/DELETE against `write`, and multipart file uploads against `upload` — each tier has an independent counter."},"retryAfterSec":{"type":"integer","description":"Number of seconds after which the rate-limit window resets and requests will be accepted again. Prefer this (or the `RateLimit-Reset` header) over the `Retry-After` header, which is not guaranteed to be present."}},"required":["status","error","tier","retryAfterSec"]},"example":{"status":"error","error":"Rate limit exceeded","tier":"read","retryAfterSec":60}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["error"]},"error":{"type":"string","description":"Human-readable error message"}},"required":["status","error"]},"example":{"status":"error","error":"Internal Server error"}}}}}}},"/api/v1/people/lookup":{"post":{"summary":"Bulk lookup people by identity","description":"Use this endpoint to check whether a batch of contacts already exist in your Atlas account - before importing or syncing them from another system.\n\nYou send a list of contact details (up to 100 at a time), and Atlas will automatically figure out what type each one is based on its format - for example, anything that looks like an email address will be treated as an email, a URL containing \"linkedin.com\" will be treated as a LinkedIn profile, and a string of digits will be treated as a phone number.\n\nFor each item you send, Atlas tells you:\n- Whether it recognised the format (if not, it returns `\"invalid identity format\"`)\n- Whether a person with that contact detail already exists in your agency\n- The ID of that person, if they exist (useful for linking records)\n\nThis is particularly useful when you have a spreadsheet or external system full of contacts and you want to quickly find out which ones are already in Atlas before deciding what to do with the rest.","tags":["People"],"security":[{"BearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LookupPeoplePayload"}}}},"responses":{"200":{"description":"Lookup results, one entry per input identity in the same order","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["ok"]},"data":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","description":"Auto-detected identity type, or \"invalid identity format\""},"value":{"type":"string","description":"Original input value"},"exists":{"type":"boolean"},"personId":{"type":["string","null"],"format":"uuid"}},"required":["type","value","exists","personId"]}}},"required":["status","data"]},"example":{"status":"ok","data":[{"type":"email","value":"test@example.com","exists":true,"personId":"123e4567-e89b-12d3-a456-426614174000"},{"type":"linkedin","value":"https://www.linkedin.com/in/johndoe","exists":true,"personId":"987e6543-e21b-12d3-a456-426614174000"},{"type":"email","value":"unknown@example.com","exists":false,"personId":null}]}}}},"401":{"description":"Unauthorized - missing or invalid API key","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["error"]},"error":{"type":"string","description":"Human-readable error message"}},"required":["status","error"]},"example":{"status":"error","error":"Unauthorized"}}}},"422":{"description":"Validation error - the request body or query parameters failed validation","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["error"]},"errors":{"type":"object","properties":{"formErrors":{"type":"array","items":{"type":"string"},"description":"Top-level validation errors"},"fieldErrors":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Per-field validation errors keyed by field name"}},"required":["formErrors","fieldErrors"]}},"required":["status","errors"]},"example":{"status":"error","errors":{"formErrors":[],"fieldErrors":{"email":["Invalid email"]}}}}}},"429":{"description":"Too many requests - the caller has exceeded the per-agency rate limit for the tier this endpoint counts against (default per minute: 1200 read / 400 write / 60 upload). Inspect the `RateLimit-*` headers — returned on every response, not only on 429s — and back off until the window resets. See the \"Rate limits\" section of the introduction for details.","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}},"content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["error"]},"error":{"type":"string","description":"Human-readable error message"},"tier":{"type":"string","enum":["read","write","upload"],"description":"The rate-limit tier whose quota was exceeded. GET endpoints count against `read`, POST/PUT/PATCH/DELETE against `write`, and multipart file uploads against `upload` — each tier has an independent counter."},"retryAfterSec":{"type":"integer","description":"Number of seconds after which the rate-limit window resets and requests will be accepted again. Prefer this (or the `RateLimit-Reset` header) over the `Retry-After` header, which is not guaranteed to be present."}},"required":["status","error","tier","retryAfterSec"]},"example":{"status":"error","error":"Rate limit exceeded","tier":"read","retryAfterSec":60}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["error"]},"error":{"type":"string","description":"Human-readable error message"}},"required":["status","error"]},"example":{"status":"error","error":"Internal Server error"}}}}}}},"/api/v1/people/search":{"get":{"summary":"Search people by identity","description":"Use this endpoint to look up a specific person in your Atlas account using a contact detail you already know - such as their email address, phone number, or LinkedIn profile URL.\n\nFor example, if someone fills out a form on your website and you have their email address, you can use this endpoint to instantly check whether they already exist in Atlas and retrieve their full record.\n\nYou must provide at least one of: email, phone, or LinkedIn URL. Atlas will search your agency's data and return any matching people along with their name, current role, current company, and all known contact details (identities) on file.\n\nIf no match is found, an empty list is returned - it will not throw an error.","tags":["People"],"security":[{"BearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"Comma-separated email addresses","example":"alice@example.com,bob@example.com"},"required":false,"name":"emails","in":"query"},{"schema":{"type":"string","description":"Comma-separated phone numbers","example":"+14155551234,+442071234567"},"required":false,"name":"phones","in":"query"},{"schema":{"type":"string","description":"Comma-separated LinkedIn URLs","example":"linkedin.com/in/john-doe,linkedin.com/in/jane-smith"},"required":false,"name":"linkedinUrls","in":"query"}],"responses":{"200":{"description":"Matching people with their identities","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["ok"]},"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"firstName":{"type":["string","null"],"description":"First name","example":"John"},"lastName":{"type":["string","null"],"description":"Last name","example":"Doe"},"headlineRole":{"type":["string","null"],"description":"Current role/job title","example":"Software Engineer"},"headlineCompanyName":{"type":["string","null"],"description":"Current company name","example":"Acme Corp"},"identities":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string"},"value":{"type":"string"},"active":{"type":"boolean"}},"required":["type","value","active"]}}},"required":["id","firstName","lastName","headlineRole","headlineCompanyName","identities"]}}},"required":["status","data"]}}}},"401":{"description":"Unauthorized - missing or invalid API key","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["error"]},"error":{"type":"string","description":"Human-readable error message"}},"required":["status","error"]},"example":{"status":"error","error":"Unauthorized"}}}},"422":{"description":"Validation error - the request body or query parameters failed validation","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["error"]},"errors":{"type":"object","properties":{"formErrors":{"type":"array","items":{"type":"string"},"description":"Top-level validation errors"},"fieldErrors":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Per-field validation errors keyed by field name"}},"required":["formErrors","fieldErrors"]}},"required":["status","errors"]},"example":{"status":"error","errors":{"formErrors":[],"fieldErrors":{"email":["Invalid email"]}}}}}},"429":{"description":"Too many requests - the caller has exceeded the per-agency rate limit for the tier this endpoint counts against (default per minute: 1200 read / 400 write / 60 upload). Inspect the `RateLimit-*` headers — returned on every response, not only on 429s — and back off until the window resets. See the \"Rate limits\" section of the introduction for details.","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}},"content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["error"]},"error":{"type":"string","description":"Human-readable error message"},"tier":{"type":"string","enum":["read","write","upload"],"description":"The rate-limit tier whose quota was exceeded. GET endpoints count against `read`, POST/PUT/PATCH/DELETE against `write`, and multipart file uploads against `upload` — each tier has an independent counter."},"retryAfterSec":{"type":"integer","description":"Number of seconds after which the rate-limit window resets and requests will be accepted again. Prefer this (or the `RateLimit-Reset` header) over the `Retry-After` header, which is not guaranteed to be present."}},"required":["status","error","tier","retryAfterSec"]},"example":{"status":"error","error":"Rate limit exceeded","tier":"read","retryAfterSec":60}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["error"]},"error":{"type":"string","description":"Human-readable error message"}},"required":["status","error"]},"example":{"status":"error","error":"Internal Server error"}}}}}}},"/api/v1/people/{id}":{"get":{"summary":"Get a person by ID","description":"Use this endpoint to retrieve the full details of a single person from your Atlas account by their ID.\n\nThis is the endpoint to use when you already know which person you want - for example, after finding them via the Search endpoint, receiving their ID from a webhook, or storing it from a previous Create call. It returns everything Atlas knows about the person in one response.\n\n**What you need to provide:**\nJust the person's ID in the URL path (e.g. `/api/v1/people/abc-123`). Person IDs are UUIDs returned by other endpoints like Search, Lookup, or Create.\n\n**What you get back:**\nThe person's full profile - basic info, identities, headline, address, work experience, education, compensation, custom attributes, source, and metadata.\n\n**Merged people:** If the requested person was merged into another person in Atlas, this endpoint transparently returns the surviving person's data. The response includes a `merged` field indicating the original ID that was looked up and the resolved ID being returned, so the caller can update any cached references.\n\nIf no person exists with the given ID in your agency, the endpoint returns a 404 error.","tags":["People"],"security":[{"BearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid","description":"Atlas person ID","example":"123e4567-e89b-12d3-a456-426614174000"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Person details","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["ok"]},"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Atlas person ID (the resolved ID, after merge resolution)"},"firstName":{"type":["string","null"]},"lastName":{"type":["string","null"]},"middleName":{"type":["string","null"]},"isContact":{"type":"boolean","description":"Whether this person is a company contact in any company"},"companyContact":{"type":["object","null"],"properties":{"id":{"type":"string","format":"uuid","description":"The CompanyContact junction ID — the link between this person and the company. This is the value to pass in `companyContactIds` when associating the person with a job_lead via POST /api/v1/projects. It is NOT the person ID; passing a person ID there returns 404.","example":"b3f1c2d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d"},"companyId":{"type":"string","format":"uuid","description":"The company this person is a contact at"},"relationship":{"type":"string","enum":["client","prospect","none"],"description":"The contact's relationship to the company","example":"prospect"},"title":{"type":["string","null"],"description":"Job title at the company","example":"VP of Engineering"}},"required":["id","companyId","relationship","title"],"description":"The active company-contact link for this person, or null if they are not a contact at any company. A person has at most one. Use its `id` as the `companyContactIds` value when linking this person to a job_lead via POST /api/v1/projects."},"gender":{"type":["string","null"],"enum":["male","female"]},"source":{"type":["object","null"],"properties":{"system":{"type":["string","null"],"description":"Source system that last touched this person","example":"api"},"externalId":{"type":["string","null"],"description":"External ID from the source system","example":"124456"}},"required":["system","externalId"],"description":"Source system metadata, or null if the person has no source recorded"},"identities":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","description":"Identity type","example":"email"},"value":{"type":"string","description":"Identity value","example":"mscott@example.com"},"isPersonal":{"type":"boolean","description":"Whether this identity is a personal contact detail","example":true},"isPrimary":{"type":"boolean","description":"Whether this is the primary/favourite identity","example":true}},"required":["type","value","isPersonal","isPrimary"]}},"headline":{"type":["object","null"],"properties":{"role":{"type":["string","null"],"description":"Current role/job title","example":"Regional Manager"},"company":{"type":["string","null"],"description":"Current company name","example":"Dunder Mifflin"},"companyId":{"type":["string","null"],"format":"uuid","description":"Atlas company ID for the current company"},"roleStartedAt":{"type":["string","null"],"description":"When the current role started (YYYY-MM-DD)","example":"2023-04-01"}},"required":["role","company","companyId","roleStartedAt"],"description":"Current role and company, or null if the person has no current role"},"address":{"type":["object","null"],"properties":{"raw":{"type":["string","null"],"description":"Full address string"},"streetAddress":{"type":["string","null"],"description":"Street address"},"addressLine2":{"type":["string","null"],"description":"Address line 2 (apt, suite, etc.)"},"city":{"type":["string","null"],"description":"City (locality)"},"region":{"type":["string","null"],"description":"Region / state"},"postalCode":{"type":["string","null"],"description":"Postal/ZIP code"},"country":{"type":["string","null"],"description":"Country"},"metro":{"type":["string","null"],"description":"Metro area (US only)"},"formattedAddress":{"type":["string","null"],"description":"Cleaned \"locality, region, country\" string"},"latitude":{"type":["number","null"],"description":"Latitude coordinate"},"longitude":{"type":["number","null"],"description":"Longitude coordinate"}},"required":["raw","streetAddress","addressLine2","city","region","postalCode","country","metro","formattedAddress","latitude","longitude"]},"experience":{"type":"array","items":{"type":"object","properties":{"companyName":{"type":"string","description":"Company name","example":"Dunder Mifflin"},"companyId":{"type":["string","null"],"format":"uuid","description":"Linked Atlas company ID","example":"550e8400-e29b-41d4-a716-446655440000"},"companyLinkedinId":{"type":["string","null"],"description":"Company LinkedIn ID","example":"12345678"},"companyDomain":{"type":["string","null"],"description":"Company website domain","example":"dundermifflin.com"},"role":{"type":"string","description":"Job title/role","example":"Regional Manager"},"description":{"type":["string","null"],"description":"Role description as plain text","example":"Led day-to-day operations for a 3-member team. Developed and maintained dashboards in Power BI."},"startDate":{"type":["string","null"],"description":"Start date (YYYY-MM-DD)","example":"2021-04-01"},"endDate":{"type":["string","null"],"description":"End date (YYYY-MM-DD, null = current)","example":null}},"required":["companyName","companyId","companyLinkedinId","companyDomain","role","description","startDate","endDate"]}},"education":{"type":"array","items":{"type":"object","properties":{"institutionName":{"type":"string","description":"Institution name","example":"University of Scranton"},"degree":{"type":["string","null"],"description":"Degree name","example":"Bachelor of Science"},"fieldOfStudy":{"type":["string","null"],"description":"Field of study","example":"Business Administration"},"grade":{"type":["string","null"],"description":"Grade/GPA","example":"3.4 GPA"},"description":{"type":["string","null"],"description":"Description"},"startDate":{"type":["string","null"],"description":"Start date","example":"2012-09-01"},"endDate":{"type":["string","null"],"description":"End date","example":"2016-06-30"}},"required":["institutionName","degree","fieldOfStudy","grade","description","startDate","endDate"]}},"compensation":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["actual","expected"],"description":"Compensation type","example":"actual"},"taxMethod":{"type":["string","null"],"description":"gross / net / hourly_rate / day_rate","example":"gross"},"currency":{"type":["string","null"],"description":"Currency code","example":"USD"},"relevantDate":{"type":["string","null"],"description":"Date this compensation is relevant to (YYYY-MM-DD)","example":"2024-06-01"},"basicSalary":{"type":["number","null"],"description":"Base salary amount","example":120000},"bonusSalary":{"type":["number","null"],"description":"Bonus salary amount","example":30000},"totalSalary":{"type":["number","null"],"description":"Total salary amount (typically base + bonus)","example":150000},"expectedSalaryMin":{"type":["number","null"],"description":"Expected base salary minimum","example":130000},"expectedSalaryMax":{"type":["number","null"],"description":"Expected base salary maximum","example":160000},"expectedBonusSalaryMin":{"type":["number","null"],"description":"Expected bonus salary minimum","example":10000},"expectedBonusSalaryMax":{"type":["number","null"],"description":"Expected bonus salary maximum","example":50000}},"required":["type","taxMethod","currency","relevantDate","basicSalary","bonusSalary","totalSalary","expectedSalaryMin","expectedSalaryMax","expectedBonusSalaryMin","expectedBonusSalaryMax"]}},"customAttributes":{"type":"array","items":{"type":"object","properties":{"attributeId":{"type":"string","format":"uuid","description":"Custom attribute definition ID"},"attributeName":{"type":["string","null"],"description":"Attribute name","example":"Priority"},"attributeType":{"type":["string","null"],"description":"Attribute type (text_line, options, number, date, etc.)","example":"options"},"values":{"type":"array","items":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"object","properties":{"optionId":{"type":"string","format":"uuid","description":"Selected option ID"},"optionValue":{"type":["string","null"],"description":"Selected option label","example":"Yes"}},"required":["optionId","optionValue"]}]},"description":"Values for this attribute. For \"options\" attributes each entry is { optionId, optionValue } and the array supports multi-select. For text/number/date attributes each entry is the typed value."}},"required":["attributeId","attributeName","attributeType","values"]}},"enrichmentStatus":{"type":"string","enum":["none","in_progress","failed","completed"],"description":"State of the most recent enrichment: `none` (never enriched), `in_progress`, `completed` or `failed`. Poll this after POST /api/v1/people/{id}/enrich.","example":"none"},"createdAt":{"type":"string","description":"When this person was created"},"updatedAt":{"type":"string","description":"When this person was last updated"},"merged":{"type":["object","null"],"properties":{"fromId":{"type":"string","format":"uuid","description":"The originally requested ID that was merged"},"toId":{"type":"string","format":"uuid","description":"The surviving (target) person ID returned in this response"}},"required":["fromId","toId"],"description":"Set when the requested ID was merged into another person. The response data is for the surviving person (toId)."}},"required":["id","firstName","lastName","middleName","isContact","companyContact","gender","source","identities","headline","address","experience","education","compensation","customAttributes","enrichmentStatus","createdAt","updatedAt","merged"]}},"required":["status","data"]}}}},"401":{"description":"Unauthorized - missing or invalid API key","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["error"]},"error":{"type":"string","description":"Human-readable error message"}},"required":["status","error"]},"example":{"status":"error","error":"Unauthorized"}}}},"404":{"description":"Person not found","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["error"]},"error":{"type":"string","description":"Human-readable error message"}},"required":["status","error"]},"example":{"status":"error","error":"Not found"}}}},"422":{"description":"Validation error - the request body or query parameters failed validation","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["error"]},"errors":{"type":"object","properties":{"formErrors":{"type":"array","items":{"type":"string"},"description":"Top-level validation errors"},"fieldErrors":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Per-field validation errors keyed by field name"}},"required":["formErrors","fieldErrors"]}},"required":["status","errors"]},"example":{"status":"error","errors":{"formErrors":[],"fieldErrors":{"email":["Invalid email"]}}}}}},"429":{"description":"Too many requests - the caller has exceeded the per-agency rate limit for the tier this endpoint counts against (default per minute: 1200 read / 400 write / 60 upload). Inspect the `RateLimit-*` headers — returned on every response, not only on 429s — and back off until the window resets. See the \"Rate limits\" section of the introduction for details.","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}},"content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["error"]},"error":{"type":"string","description":"Human-readable error message"},"tier":{"type":"string","enum":["read","write","upload"],"description":"The rate-limit tier whose quota was exceeded. GET endpoints count against `read`, POST/PUT/PATCH/DELETE against `write`, and multipart file uploads against `upload` — each tier has an independent counter."},"retryAfterSec":{"type":"integer","description":"Number of seconds after which the rate-limit window resets and requests will be accepted again. Prefer this (or the `RateLimit-Reset` header) over the `Retry-After` header, which is not guaranteed to be present."}},"required":["status","error","tier","retryAfterSec"]},"example":{"status":"error","error":"Rate limit exceeded","tier":"read","retryAfterSec":60}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["error"]},"error":{"type":"string","description":"Human-readable error message"}},"required":["status","error"]},"example":{"status":"error","error":"Internal Server error"}}}}}},"patch":{"summary":"Update a person","description":"Use this endpoint to update an existing person in your Atlas account.\n\nThis endpoint changes **only the parts of a person that are applied immediately** — fields on the person record (name, gender, headline, location, source), their contact details (identities), and their custom attribute values. Work experience, education, compensation and the company-contact flag are **not** handled here — set them on `POST /api/v1/people` (experience, education and compensation are created via background jobs there; the company-contact link is created synchronously).\n\nEvery field is optional — send only what you want to change. An omitted field is left untouched; sending `null` on a nullable field clears it. At least one updatable field must be present.\n\n**Identities are additive.** Any identities you send are *added* to the person — existing ones are never removed. An identity already on this person is ignored; an identity that belongs to a **different** person fails with **409 Conflict** (`conflictType: \"identity\"`) and returns that person's `personId`. Updating identities requires `addedByEmail` (the acting user).\n\n**`source.externalId` uniqueness.** A `(source.system, source.externalId)` pair is unique within your agency. Setting `source` to a pair that already belongs to a **different** person fails with **409 Conflict** (`conflictType: \"externalId\"`) and returns that person's `personId` — even when no identities are supplied. Re-sending the pair already stored on the person being updated is fine.\n\n**Custom attributes are replaced per attribute.** For every `customAttributeId` you send, the person's existing values for that attribute are removed and the supplied ones written. Attributes you don't mention are left as-is. (Clearing an attribute by sending it empty is not supported here.)\n\n**Attribution.** `addedByEmail` is optional and records which Atlas user made the change; if omitted the update is unattributed (but is required when changing identities).","tags":["People"],"security":[{"BearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid","description":"Atlas person ID","example":"123e4567-e89b-12d3-a456-426614174000"},"required":true,"name":"id","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdatePersonPayload"}}}},"responses":{"200":{"description":"Person updated. All changes are applied synchronously.","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["ok"]},"data":{"type":"object","properties":{"personId":{"type":"string","format":"uuid"},"identitiesAdded":{"type":"integer","description":"New identities added synchronously"},"customAttributesReplaced":{"type":"integer","description":"Custom attribute value rows written (after per-attribute replace)"}},"required":["personId","identitiesAdded","customAttributesReplaced"]}},"required":["status","data"]}}}},"401":{"description":"Unauthorized - missing or invalid API key","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["error"]},"error":{"type":"string","description":"Human-readable error message"}},"required":["status","error"]},"example":{"status":"error","error":"Unauthorized"}}}},"404":{"description":"Person not found, the provided addedByEmail matches no user, or a referenced customAttribute / option does not exist.","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["error"]},"error":{"type":"string","description":"Human-readable error message"}},"required":["status","error"]},"example":{"status":"error","error":"Not found"}}}},"409":{"description":"One of the supplied identities — or the supplied (source.system, source.externalId) pair — already belongs to a **different** person in this agency. `conflictType` says which rule matched (`identity` vs `externalId`) and the `error` message differs accordingly; `personId` is the conflicting person. Values already on the person being updated never conflict.","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["error"]},"error":{"type":"string","description":"Human-readable conflict explanation. Distinct per rule: identity conflicts return \"A person with one of the supplied identities already exists\"; (source.system, source.externalId) conflicts return \"A person with the same (source.system, source.externalId) pair already exists\".","example":"A person with one of the supplied identities already exists"},"conflictType":{"type":"string","enum":["identity","externalId"],"description":"Which uniqueness rule matched: `externalId` — the (source.system, source.externalId) pair already belongs to a person; `identity` — an email / LinkedIn URL / phone number already belongs to a person. When both would match, `externalId` wins (it is checked first).","example":"identity"},"personId":{"type":"string","format":"uuid","description":"ID of the existing person that conflicted. Use it with GET /api/v1/people/{id} or PATCH /api/v1/people/{id}."}},"required":["status","error","conflictType","personId"]}}}},"422":{"description":"Validation error - the request body or query parameters failed validation","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["error"]},"errors":{"type":"object","properties":{"formErrors":{"type":"array","items":{"type":"string"},"description":"Top-level validation errors"},"fieldErrors":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Per-field validation errors keyed by field name"}},"required":["formErrors","fieldErrors"]}},"required":["status","errors"]},"example":{"status":"error","errors":{"formErrors":[],"fieldErrors":{"email":["Invalid email"]}}}}}},"429":{"description":"Too many requests - the caller has exceeded the per-agency rate limit for the tier this endpoint counts against (default per minute: 1200 read / 400 write / 60 upload). Inspect the `RateLimit-*` headers — returned on every response, not only on 429s — and back off until the window resets. See the \"Rate limits\" section of the introduction for details.","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}},"content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["error"]},"error":{"type":"string","description":"Human-readable error message"},"tier":{"type":"string","enum":["read","write","upload"],"description":"The rate-limit tier whose quota was exceeded. GET endpoints count against `read`, POST/PUT/PATCH/DELETE against `write`, and multipart file uploads against `upload` — each tier has an independent counter."},"retryAfterSec":{"type":"integer","description":"Number of seconds after which the rate-limit window resets and requests will be accepted again. Prefer this (or the `RateLimit-Reset` header) over the `Retry-After` header, which is not guaranteed to be present."}},"required":["status","error","tier","retryAfterSec"]},"example":{"status":"error","error":"Rate limit exceeded","tier":"read","retryAfterSec":60}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["error"]},"error":{"type":"string","description":"Human-readable error message"}},"required":["status","error"]},"example":{"status":"error","error":"Internal Server error"}}}}}}},"/api/v1/people/{id}/experiences":{"post":{"summary":"Add a work experience to a person","description":"Use this endpoint to add a single work-experience entry to an existing person.\n\nProvide the company name (and optionally its website domain and/or LinkedIn company id) — Atlas resolves or creates the matching Company and links it. A domain/LinkedIn match links to that Company even when the supplied name differs. Supplying `companyId` instead links the exact existing Company and skips matching entirely. The role, start date, and (optionally) end date and description complete the entry.\n\nUnlike the bulk experience data on `POST /api/v1/people` (which is created asynchronously), this endpoint creates the experience **synchronously** and returns it. Adding an experience recalculates the person's headline.","tags":["People"],"security":[{"BearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid","description":"Atlas person ID","example":"123e4567-e89b-12d3-a456-426614174000"},"required":true,"name":"id","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"companyName":{"type":"string","minLength":1,"maxLength":255,"description":"Company name","example":"Dunder Mifflin"},"companyId":{"type":["string","null"],"format":"uuid","description":"Atlas company ID to link this experience to an existing company. When provided, no new company is created and name/domain/LinkedIn matching is skipped. On update, an explicit `null` unlinks the company; when present (id or null) it takes precedence over `companyName` matching.","example":"550e8400-e29b-41d4-a716-446655440000"},"companyLinkedinId":{"type":["string","null"],"minLength":1,"maxLength":255,"description":"Company LinkedIn ID","example":"12345678"},"companyDomain":{"type":["string","null"],"minLength":1,"maxLength":255,"description":"Company website domain (bare domain; full URLs are accepted and normalized to their hostname)","example":"dundermifflin.com"},"role":{"type":"string","minLength":1,"maxLength":255,"description":"Job title/role","example":"Regional Manager"},"description":{"type":["string","null"],"minLength":1,"maxLength":16384,"description":"Role description","example":"Responsible for managing Scranton branch."},"startDate":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Start date (YYYY-MM-DD)","example":"2021-04-01"},"endDate":{"type":["string","null"],"pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"End date (YYYY-MM-DD, null = current)","example":null}},"required":["companyName","role","startDate"]}}}},"responses":{"201":{"description":"Experience created","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["ok"]},"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"companyName":{"type":"string","example":"Dunder Mifflin"},"companyId":{"type":["string","null"],"format":"uuid","example":"550e8400-e29b-41d4-a716-446655440000"},"companyLinkedinId":{"type":["string","null"],"example":"12345678"},"companyDomain":{"type":["string","null"],"example":"dundermifflin.com"},"role":{"type":"string","example":"Regional Manager"},"description":{"type":["string","null"]},"startDate":{"type":["string","null"],"example":"2021-04-01"},"endDate":{"type":["string","null"],"example":null}},"required":["id","companyName","companyId","companyLinkedinId","companyDomain","role","description","startDate","endDate"]}},"required":["status","data"]}}}},"401":{"description":"Unauthorized - missing or invalid API key","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["error"]},"error":{"type":"string","description":"Human-readable error message"}},"required":["status","error"]},"example":{"status":"error","error":"Unauthorized"}}}},"404":{"description":"Person not found","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["error"]},"error":{"type":"string","description":"Human-readable error message"}},"required":["status","error"]},"example":{"status":"error","error":"Not found"}}}},"422":{"description":"Validation error - the request body or query parameters failed validation","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["error"]},"errors":{"type":"object","properties":{"formErrors":{"type":"array","items":{"type":"string"},"description":"Top-level validation errors"},"fieldErrors":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Per-field validation errors keyed by field name"}},"required":["formErrors","fieldErrors"]}},"required":["status","errors"]},"example":{"status":"error","errors":{"formErrors":[],"fieldErrors":{"email":["Invalid email"]}}}}}},"429":{"description":"Too many requests - the caller has exceeded the per-agency rate limit for the tier this endpoint counts against (default per minute: 1200 read / 400 write / 60 upload). Inspect the `RateLimit-*` headers — returned on every response, not only on 429s — and back off until the window resets. See the \"Rate limits\" section of the introduction for details.","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}},"content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["error"]},"error":{"type":"string","description":"Human-readable error message"},"tier":{"type":"string","enum":["read","write","upload"],"description":"The rate-limit tier whose quota was exceeded. GET endpoints count against `read`, POST/PUT/PATCH/DELETE against `write`, and multipart file uploads against `upload` — each tier has an independent counter."},"retryAfterSec":{"type":"integer","description":"Number of seconds after which the rate-limit window resets and requests will be accepted again. Prefer this (or the `RateLimit-Reset` header) over the `Retry-After` header, which is not guaranteed to be present."}},"required":["status","error","tier","retryAfterSec"]},"example":{"status":"error","error":"Rate limit exceeded","tier":"read","retryAfterSec":60}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["error"]},"error":{"type":"string","description":"Human-readable error message"}},"required":["status","error"]},"example":{"status":"error","error":"Internal Server error"}}}}}}},"/api/v1/people/{id}/experiences/{experienceId}":{"patch":{"summary":"Update a person’s work experience","description":"Use this endpoint to update a single work-experience entry. Every field is optional — send only what you want to change; at least one field is required. Supplying `companyName` (with optional `companyDomain`/`companyLinkedinId`) re-resolves and re-links the Company — a domain/LinkedIn match wins even when the name differs; supplying `companyId` links the exact existing Company and skips matching. Updating an experience recalculates the person's headline.","tags":["People"],"security":[{"BearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid","description":"Atlas person ID","example":"123e4567-e89b-12d3-a456-426614174000"},"required":true,"name":"id","in":"path"},{"schema":{"type":"string","format":"uuid","description":"Experience ID","example":"7c9e6679-7425-40de-944b-e07fc1f90ae7"},"required":true,"name":"experienceId","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateExperiencePayload"}}}},"responses":{"200":{"description":"Experience updated","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["ok"]},"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"companyName":{"type":"string","example":"Dunder Mifflin"},"companyId":{"type":["string","null"],"format":"uuid","example":"550e8400-e29b-41d4-a716-446655440000"},"companyLinkedinId":{"type":["string","null"],"example":"12345678"},"companyDomain":{"type":["string","null"],"example":"dundermifflin.com"},"role":{"type":"string","example":"Regional Manager"},"description":{"type":["string","null"]},"startDate":{"type":["string","null"],"example":"2021-04-01"},"endDate":{"type":["string","null"],"example":null}},"required":["id","companyName","companyId","companyLinkedinId","companyDomain","role","description","startDate","endDate"]}},"required":["status","data"]}}}},"401":{"description":"Unauthorized - missing or invalid API key","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["error"]},"error":{"type":"string","description":"Human-readable error message"}},"required":["status","error"]},"example":{"status":"error","error":"Unauthorized"}}}},"404":{"description":"Person or experience not found","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["error"]},"error":{"type":"string","description":"Human-readable error message"}},"required":["status","error"]},"example":{"status":"error","error":"Not found"}}}},"422":{"description":"Validation error - the request body or path parameters failed validation. This includes the date-order rule, which is checked against the stored record: sending only `startDate` (or only `endDate`) fails with an `endDate` field error when the resulting range would end before it starts.","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["error"]},"errors":{"type":"object","properties":{"formErrors":{"type":"array","items":{"type":"string"},"description":"Top-level validation errors"},"fieldErrors":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Per-field validation errors keyed by field name"}},"required":["formErrors","fieldErrors"]}},"required":["status","errors"]},"example":{"status":"error","errors":{"formErrors":[],"fieldErrors":{"email":["Invalid email"]}}}}}},"429":{"description":"Too many requests - the caller has exceeded the per-agency rate limit for the tier this endpoint counts against (default per minute: 1200 read / 400 write / 60 upload). Inspect the `RateLimit-*` headers — returned on every response, not only on 429s — and back off until the window resets. See the \"Rate limits\" section of the introduction for details.","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}},"content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["error"]},"error":{"type":"string","description":"Human-readable error message"},"tier":{"type":"string","enum":["read","write","upload"],"description":"The rate-limit tier whose quota was exceeded. GET endpoints count against `read`, POST/PUT/PATCH/DELETE against `write`, and multipart file uploads against `upload` — each tier has an independent counter."},"retryAfterSec":{"type":"integer","description":"Number of seconds after which the rate-limit window resets and requests will be accepted again. Prefer this (or the `RateLimit-Reset` header) over the `Retry-After` header, which is not guaranteed to be present."}},"required":["status","error","tier","retryAfterSec"]},"example":{"status":"error","error":"Rate limit exceeded","tier":"read","retryAfterSec":60}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["error"]},"error":{"type":"string","description":"Human-readable error message"}},"required":["status","error"]},"example":{"status":"error","error":"Internal Server error"}}}}}},"delete":{"summary":"Delete a person’s work experience","description":"Use this endpoint to remove a single work-experience entry from a person. Deleting an experience recalculates the person's headline.","tags":["People"],"security":[{"BearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid","description":"Atlas person ID","example":"123e4567-e89b-12d3-a456-426614174000"},"required":true,"name":"id","in":"path"},{"schema":{"type":"string","format":"uuid","description":"Experience ID","example":"7c9e6679-7425-40de-944b-e07fc1f90ae7"},"required":true,"name":"experienceId","in":"path"}],"responses":{"200":{"description":"Experience deleted","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["ok"]},"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"}},"required":["id"]}},"required":["status","data"]}}}},"401":{"description":"Unauthorized - missing or invalid API key","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["error"]},"error":{"type":"string","description":"Human-readable error message"}},"required":["status","error"]},"example":{"status":"error","error":"Unauthorized"}}}},"404":{"description":"Person or experience not found","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["error"]},"error":{"type":"string","description":"Human-readable error message"}},"required":["status","error"]},"example":{"status":"error","error":"Not found"}}}},"422":{"description":"Validation error - the request body or query parameters failed validation","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["error"]},"errors":{"type":"object","properties":{"formErrors":{"type":"array","items":{"type":"string"},"description":"Top-level validation errors"},"fieldErrors":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Per-field validation errors keyed by field name"}},"required":["formErrors","fieldErrors"]}},"required":["status","errors"]},"example":{"status":"error","errors":{"formErrors":[],"fieldErrors":{"email":["Invalid email"]}}}}}},"429":{"description":"Too many requests - the caller has exceeded the per-agency rate limit for the tier this endpoint counts against (default per minute: 1200 read / 400 write / 60 upload). Inspect the `RateLimit-*` headers — returned on every response, not only on 429s — and back off until the window resets. See the \"Rate limits\" section of the introduction for details.","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}},"content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["error"]},"error":{"type":"string","description":"Human-readable error message"},"tier":{"type":"string","enum":["read","write","upload"],"description":"The rate-limit tier whose quota was exceeded. GET endpoints count against `read`, POST/PUT/PATCH/DELETE against `write`, and multipart file uploads against `upload` — each tier has an independent counter."},"retryAfterSec":{"type":"integer","description":"Number of seconds after which the rate-limit window resets and requests will be accepted again. Prefer this (or the `RateLimit-Reset` header) over the `Retry-After` header, which is not guaranteed to be present."}},"required":["status","error","tier","retryAfterSec"]},"example":{"status":"error","error":"Rate limit exceeded","tier":"read","retryAfterSec":60}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["error"]},"error":{"type":"string","description":"Human-readable error message"}},"required":["status","error"]},"example":{"status":"error","error":"Internal Server error"}}}}}}},"/api/v1/people/{personId}/identities":{"get":{"summary":"Get identities for a person","description":"Use this endpoint to retrieve all contact details (known as \"identities\") stored against a specific person in Atlas.\n\nIn Atlas, a person can have multiple ways of being contacted - for example, two email addresses, a mobile number, and a LinkedIn profile. Each of these is stored as a separate \"identity\". This endpoint returns all of them for a given person.\n\nTo use it, you need the person's Atlas ID (a unique identifier, returned by other endpoints like Search or Lookup). You can optionally filter the results to only return a specific type - for example, only phone numbers or only emails.\n\nEach identity returned includes its type (e.g. `email`, `phone`, `linkedin`), its value (e.g. `john@example.com`), and whether it is currently active.","tags":["People"],"security":[{"BearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid","description":"Person ID","example":"123e4567-e89b-12d3-a456-426614174000"},"required":true,"name":"personId","in":"path"},{"schema":{"type":"string","minLength":1,"description":"Comma-separated identity types to filter by","example":"email,phone"},"required":false,"name":"type","in":"query"}],"responses":{"200":{"description":"Person identities","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["ok"]},"data":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string"},"value":{"type":"string"},"active":{"type":"boolean"}},"required":["type","value","active"]}}},"required":["status","data"]}}}},"401":{"description":"Unauthorized - missing or invalid API key","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["error"]},"error":{"type":"string","description":"Human-readable error message"}},"required":["status","error"]},"example":{"status":"error","error":"Unauthorized"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["error"]},"error":{"type":"string","description":"Human-readable error message"}},"required":["status","error"]},"example":{"status":"error","error":"Not found"}}}},"422":{"description":"Validation error - the request body or query parameters failed validation","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["error"]},"errors":{"type":"object","properties":{"formErrors":{"type":"array","items":{"type":"string"},"description":"Top-level validation errors"},"fieldErrors":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Per-field validation errors keyed by field name"}},"required":["formErrors","fieldErrors"]}},"required":["status","errors"]},"example":{"status":"error","errors":{"formErrors":[],"fieldErrors":{"email":["Invalid email"]}}}}}},"429":{"description":"Too many requests - the caller has exceeded the per-agency rate limit for the tier this endpoint counts against (default per minute: 1200 read / 400 write / 60 upload). Inspect the `RateLimit-*` headers — returned on every response, not only on 429s — and back off until the window resets. See the \"Rate limits\" section of the introduction for details.","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}},"content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["error"]},"error":{"type":"string","description":"Human-readable error message"},"tier":{"type":"string","enum":["read","write","upload"],"description":"The rate-limit tier whose quota was exceeded. GET endpoints count against `read`, POST/PUT/PATCH/DELETE against `write`, and multipart file uploads against `upload` — each tier has an independent counter."},"retryAfterSec":{"type":"integer","description":"Number of seconds after which the rate-limit window resets and requests will be accepted again. Prefer this (or the `RateLimit-Reset` header) over the `Retry-After` header, which is not guaranteed to be present."}},"required":["status","error","tier","retryAfterSec"]},"example":{"status":"error","error":"Rate limit exceeded","tier":"read","retryAfterSec":60}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["error"]},"error":{"type":"string","description":"Human-readable error message"}},"required":["status","error"]},"example":{"status":"error","error":"Internal Server error"}}}}}}},"/api/v1/people/notes":{"put":{"summary":"Create a note on a person","description":"Use this endpoint to add a written note to a person's record in Atlas.\n\nNotes are a way of recording important context about a candidate or contact - for example, a summary of a phone call, a reminder about their availability, or any other information you want to log against them.\n\n**Identifying the person:**\nProvide exactly one of:\n- `email` - the person's email address. Atlas finds the person by matching against their stored email identities.\n- `personId` - the Atlas person ID. Atlas looks the person up directly within your agency.\n- `linkedinUrl` - the person's LinkedIn profile URL. Atlas normalises the URL (stripping protocol, `www.`, trailing slash, case) before matching against the person's stored LinkedIn identity. Public profile (`linkedin.com/in/...`), Talent/Recruiter, and Sales Navigator URLs are all supported.\n- `phone` - the person's phone number. Atlas matches against stored phone identities across common formatting variations. The number must map to exactly one person; if it is ambiguous (matches more than one person) the request returns 404 and you should use `personId` instead.\n\nIf zero or more than one identifier is supplied, the request is rejected with a 422 validation error.\n\n**Identifying the note author:**\n- `ownerEmail` - the email address of the Atlas user the note should be attributed to.\n\n**What you also provide:**\n- The text content of the note (`note`)\n- `projectId` (optional) - an Atlas project ID to scope the note to that person's candidacy on the project, the same way a note added from a project's candidate drawer is scoped inside Atlas. When set, the note shows only on that project's candidate drawer; when omitted the note is person-level and shows everywhere. A `projectId` that does not exist in your agency is rejected with a 404.\n\nThe note will be created as type `manual` and will appear on that person's timeline inside Atlas, visible to your team.","tags":["People"],"security":[{"BearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateNotePayload"}}}},"responses":{"201":{"description":"Note created","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["ok"]},"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"text":{"type":"string"},"type":{"type":"string","enum":["manual","phone_call"]},"personId":{"type":"string","format":"uuid"},"projectId":{"type":["string","null"],"format":"uuid","description":"Project the note is scoped to (candidacy note), or null for a person-level note. Echoes the projectId from the request."},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","text","type","personId","projectId","createdAt","updatedAt"]}},"required":["status","data"]}}}},"401":{"description":"Unauthorized - missing or invalid API key","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["error"]},"error":{"type":"string","description":"Human-readable error message"}},"required":["status","error"]},"example":{"status":"error","error":"Unauthorized"}}}},"404":{"description":"Person, user, or project not found","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["error"]},"error":{"type":"string","description":"Human-readable error message"}},"required":["status","error"]},"example":{"status":"error","error":"Not found"}}}},"422":{"description":"Validation error - the request body or query parameters failed validation","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["error"]},"errors":{"type":"object","properties":{"formErrors":{"type":"array","items":{"type":"string"},"description":"Top-level validation errors"},"fieldErrors":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Per-field validation errors keyed by field name"}},"required":["formErrors","fieldErrors"]}},"required":["status","errors"]},"example":{"status":"error","errors":{"formErrors":[],"fieldErrors":{"email":["Invalid email"]}}}}}},"429":{"description":"Too many requests - the caller has exceeded the per-agency rate limit for the tier this endpoint counts against (default per minute: 1200 read / 400 write / 60 upload). Inspect the `RateLimit-*` headers — returned on every response, not only on 429s — and back off until the window resets. See the \"Rate limits\" section of the introduction for details.","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}},"content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["error"]},"error":{"type":"string","description":"Human-readable error message"},"tier":{"type":"string","enum":["read","write","upload"],"description":"The rate-limit tier whose quota was exceeded. GET endpoints count against `read`, POST/PUT/PATCH/DELETE against `write`, and multipart file uploads against `upload` — each tier has an independent counter."},"retryAfterSec":{"type":"integer","description":"Number of seconds after which the rate-limit window resets and requests will be accepted again. Prefer this (or the `RateLimit-Reset` header) over the `Retry-After` header, which is not guaranteed to be present."}},"required":["status","error","tier","retryAfterSec"]},"example":{"status":"error","error":"Rate limit exceeded","tier":"read","retryAfterSec":60}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["error"]},"error":{"type":"string","description":"Human-readable error message"}},"required":["status","error"]},"example":{"status":"error","error":"Internal Server error"}}}}}},"get":{"summary":"List notes across the agency","description":"Use this endpoint to keep an external system in step with the notes your recruiters record against people in Atlas - for example, to report on business-development activity such as a logged BD call.\n\nThis is the agency-wide counterpart to `POST /api/v1/people/notes/lookup`. The lookup endpoint requires you to name the people you are interested in (up to 100 per request), which means an account with tens of thousands of contacts would need hundreds of calls per polling cycle. This endpoint instead returns every note in your agency, newest change first, so you can sync on a timestamp cursor and never send a person ID at all.\n\n**Keeping in sync (recommended pattern):**\n1. **Backfill once.** Page through the endpoint using `createdAfter` / `createdBefore` to walk your history in windows (for example a month at a time). Both bounds are inclusive and accept either a full ISO 8601 datetime or a date-only `YYYY-MM-DD` value.\n2. **Record your cursor.** Keep the highest `updatedAt` you have *fully* processed. Seed it with the time your backfill *started*, not the time it finished, so a note edited while the backfill was running is picked up by your first poll instead of being skipped.\n3. **Poll a closed window.** On each subsequent poll (every few minutes is fine) send `updatedAfter` set to your stored cursor *minus a small overlap* - a minute or two, to absorb clock skew and rows committed mid-request - together with `updatedBefore` set to the current time. Pinning the upper bound matters: paging is offset-based over an `updatedAt` descending sort, so without it a note edited while you are partway through the pages jumps to the top of the result set and pushes a row you have not read yet off the end of the page you are about to request. The overlap means you will occasionally re-receive a note you already have, so **de-duplicate on `id`** and treat a repeat as an update rather than a new note.\n4. **Drain every page of that window.** `pageSize` caps at 100, so any interval with more changes than that spans several pages - keep requesting `page` 2, 3, ... until you have read `totalPages`. Because the sort is newest change first, the later pages hold the *older* changes in the window: stopping after page 1 and advancing the cursor puts them permanently behind it.\n5. **Advance the cursor** to the `updatedBefore` you pinned in step 3, and only once every page of the window has been processed. If a poll fails part-way, leave the cursor untouched and re-run the same window - de-duplicating on `id` makes the replay harmless.\n\nA note that is edited gets a fresh `updatedAt`, so edits arrive through the same cursor as new notes. Notes that have not changed are not returned.\n\n**Picking up deletions:**\nDeleted notes are retained as tombstones. Pass `includeDeleted=true` and a soft-deleted note comes back with its `deletedAt` populated (it is `null` for live notes); deleting a note also bumps its `updatedAt`, so deletions flow through your `updatedAfter` cursor alongside creations and edits. Without the flag, only live notes are returned.\n\n**Optional narrowing:**\n- `type` - comma-separated note types. `manual` is a note typed by a user, `phone_call` is a note logged against a call (these also carry a `phoneCallOutcome`), and `integration` is a note written by an inbound integration rather than a person.\n- `personId` - restrict to a single person, for drill-down. Leave it off for the sync path.\n\n**What you get back:**\nA paginated list of notes sorted by `updatedAt` descending, then by `id`. Each note includes its text, type, the person it belongs to, the project it is scoped to (`projectId` - set when the note was added against the person's candidacy on a specific project, null for a person-level note), the author (id, name, email), `phoneCallOutcome` where the note came from a logged call, and its timestamps.\n\nResults are always scoped to your agency, and an empty result set is a successful response with an empty `data` array, not an error.","tags":["People"],"security":[{"BearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid","description":"Drill down to the notes of a single person. Omit to list notes across the whole agency (the incremental-sync path).","example":"550e8400-e29b-41d4-a716-446655440000"},"required":false,"name":"personId","in":"query"},{"schema":{"type":"string","description":"Comma-separated note types to include. One or more of: phone_call, manual, integration. Defaults to all types.","example":"phone_call"},"required":false,"name":"type","in":"query"},{"schema":{"anyOf":[{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},{"type":"string","format":"date-time"}],"description":"Only notes created after this point (inclusive). Accepts an ISO 8601 datetime or a date-only YYYY-MM-DD value (covering from the start of that UTC day)","example":"2025-01-01"},"required":false,"name":"createdAfter","in":"query"},{"schema":{"anyOf":[{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},{"type":"string","format":"date-time"}],"description":"Only notes created before this point (inclusive). Accepts an ISO 8601 datetime or a date-only YYYY-MM-DD value (covering through the end of that UTC day)","example":"2026-01-01"},"required":false,"name":"createdBefore","in":"query"},{"schema":{"anyOf":[{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},{"type":"string","format":"date-time"}],"description":"Only notes updated after this point (inclusive). Accepts an ISO 8601 datetime or a date-only YYYY-MM-DD value (covering from the start of that UTC day)","example":"2025-06-01"},"required":false,"name":"updatedAfter","in":"query"},{"schema":{"anyOf":[{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},{"type":"string","format":"date-time"}],"description":"Only notes updated before this point (inclusive). Accepts an ISO 8601 datetime or a date-only YYYY-MM-DD value (covering through the end of that UTC day)","example":"2026-06-01"},"required":false,"name":"updatedBefore","in":"query"},{"schema":{"type":"string","enum":["true","false"],"description":"Include soft-deleted notes as tombstones (with a populated `deletedAt`). Defaults to false. Pair with `updatedAfter` to incrementally sync deletions.","example":"false"},"required":false,"name":"includeDeleted","in":"query"},{"schema":{"type":"integer","minimum":1,"default":1,"description":"Page number (1-indexed)","example":1},"required":false,"name":"page","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":100,"description":"Items per page (max 100)","example":25},"required":false,"name":"pageSize","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":100,"description":"Alias for pageSize","deprecated":true},"required":false,"name":"perPage","in":"query"}],"responses":{"200":{"description":"Paginated agency-wide notes, sorted by updatedAt descending","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["ok"]},"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"personId":{"type":"string","format":"uuid"},"projectId":{"type":["string","null"],"format":"uuid","description":"Project the note is scoped to, when it was added against the person’s candidacy on a specific project. Null for a person-level note."},"text":{"type":"string","example":"BD call - happy for us to send two profiles this week."},"type":{"type":"string","enum":["manual","phone_call","integration"],"example":"phone_call"},"phoneCallOutcome":{"type":["string","null"],"enum":["no_answer","interested","not_interested","replied"],"description":"Outcome when the note came from a logged phone call, otherwise null"},"createdBy":{"type":["object","null"],"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string","example":"Sarah Johnson"},"email":{"type":["string","null"],"example":"sarah@agency.com"}},"required":["id","name","email"],"description":"Note author, or null if the author can no longer be resolved"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"deletedAt":{"type":["string","null"],"format":"date-time","description":"When the note was deleted, or null if it is live. Only ever non-null when the request passed includeDeleted=true."}},"required":["id","personId","projectId","text","type","phoneCallOutcome","createdBy","createdAt","updatedAt","deletedAt"]}},"pagination":{"type":"object","properties":{"page":{"type":"integer","description":"Current page number","example":1},"pageSize":{"type":"integer","description":"Items per page","example":100},"total":{"type":"integer","description":"Total matching notes","example":1},"totalPages":{"type":"integer","description":"Total number of pages","example":1}},"required":["page","pageSize","total","totalPages"]}},"required":["status","data","pagination"]},"example":{"status":"ok","data":[{"id":"f47ac10b-58cc-4372-a567-0e02b2c3d479","personId":"a1b2c3d4-e5f6-7890-abcd-ef1234567890","projectId":null,"text":"BD call - happy for us to send two profiles this week.","type":"phone_call","phoneCallOutcome":"interested","createdBy":{"id":"c3d4e5f6-a7b8-9012-cdef-123456789012","name":"Sarah Johnson","email":"sarah@agency.com"},"createdAt":"2026-06-15T14:30:00.000Z","updatedAt":"2026-06-15T14:30:00.000Z","deletedAt":null}],"pagination":{"page":1,"pageSize":100,"total":1,"totalPages":1}}}}},"401":{"description":"Unauthorized - missing or invalid API key","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["error"]},"error":{"type":"string","description":"Human-readable error message"}},"required":["status","error"]},"example":{"status":"error","error":"Unauthorized"}}}},"422":{"description":"Validation error - the request body or query parameters failed validation","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["error"]},"errors":{"type":"object","properties":{"formErrors":{"type":"array","items":{"type":"string"},"description":"Top-level validation errors"},"fieldErrors":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Per-field validation errors keyed by field name"}},"required":["formErrors","fieldErrors"]}},"required":["status","errors"]},"example":{"status":"error","errors":{"formErrors":[],"fieldErrors":{"email":["Invalid email"]}}}}}},"429":{"description":"Too many requests - the caller has exceeded the per-agency rate limit for the tier this endpoint counts against (default per minute: 1200 read / 400 write / 60 upload). Inspect the `RateLimit-*` headers — returned on every response, not only on 429s — and back off until the window resets. See the \"Rate limits\" section of the introduction for details.","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}},"content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["error"]},"error":{"type":"string","description":"Human-readable error message"},"tier":{"type":"string","enum":["read","write","upload"],"description":"The rate-limit tier whose quota was exceeded. GET endpoints count against `read`, POST/PUT/PATCH/DELETE against `write`, and multipart file uploads against `upload` — each tier has an independent counter."},"retryAfterSec":{"type":"integer","description":"Number of seconds after which the rate-limit window resets and requests will be accepted again. Prefer this (or the `RateLimit-Reset` header) over the `Retry-After` header, which is not guaranteed to be present."}},"required":["status","error","tier","retryAfterSec"]},"example":{"status":"error","error":"Rate limit exceeded","tier":"read","retryAfterSec":60}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["error"]},"error":{"type":"string","description":"Human-readable error message"}},"required":["status","error"]},"example":{"status":"error","error":"Internal Server error"}}}}}}},"/api/v1/people/notes/lookup":{"post":{"summary":"Look up notes for people","description":"Use this endpoint to retrieve the notes recorded against one or more people in your Atlas account - for example, to build an activity report, populate a dashboard, or sync recruiter activity into another system.\n\nUnlike the create-note endpoint (`PUT /api/v1/people/notes`), this is a read-only endpoint. You send a list of person IDs (up to 100 at a time) and, optionally, a date range, and Atlas returns every matching note - including who wrote it and when.\n\n**What you provide:**\n- `personIds` - the Atlas person IDs whose notes you want (1-100).\n- `createdAfter` / `createdBefore` - optional ISO 8601 timestamps to restrict the notes to a date range. Both bounds are **inclusive**.\n- `page` / `pageSize` - optional pagination controls (`pageSize` defaults to 100, maximum 100).\n\n**What you get back:**\nA paginated list of notes sorted by creation date, newest first. Each note includes its text, type, the person it belongs to, the project it is scoped to (`projectId` - set when the note was added against the person's candidacy on a specific project, null for a person-level note), the author (id, name, email), and timestamps. A note created from a logged phone call also includes the `phoneCallOutcome`; for manually-written notes this is `null`.\n\nResults are always scoped to your agency - person IDs that belong to another agency simply return no notes. An empty result set is a successful response with an empty `data` array, not an error.","tags":["People"],"security":[{"BearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"personIds":{"type":"array","items":{"type":"string","format":"uuid"},"minItems":1,"maxItems":100,"description":"Atlas person IDs to fetch notes for (minimum 1, maximum 100).","example":["a1b2c3d4-e5f6-7890-abcd-ef1234567890","b2c3d4e5-f6a7-8901-bcde-f12345678901"]},"createdAfter":{"anyOf":[{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},{"type":"string","format":"date-time"}],"description":"Only notes created after this point (inclusive). Accepts an ISO 8601 datetime or a date-only YYYY-MM-DD value (covering from the start of that UTC day)","example":"2025-01-01"},"createdBefore":{"anyOf":[{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},{"type":"string","format":"date-time"}],"description":"Only notes created before this point (inclusive). Accepts an ISO 8601 datetime or a date-only YYYY-MM-DD value (covering through the end of that UTC day)","example":"2026-01-01"},"page":{"type":"integer","minimum":1,"default":1,"description":"Page number (1-indexed)","example":1},"pageSize":{"type":"integer","minimum":1,"maximum":100,"description":"Items per page (max 100)","example":25},"perPage":{"type":"integer","minimum":1,"maximum":100,"description":"Alias for pageSize","deprecated":true}},"required":["personIds"]}}}},"responses":{"200":{"description":"Paginated notes for the requested people, sorted by createdAt descending","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["ok"]},"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"personId":{"type":"string","format":"uuid"},"projectId":{"type":["string","null"],"format":"uuid","description":"Project the note is scoped to, when it was added against the person’s candidacy on a specific project. Null for a person-level note."},"text":{"type":"string","example":"Spoke with candidate. Very interested in the senior role."},"type":{"type":"string","enum":["manual","phone_call"],"example":"manual"},"phoneCallOutcome":{"type":["string","null"],"enum":["no_answer","interested","not_interested","replied"],"description":"Outcome when the note came from a logged phone call, otherwise null"},"createdBy":{"type":["object","null"],"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string","example":"Sarah Johnson"},"email":{"type":["string","null"],"example":"sarah@agency.com"}},"required":["id","name","email"],"description":"Note author, or null if the author can no longer be resolved"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","personId","projectId","text","type","phoneCallOutcome","createdBy","createdAt","updatedAt"]}},"pagination":{"type":"object","properties":{"page":{"type":"integer","description":"Current page number","example":1},"pageSize":{"type":"integer","description":"Items per page","example":50},"total":{"type":"integer","description":"Total matching notes","example":1},"totalPages":{"type":"integer","description":"Total number of pages","example":1}},"required":["page","pageSize","total","totalPages"]}},"required":["status","data","pagination"]},"example":{"status":"ok","data":[{"id":"f47ac10b-58cc-4372-a567-0e02b2c3d479","personId":"a1b2c3d4-e5f6-7890-abcd-ef1234567890","projectId":"9f8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d","text":"Spoke with candidate. Very interested in the senior role.","type":"manual","phoneCallOutcome":null,"createdBy":{"id":"c3d4e5f6-a7b8-9012-cdef-123456789012","name":"Sarah Johnson","email":"sarah@agency.com"},"createdAt":"2025-06-15T14:30:00.000Z","updatedAt":"2025-06-15T14:30:00.000Z"}],"pagination":{"page":1,"pageSize":50,"total":1,"totalPages":1}}}}},"401":{"description":"Unauthorized - missing or invalid API key","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["error"]},"error":{"type":"string","description":"Human-readable error message"}},"required":["status","error"]},"example":{"status":"error","error":"Unauthorized"}}}},"422":{"description":"Validation error - the request body or query parameters failed validation","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["error"]},"errors":{"type":"object","properties":{"formErrors":{"type":"array","items":{"type":"string"},"description":"Top-level validation errors"},"fieldErrors":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Per-field validation errors keyed by field name"}},"required":["formErrors","fieldErrors"]}},"required":["status","errors"]},"example":{"status":"error","errors":{"formErrors":[],"fieldErrors":{"email":["Invalid email"]}}}}}},"429":{"description":"Too many requests - the caller has exceeded the per-agency rate limit for the tier this endpoint counts against (default per minute: 1200 read / 400 write / 60 upload). Inspect the `RateLimit-*` headers — returned on every response, not only on 429s — and back off until the window resets. See the \"Rate limits\" section of the introduction for details.","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}},"content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["error"]},"error":{"type":"string","description":"Human-readable error message"},"tier":{"type":"string","enum":["read","write","upload"],"description":"The rate-limit tier whose quota was exceeded. GET endpoints count against `read`, POST/PUT/PATCH/DELETE against `write`, and multipart file uploads against `upload` — each tier has an independent counter."},"retryAfterSec":{"type":"integer","description":"Number of seconds after which the rate-limit window resets and requests will be accepted again. Prefer this (or the `RateLimit-Reset` header) over the `Retry-After` header, which is not guaranteed to be present."}},"required":["status","error","tier","retryAfterSec"]},"example":{"status":"error","error":"Rate limit exceeded","tier":"read","retryAfterSec":60}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["error"]},"error":{"type":"string","description":"Human-readable error message"}},"required":["status","error"]},"example":{"status":"error","error":"Internal Server error"}}}}}}},"/api/v1/people/identities":{"get":{"summary":"Bulk identity feed for contact sync","description":"Use this endpoint to download a full list of contact details (phone numbers, email addresses, LinkedIn URLs, etc.) for everyone in your Atlas account - intended for syncing contacts into an external system such as a VOIP phone system or address book.\n\nFor example, a phone system integration could call this endpoint periodically to keep its contact list up to date, so that when a candidate calls in, their name automatically appears on screen.\n\n**How it works:**\n- Results are returned in the order they were added to Atlas (oldest first), making it easy to pick up only what's new since your last sync\n- You can filter by a `since` date to only fetch identities added or updated after a certain point\n- Results are paginated - if there are more results than fit in one response, `hasMore` will be `true` and you can fetch the next page\n\n**Important:** This feed is designed for background syncing and caching, not for real-time lookups. You may occasionally receive duplicate entries - your system should handle this by updating existing records rather than creating duplicates (known as an \"upsert\"). Use the `identityId` field as the unique key when doing so.","tags":["People"],"security":[{"BearerAuth":[]}],"parameters":[{"schema":{"type":"integer","minimum":1,"default":1,"description":"Page number (1-indexed)","example":1},"required":false,"name":"page","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":100,"description":"Items per page (max 100)","example":25},"required":false,"name":"pageSize","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":100,"description":"Alias for pageSize","deprecated":true},"required":false,"name":"perPage","in":"query"},{"schema":{"anyOf":[{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},{"type":"string","format":"date-time"}],"description":"Only identities created after this point (inclusive). Accepts an ISO 8601 datetime or a date-only YYYY-MM-DD value (covering from the start of that UTC day)","example":"2025-01-01"},"required":false,"name":"createdAfter","in":"query"},{"schema":{"anyOf":[{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},{"type":"string","format":"date-time"}],"description":"Only identities created before this point (inclusive). Accepts an ISO 8601 datetime or a date-only YYYY-MM-DD value (covering through the end of that UTC day)","example":"2026-01-01"},"required":false,"name":"createdBefore","in":"query"},{"schema":{"anyOf":[{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},{"type":"string","format":"date-time"}],"description":"Only identities updated after this point (inclusive). Accepts an ISO 8601 datetime or a date-only YYYY-MM-DD value (covering from the start of that UTC day)","example":"2025-06-01"},"required":false,"name":"updatedAfter","in":"query"},{"schema":{"anyOf":[{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},{"type":"string","format":"date-time"}],"description":"Only identities updated before this point (inclusive). Accepts an ISO 8601 datetime or a date-only YYYY-MM-DD value (covering through the end of that UTC day)","example":"2026-06-01"},"required":false,"name":"updatedBefore","in":"query"}],"responses":{"200":{"description":"Paginated list of contact identities","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["ok"]},"data":{"type":"array","items":{"type":"object","properties":{"identityId":{"type":"string","format":"uuid","description":"Identity ID"},"type":{"type":"string","description":"Identity type (email, phone, linkedin, etc.)","example":"phone"},"value":{"type":"string","description":"Identity value","example":"+447786267677"},"createdAt":{"type":"string","format":"date-time","description":"When the identity was created"},"updatedAt":{"type":"string","format":"date-time","description":"When the identity was last updated"},"person":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"firstName":{"type":["string","null"],"example":"Jordan"},"lastName":{"type":["string","null"],"example":"Shlosberg"}},"required":["id","firstName","lastName"]}},"required":["identityId","type","value","createdAt","updatedAt","person"]}},"page":{"type":"integer","description":"Use pagination.page instead","deprecated":true},"pageSize":{"type":"integer","description":"Use pagination.pageSize instead","deprecated":true},"hasMore":{"type":"boolean","description":"Use pagination instead","deprecated":true},"pagination":{"type":"object","properties":{"page":{"type":"integer","description":"Current page number","example":1},"pageSize":{"type":"integer","description":"Items per page","example":100},"total":{"type":"integer","description":"Total matching items","example":500},"totalPages":{"type":"integer","description":"Total number of pages","example":5}},"required":["page","pageSize","total","totalPages"]}},"required":["status","data","page","pageSize","hasMore","pagination"]}}}},"401":{"description":"Unauthorized - missing or invalid API key","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["error"]},"error":{"type":"string","description":"Human-readable error message"}},"required":["status","error"]},"example":{"status":"error","error":"Unauthorized"}}}},"422":{"description":"Validation error - the request body or query parameters failed validation","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["error"]},"errors":{"type":"object","properties":{"formErrors":{"type":"array","items":{"type":"string"},"description":"Top-level validation errors"},"fieldErrors":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Per-field validation errors keyed by field name"}},"required":["formErrors","fieldErrors"]}},"required":["status","errors"]},"example":{"status":"error","errors":{"formErrors":[],"fieldErrors":{"email":["Invalid email"]}}}}}},"429":{"description":"Too many requests - the caller has exceeded the per-agency rate limit for the tier this endpoint counts against (default per minute: 1200 read / 400 write / 60 upload). Inspect the `RateLimit-*` headers — returned on every response, not only on 429s — and back off until the window resets. See the \"Rate limits\" section of the introduction for details.","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}},"content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["error"]},"error":{"type":"string","description":"Human-readable error message"},"tier":{"type":"string","enum":["read","write","upload"],"description":"The rate-limit tier whose quota was exceeded. GET endpoints count against `read`, POST/PUT/PATCH/DELETE against `write`, and multipart file uploads against `upload` — each tier has an independent counter."},"retryAfterSec":{"type":"integer","description":"Number of seconds after which the rate-limit window resets and requests will be accepted again. Prefer this (or the `RateLimit-Reset` header) over the `Retry-After` header, which is not guaranteed to be present."}},"required":["status","error","tier","retryAfterSec"]},"example":{"status":"error","error":"Rate limit exceeded","tier":"read","retryAfterSec":60}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["error"]},"error":{"type":"string","description":"Human-readable error message"}},"required":["status","error"]},"example":{"status":"error","error":"Internal Server error"}}}}}}},"/api/v1/projects":{"get":{"summary":"List projects","description":"Use this endpoint to retrieve a list of projects (also called jobs or roles) from your Atlas account.\n\nIn Atlas, a **project** represents a recruitment assignment - for example, \"Head of Engineering at Acme Corp\" or \"Sales Manager at Globex\". This endpoint returns a summary list of all your projects, which you can filter and page through.\n\n**What you can filter by:**\n- `state` - the current status of the project. Options are: `active` (being worked on), `closed` (finished), `on_hold` (paused), `lead` (a potential opportunity not yet confirmed), `pitch` (being pitched to a client), `opportunity` (a speculative role), or `talent_pool` (a pipeline of candidates not tied to a specific role). You can pass multiple states at once.\n- `createdAfter` / `createdBefore` - only return projects created within a specific date range\n- `updatedAfter` / `updatedBefore` - only return projects last modified within a specific date range (ISO 8601). Filters on the `updatedAt` field. To keep an external copy in sync, use `updatedAfter` as a cursor: persist the maximum `updatedAt` you receive and pass it back as `updatedAfter` on the next run to fetch only what changed since (the bound is inclusive, so upsert by `id` to stay idempotent)\n- `ownerEmail` - only return projects owned by a specific consultant (identified by their Atlas email address)\n- `memberEmail` - only return projects where a specific consultant is a team member\n- `companyId` - only return projects belonging to a specific company (multiple comma-separated company IDs return the union)\n- `role` - filter by job title (partial matches are supported)\n- `public` - filter by public (job-board) visibility. `public=true` returns only the projects advertised on your public job board, `public=false` only the ones that are not, and omitting it returns both. Combine with `state=active` to get exactly the set the public jobs portal advertises\n- `includeDeleted` - include soft-deleted projects as tombstones (with a populated `deletedAt`)\n\n**Unknown query parameters are rejected:**\nAny parameter that is not documented here is rejected with a `422` — the endpoint never silently ignores a filter it does not understand, so a typo (or a filter that does not exist) can never come back as a `200` with the full unfiltered list.\n\n**Pagination:**\nResults are returned in pages. Use the `page` and `pageSize` parameters to move through large result sets. The response includes a `total` count so you know how many results exist in total.\n\n**Requesting extra job metadata (`expand`):**\nBy default the list returns the summary fields described below. Pass a comma-separated `expand` list to have selected job metadata returned on every row, so an incremental sync does not need a follow-up detail call per project:\n\n`GET /api/v1/projects?updatedAfter=2026-06-01T00:00:00Z&expand=contractType,func,salary,seniority,workMode`\n\n- Allowed values: `contractType`, `func`, `salary`, `seniority`, `workMode`. Any other value is rejected with `422`.\n- `expand=salary` returns both `salary` and `salaryCurrency`.\n- Each field holds the same value and enum shape as the corresponding field on **Get project details**, and is `null` when the project has no value set.\n- `expand` combines freely with every filter and with pagination — expanded fields appear on all pages.\n- **Backward compatible:** omit `expand` (or send it empty) and the response is exactly as before — a field you did not request is absent from the row, not returned as `null`.\n\n**What you get back:**\nEach project in the list includes its ID, job role title, current state, the associated company, and the `owner` (the consultant the project is attributed to, as `{ userId, email, name }`). The `owner` is the primary recruiter attribution field for rolling projects up per recruiter; it is `null` when the project has no owner (projects have no creator fallback). To get the full details of a specific project (including pipeline stages, salary, members, etc.), use the **Get project details** endpoint with the project's ID.","tags":["Projects"],"security":[{"BearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"Comma-separated project states to filter by","example":"active,lead"},"required":false,"name":"state","in":"query"},{"schema":{"anyOf":[{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},{"type":"string","format":"date-time"}],"description":"Only projects created after this point (inclusive). Accepts an ISO 8601 datetime or a date-only YYYY-MM-DD value (covering from the start of that UTC day)","example":"2025-01-01"},"required":false,"name":"createdAfter","in":"query"},{"schema":{"anyOf":[{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},{"type":"string","format":"date-time"}],"description":"Only projects created before this point (inclusive). Accepts an ISO 8601 datetime or a date-only YYYY-MM-DD value (covering through the end of that UTC day)","example":"2026-01-01"},"required":false,"name":"createdBefore","in":"query"},{"schema":{"anyOf":[{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},{"type":"string","format":"date-time"}],"description":"Only projects updated after this point (inclusive). Accepts an ISO 8601 datetime or a date-only YYYY-MM-DD value (covering from the start of that UTC day)","example":"2025-06-01"},"required":false,"name":"updatedAfter","in":"query"},{"schema":{"anyOf":[{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},{"type":"string","format":"date-time"}],"description":"Only projects updated before this point (inclusive). Accepts an ISO 8601 datetime or a date-only YYYY-MM-DD value (covering through the end of that UTC day)","example":"2026-06-01"},"required":false,"name":"updatedBefore","in":"query"},{"schema":{"type":"string","enum":["true","false"],"description":"Include soft-deleted projects as tombstones (with a populated `deletedAt`). Defaults to false. Pair with `updatedAfter` to incrementally sync deletions.","example":"false"},"required":false,"name":"includeDeleted","in":"query"},{"schema":{"type":"string","description":"Comma-separated project owner emails","example":"owner1@agency.com,owner2@agency.com"},"required":false,"name":"ownerEmail","in":"query"},{"schema":{"type":"string","description":"Comma-separated project member emails","example":"member1@agency.com,member2@agency.com"},"required":false,"name":"memberEmail","in":"query"},{"schema":{"type":"string","description":"Comma-separated company UUIDs — only projects belonging to these companies are returned","example":"550e8400-e29b-41d4-a716-446655440000"},"required":false,"name":"companyId","in":"query"},{"schema":{"type":"string","description":"Filter by job role (case-insensitive partial match)","example":"Software Engineer"},"required":false,"name":"role","in":"query"},{"schema":{"type":"string","enum":["true","false"],"description":"Filter by public (job-board) visibility. `true` returns only projects advertised on the public job board, `false` only the ones that are not. Omit to return both.","example":"true"},"required":false,"name":"public","in":"query"},{"schema":{"type":"string","description":"Comma-separated job metadata fields to add to every list row. Omit it (or send an empty value) and the response shape is unchanged. Unknown values are rejected with 422. Allowed values: contractType, func, salary, seniority, workMode. Requesting `salary` also returns `salaryCurrency`.","example":"contractType,func,salary,seniority,workMode"},"required":false,"name":"expand","in":"query"},{"schema":{"type":"integer","minimum":1,"default":1,"description":"Page number (1-indexed)","example":1},"required":false,"name":"page","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":100,"description":"Items per page (max 100)","example":25},"required":false,"name":"pageSize","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":100,"description":"Alias for pageSize","deprecated":true},"required":false,"name":"perPage","in":"query"}],"responses":{"200":{"description":"Paginated list of projects","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["ok"]},"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"jobRole":{"type":"string","description":"Job role/title","example":"Software Engineer"},"state":{"type":"string","description":"Project state","example":"active"},"jobDescriptionFormatted":{"type":["string","null"],"description":"Job description in formatted HTML"},"company":{"type":["object","null"],"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"}},"required":["id","name"],"description":"Associated company, null for talent pool projects"},"owner":{"type":["object","null"],"properties":{"userId":{"type":"string","format":"uuid","description":"Owner user ID"},"email":{"type":"string","description":"Owner email","example":"owner@agency.com"},"name":{"type":"string","description":"Owner name","example":"Jane Smith"}},"required":["userId","email","name"],"description":"Project owner"},"customAttributes":{"type":"array","items":{"type":"object","properties":{"attributeId":{"type":"string","format":"uuid","description":"Custom attribute definition ID"},"attributeName":{"type":["string","null"],"description":"Attribute name"},"attributeType":{"type":["string","null"],"enum":["options","text_block","text_line","number_input","integer","date"],"description":"Attribute type — drives the shape of each entry in `values`."},"values":{"type":"array","items":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"object","properties":{"optionId":{"type":"string","format":"uuid","description":"Selected option ID"},"optionValue":{"type":["string","null"],"description":"Display value of the option"}},"required":["optionId","optionValue"]}],"description":"A single value entry. Shape depends on `attributeType`:\n- `text_line` / `text_block` → string\n- `integer` / `number_input` → number\n- `date` → ISO `YYYY-MM-DD` string\n- `options` → `{ optionId, optionValue }` object"},"description":"All values recorded for this attribute. For single-value attributes the array has one entry; for multi-select `options` attributes it may have several."}},"required":["attributeId","attributeName","attributeType","values"]},"description":"Custom attribute values for this project"},"updatedAt":{"type":["string","null"],"description":"ISO 8601 — when the project was last modified. Use as the incremental-sync cursor: persist the maximum value across a page and pass it back as `updatedAfter`","example":"2026-06-01T12:00:00.000Z"},"createdAt":{"type":["string","null"],"description":"ISO 8601 — when the project was created","example":"2026-06-01T12:00:00.000Z"},"deletedAt":{"type":["string","null"],"description":"ISO 8601 soft-delete timestamp. `null` for live projects; populated for tombstones (only returned when `includeDeleted=true`)"},"contractType":{"type":["string","null"],"enum":["full_time","part_time","contract","non_exec"],"description":"Contract type. Returned only when `expand` includes `contractType`"},"func":{"type":["string","null"],"description":"Job function. Returned only when `expand` includes `func`"},"salary":{"type":["string","null"],"description":"Salary or salary range. Returned only when `expand` includes `salary`"},"salaryCurrency":{"type":["string","null"],"description":"Salary currency code. Returned only when `expand` includes `salary`","example":"USD"},"seniority":{"type":["string","null"],"enum":["partner","board","founder","cxo","vp","director","manager","senior","middle","junior"],"description":"Seniority level. Returned only when `expand` includes `seniority`"},"workMode":{"type":["string","null"],"enum":["office","hybrid","remote"],"description":"Work mode. Returned only when `expand` includes `workMode`"}},"required":["id","jobRole","state","jobDescriptionFormatted","company","owner","customAttributes","updatedAt","createdAt","deletedAt"]}},"pagination":{"type":"object","properties":{"page":{"type":"integer","description":"Current page number","example":1},"pageSize":{"type":"integer","description":"Items per page","example":25},"total":{"type":"integer","description":"Total matching items","example":42},"totalPages":{"type":"integer","description":"Total number of pages","example":2}},"required":["page","pageSize","total","totalPages"]}},"required":["status","data","pagination"]}}}},"401":{"description":"Unauthorized - missing or invalid API key","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["error"]},"error":{"type":"string","description":"Human-readable error message"}},"required":["status","error"]},"example":{"status":"error","error":"Unauthorized"}}}},"422":{"description":"Validation error - the request body or query parameters failed validation","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["error"]},"errors":{"type":"object","properties":{"formErrors":{"type":"array","items":{"type":"string"},"description":"Top-level validation errors"},"fieldErrors":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Per-field validation errors keyed by field name"}},"required":["formErrors","fieldErrors"]}},"required":["status","errors"]},"example":{"status":"error","errors":{"formErrors":[],"fieldErrors":{"email":["Invalid email"]}}}}}},"429":{"description":"Too many requests - the caller has exceeded the per-agency rate limit for the tier this endpoint counts against (default per minute: 1200 read / 400 write / 60 upload). Inspect the `RateLimit-*` headers — returned on every response, not only on 429s — and back off until the window resets. See the \"Rate limits\" section of the introduction for details.","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}},"content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["error"]},"error":{"type":"string","description":"Human-readable error message"},"tier":{"type":"string","enum":["read","write","upload"],"description":"The rate-limit tier whose quota was exceeded. GET endpoints count against `read`, POST/PUT/PATCH/DELETE against `write`, and multipart file uploads against `upload` — each tier has an independent counter."},"retryAfterSec":{"type":"integer","description":"Number of seconds after which the rate-limit window resets and requests will be accepted again. Prefer this (or the `RateLimit-Reset` header) over the `Retry-After` header, which is not guaranteed to be present."}},"required":["status","error","tier","retryAfterSec"]},"example":{"status":"error","error":"Rate limit exceeded","tier":"read","retryAfterSec":60}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["error"]},"error":{"type":"string","description":"Human-readable error message"}},"required":["status","error"]},"example":{"status":"error","error":"Internal Server error"}}}}}},"post":{"summary":"Create a project","description":"Use this endpoint to create a new project (job, job lead, or talent pool) in your Atlas account.\n\n**Project types:**\n- `job` — an active recruitment assignment for a confirmed role at a client company. Maps to project state `active`.\n- `job_lead` — a potential opportunity that is not yet confirmed. Maps to project state `lead`. Optionally link to an existing opportunity via `opportunityId`.\n- `talent_pool` — a pipeline of candidates not tied to a specific role. Maps to project state `talent_pool`. Does not require a `companyId`.\n\n**Required fields:**\n- `projectType`, `jobRole`, `ownerEmail` (and `companyId` for job and job_lead).\n\n**Validation rules:**\n- `ownerEmail` must resolve to an existing user within the agency.\n- `companyId`, when provided, must belong to the same agency.\n- `opportunityId`, when provided, must belong to the same agency.\n- `memberEmails` entries that don't match a user in the agency are silently skipped — only matching emails are added as members.\n- `companyContactIds` must be CompanyContact junction IDs (the person↔company link, retrievable from `companyContact.id` on GET /api/v1/people/{id}) belonging to the project's `companyId` — not person IDs.\n- `customAttributes[].customAttributeId` must reference a project-scoped custom attribute in the agency.\n\nThe owner is automatically added as a project member with the lead role; additional `memberEmails` are added as regular members.","tags":["Projects"],"security":[{"BearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"projectType":{"type":"string","enum":["job","job_lead","talent_pool"],"description":"Type of project: job, job_lead, talent_pool","example":"job"},"jobRole":{"type":"string","minLength":1,"maxLength":255,"description":"Job title or role name","example":"Senior Software Engineer"},"companyId":{"type":["string","null"],"format":"uuid","description":"Company this project belongs to. Required for job and job_lead"},"ownerEmail":{"type":"string","maxLength":255,"format":"email","description":"Email of the project owner. Must be an existing, active user in the agency","example":"owner@agency.com"},"jobDescription":{"type":["string","null"],"maxLength":16384,"description":"Plain text job description"},"jobNumber":{"type":["string","null"],"minLength":1,"maxLength":255,"description":"Job reference number. Must be non-empty when supplied; omit to auto-generate.","example":"ENG-2026-042"},"contractType":{"type":["string","null"],"enum":["full_time","part_time","contract","non_exec"],"description":"Contract type"},"workMode":{"type":["string","null"],"enum":["office","hybrid","remote"],"description":"Work mode"},"seniority":{"type":["string","null"],"enum":["partner","board","founder","cxo","vp","director","manager","senior","middle","junior","training","unpaid"],"description":"Seniority level","example":"senior"},"func":{"type":["string","null"],"minLength":1,"maxLength":80,"description":"Job function (e.g. Engineering, Sales). Empty strings are rejected — omit or send null to clear.","example":"Engineering"},"sourceUrl":{"type":["string","null"],"minLength":1,"maxLength":2048,"description":"URL where this project was sourced from","example":"https://example.com/jobs/senior-engineer"},"skills":{"type":["array","null"],"items":{"type":"string","minLength":1,"maxLength":80},"maxItems":100,"description":"List of required skills. Duplicate entries are silently dropped.","example":["TypeScript","React"]},"hireTarget":{"type":"integer","minimum":1,"maximum":10000,"default":1,"description":"Number of positions to fill","example":1},"visaSupport":{"type":["boolean","null"],"description":"Whether visa sponsorship is offered"},"public":{"type":"boolean","default":false,"description":"Whether the project is publicly visible"},"salary":{"type":["object","null"],"properties":{"value":{"type":"string","minLength":1,"maxLength":80,"description":"Salary or salary range (free text)","example":"120000-150000"},"currency":{"type":"string","enum":["USD","EUR","JPY","GBP","AUD","CAD","CHF","CNY","HKD","NZD","SEK","NOK","MXN","SGD","RUB","ZAR","TRY","BRL","INR","KRW","DKK","PLN","ILS","HUF","CZK","RON","THB","MYR","IDR","VND","PHP","SAR","AED","QAR","KWD","JOD","CLP","COP","PEN","ARS","UYU","CRC","PKR","BDT","LKR","EGP","NGN","TWD","KES","GHS","UGX","TZS","MAD","BWP","BGN","UAH","KZT","GEL","ISK","BHD","OMR"],"description":"Currency code","example":"USD"}},"required":["value","currency"],"description":"Salary"},"expectedFee":{"type":["object","null"],"properties":{"value":{"type":"string","pattern":"^(0|[1-9]\\d{0,17})(\\.\\d{1,2})?$","description":"Expected placement fee amount (decimal string, numeric(20,2))","example":"25000.00"},"currency":{"type":"string","enum":["USD","EUR","JPY","GBP","AUD","CAD","CHF","CNY","HKD","NZD","SEK","NOK","MXN","SGD","RUB","ZAR","TRY","BRL","INR","KRW","DKK","PLN","ILS","HUF","CZK","RON","THB","MYR","IDR","VND","PHP","SAR","AED","QAR","KWD","JOD","CLP","COP","PEN","ARS","UYU","CRC","PKR","BDT","LKR","EGP","NGN","TWD","KES","GHS","UGX","TZS","MAD","BWP","BGN","UAH","KZT","GEL","ISK","BHD","OMR"],"description":"Currency code","example":"USD"}},"required":["value","currency"],"description":"Expected placement fee"},"feeTerms":{"type":["string","null"],"minLength":1,"maxLength":80,"description":"Fee terms description","example":"20% of annual salary"},"notes":{"type":["string","null"],"maxLength":16384,"description":"Internal notes"},"startedAt":{"type":["string","null"],"pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Planned or actual start date (YYYY-MM-DD). Must be no earlier than one calendar month ago. Stored as UTC midnight of that calendar day.","example":"2026-04-01"},"location":{"type":["object","null"],"properties":{"name":{"type":["string","null"],"minLength":1,"maxLength":255,"description":"Display name / formatted address (e.g. \"London, UK\")","example":"London, UK"},"locality":{"type":["string","null"],"minLength":1,"maxLength":255,"description":"City name","example":"London"},"region":{"type":["string","null"],"minLength":1,"maxLength":255,"description":"State or region","example":"England"},"metro":{"type":["string","null"],"minLength":1,"maxLength":255,"description":"Metro area (People Data Labs convention, e.g. \"new york, new york\")","example":"new york, new york"},"country":{"type":["string","null"],"minLength":1,"maxLength":255,"description":"Country name","example":"United Kingdom"},"streetAddress":{"type":["string","null"],"minLength":1,"maxLength":255,"description":"Street address line 1","example":"123 Baker Street"},"addressLine2":{"type":["string","null"],"minLength":1,"maxLength":255,"description":"Street address line 2 (apartment, suite, unit, etc.)","example":"Suite 200"},"postalCode":{"type":["string","null"],"minLength":1,"maxLength":255,"description":"Postal / ZIP code","example":"NW1 6XE"},"raw":{"type":["string","null"],"minLength":1,"maxLength":255,"description":"Raw unstructured address text (used for geocoding)","example":"123 Baker Street, London NW1 6XE, United Kingdom"},"latitude":{"type":["number","null"],"minimum":-90,"maximum":90,"description":"Latitude coordinate (-90..90)","example":51.523767},"longitude":{"type":["number","null"],"minimum":-180,"maximum":180,"description":"Longitude coordinate (-180..180)","example":-0.158519}},"description":"Location"},"memberEmails":{"type":"array","items":{"type":"string","maxLength":255,"format":"email"},"maxItems":100,"default":[],"description":"Emails of team members to add. Must be existing users in the agency. Duplicate entries are silently dropped."},"companyContactIds":{"type":"array","items":{"type":"string","format":"uuid"},"maxItems":100,"default":[],"description":"CompanyContact IDs to associate with the project — these are the person↔company link IDs, NOT person IDs. Retrieve a value from the `companyContact.id` field on GET /api/v1/people/{id}. Each must belong to the project's `companyId`; passing a person ID (or an ID from another company) returns 404. Duplicate entries are silently dropped."},"opportunityId":{"type":["string","null"],"format":"uuid","description":"Opportunity to link this project to. Only allowed for job_lead"},"customAttributes":{"type":"array","items":{"type":"object","properties":{"customAttributeId":{"type":"string","format":"uuid","description":"Custom attribute definition ID — must belong to the agency at the correct scope."},"optionId":{"type":["string","null"],"format":"uuid","description":"Required for `options`-type attributes — set to the chosen option's UUID. Mutually exclusive with `value`. For multi-select (`multipleValues: true`), repeat the entry once per chosen optionId."},"value":{"anyOf":[{"type":"string","minLength":1,"maxLength":16384},{"type":"number"},{"type":"null"}],"description":"Attribute value. Shape depends on the attribute `type`:\n- `text_line` / `text_block`: non-empty string (trimmed, max 16384 chars).\n- `integer` / `number_input`: JSON number, integer only, must fit Postgres int32 (-2147483648..2147483647).\n- `date`: string `YYYY-MM-DD`, calendar-validated.\n- `options`: do not send `value` — use `optionId` instead.\nMutually exclusive with `optionId`. Sending neither is rejected (422).","example":"Some text value"}},"required":["customAttributeId"],"description":"Custom attribute value"},"maxItems":100,"default":[],"description":"Custom attribute values to set on the project. Each entry references a custom attribute definition by id (must be `of: \"project\"` and belong to your agency).\n\nHow to send a value depends on the attribute `type`:\n\n- `text_line` — short single-line text. Send `value` as a non-empty string (trimmed, max 16384 chars).\n- `text_block` — rich/multi-line text. Send `value` as a non-empty string (trimmed, max 16384 chars).\n- `integer` — whole number. Send `value` as a JSON number (no quotes). Must fit Postgres int32 (-2147483648..2147483647); decimals are rejected.\n- `number_input` — same shape as `integer` (legacy alias).\n- `date` — calendar date with no timezone. Send `value` as `YYYY-MM-DD`; the calendar is validated, so `2026-13-32` is rejected.\n- `options` — pick from a fixed list. Send `optionId` (a UUID of one of the attribute's options). Do **not** send `value`. For attributes with `multipleValues: true`, repeat the same `customAttributeId` with each distinct `optionId` you want to set.\n\nValidation rules enforced by the API:\n- Either `value` or `optionId` must be present — sending only `customAttributeId` is rejected (422).\n- `optionId` and `value` are mutually exclusive — sending both is rejected (422).\n- For single-value attributes (`multipleValues: false` or non-`options` types) each `customAttributeId` may appear only once. Duplicates are rejected (422).\n- For `options` multi-select, repeating the same (`customAttributeId`, `optionId`) pair is rejected (422).\n- Wrong-type values are rejected (422): e.g. sending a string for `integer`, a number for `date`.\n- The referenced `customAttributeId` and `optionId` must belong to your agency and the option must belong to the specified attribute, otherwise 404 / 422.\n\nExample — one of each non-trivial type:\n```json\n\"customAttributes\": [\n { \"customAttributeId\": \"…uuid…\", \"value\": \"EU\" }, // text_line\n { \"customAttributeId\": \"…uuid…\", \"value\": 3 }, // integer\n { \"customAttributeId\": \"…uuid…\", \"value\": \"2026-06-01\" }, // date\n { \"customAttributeId\": \"…uuid…\", \"optionId\": \"…uuid…\" }, // options (single-select)\n { \"customAttributeId\": \"…uuid…\", \"optionId\": \"…uuid-a…\" }, // options multi-select…\n { \"customAttributeId\": \"…uuid…\", \"optionId\": \"…uuid-b…\" } // …same attribute, two picks\n]\n```"}},"required":["projectType","jobRole","ownerEmail"]}}}},"responses":{"201":{"description":"Project created","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["ok"]},"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"jobRole":{"type":"string"},"jobNumber":{"type":["string","null"]},"state":{"type":"string"}},"required":["id","jobRole","jobNumber","state"]}},"required":["status","data"]}}}},"401":{"description":"Unauthorized - missing or invalid API key","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["error"]},"error":{"type":"string","description":"Human-readable error message"}},"required":["status","error"]},"example":{"status":"error","error":"Unauthorized"}}}},"404":{"description":"Owner, company, contact, opportunity, or custom attribute not found / not in scope","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["error"]},"error":{"type":"string","description":"Human-readable error message"}},"required":["status","error"]},"example":{"status":"error","error":"Not found"}}}},"409":{"description":"A project with the provided jobNumber already exists in this agency.","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["error"]},"error":{"type":"string","description":"Human-readable error message"}},"required":["status","error"]},"example":{"status":"error","error":"Project with jobNumber \"JOB-123\" already exists"}}}},"422":{"description":"Validation error - the request body or query parameters failed validation","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["error"]},"errors":{"type":"object","properties":{"formErrors":{"type":"array","items":{"type":"string"},"description":"Top-level validation errors"},"fieldErrors":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Per-field validation errors keyed by field name"}},"required":["formErrors","fieldErrors"]}},"required":["status","errors"]},"example":{"status":"error","errors":{"formErrors":[],"fieldErrors":{"email":["Invalid email"]}}}}}},"429":{"description":"Too many requests - the caller has exceeded the per-agency rate limit for the tier this endpoint counts against (default per minute: 1200 read / 400 write / 60 upload). Inspect the `RateLimit-*` headers — returned on every response, not only on 429s — and back off until the window resets. See the \"Rate limits\" section of the introduction for details.","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}},"content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["error"]},"error":{"type":"string","description":"Human-readable error message"},"tier":{"type":"string","enum":["read","write","upload"],"description":"The rate-limit tier whose quota was exceeded. GET endpoints count against `read`, POST/PUT/PATCH/DELETE against `write`, and multipart file uploads against `upload` — each tier has an independent counter."},"retryAfterSec":{"type":"integer","description":"Number of seconds after which the rate-limit window resets and requests will be accepted again. Prefer this (or the `RateLimit-Reset` header) over the `Retry-After` header, which is not guaranteed to be present."}},"required":["status","error","tier","retryAfterSec"]},"example":{"status":"error","error":"Rate limit exceeded","tier":"read","retryAfterSec":60}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["error"]},"error":{"type":"string","description":"Human-readable error message"}},"required":["status","error"]},"example":{"status":"error","error":"Internal Server error"}}}}}}},"/api/v1/projects/{id}":{"get":{"summary":"Get project details","description":"Use this endpoint to retrieve the full details of a single project by its ID.\n\nThis is the endpoint to use when you already know which project you want - for example, after finding it via the List projects endpoint. It returns everything Atlas knows about the project in one response.\n\n**What you need to provide:**\nJust the project's ID in the URL path (e.g. `/api/v1/projects/abc-123`). Project IDs are UUIDs - long strings of letters and numbers - returned by the List projects endpoint.\n\n**What you get back:**\n\n- **Basic info** - job role title, job reference number, current state (active, closed, etc.), and close reason if applicable\n- **Job details** - contract type (full-time, part-time, contract, non-exec), work mode (office, hybrid, remote), seniority level, job function, required skills, target number of hires, and whether visa support is offered\n- **Compensation** - salary, salary currency, expected fee, fee currency, and fee terms\n- **Notes** - internal notes about the project\n- **Location** - city, region, country, and formatted address\n- **Company** - the client company the role is for, including their name, industry, size, and logo\n- **Owner** - the consultant responsible for the project\n- **Members** - all consultants working on the project and their role (member or lead)\n- **Pipeline stages and statuses** - the full recruitment pipeline configured for this project (e.g. Sourcing → Longlist → Shortlist → Offer). Each stage contains its statuses (e.g. \"Added\", \"Reviewed\", \"Approved\"). These IDs are needed when adding a candidate to the project.\n- **Custom attributes** - any agency-specific fields configured in your Atlas account\n- **Dates** - when the project was created, started, and closed","tags":["Projects"],"security":[{"BearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid","description":"Project ID","example":"550e8400-e29b-41d4-a716-446655440000"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Extended project details","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["ok"]},"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"jobRole":{"type":"string","description":"Job role/title","example":"Software Engineer"},"jobNumber":{"type":["string","null"],"description":"Job reference number"},"state":{"type":"string","enum":["active","closed","on_hold","talent_pool","lead","pitch","opportunity"],"description":"Project state","example":"active"},"closeReason":{"type":["string","null"],"enum":["filled","worked_lost","cancelled","lead_lost","opportunity_lost","pitch_lost"],"description":"Reason the project was closed."},"jobDescription":{"type":["string","null"],"description":"Plain text job description"},"jobDescriptionFormatted":{"type":["string","null"],"description":"Job description in formatted HTML"},"public":{"type":"boolean","description":"Whether the project is public"},"contractType":{"type":["string","null"],"enum":["full_time","part_time","contract","non_exec"],"description":"Contract type"},"workMode":{"type":["string","null"],"enum":["office","hybrid","remote"],"description":"Work mode"},"seniority":{"type":["string","null"],"enum":["partner","board","founder","cxo","vp","director","manager","senior","middle","junior"],"description":"Seniority level"},"func":{"type":["string","null"],"description":"Job function"},"skills":{"type":["array","null"],"items":{"type":"string"},"description":"Required skills","example":["TypeScript","React"]},"hireTarget":{"type":["integer","null"],"description":"Target number of hires","example":1},"visaSupport":{"type":["boolean","null"],"description":"Whether visa support is offered"},"salary":{"type":["string","null"],"description":"Salary or salary range"},"salaryCurrency":{"type":["string","null"],"description":"Salary currency code","example":"USD"},"expectedFee":{"type":["string","null"],"description":"Expected fee amount"},"expectedFeeCurrency":{"type":["string","null"],"description":"Expected fee currency code"},"feeTerms":{"type":["string","null"],"description":"Fee terms"},"notes":{"type":["string","null"],"description":"Internal notes about the project"},"location":{"type":["object","null"],"properties":{"city":{"type":["string","null"],"description":"City/locality","example":"London"},"region":{"type":["string","null"],"description":"Region/state","example":"England"},"country":{"type":["string","null"],"description":"Country","example":"United Kingdom"},"formattedAddress":{"type":["string","null"],"description":"Full formatted address","example":"London, England, United Kingdom"}},"required":["city","region","country","formattedAddress"],"description":"Project location"},"company":{"type":["object","null"],"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string","example":"Acme Corp"},"industry":{"type":["string","null"],"description":"Primary industry","example":"Technology"},"size":{"type":["string","null"],"description":"Company size","example":"51-200"},"logoUrl":{"type":["string","null"],"description":"Company logo URL"}},"required":["id","name","industry","size","logoUrl"],"description":"Associated company"},"owner":{"type":["object","null"],"properties":{"userId":{"type":"string","format":"uuid","description":"Owner user ID"},"email":{"type":"string","description":"Owner email","example":"owner@agency.com"},"name":{"type":"string","description":"Owner name","example":"Jane Smith"}},"required":["userId","email","name"],"description":"Project owner"},"members":{"type":"array","items":{"type":"object","properties":{"userId":{"type":"string","format":"uuid","description":"Member user ID"},"email":{"type":"string","description":"Member email","example":"member@agency.com"},"name":{"type":"string","description":"Member name","example":"John Doe"},"memberType":{"type":"string","enum":["member","lead"],"description":"Member role - lead is the project owner","example":"member"}},"required":["userId","email","name","memberType"]},"description":"Project members"},"stages":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string","description":"Stage name","example":"Sourcing"},"type":{"type":"string","description":"Stage type","example":"sourcing"},"phase":{"type":"string","description":"Stage phase","example":"internal_selection"},"position":{"type":"integer","description":"Position in pipeline","example":0},"statuses":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string","description":"Status name","example":"Added"},"type":{"type":"string","description":"Status type","example":"sourcing_added"},"position":{"type":"integer","description":"Position within stage","example":0}},"required":["id","name","type","position"]},"description":"Statuses within this stage"}},"required":["id","name","type","phase","position","statuses"]},"description":"Project stages with statuses"},"customAttributes":{"type":"array","items":{"type":"object","properties":{"attributeId":{"type":"string","format":"uuid","description":"Custom attribute definition ID"},"attributeName":{"type":["string","null"],"description":"Attribute name"},"attributeType":{"type":["string","null"],"enum":["options","text_block","text_line","number_input","integer","date"],"description":"Attribute type — drives the shape of each entry in `values`."},"values":{"type":"array","items":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"object","properties":{"optionId":{"type":"string","format":"uuid","description":"Selected option ID"},"optionValue":{"type":["string","null"],"description":"Display value of the option"}},"required":["optionId","optionValue"]}],"description":"A single value entry. Shape depends on `attributeType`:\n- `text_line` / `text_block` → string\n- `integer` / `number_input` → number\n- `date` → ISO `YYYY-MM-DD` string\n- `options` → `{ optionId, optionValue }` object"},"description":"All values recorded for this attribute. For single-value attributes the array has one entry; for multi-select `options` attributes it may have several."}},"required":["attributeId","attributeName","attributeType","values"]},"description":"Custom attribute values for this project"},"createdAt":{"type":["string","null"],"description":"ISO 8601 creation date"},"startedAt":{"type":["string","null"],"description":"Start date (YYYY-MM-DD)","example":"2026-03-23"},"closedAt":{"type":["string","null"],"description":"Close date (YYYY-MM-DD)","example":"2026-04-15"}},"required":["id","jobRole","jobNumber","state","closeReason","jobDescription","jobDescriptionFormatted","public","contractType","workMode","seniority","func","skills","hireTarget","visaSupport","salary","salaryCurrency","expectedFee","expectedFeeCurrency","feeTerms","notes","location","company","owner","members","stages","customAttributes","createdAt","startedAt","closedAt"]}},"required":["status","data"]}}}},"401":{"description":"Unauthorized - missing or invalid API key","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["error"]},"error":{"type":"string","description":"Human-readable error message"}},"required":["status","error"]},"example":{"status":"error","error":"Unauthorized"}}}},"404":{"description":"Project not found","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["error"]},"error":{"type":"string","description":"Human-readable error message"}},"required":["status","error"]},"example":{"status":"error","error":"Not found"}}}},"422":{"description":"Validation error - the request body or query parameters failed validation","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["error"]},"errors":{"type":"object","properties":{"formErrors":{"type":"array","items":{"type":"string"},"description":"Top-level validation errors"},"fieldErrors":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Per-field validation errors keyed by field name"}},"required":["formErrors","fieldErrors"]}},"required":["status","errors"]},"example":{"status":"error","errors":{"formErrors":[],"fieldErrors":{"email":["Invalid email"]}}}}}},"429":{"description":"Too many requests - the caller has exceeded the per-agency rate limit for the tier this endpoint counts against (default per minute: 1200 read / 400 write / 60 upload). Inspect the `RateLimit-*` headers — returned on every response, not only on 429s — and back off until the window resets. See the \"Rate limits\" section of the introduction for details.","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}},"content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["error"]},"error":{"type":"string","description":"Human-readable error message"},"tier":{"type":"string","enum":["read","write","upload"],"description":"The rate-limit tier whose quota was exceeded. GET endpoints count against `read`, POST/PUT/PATCH/DELETE against `write`, and multipart file uploads against `upload` — each tier has an independent counter."},"retryAfterSec":{"type":"integer","description":"Number of seconds after which the rate-limit window resets and requests will be accepted again. Prefer this (or the `RateLimit-Reset` header) over the `Retry-After` header, which is not guaranteed to be present."}},"required":["status","error","tier","retryAfterSec"]},"example":{"status":"error","error":"Rate limit exceeded","tier":"read","retryAfterSec":60}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["error"]},"error":{"type":"string","description":"Human-readable error message"}},"required":["status","error"]},"example":{"status":"error","error":"Internal Server error"}}}}}},"patch":{"summary":"Update a project","description":"Use this endpoint to update a project's fields, link it to an opportunity, and/or add hiring contacts to it.\n\nAll fields are optional, but at least one must be provided.\n\n**Partial-update semantics for scalar fields** (`jobRole`, `ownerEmail`, `jobDescription`, `notes`, `func`, `seniority`, `contractType`, `workMode`, `salary`, `expectedFee`, `hireTarget`, `visaSupport`, `public`, `location`, `startedAt`): omitted fields are left untouched, `null` clears a nullable field, and a value replaces the stored one. `jobRole`, `ownerEmail`, and `public` cannot be cleared. `ownerEmail` transfers ownership and must resolve to an existing, active user in the agency (404 otherwise).\n\n**Link fields:**\n- `opportunityId` — links the project to an existing opportunity. Only allowed for **job_lead** projects (state `lead`); sending it for any other project type returns 422. Linking an opportunity that is already linked to the project is a no-op.\n- `companyContactIds` — adds hiring contacts to the project. These are **CompanyContact junction IDs** (the person↔company link, retrievable from `companyContact.id` on GET /api/v1/people/{id}), not person IDs. Each must belong to the project's `companyId` — passing a person ID, an ID from another company, or an ID from another agency returns 404. This field is **additive only**: contacts already linked to the project are skipped (no-op) and existing links are never removed.\n\n**Not updatable here:** `companyId`, `state`, and `closedAt` — changing the company or closing a project have side effects on linked contacts, opportunities, and candidates and are deliberately excluded from this endpoint.\n\n**What you get back:**\nA core snapshot of the updated project (`id`, `jobRole`, `jobNumber`, `state`), the opportunity it is linked to (`null` when it has none), and the full list of hiring contact IDs linked to the project after the update — pre-existing links included. Use **Get project details** to read back all other fields.","tags":["Projects"],"security":[{"BearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid","description":"Project ID","example":"550e8400-e29b-41d4-a716-446655440000"},"required":true,"name":"id","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"opportunityId":{"type":"string","format":"uuid","description":"Opportunity to link this project to. Only allowed for job_lead projects (state `lead`) — sending it for any other project type returns 422. Linking the same opportunity again is a no-op.","example":"550e8400-e29b-41d4-a716-446655440005"},"companyContactIds":{"type":"array","items":{"type":"string","format":"uuid"},"maxItems":100,"description":"CompanyContact IDs to add as hiring contacts — these are the person↔company link IDs, NOT person IDs. Retrieve a value from the `companyContact.id` field on GET /api/v1/people/{id}. Each must belong to the project's `companyId`; passing a person ID (or an ID from another company) returns 404. Additive only: already-linked contacts are skipped (no-op), existing links are never removed. Duplicate entries are silently dropped.","example":["550e8400-e29b-41d4-a716-446655440006"]},"jobRole":{"type":"string","minLength":1,"maxLength":255,"description":"Job title or role name. Cannot be cleared — omit to leave untouched","example":"Senior Software Engineer"},"ownerEmail":{"type":"string","maxLength":255,"format":"email","description":"Transfer project ownership. Must be an existing, active user in the agency","example":"owner@agency.com"},"jobDescription":{"type":["string","null"],"maxLength":16384,"description":"Plain text job description. Send null to clear"},"notes":{"type":["string","null"],"maxLength":16384,"description":"Internal notes. Send null to clear"},"func":{"type":["string","null"],"minLength":1,"maxLength":80,"description":"Job function (e.g. Engineering, Sales). Empty strings are rejected — send null to clear.","example":"Engineering"},"seniority":{"type":["string","null"],"enum":["partner","board","founder","cxo","vp","director","manager","senior","middle","junior","training","unpaid"],"description":"Seniority level","example":"senior"},"contractType":{"type":["string","null"],"enum":["full_time","part_time","contract","non_exec"],"description":"Contract type. Send null to clear"},"workMode":{"type":["string","null"],"enum":["office","hybrid","remote"],"description":"Work mode. Send null to clear"},"salary":{"type":["object","null"],"properties":{"value":{"type":"string","minLength":1,"maxLength":80,"description":"Salary or salary range (free text)","example":"120000-150000"},"currency":{"type":"string","enum":["USD","EUR","JPY","GBP","AUD","CAD","CHF","CNY","HKD","NZD","SEK","NOK","MXN","SGD","RUB","ZAR","TRY","BRL","INR","KRW","DKK","PLN","ILS","HUF","CZK","RON","THB","MYR","IDR","VND","PHP","SAR","AED","QAR","KWD","JOD","CLP","COP","PEN","ARS","UYU","CRC","PKR","BDT","LKR","EGP","NGN","TWD","KES","GHS","UGX","TZS","MAD","BWP","BGN","UAH","KZT","GEL","ISK","BHD","OMR"],"description":"Currency code","example":"USD"}},"required":["value","currency"],"description":"Salary"},"expectedFee":{"type":["object","null"],"properties":{"value":{"type":"string","pattern":"^(0|[1-9]\\d{0,17})(\\.\\d{1,2})?$","description":"Expected placement fee amount (decimal string, numeric(20,2))","example":"25000.00"},"currency":{"type":"string","enum":["USD","EUR","JPY","GBP","AUD","CAD","CHF","CNY","HKD","NZD","SEK","NOK","MXN","SGD","RUB","ZAR","TRY","BRL","INR","KRW","DKK","PLN","ILS","HUF","CZK","RON","THB","MYR","IDR","VND","PHP","SAR","AED","QAR","KWD","JOD","CLP","COP","PEN","ARS","UYU","CRC","PKR","BDT","LKR","EGP","NGN","TWD","KES","GHS","UGX","TZS","MAD","BWP","BGN","UAH","KZT","GEL","ISK","BHD","OMR"],"description":"Currency code","example":"USD"}},"required":["value","currency"],"description":"Expected placement fee"},"hireTarget":{"type":["integer","null"],"minimum":1,"maximum":10000,"description":"Number of positions to fill. Send null to clear","example":1},"visaSupport":{"type":["boolean","null"],"description":"Whether visa sponsorship is offered"},"public":{"type":"boolean","description":"Whether the project is publicly visible"},"location":{"type":["object","null"],"properties":{"name":{"type":["string","null"],"minLength":1,"maxLength":255,"description":"Display name / formatted address (e.g. \"London, UK\")","example":"London, UK"},"locality":{"type":["string","null"],"minLength":1,"maxLength":255,"description":"City name","example":"London"},"region":{"type":["string","null"],"minLength":1,"maxLength":255,"description":"State or region","example":"England"},"metro":{"type":["string","null"],"minLength":1,"maxLength":255,"description":"Metro area (People Data Labs convention, e.g. \"new york, new york\")","example":"new york, new york"},"country":{"type":["string","null"],"minLength":1,"maxLength":255,"description":"Country name","example":"United Kingdom"},"streetAddress":{"type":["string","null"],"minLength":1,"maxLength":255,"description":"Street address line 1","example":"123 Baker Street"},"addressLine2":{"type":["string","null"],"minLength":1,"maxLength":255,"description":"Street address line 2 (apartment, suite, unit, etc.)","example":"Suite 200"},"postalCode":{"type":["string","null"],"minLength":1,"maxLength":255,"description":"Postal / ZIP code","example":"NW1 6XE"},"raw":{"type":["string","null"],"minLength":1,"maxLength":255,"description":"Raw unstructured address text (used for geocoding)","example":"123 Baker Street, London NW1 6XE, United Kingdom"},"latitude":{"type":["number","null"],"minimum":-90,"maximum":90,"description":"Latitude coordinate (-90..90)","example":51.523767},"longitude":{"type":["number","null"],"minimum":-180,"maximum":180,"description":"Longitude coordinate (-180..180)","example":-0.158519}},"description":"Location"},"startedAt":{"type":["string","null"],"pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Planned or actual start date (YYYY-MM-DD). Must be no earlier than one calendar month ago. Stored as UTC midnight of that calendar day.","example":"2026-04-01"}}}}}},"responses":{"200":{"description":"Project updated","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["ok"]},"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Project ID"},"jobRole":{"type":"string","description":"Job role/title after the update"},"jobNumber":{"type":["string","null"],"description":"Job reference number"},"state":{"type":"string","description":"Project state","example":"lead"},"opportunityId":{"type":["string","null"],"format":"uuid","description":"Opportunity the project is linked to, null when it has none"},"companyContactIds":{"type":"array","items":{"type":"string","format":"uuid"},"description":"All hiring contact IDs linked to the project after the update"}},"required":["id","jobRole","jobNumber","state","opportunityId","companyContactIds"]}},"required":["status","data"]}}}},"401":{"description":"Unauthorized - missing or invalid API key","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["error"]},"error":{"type":"string","description":"Human-readable error message"}},"required":["status","error"]},"example":{"status":"error","error":"Unauthorized"}}}},"404":{"description":"Project, opportunity, or company contact not found / not in scope","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["error"]},"error":{"type":"string","description":"Human-readable error message"}},"required":["status","error"]},"example":{"status":"error","error":"Not found"}}}},"422":{"description":"Validation error - the request body or query parameters failed validation","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["error"]},"errors":{"type":"object","properties":{"formErrors":{"type":"array","items":{"type":"string"},"description":"Top-level validation errors"},"fieldErrors":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Per-field validation errors keyed by field name"}},"required":["formErrors","fieldErrors"]}},"required":["status","errors"]},"example":{"status":"error","errors":{"formErrors":[],"fieldErrors":{"email":["Invalid email"]}}}}}},"429":{"description":"Too many requests - the caller has exceeded the per-agency rate limit for the tier this endpoint counts against (default per minute: 1200 read / 400 write / 60 upload). Inspect the `RateLimit-*` headers — returned on every response, not only on 429s — and back off until the window resets. See the \"Rate limits\" section of the introduction for details.","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}},"content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["error"]},"error":{"type":"string","description":"Human-readable error message"},"tier":{"type":"string","enum":["read","write","upload"],"description":"The rate-limit tier whose quota was exceeded. GET endpoints count against `read`, POST/PUT/PATCH/DELETE against `write`, and multipart file uploads against `upload` — each tier has an independent counter."},"retryAfterSec":{"type":"integer","description":"Number of seconds after which the rate-limit window resets and requests will be accepted again. Prefer this (or the `RateLimit-Reset` header) over the `Retry-After` header, which is not guaranteed to be present."}},"required":["status","error","tier","retryAfterSec"]},"example":{"status":"error","error":"Rate limit exceeded","tier":"read","retryAfterSec":60}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["error"]},"error":{"type":"string","description":"Human-readable error message"}},"required":["status","error"]},"example":{"status":"error","error":"Internal Server error"}}}}}}},"/api/v1/projects/{id}/stages":{"get":{"summary":"List project stages","description":"Use this endpoint to retrieve the recruitment pipeline configured for a specific project — every stage and the statuses within it.\n\nIn Atlas, a **stage** represents a step in the pipeline (e.g. Sourcing, Longlist, Shortlist, Offer) and each stage contains one or more **statuses** (e.g. \"Added\", \"Interested\", \"On Probation\"). Together they define how a candidate moves through a project.\n\nThis is the lightweight counterpart to **Get project details** when all you need is the pipeline shape — for example, to render a stage/status picker before adding or moving a candidate.\n\n**What you need to provide:**\nJust the project's ID in the URL path. Project IDs are UUIDs returned by the **List projects** endpoint.\n\n**Ordering:**\nStages are returned ordered by `position` ascending. Statuses within each stage are also ordered by `position` ascending.\n\n**What you get back:**\nFor each stage: its `id`, `name`, `type`, `phase`, `position`, and the array of nested `statuses`. Each status includes its `id`, `name`, `type`, and `position`.","tags":["Projects"],"security":[{"BearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid","description":"Project ID","example":"550e8400-e29b-41d4-a716-446655440000"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Project stages with nested statuses, ordered by position ascending","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["ok"]},"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string","description":"Stage name","example":"Sourcing"},"type":{"type":"string","description":"Stage type","example":"sourcing"},"phase":{"type":"string","description":"Stage phase","example":"internal_selection"},"position":{"type":"integer","description":"Position in pipeline","example":0},"statuses":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string","description":"Status name","example":"Added"},"type":{"type":"string","description":"Status type","example":"sourcing_added"},"position":{"type":"integer","description":"Position within stage","example":0}},"required":["id","name","type","position"]},"description":"Statuses within this stage"}},"required":["id","name","type","phase","position","statuses"]}}},"required":["status","data"]}}}},"401":{"description":"Unauthorized - missing or invalid API key","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["error"]},"error":{"type":"string","description":"Human-readable error message"}},"required":["status","error"]},"example":{"status":"error","error":"Unauthorized"}}}},"404":{"description":"Project not found","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["error"]},"error":{"type":"string","description":"Human-readable error message"}},"required":["status","error"]},"example":{"status":"error","error":"Not found"}}}},"422":{"description":"Validation error - the request body or query parameters failed validation","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["error"]},"errors":{"type":"object","properties":{"formErrors":{"type":"array","items":{"type":"string"},"description":"Top-level validation errors"},"fieldErrors":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Per-field validation errors keyed by field name"}},"required":["formErrors","fieldErrors"]}},"required":["status","errors"]},"example":{"status":"error","errors":{"formErrors":[],"fieldErrors":{"email":["Invalid email"]}}}}}},"429":{"description":"Too many requests - the caller has exceeded the per-agency rate limit for the tier this endpoint counts against (default per minute: 1200 read / 400 write / 60 upload). Inspect the `RateLimit-*` headers — returned on every response, not only on 429s — and back off until the window resets. See the \"Rate limits\" section of the introduction for details.","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}},"content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["error"]},"error":{"type":"string","description":"Human-readable error message"},"tier":{"type":"string","enum":["read","write","upload"],"description":"The rate-limit tier whose quota was exceeded. GET endpoints count against `read`, POST/PUT/PATCH/DELETE against `write`, and multipart file uploads against `upload` — each tier has an independent counter."},"retryAfterSec":{"type":"integer","description":"Number of seconds after which the rate-limit window resets and requests will be accepted again. Prefer this (or the `RateLimit-Reset` header) over the `Retry-After` header, which is not guaranteed to be present."}},"required":["status","error","tier","retryAfterSec"]},"example":{"status":"error","error":"Rate limit exceeded","tier":"read","retryAfterSec":60}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["error"]},"error":{"type":"string","description":"Human-readable error message"}},"required":["status","error"]},"example":{"status":"error","error":"Internal Server error"}}}}}}},"/api/v1/projects/{id}/candidates":{"get":{"summary":"List candidates in a project","description":"Use this endpoint to retrieve a paginated list of candidates enrolled in a specific project, including both active and rejected candidates by default.\n\nIn Atlas, a **candidate** represents a person who has been added to a project's recruitment pipeline. Each candidate sits at a specific status within a specific stage of the pipeline (e.g. Sourcing → Added, Shortlist → Reviewed). This endpoint lets you read the current state of every candidate in a project, with the same ordering and filtering used by the Atlas web app candidate list.\n\n**What you can filter by:**\n- `phase` — comma-separated pipeline phase names (`internal_selection`, `presentation`, `first_round`, `late_stage`)\n- `stageId` — comma-separated CandidateStage UUIDs\n- `statusId` — comma-separated CandidateStatus UUIDs\n- `excludeRejected` — when `true`, candidates with a non-null rejection type are omitted\n\n**Ordering:**\nResults are sorted by pipeline position — first by stage position, then by status position. Use `sortDirection=asc` or `sortDirection=desc` (default `desc`) to control the order. This matches the in-app candidate list ordering.\n\n**Pagination:**\nUse `page` (1-based) and `pageSize` (1–100, default 25). The response includes a `pagination` object with `page`, `pageSize`, `total`, and `hasMore`.\n\n**What you get back:**\nEach candidate includes its ID, a nested `person` object (with `id`, name, and headline — use `person.id` with the People endpoints to fetch the person's full details, history, etc.), the current pipeline phase/stage/status, rejection state (`rejectedAt`, `rejectionReason`, `customRejectionReasonId`, `rejectionDetails` — where `rejectionReason` is the label of the agency-defined reason when one was picked, falling back to the predefined reason code), and timestamps. To find the available stage/status IDs for a project, call the **Get project details** endpoint first.\n\n**Deprecated fields:** `firstName`, `lastName`, `headlineRole`, and `headlineCompanyName` are still returned at the top level for backwards compatibility but are deprecated — use the equivalent fields inside `person` instead.","tags":["Projects"],"security":[{"BearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid","description":"Project ID","example":"550e8400-e29b-41d4-a716-446655440000"},"required":true,"name":"id","in":"path"},{"schema":{"type":"string","description":"Comma-separated pipeline phases to filter by","example":"internal_selection,presentation"},"required":false,"name":"phase","in":"query"},{"schema":{"type":"string","description":"Comma-separated CandidateStage UUIDs to filter by","example":"550e8400-e29b-41d4-a716-446655440002"},"required":false,"name":"stageId","in":"query"},{"schema":{"type":"string","description":"Comma-separated CandidateStatus UUIDs to filter by","example":"550e8400-e29b-41d4-a716-446655440003"},"required":false,"name":"statusId","in":"query"},{"schema":{"type":"string","enum":["true","false"],"description":"When true, candidates with a non-null rejectionType are excluded","example":"true"},"required":false,"name":"excludeRejected","in":"query"},{"schema":{"type":"string","enum":["asc","desc"],"default":"desc","description":"Sort direction applied to pipeline position (stage, then status)","example":"desc"},"required":false,"name":"sortDirection","in":"query"},{"schema":{"type":"integer","minimum":1,"default":1,"description":"Page number (min: 1)","example":1},"required":false,"name":"page","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":25,"description":"Results per page","example":25},"required":false,"name":"pageSize","in":"query"}],"responses":{"200":{"description":"Paginated list of candidates","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["ok"]},"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Candidate record ID"},"firstName":{"type":["string","null"],"description":"Deprecated — use `person.firstName` instead.","deprecated":true},"lastName":{"type":["string","null"],"description":"Deprecated — use `person.lastName` instead.","deprecated":true},"headlineRole":{"type":["string","null"],"description":"Deprecated — use `person.headlineRole` instead.","deprecated":true},"headlineCompanyName":{"type":["string","null"],"description":"Deprecated — use `person.headlineCompanyName` instead.","deprecated":true},"person":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Person ID (people.id)"},"firstName":{"type":["string","null"],"description":"Person first name"},"lastName":{"type":["string","null"],"description":"Person last name"},"headlineRole":{"type":["string","null"],"description":"Current/most recent job title"},"headlineCompanyName":{"type":["string","null"],"description":"Current/most recent company name"}},"required":["id","firstName","lastName","headlineRole","headlineCompanyName"],"description":"The person record for this candidate"},"stage":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Pipeline stage ID"},"name":{"type":"string","description":"Pipeline stage name","example":"Sourcing"},"phase":{"type":"string","enum":["internal_selection","presentation","first_round","late_stage"],"description":"Pipeline phase of the stage"}},"required":["id","name","phase"],"description":"Candidate's current pipeline stage"},"status":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Pipeline status ID"},"name":{"type":"string","description":"Pipeline status name","example":"Added"}},"required":["id","name"],"description":"Candidate's current pipeline status within the stage"},"rejectedAt":{"type":["string","null"],"description":"ISO 8601 — when the candidate was rejected, null if active"},"rejectionReason":{"type":["string","null"],"description":"Rejection reason, null if active. Returns the label of the agency-defined reason when one was picked (see `customRejectionReasonId`), otherwise the predefined reason code (e.g. `not_qualified`)","example":"Above budget"},"customRejectionReasonId":{"type":["string","null"],"format":"uuid","description":"ID of the agency-defined rejection reason recorded against the candidate, null when none was picked"},"rejectionDetails":{"type":["string","null"],"description":"Free-text rejection details, null when none were given"},"createdAt":{"type":"string","description":"ISO 8601 — when the candidate was added"},"updatedAt":{"type":"string","description":"ISO 8601 — when the candidate was last modified"}},"required":["id","firstName","lastName","headlineRole","headlineCompanyName","person","stage","status","rejectedAt","rejectionReason","customRejectionReasonId","rejectionDetails","createdAt","updatedAt"]}},"pagination":{"type":"object","properties":{"page":{"type":"integer","description":"Current page number","example":1},"pageSize":{"type":"integer","description":"Results per page","example":25},"total":{"type":"integer","description":"Total number of matching candidates","example":42},"hasMore":{"type":"boolean","description":"Whether more pages of results are available","example":true}},"required":["page","pageSize","total","hasMore"]}},"required":["status","data","pagination"]}}}},"401":{"description":"Unauthorized - missing or invalid API key","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["error"]},"error":{"type":"string","description":"Human-readable error message"}},"required":["status","error"]},"example":{"status":"error","error":"Unauthorized"}}}},"404":{"description":"Project not found","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["error"]},"error":{"type":"string","description":"Human-readable error message"}},"required":["status","error"]},"example":{"status":"error","error":"Not found"}}}},"422":{"description":"Validation error - the request body or query parameters failed validation","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["error"]},"errors":{"type":"object","properties":{"formErrors":{"type":"array","items":{"type":"string"},"description":"Top-level validation errors"},"fieldErrors":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Per-field validation errors keyed by field name"}},"required":["formErrors","fieldErrors"]}},"required":["status","errors"]},"example":{"status":"error","errors":{"formErrors":[],"fieldErrors":{"email":["Invalid email"]}}}}}},"429":{"description":"Too many requests - the caller has exceeded the per-agency rate limit for the tier this endpoint counts against (default per minute: 1200 read / 400 write / 60 upload). Inspect the `RateLimit-*` headers — returned on every response, not only on 429s — and back off until the window resets. See the \"Rate limits\" section of the introduction for details.","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}},"content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["error"]},"error":{"type":"string","description":"Human-readable error message"},"tier":{"type":"string","enum":["read","write","upload"],"description":"The rate-limit tier whose quota was exceeded. GET endpoints count against `read`, POST/PUT/PATCH/DELETE against `write`, and multipart file uploads against `upload` — each tier has an independent counter."},"retryAfterSec":{"type":"integer","description":"Number of seconds after which the rate-limit window resets and requests will be accepted again. Prefer this (or the `RateLimit-Reset` header) over the `Retry-After` header, which is not guaranteed to be present."}},"required":["status","error","tier","retryAfterSec"]},"example":{"status":"error","error":"Rate limit exceeded","tier":"read","retryAfterSec":60}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["error"]},"error":{"type":"string","description":"Human-readable error message"}},"required":["status","error"]},"example":{"status":"error","error":"Internal Server error"}}}}}},"post":{"summary":"Create a candidate","description":"Use this endpoint to add a person from your Atlas contacts into a specific project as a candidate - moving them into the recruitment pipeline for that role.\n\nFor example, if you receive a job application through your website and have already added the person to Atlas (using the People endpoints), you can use this endpoint to automatically add them as a candidate to the relevant project, at the right stage of the pipeline.\n\n**What you need to provide:**\n- The **project ID** in the URL path - the project you want to add them to\n- The **person ID** in the request body - the Atlas ID of the person you are adding as a candidate\n- Optionally, a **statusId** or **stageId** to control where in the pipeline they are placed (see below)\n\n**How pipeline placement works:**\n\nEvery project in Atlas has a pipeline made up of stages (e.g. Sourcing, Longlist, Shortlist) and within each stage there are statuses (e.g. Added, Reviewed, Approved). When you add a candidate, you can control exactly where they land:\n\n- **If you provide a `statusId`** - the candidate is placed at that exact status. The `stageId` is ignored if both are provided.\n- **If you provide only a `stageId`** - the candidate is placed at the first status within that stage.\n- **If you provide neither** - the candidate is placed at the very first status of the very first stage (the default starting point).\n\nTo find the correct `statusId` or `stageId` for a project, first call the **Get project details** endpoint - it returns the full pipeline with all stage and status IDs.\n\n**What you get back:**\nThe newly created candidate record, including the candidate ID, person ID, project ID, and the status they were placed at.","tags":["Projects"],"security":[{"BearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid","description":"Project ID","example":"550e8400-e29b-41d4-a716-446655440000"},"required":true,"name":"id","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateCandidatePayload"}}}},"responses":{"201":{"description":"Candidate created","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["ok"]},"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Candidate ID"},"personId":{"type":"string","format":"uuid","description":"Person ID"},"projectId":{"type":"string","format":"uuid","description":"Project ID"},"statusId":{"type":"string","format":"uuid","description":"Assigned status ID"}},"required":["id","personId","projectId","statusId"]}}},"required":["status","data"]}}}},"401":{"description":"Unauthorized - missing or invalid API key","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["error"]},"error":{"type":"string","description":"Human-readable error message"}},"required":["status","error"]},"example":{"status":"error","error":"Unauthorized"}}}},"404":{"description":"Person, project, status, or stage not found","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["error"]},"error":{"type":"string","description":"Human-readable error message"}},"required":["status","error"]},"example":{"status":"error","error":"Not found"}}}},"422":{"description":"Validation error - the request body or query parameters failed validation","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["error"]},"errors":{"type":"object","properties":{"formErrors":{"type":"array","items":{"type":"string"},"description":"Top-level validation errors"},"fieldErrors":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Per-field validation errors keyed by field name"}},"required":["formErrors","fieldErrors"]}},"required":["status","errors"]},"example":{"status":"error","errors":{"formErrors":[],"fieldErrors":{"email":["Invalid email"]}}}}}},"429":{"description":"Too many requests - the caller has exceeded the per-agency rate limit for the tier this endpoint counts against (default per minute: 1200 read / 400 write / 60 upload). Inspect the `RateLimit-*` headers — returned on every response, not only on 429s — and back off until the window resets. See the \"Rate limits\" section of the introduction for details.","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}},"content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["error"]},"error":{"type":"string","description":"Human-readable error message"},"tier":{"type":"string","enum":["read","write","upload"],"description":"The rate-limit tier whose quota was exceeded. GET endpoints count against `read`, POST/PUT/PATCH/DELETE against `write`, and multipart file uploads against `upload` — each tier has an independent counter."},"retryAfterSec":{"type":"integer","description":"Number of seconds after which the rate-limit window resets and requests will be accepted again. Prefer this (or the `RateLimit-Reset` header) over the `Retry-After` header, which is not guaranteed to be present."}},"required":["status","error","tier","retryAfterSec"]},"example":{"status":"error","error":"Rate limit exceeded","tier":"read","retryAfterSec":60}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["error"]},"error":{"type":"string","description":"Human-readable error message"}},"required":["status","error"]},"example":{"status":"error","error":"Internal Server error"}}}}}}},"/api/v1/projects/{projectId}/candidates/{candidateId}":{"get":{"summary":"Get a candidate in a project","description":"Use this endpoint to retrieve the current pipeline position of a single candidate within a specific project — what stage and status they sit at, who owns the candidate record, whether they have been rejected (and why), and a snapshot of the person and project they relate to.\n\nIn Atlas, a **candidate** represents a person who has been added to a project's recruitment pipeline. Each candidate sits at a specific status within a specific stage of the pipeline (e.g. Sourcing → Added, Shortlist → Reviewed). This endpoint returns the full state of one candidate by its ID, scoped to the project provided in the URL.\n\n**What you need to provide:**\n- The **project ID** in the URL path — the project the candidate belongs to\n- The **candidate ID** in the URL path — the candidate record to look up\n\nBoth IDs are UUIDs returned by the **List projects** and **List candidates in a project** endpoints respectively.\n\n**What you get back:**\n- `id` — the candidate record ID\n- `stage` — the candidate's current pipeline stage (`id`, `name`, `phase`)\n- `status` — the candidate's current status within the stage (`id`, `name`)\n- `owner` — the user who owns the candidate record (`id`, `name`, `email`); this is the candidate's owner, not necessarily the project's owner\n- `person` — a snapshot of the underlying person (`id`, `firstName`, `lastName`, `headlineRole`, `headlineCompanyName`); use `person.id` with the People endpoints to fetch the person's full details\n- `project` — a snapshot of the project the candidate is in (`id`, `jobRole`, `state`)\n- `rejectedAt` / `rejectionReason` / `customRejectionReasonId` / `rejectionDetails` — populated when the candidate has been rejected, otherwise `null`. `rejectionReason` returns the label of the agency-defined reason when one was picked (the same label the Atlas app shows), and falls back to the predefined reason code (e.g. `not_qualified`) for rejections recorded before agency-defined reasons existed\n\n**Returns `404` when:**\n- The candidate does not exist, does not belong to the specified project, or is in a different agency.","tags":["Projects"],"security":[{"BearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid","description":"Project ID","example":"550e8400-e29b-41d4-a716-446655440000"},"required":true,"name":"projectId","in":"path"},{"schema":{"type":"string","format":"uuid","description":"Candidate ID","example":"550e8400-e29b-41d4-a716-446655440004"},"required":true,"name":"candidateId","in":"path"}],"responses":{"200":{"description":"Candidate detail within the specified project","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["ok"]},"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Candidate record ID"},"stage":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Pipeline stage ID"},"name":{"type":"string","description":"Pipeline stage name","example":"Sourcing"},"phase":{"type":"string","enum":["internal_selection","presentation","first_round","late_stage"],"description":"Pipeline phase of the stage"}},"required":["id","name","phase"],"description":"Candidate's current pipeline stage"},"status":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Pipeline status ID"},"name":{"type":"string","description":"Pipeline status name","example":"Added"}},"required":["id","name"],"description":"Candidate's current pipeline status within the stage"},"owner":{"type":["object","null"],"properties":{"id":{"type":"string","format":"uuid","description":"Owner user ID"},"name":{"type":"string","description":"Owner name","example":"Jane Smith"},"email":{"type":"string","description":"Owner email","example":"owner@agency.com"}},"required":["id","name","email"],"description":"User who owns this candidate record"},"person":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Person ID (people.id)"},"firstName":{"type":["string","null"],"description":"Person first name"},"lastName":{"type":["string","null"],"description":"Person last name"},"headlineRole":{"type":["string","null"],"description":"Current/most recent job title"},"headlineCompanyName":{"type":["string","null"],"description":"Current/most recent company name"}},"required":["id","firstName","lastName","headlineRole","headlineCompanyName"],"description":"The person record for this candidate"},"project":{"type":["object","null"],"properties":{"id":{"type":"string","format":"uuid","description":"Project ID"},"jobRole":{"type":"string","description":"Project job role/title","example":"Software Engineer"},"state":{"type":"string","enum":["active","closed","on_hold","talent_pool","lead","pitch","opportunity"],"description":"Project state","example":"active"}},"required":["id","jobRole","state"],"description":"The project the candidate is in"},"rejectedAt":{"type":["string","null"],"description":"ISO 8601 — when the candidate was rejected, null if active"},"rejectionReason":{"type":["string","null"],"description":"Rejection reason, null if active. Returns the label of the agency-defined reason when one was picked (see `customRejectionReasonId`), otherwise the predefined reason code (e.g. `not_qualified`)","example":"Above budget"},"customRejectionReasonId":{"type":["string","null"],"format":"uuid","description":"ID of the agency-defined rejection reason recorded against the candidate, null when none was picked"},"rejectionDetails":{"type":["string","null"],"description":"Free-text rejection details, null when none were given"}},"required":["id","stage","status","owner","person","project","rejectedAt","rejectionReason","customRejectionReasonId","rejectionDetails"]}},"required":["status","data"]}}}},"401":{"description":"Unauthorized - missing or invalid API key","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["error"]},"error":{"type":"string","description":"Human-readable error message"}},"required":["status","error"]},"example":{"status":"error","error":"Unauthorized"}}}},"404":{"description":"Candidate not found","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["error"]},"error":{"type":"string","description":"Human-readable error message"}},"required":["status","error"]},"example":{"status":"error","error":"Not found"}}}},"422":{"description":"Validation error - the request body or query parameters failed validation","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["error"]},"errors":{"type":"object","properties":{"formErrors":{"type":"array","items":{"type":"string"},"description":"Top-level validation errors"},"fieldErrors":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Per-field validation errors keyed by field name"}},"required":["formErrors","fieldErrors"]}},"required":["status","errors"]},"example":{"status":"error","errors":{"formErrors":[],"fieldErrors":{"email":["Invalid email"]}}}}}},"429":{"description":"Too many requests - the caller has exceeded the per-agency rate limit for the tier this endpoint counts against (default per minute: 1200 read / 400 write / 60 upload). Inspect the `RateLimit-*` headers — returned on every response, not only on 429s — and back off until the window resets. See the \"Rate limits\" section of the introduction for details.","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}},"content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["error"]},"error":{"type":"string","description":"Human-readable error message"},"tier":{"type":"string","enum":["read","write","upload"],"description":"The rate-limit tier whose quota was exceeded. GET endpoints count against `read`, POST/PUT/PATCH/DELETE against `write`, and multipart file uploads against `upload` — each tier has an independent counter."},"retryAfterSec":{"type":"integer","description":"Number of seconds after which the rate-limit window resets and requests will be accepted again. Prefer this (or the `RateLimit-Reset` header) over the `Retry-After` header, which is not guaranteed to be present."}},"required":["status","error","tier","retryAfterSec"]},"example":{"status":"error","error":"Rate limit exceeded","tier":"read","retryAfterSec":60}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["error"]},"error":{"type":"string","description":"Human-readable error message"}},"required":["status","error"]},"example":{"status":"error","error":"Internal Server error"}}}}}}},"/api/v1/projects/{projectId}/candidates/{candidateId}/move":{"patch":{"summary":"Move a candidate to a different stage or status","description":"Move an existing candidate to a different stage or status within the same project pipeline.\n\n**How pipeline placement works:**\n\n- **If you provide a `statusId`** - the candidate is moved to that exact status. `stageId` is ignored if both are provided.\n- **If you provide only a `stageId`** - the candidate is moved to the first status within that stage.\n\nTo find the correct `statusId` or `stageId` for a project, call the **Get project details** endpoint - it returns the full pipeline with all stage and status IDs.\n\n**Returns `422` when:**\n- The project is closed\n- The candidate has been rejected (the rejection must be rolled back first)","tags":["Projects"],"security":[{"BearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid","description":"Project ID","example":"550e8400-e29b-41d4-a716-446655440000"},"required":true,"name":"projectId","in":"path"},{"schema":{"type":"string","format":"uuid","description":"Candidate ID","example":"550e8400-e29b-41d4-a716-446655440004"},"required":true,"name":"candidateId","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"statusId":{"type":"string","format":"uuid","description":"Target status ID. When provided, stageId is ignored","example":"550e8400-e29b-41d4-a716-446655440002"},"stageId":{"type":"string","format":"uuid","description":"Target stage ID — candidate is moved to the first status of this stage. Ignored when statusId is provided","example":"550e8400-e29b-41d4-a716-446655440003"}}}}}},"responses":{"200":{"description":"Candidate moved","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["ok"]},"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Candidate ID"},"personId":{"type":"string","format":"uuid","description":"Person ID"},"projectId":{"type":"string","format":"uuid","description":"Project ID"},"statusId":{"type":"string","format":"uuid","description":"Resolved target status ID"}},"required":["id","personId","projectId","statusId"]}},"required":["status","data"]}}}},"401":{"description":"Unauthorized - missing or invalid API key","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["error"]},"error":{"type":"string","description":"Human-readable error message"}},"required":["status","error"]},"example":{"status":"error","error":"Unauthorized"}}}},"404":{"description":"Candidate, stage, or status not found","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["error"]},"error":{"type":"string","description":"Human-readable error message"}},"required":["status","error"]},"example":{"status":"error","error":"Not found"}}}},"422":{"description":"Validation error - the request body or query parameters failed validation","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["error"]},"errors":{"type":"object","properties":{"formErrors":{"type":"array","items":{"type":"string"},"description":"Top-level validation errors"},"fieldErrors":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Per-field validation errors keyed by field name"}},"required":["formErrors","fieldErrors"]}},"required":["status","errors"]},"example":{"status":"error","errors":{"formErrors":[],"fieldErrors":{"email":["Invalid email"]}}}}}},"429":{"description":"Too many requests - the caller has exceeded the per-agency rate limit for the tier this endpoint counts against (default per minute: 1200 read / 400 write / 60 upload). Inspect the `RateLimit-*` headers — returned on every response, not only on 429s — and back off until the window resets. See the \"Rate limits\" section of the introduction for details.","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}},"content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["error"]},"error":{"type":"string","description":"Human-readable error message"},"tier":{"type":"string","enum":["read","write","upload"],"description":"The rate-limit tier whose quota was exceeded. GET endpoints count against `read`, POST/PUT/PATCH/DELETE against `write`, and multipart file uploads against `upload` — each tier has an independent counter."},"retryAfterSec":{"type":"integer","description":"Number of seconds after which the rate-limit window resets and requests will be accepted again. Prefer this (or the `RateLimit-Reset` header) over the `Retry-After` header, which is not guaranteed to be present."}},"required":["status","error","tier","retryAfterSec"]},"example":{"status":"error","error":"Rate limit exceeded","tier":"read","retryAfterSec":60}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["error"]},"error":{"type":"string","description":"Human-readable error message"}},"required":["status","error"]},"example":{"status":"error","error":"Internal Server error"}}}}}}},"/api/v1/projects/{projectId}/candidates/{candidateId}/reject":{"patch":{"summary":"Reject a candidate","description":"Reject a candidate in a project pipeline. The candidate keeps their current stage and status but is marked as rejected, and any active outreach campaigns for the candidate are stopped.\n\n**What you need to provide:**\n\n- **`rejectionType`** (required) - who rejected the candidate: `by_us` (the agency), `by_client`, or `self` (the candidate withdrew).\n- **`rejectionReason`** (optional) - a predefined reason code.\n- **`customRejectionReasonId`** (optional) - the ID of one of your agency's custom rejection reasons. Deactivated reasons are rejected with `404`.\n- **`rejectionDetails`** (optional) - free-text notes about the rejection (max 512 characters).\n\nOptional fields also accept an explicit `null`, which is treated the same as omitting the field.\n\n**Returns `422` when:**\n- The project is closed\n- The candidate is already rejected\n- The candidate sits on a legacy pipeline status that does not support rejection\n\nTo move a rejected candidate again, the rejection must be rolled back first (currently only possible in the Atlas app).","tags":["Projects"],"security":[{"BearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid","description":"Project ID","example":"550e8400-e29b-41d4-a716-446655440000"},"required":true,"name":"projectId","in":"path"},{"schema":{"type":"string","format":"uuid","description":"Candidate ID","example":"550e8400-e29b-41d4-a716-446655440004"},"required":true,"name":"candidateId","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"rejectionType":{"type":"string","enum":["by_us","by_client","self"],"description":"Who rejected the candidate: by_us (the agency), by_client, or self (candidate withdrew)","example":"by_us"},"rejectionReason":{"type":["string","null"],"enum":["above_budget","accepted_another_offer","cultural_fit","did_not_attend_the_interview","not_available","not_qualified","other","overqualified","reference_check_failed","rejected_the_offer","technical_test_failed","unresponsive","location","rejected_by_us_or_client","poor_communication","no_right_to_work","lacks_primary_skillset","not_enough_experience","doesnt_have_qualification","position_was_closed","went_with_another_provider","went_cold","too_expensive","not_using_agencies","not_interested","not_currently_hiring","no_response","no_reason","decided_not_to_hire"],"description":"Predefined rejection reason. Optional — omit or send null, e.g. for self rejections","example":"not_qualified"},"customRejectionReasonId":{"type":["string","null"],"format":"uuid","description":"ID of an agency-defined custom rejection reason (must be active). May be combined with rejectionReason. Omit or send null to skip","example":"550e8400-e29b-41d4-a716-446655440005"},"rejectionDetails":{"type":["string","null"],"maxLength":512,"description":"Free-text details about the rejection (max 512 characters). Omit or send null to skip","example":"Salary expectations above the approved band"}},"required":["rejectionType"]}}}},"responses":{"200":{"description":"Candidate rejected","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["ok"]},"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Candidate ID"},"personId":{"type":"string","format":"uuid","description":"Person ID"},"projectId":{"type":"string","format":"uuid","description":"Project ID"},"statusId":{"type":"string","format":"uuid","description":"Pipeline status the candidate was in when rejected"},"rejectionType":{"type":"string","description":"Who rejected the candidate","example":"by_us"},"rejectionReason":{"type":["string","null"],"description":"Predefined rejection reason","example":"not_qualified"},"customRejectionReasonId":{"type":["string","null"],"format":"uuid","description":"Agency-defined custom rejection reason ID"},"rejectionDetails":{"type":["string","null"],"description":"Free-text rejection details"},"rejectedAt":{"type":"string","description":"When the rejection was recorded (ISO 8601, UTC)","example":"2026-07-09T12:00:00.000Z"}},"required":["id","personId","projectId","statusId","rejectionType","rejectionReason","customRejectionReasonId","rejectionDetails","rejectedAt"]}},"required":["status","data"]}}}},"400":{"description":"Bad request - the request body is not valid JSON","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message"},"description":{"type":"string","description":"Details of the JSON parse failure"}},"required":["error","description"]},"example":{"error":"Bad Request. The JSON you sent is not valid.","description":"Unexpected end of JSON input"}}}},"401":{"description":"Unauthorized - missing or invalid API key","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["error"]},"error":{"type":"string","description":"Human-readable error message"}},"required":["status","error"]},"example":{"status":"error","error":"Unauthorized"}}}},"404":{"description":"Project, candidate, or rejection reason not found","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["error"]},"error":{"type":"string","description":"Human-readable error message"}},"required":["status","error"]},"example":{"status":"error","error":"Not found"}}}},"422":{"description":"Validation error - the request body or query parameters failed validation","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["error"]},"errors":{"type":"object","properties":{"formErrors":{"type":"array","items":{"type":"string"},"description":"Top-level validation errors"},"fieldErrors":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Per-field validation errors keyed by field name"}},"required":["formErrors","fieldErrors"]}},"required":["status","errors"]},"example":{"status":"error","errors":{"formErrors":[],"fieldErrors":{"email":["Invalid email"]}}}}}},"429":{"description":"Too many requests - the caller has exceeded the per-agency rate limit for the tier this endpoint counts against (default per minute: 1200 read / 400 write / 60 upload). Inspect the `RateLimit-*` headers — returned on every response, not only on 429s — and back off until the window resets. See the \"Rate limits\" section of the introduction for details.","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}},"content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["error"]},"error":{"type":"string","description":"Human-readable error message"},"tier":{"type":"string","enum":["read","write","upload"],"description":"The rate-limit tier whose quota was exceeded. GET endpoints count against `read`, POST/PUT/PATCH/DELETE against `write`, and multipart file uploads against `upload` — each tier has an independent counter."},"retryAfterSec":{"type":"integer","description":"Number of seconds after which the rate-limit window resets and requests will be accepted again. Prefer this (or the `RateLimit-Reset` header) over the `Retry-After` header, which is not guaranteed to be present."}},"required":["status","error","tier","retryAfterSec"]},"example":{"status":"error","error":"Rate limit exceeded","tier":"read","retryAfterSec":60}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["error"]},"error":{"type":"string","description":"Human-readable error message"}},"required":["status","error"]},"example":{"status":"error","error":"Internal Server error"}}}}}}},"/api/v1/projects/{id}/applicants":{"post":{"summary":"Create an applicant","description":"Use this endpoint to create an applicant on a project from an uploaded resume file.\n\nUnlike candidates (where you add an existing person to a project), applicants are created from a resume file that has been uploaded via the Files endpoint. Atlas will automatically parse the resume and score the applicant against project criteria.\n\n**What you need to provide:**\n- The **project ID** in the URL path\n- A **file_id** in the request body - the ID of a previously uploaded resume file (must be type \"resume\")\n- Optionally, applicant details (name, email, phone, etc.) - if omitted, these are extracted from the resume\n\nTo get a file ID, first upload the resume using the **Upload a file** endpoint.","tags":["Projects"],"security":[{"BearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid","description":"Project ID","example":"550e8400-e29b-41d4-a716-446655440000"},"required":true,"name":"id","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"fileId":{"type":"string","format":"uuid","description":"ID of the uploaded file (must be type \"resume\")","example":"550e8400-e29b-41d4-a716-446655440000"},"firstName":{"type":["string","null"],"minLength":1,"description":"First name","example":"Jane"},"lastName":{"type":["string","null"],"minLength":1,"description":"Last name","example":"Doe"},"email":{"type":["string","null"],"format":"email","description":"Email address","example":"jane.doe@example.com"},"phone":{"type":["string","null"],"minLength":1,"description":"Phone number","example":"+442071234567"},"currentRole":{"type":["string","null"],"minLength":1,"description":"Current job title","example":"Software Engineer"},"currentEmployer":{"type":["string","null"],"minLength":1,"description":"Current employer","example":"Acme Corp"},"source":{"type":"string","enum":["form","manual_upload","api"],"description":"Applicant source","example":"api"},"notes":{"type":["string","null"],"minLength":1,"description":"Free-text notes","example":"Referred by internal team"}},"required":["fileId"]}}}},"responses":{"201":{"description":"Applicant created","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["ok"]},"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Applicant ID"},"project_id":{"type":"string","format":"uuid","description":"Project ID"},"status":{"type":"string","description":"Applicant status","example":"pending"},"first_name":{"type":["string","null"],"description":"First name"},"last_name":{"type":["string","null"],"description":"Last name"},"email":{"type":["string","null"],"description":"Email address"},"phone":{"type":["string","null"],"description":"Phone number"},"current_role":{"type":["string","null"],"description":"Current job title"},"current_employer":{"type":["string","null"],"description":"Current employer"},"source":{"type":"string","description":"Applicant source","example":"api"},"notes":{"type":["string","null"],"description":"Notes"},"file_id":{"type":["string","null"],"format":"uuid","description":"Resume file ID"},"created_at":{"type":"string","format":"date-time","description":"Creation timestamp"}},"required":["id","project_id","status","first_name","last_name","email","phone","current_role","current_employer","source","notes","file_id","created_at"]}},"required":["status","data"]}}}},"400":{"description":"Bad request - file is not of type resume","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["error"]},"error":{"type":"string","description":"Human-readable error message"}},"required":["status","error"]},"example":{"status":"error","error":"File type must be \"resume\""}}}},"401":{"description":"Unauthorized - missing or invalid API key","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["error"]},"error":{"type":"string","description":"Human-readable error message"}},"required":["status","error"]},"example":{"status":"error","error":"Unauthorized"}}}},"404":{"description":"Project or file not found","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["error"]},"error":{"type":"string","description":"Human-readable error message"}},"required":["status","error"]},"example":{"status":"error","error":"Not found"}}}},"422":{"description":"Validation error - the request body or query parameters failed validation","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["error"]},"errors":{"type":"object","properties":{"formErrors":{"type":"array","items":{"type":"string"},"description":"Top-level validation errors"},"fieldErrors":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Per-field validation errors keyed by field name"}},"required":["formErrors","fieldErrors"]}},"required":["status","errors"]},"example":{"status":"error","errors":{"formErrors":[],"fieldErrors":{"email":["Invalid email"]}}}}}},"429":{"description":"Too many requests - the caller has exceeded the per-agency rate limit for the tier this endpoint counts against (default per minute: 1200 read / 400 write / 60 upload). Inspect the `RateLimit-*` headers — returned on every response, not only on 429s — and back off until the window resets. See the \"Rate limits\" section of the introduction for details.","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}},"content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["error"]},"error":{"type":"string","description":"Human-readable error message"},"tier":{"type":"string","enum":["read","write","upload"],"description":"The rate-limit tier whose quota was exceeded. GET endpoints count against `read`, POST/PUT/PATCH/DELETE against `write`, and multipart file uploads against `upload` — each tier has an independent counter."},"retryAfterSec":{"type":"integer","description":"Number of seconds after which the rate-limit window resets and requests will be accepted again. Prefer this (or the `RateLimit-Reset` header) over the `Retry-After` header, which is not guaranteed to be present."}},"required":["status","error","tier","retryAfterSec"]},"example":{"status":"error","error":"Rate limit exceeded","tier":"read","retryAfterSec":60}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["error"]},"error":{"type":"string","description":"Human-readable error message"}},"required":["status","error"]},"example":{"status":"error","error":"Internal Server error"}}}}}}},"/api/v1/public/{agencyId}/projects":{"get":{"summary":"List public projects","description":"Use this endpoint to retrieve a paginated list of public projects for an agency without authentication.\n\nThis endpoint is limited to projects where `public` is `true` and `state` is `active`. It is intended for use in public-facing integrations such as career pages or job boards, where you want to show a list of open roles.\n\nEach item in the list has the same shape as the response from **Get public project details** — so you can render a full role card from the list response without making an extra request per project. This includes the `owner` (the lead consultant on the role, as `{ userId, name, email }`) so you can display contact details next to each job; `owner` is `null` when the project has no owner, or when the recorded owner does not belong to the project's agency.\n\n**What you need to provide:**\n- The **agency ID** in the URL path - the agency whose public projects you want to list\n\n**Incremental sync:**\nPass `updatedAfter` with an ISO 8601 timestamp to receive only projects whose `updatedAt` is later than that timestamp. Each returned item includes `updatedAt`; persist the largest value you see and pass it on the next call as your sync cursor.\n\n**Pagination:**\nResults are returned in pages. Use the `page` and `pageSize` query parameters to move through large result sets. The response includes a `pagination` object so you know how many results exist in total.","tags":["Jobs Portal"],"parameters":[{"schema":{"type":"string","format":"uuid","description":"Agency ID","example":"550e8400-e29b-41d4-a716-446655440000"},"required":true,"name":"agencyId","in":"path"},{"schema":{"type":"string","format":"date-time","description":"Only projects updated after this ISO 8601 timestamp (inclusive)","example":"2026-06-04T10:00:00Z"},"required":false,"name":"updatedAfter","in":"query"},{"schema":{"type":"integer","minimum":1,"default":1,"description":"Page number (1-indexed)","example":1},"required":false,"name":"page","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":100,"description":"Items per page (max 100)","example":25},"required":false,"name":"pageSize","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":100,"description":"Alias for pageSize","deprecated":true},"required":false,"name":"perPage","in":"query"}],"responses":{"200":{"description":"Paginated list of public projects","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["ok"]},"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"jobRole":{"type":"string","description":"Job role/title","example":"Software Engineer"},"jobNumber":{"type":["string","null"],"description":"Job reference number"},"state":{"type":"string","enum":["active","closed","on_hold","talent_pool","lead","pitch","opportunity"],"description":"Project state","example":"active"},"jobDescription":{"type":["string","null"],"description":"Plain text job description"},"jobDescriptionFormatted":{"type":["string","null"],"description":"Job description in formatted HTML"},"contractType":{"type":["string","null"],"enum":["full_time","part_time","contract","non_exec"],"description":"Contract type"},"workMode":{"type":["string","null"],"enum":["office","hybrid","remote"],"description":"Work mode"},"seniority":{"type":["string","null"],"enum":["partner","board","founder","cxo","vp","director","manager","senior","middle","junior"],"description":"Seniority level"},"func":{"type":["string","null"],"description":"Job function"},"hireTarget":{"type":["integer","null"],"description":"Target number of hires","example":1},"visaSupport":{"type":["boolean","null"],"description":"Whether visa support is offered"},"salary":{"type":["string","null"],"description":"Salary or salary range"},"salaryCurrency":{"type":["string","null"],"description":"Salary currency code","example":"USD"},"location":{"type":["object","null"],"properties":{"city":{"type":["string","null"],"description":"City/locality","example":"London"},"region":{"type":["string","null"],"description":"Region/state","example":"England"},"country":{"type":["string","null"],"description":"Country","example":"United Kingdom"},"formattedAddress":{"type":["string","null"],"description":"Full formatted address","example":"London, England, United Kingdom"}},"required":["city","region","country","formattedAddress"],"description":"Project location"},"customAttributes":{"type":"array","items":{"type":"object","properties":{"attributeId":{"type":"string","format":"uuid","description":"Custom attribute definition ID"},"attributeName":{"type":["string","null"],"description":"Attribute name"},"attributeType":{"type":["string","null"],"enum":["options","text_block","text_line","number_input","integer","date"],"description":"Attribute type — drives the shape of each entry in `values`."},"values":{"type":"array","items":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"object","properties":{"optionId":{"type":"string","format":"uuid","description":"Selected option ID"},"optionValue":{"type":["string","null"],"description":"Display value of the option"}},"required":["optionId","optionValue"]}],"description":"A single value entry. Shape depends on `attributeType`:\n- `text_line` / `text_block` → string\n- `integer` / `number_input` → number\n- `date` → ISO `YYYY-MM-DD` string\n- `options` → `{ optionId, optionValue }` object"},"description":"All values recorded for this attribute. For single-value attributes the array has one entry; for multi-select `options` attributes it may have several."}},"required":["attributeId","attributeName","attributeType","values"]},"description":"Custom attribute values for this project"},"createdAt":{"type":["string","null"],"description":"ISO 8601 creation date"},"startedAt":{"type":["string","null"],"description":"Start date (YYYY-MM-DD)","example":"2026-03-23"},"owner":{"type":["object","null"],"properties":{"userId":{"type":"string","format":"uuid","description":"Owner user ID"},"email":{"type":"string","description":"Owner email","example":"owner@agency.com"},"name":{"type":"string","description":"Owner name","example":"Jane Smith"}},"required":["userId","email","name"],"description":"Project owner (lead consultant), or null when the project has no owner or the recorded owner does not belong to the project's agency"},"updatedAt":{"type":["string","null"],"description":"ISO 8601 timestamp of the project's last modification. Persist the largest value seen across a response as the next sync cursor for `updatedAfter`.","example":"2026-06-04T10:00:00.000Z"}},"required":["id","jobRole","jobNumber","state","jobDescription","jobDescriptionFormatted","contractType","workMode","seniority","func","hireTarget","visaSupport","salary","salaryCurrency","location","customAttributes","createdAt","startedAt","owner","updatedAt"]}},"pagination":{"type":"object","properties":{"page":{"type":"integer","description":"Current page number","example":1},"pageSize":{"type":"integer","description":"Items per page","example":25},"total":{"type":"integer","description":"Total matching items","example":42},"totalPages":{"type":"integer","description":"Total number of pages","example":2}},"required":["page","pageSize","total","totalPages"]}},"required":["status","data","pagination"]}}}},"422":{"description":"Validation error - the request body or query parameters failed validation","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["error"]},"errors":{"type":"object","properties":{"formErrors":{"type":"array","items":{"type":"string"},"description":"Top-level validation errors"},"fieldErrors":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Per-field validation errors keyed by field name"}},"required":["formErrors","fieldErrors"]}},"required":["status","errors"]},"example":{"status":"error","errors":{"formErrors":[],"fieldErrors":{"email":["Invalid email"]}}}}}},"429":{"description":"Too many requests - the caller has exceeded the per-agency rate limit for the tier this endpoint counts against (default per minute: 1200 read / 400 write / 60 upload). Inspect the `RateLimit-*` headers — returned on every response, not only on 429s — and back off until the window resets. See the \"Rate limits\" section of the introduction for details.","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}},"content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["error"]},"error":{"type":"string","description":"Human-readable error message"},"tier":{"type":"string","enum":["read","write","upload"],"description":"The rate-limit tier whose quota was exceeded. GET endpoints count against `read`, POST/PUT/PATCH/DELETE against `write`, and multipart file uploads against `upload` — each tier has an independent counter."},"retryAfterSec":{"type":"integer","description":"Number of seconds after which the rate-limit window resets and requests will be accepted again. Prefer this (or the `RateLimit-Reset` header) over the `Retry-After` header, which is not guaranteed to be present."}},"required":["status","error","tier","retryAfterSec"]},"example":{"status":"error","error":"Rate limit exceeded","tier":"read","retryAfterSec":60}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["error"]},"error":{"type":"string","description":"Human-readable error message"}},"required":["status","error"]},"example":{"status":"error","error":"Internal Server error"}}}}}}},"/api/v1/public/{agencyId}/projects/{id}":{"get":{"summary":"Get public project details","description":"Use this endpoint to retrieve details of a public project without authentication.\n\nThis endpoint is limited to projects where `public` is `true`. It is intended for use in public-facing integrations such as career pages or job boards.\n\nThe response includes the `owner` — the lead consultant on the role, as `{ userId, name, email }` — so you can display contact details on the job page. `owner` is `null` when the project has no owner, or when the recorded owner does not belong to the project's agency.\n\nCompared to the authenticated **Get project details** endpoint, this response does not include `company`, `members`, or `stages`.\n\n**What you need to provide:**\n- The **agency ID** in the URL path - the agency the project belongs to\n- The **project ID** in the URL path - the project you want to retrieve\n\nBoth IDs are UUIDs. If the project does not exist, does not belong to the specified agency, or is not marked as public, a 404 response is returned.","tags":["Jobs Portal"],"parameters":[{"schema":{"type":"string","format":"uuid","description":"Agency ID","example":"550e8400-e29b-41d4-a716-446655440000"},"required":true,"name":"agencyId","in":"path"},{"schema":{"type":"string","format":"uuid","description":"Project ID","example":"550e8400-e29b-41d4-a716-446655440001"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Public project details","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["ok"]},"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"jobRole":{"type":"string","description":"Job role/title","example":"Software Engineer"},"jobNumber":{"type":["string","null"],"description":"Job reference number"},"state":{"type":"string","enum":["active","closed","on_hold","talent_pool","lead","pitch","opportunity"],"description":"Project state","example":"active"},"jobDescription":{"type":["string","null"],"description":"Plain text job description"},"jobDescriptionFormatted":{"type":["string","null"],"description":"Job description in formatted HTML"},"contractType":{"type":["string","null"],"enum":["full_time","part_time","contract","non_exec"],"description":"Contract type"},"workMode":{"type":["string","null"],"enum":["office","hybrid","remote"],"description":"Work mode"},"seniority":{"type":["string","null"],"enum":["partner","board","founder","cxo","vp","director","manager","senior","middle","junior"],"description":"Seniority level"},"func":{"type":["string","null"],"description":"Job function"},"hireTarget":{"type":["integer","null"],"description":"Target number of hires","example":1},"visaSupport":{"type":["boolean","null"],"description":"Whether visa support is offered"},"salary":{"type":["string","null"],"description":"Salary or salary range"},"salaryCurrency":{"type":["string","null"],"description":"Salary currency code","example":"USD"},"location":{"type":["object","null"],"properties":{"city":{"type":["string","null"],"description":"City/locality","example":"London"},"region":{"type":["string","null"],"description":"Region/state","example":"England"},"country":{"type":["string","null"],"description":"Country","example":"United Kingdom"},"formattedAddress":{"type":["string","null"],"description":"Full formatted address","example":"London, England, United Kingdom"}},"required":["city","region","country","formattedAddress"],"description":"Project location"},"customAttributes":{"type":"array","items":{"type":"object","properties":{"attributeId":{"type":"string","format":"uuid","description":"Custom attribute definition ID"},"attributeName":{"type":["string","null"],"description":"Attribute name"},"attributeType":{"type":["string","null"],"enum":["options","text_block","text_line","number_input","integer","date"],"description":"Attribute type — drives the shape of each entry in `values`."},"values":{"type":"array","items":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"object","properties":{"optionId":{"type":"string","format":"uuid","description":"Selected option ID"},"optionValue":{"type":["string","null"],"description":"Display value of the option"}},"required":["optionId","optionValue"]}],"description":"A single value entry. Shape depends on `attributeType`:\n- `text_line` / `text_block` → string\n- `integer` / `number_input` → number\n- `date` → ISO `YYYY-MM-DD` string\n- `options` → `{ optionId, optionValue }` object"},"description":"All values recorded for this attribute. For single-value attributes the array has one entry; for multi-select `options` attributes it may have several."}},"required":["attributeId","attributeName","attributeType","values"]},"description":"Custom attribute values for this project"},"createdAt":{"type":["string","null"],"description":"ISO 8601 creation date"},"startedAt":{"type":["string","null"],"description":"Start date (YYYY-MM-DD)","example":"2026-03-23"},"owner":{"type":["object","null"],"properties":{"userId":{"type":"string","format":"uuid","description":"Owner user ID"},"email":{"type":"string","description":"Owner email","example":"owner@agency.com"},"name":{"type":"string","description":"Owner name","example":"Jane Smith"}},"required":["userId","email","name"],"description":"Project owner (lead consultant), or null when the project has no owner or the recorded owner does not belong to the project's agency"},"updatedAt":{"type":["string","null"],"description":"ISO 8601 timestamp of the project's last modification. Persist the largest value seen across a response as the next sync cursor for `updatedAfter`.","example":"2026-06-04T10:00:00.000Z"}},"required":["id","jobRole","jobNumber","state","jobDescription","jobDescriptionFormatted","contractType","workMode","seniority","func","hireTarget","visaSupport","salary","salaryCurrency","location","customAttributes","createdAt","startedAt","owner","updatedAt"]}},"required":["status","data"]}}}},"404":{"description":"Project not found or not public","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["error"]},"error":{"type":"string","description":"Human-readable error message"}},"required":["status","error"]},"example":{"status":"error","error":"Not found"}}}},"422":{"description":"Validation error - the request body or query parameters failed validation","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["error"]},"errors":{"type":"object","properties":{"formErrors":{"type":"array","items":{"type":"string"},"description":"Top-level validation errors"},"fieldErrors":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Per-field validation errors keyed by field name"}},"required":["formErrors","fieldErrors"]}},"required":["status","errors"]},"example":{"status":"error","errors":{"formErrors":[],"fieldErrors":{"email":["Invalid email"]}}}}}},"429":{"description":"Too many requests - the caller has exceeded the per-agency rate limit for the tier this endpoint counts against (default per minute: 1200 read / 400 write / 60 upload). Inspect the `RateLimit-*` headers — returned on every response, not only on 429s — and back off until the window resets. See the \"Rate limits\" section of the introduction for details.","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}},"content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["error"]},"error":{"type":"string","description":"Human-readable error message"},"tier":{"type":"string","enum":["read","write","upload"],"description":"The rate-limit tier whose quota was exceeded. GET endpoints count against `read`, POST/PUT/PATCH/DELETE against `write`, and multipart file uploads against `upload` — each tier has an independent counter."},"retryAfterSec":{"type":"integer","description":"Number of seconds after which the rate-limit window resets and requests will be accepted again. Prefer this (or the `RateLimit-Reset` header) over the `Retry-After` header, which is not guaranteed to be present."}},"required":["status","error","tier","retryAfterSec"]},"example":{"status":"error","error":"Rate limit exceeded","tier":"read","retryAfterSec":60}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["error"]},"error":{"type":"string","description":"Human-readable error message"}},"required":["status","error"]},"example":{"status":"error","error":"Internal Server error"}}}}}}},"/api/v1/candidates":{"get":{"summary":"List candidates","description":"Use this endpoint to retrieve a paginated list of candidates across **all** projects in your agency.\n\nIn Atlas, a **candidate** represents a person who has been added to a project's recruitment pipeline. The same person can be a candidate on several projects at once, so each item in this list is one *candidacy* — a person at a specific status within a specific project's pipeline. Unlike **List candidates in a project**, this endpoint is not scoped to a single project, which makes it the right choice for syncing or reporting on candidates agency-wide.\n\n**What you can filter by:**\n- `personId` — return every candidacy for a single person, across all of their projects\n- `createdAfter` / `createdBefore` — only candidacies added within a date range (inclusive). Accepts an ISO 8601 datetime or a date-only `YYYY-MM-DD` value\n- `updatedAfter` / `updatedBefore` — only candidacies last modified within a date range (inclusive). Use `updatedAfter` as an incremental-sync cursor: persist the largest `updatedAt` you receive and pass it back on the next run\n- `includeDeleted` — when `true`, soft-deleted candidacies are included as tombstones (with a populated `deletedAt`) so you can sync deletions\n\n**Ordering:**\nResults are ordered by candidate creation date (`createdAt`, then `id` as a tiebreaker). Use `sortDirection=asc` or `sortDirection=desc` (default `desc`, newest first) to control the order.\n\n**Pagination:**\nUse `page` (1-based) and `pageSize` (1–100, default 25). The response includes a `pagination` object with `page`, `pageSize`, `total`, and `totalPages`.\n\n**What you get back:**\nEach candidacy includes its ID, a nested `person` (id, name, headline, and contact `identities`), the `project` it belongs to, the current pipeline `stage` and `status`, the `owner`, `rejection` state (null when active), and timestamps. Use `person.id` with the People endpoints to fetch a person's full details.","tags":["Candidates"],"security":[{"BearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid","description":"Filter to candidacies for a single person (across every project they are a candidate in)","example":"550e8400-e29b-41d4-a716-446655440000"},"required":false,"name":"personId","in":"query"},{"schema":{"anyOf":[{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},{"type":"string","format":"date-time"}],"description":"Only candidates created after this point (inclusive). Accepts an ISO 8601 datetime or a date-only YYYY-MM-DD value (covering from the start of that UTC day)","example":"2025-01-01"},"required":false,"name":"createdAfter","in":"query"},{"schema":{"anyOf":[{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},{"type":"string","format":"date-time"}],"description":"Only candidates created before this point (inclusive). Accepts an ISO 8601 datetime or a date-only YYYY-MM-DD value (covering through the end of that UTC day)","example":"2026-01-01"},"required":false,"name":"createdBefore","in":"query"},{"schema":{"anyOf":[{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},{"type":"string","format":"date-time"}],"description":"Only candidates updated after this point (inclusive). Accepts an ISO 8601 datetime or a date-only YYYY-MM-DD value (covering from the start of that UTC day)","example":"2025-06-01"},"required":false,"name":"updatedAfter","in":"query"},{"schema":{"anyOf":[{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},{"type":"string","format":"date-time"}],"description":"Only candidates updated before this point (inclusive). Accepts an ISO 8601 datetime or a date-only YYYY-MM-DD value (covering through the end of that UTC day)","example":"2026-06-01"},"required":false,"name":"updatedBefore","in":"query"},{"schema":{"type":"string","enum":["true","false"],"description":"Include soft-deleted candidates as tombstones (with a populated `deletedAt`). Defaults to false. Pair with `updatedAfter` to incrementally sync deletions.","example":"false"},"required":false,"name":"includeDeleted","in":"query"},{"schema":{"type":"string","enum":["asc","desc"],"default":"desc","description":"Sort direction by candidate creation date (createdAt, then id). Defaults to desc (newest first).","example":"desc"},"required":false,"name":"sortDirection","in":"query"},{"schema":{"type":"integer","minimum":1,"default":1,"description":"Page number (1-indexed)","example":1},"required":false,"name":"page","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":100,"description":"Items per page (max 100)","example":25},"required":false,"name":"pageSize","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":100,"description":"Alias for pageSize","deprecated":true},"required":false,"name":"perPage","in":"query"}],"responses":{"200":{"description":"Paginated list of candidates","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["ok"]},"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Candidate record ID"},"person":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Person ID (people.id)"},"firstName":{"type":["string","null"],"description":"Person first name"},"lastName":{"type":["string","null"],"description":"Person last name"},"headlineRole":{"type":["string","null"],"description":"Current/most recent job title"},"headlineCompanyName":{"type":["string","null"],"description":"Current/most recent company name"},"identities":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["email","phone","linkedin","website"],"description":"Identity type"},"value":{"type":"string","description":"Identity value (email address, phone number, LinkedIn URL, …)"},"isPersonal":{"type":"boolean","description":"Whether this is a personal (vs. work) identity"},"isPrimary":{"type":"boolean","description":"Whether this is the favourited / primary identity of its type"}},"required":["type","value","isPersonal","isPrimary"]},"description":"Active, non-hidden contact identities (email / phone / LinkedIn)"}},"required":["id","firstName","lastName","headlineRole","headlineCompanyName","identities"],"description":"The person record for this candidate"},"project":{"type":["object","null"],"properties":{"id":{"type":"string","format":"uuid","description":"Project ID"},"jobRole":{"type":["string","null"],"description":"Job role of the project"},"state":{"type":"string","description":"Project state","example":"active"}},"required":["id","jobRole","state"],"description":"The project this candidacy belongs to"},"stage":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Pipeline stage ID"},"name":{"type":"string","description":"Pipeline stage name","example":"Sourcing"},"phase":{"type":"string","enum":["internal_selection","presentation","first_round","late_stage","lead_generation","prospect","early_interest","proposal_and_negotiation","closed","client","all_contacts","won"],"description":"Pipeline phase of the stage"}},"required":["id","name","phase"],"description":"Candidate's current pipeline stage"},"status":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Pipeline status ID"},"name":{"type":"string","description":"Pipeline status name","example":"Added"}},"required":["id","name"],"description":"Candidate's current pipeline status within the stage"},"owner":{"type":["object","null"],"properties":{"id":{"type":"string","format":"uuid","description":"Owning user ID"},"name":{"type":["string","null"],"description":"Owning user name"},"email":{"type":["string","null"],"description":"Owning user email"}},"required":["id","name","email"],"description":"The user who owns this candidate record"},"rejection":{"type":["object","null"],"properties":{"type":{"type":["string","null"],"description":"Rejection type"},"reason":{"type":["string","null"],"description":"Rejection reason"},"details":{"type":["string","null"],"description":"Free-text rejection details"},"rejectedAt":{"type":["string","null"],"description":"ISO 8601 — when the candidate was rejected"},"rejectedById":{"type":["string","null"],"format":"uuid","description":"User ID who rejected the candidate"}},"required":["type","reason","details","rejectedAt","rejectedById"],"description":"Rejection state — null when the candidate is active"},"createdAt":{"type":["string","null"],"description":"ISO 8601 — when the candidate was added"},"updatedAt":{"type":["string","null"],"description":"ISO 8601 — when the candidate was last modified"},"deletedAt":{"type":["string","null"],"description":"ISO 8601 — when the candidate was soft-deleted, null unless returned as a tombstone"}},"required":["id","person","project","stage","status","owner","rejection","createdAt","updatedAt","deletedAt"]}},"pagination":{"type":"object","properties":{"page":{"type":"integer","description":"Current page number","example":1},"pageSize":{"type":"integer","description":"Results per page","example":25},"total":{"type":"integer","description":"Total number of matching candidates","example":42},"totalPages":{"type":"integer","description":"Total number of pages","example":2}},"required":["page","pageSize","total","totalPages"]}},"required":["status","data","pagination"]}}}},"401":{"description":"Unauthorized - missing or invalid API key","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["error"]},"error":{"type":"string","description":"Human-readable error message"}},"required":["status","error"]},"example":{"status":"error","error":"Unauthorized"}}}},"422":{"description":"Validation error - the request body or query parameters failed validation","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["error"]},"errors":{"type":"object","properties":{"formErrors":{"type":"array","items":{"type":"string"},"description":"Top-level validation errors"},"fieldErrors":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Per-field validation errors keyed by field name"}},"required":["formErrors","fieldErrors"]}},"required":["status","errors"]},"example":{"status":"error","errors":{"formErrors":[],"fieldErrors":{"email":["Invalid email"]}}}}}},"429":{"description":"Too many requests - the caller has exceeded the per-agency rate limit for the tier this endpoint counts against (default per minute: 1200 read / 400 write / 60 upload). Inspect the `RateLimit-*` headers — returned on every response, not only on 429s — and back off until the window resets. See the \"Rate limits\" section of the introduction for details.","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}},"content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["error"]},"error":{"type":"string","description":"Human-readable error message"},"tier":{"type":"string","enum":["read","write","upload"],"description":"The rate-limit tier whose quota was exceeded. GET endpoints count against `read`, POST/PUT/PATCH/DELETE against `write`, and multipart file uploads against `upload` — each tier has an independent counter."},"retryAfterSec":{"type":"integer","description":"Number of seconds after which the rate-limit window resets and requests will be accepted again. Prefer this (or the `RateLimit-Reset` header) over the `Retry-After` header, which is not guaranteed to be present."}},"required":["status","error","tier","retryAfterSec"]},"example":{"status":"error","error":"Rate limit exceeded","tier":"read","retryAfterSec":60}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["error"]},"error":{"type":"string","description":"Human-readable error message"}},"required":["status","error"]},"example":{"status":"error","error":"Internal Server error"}}}}}}},"/api/v1/candidate-stage-events":{"get":{"summary":"List candidate stage transitions","description":"Returns a keyset-paginated, agency-wide feed of candidate stage transitions (a candidate moving between pipeline stages, e.g. \"Interviewing\" -> \"Offered\"), oldest first. Each row records the from/to stage (id and name), the candidacy with its person (name), the project with its company, the user who moved it (name and email), and when. Nested references are resolved even when the underlying record was later deleted; a reference is null only when it could not be resolved.\n\n**Pagination (keyset):** Responses carry `pagination.hasMore` and `pagination.nextCursor` rather than a page number or total count. Request the first page without a cursor, then send the returned `nextCursor.cursorDate`/`cursorId` on each subsequent request. This stays O(pageSize) at any depth, so it is safe for large historical backfills.\n\n**Backfill:** Loop the cursor until `hasMore` is `false`; optionally bound with `createdAfter` to cap the horizon.\n\n**Incremental sync:** Poll with `createdAfter` (the max `movedAt` from the previous run) and page the cursor within each poll. Overlap slightly and dedupe by `id` so a row written exactly at the boundary is never missed.\n\n**Access:** Requires a key with BOTH `Candidates` and `Users` read scopes, since each row is enriched with the acting user (name and email).\n\n**Notes:** Reverted moves (backward-move corrections) are excluded unless `includeReverted=true`. `stageFrom` is null on the first move into the pipeline. This feed is eventually consistent (populated asynchronously) and is not emitted for talent-pool or lead projects.","tags":["Candidate stage events"],"security":[{"BearerAuth":[]}],"parameters":[{"schema":{"anyOf":[{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},{"type":"string","format":"date-time"}],"description":"Only candidate stage events created after this point (inclusive). Accepts an ISO 8601 datetime or a date-only YYYY-MM-DD value (covering from the start of that UTC day)","example":"2025-01-01"},"required":false,"name":"createdAfter","in":"query"},{"schema":{"anyOf":[{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},{"type":"string","format":"date-time"}],"description":"Only candidate stage events created before this point (inclusive). Accepts an ISO 8601 datetime or a date-only YYYY-MM-DD value (covering through the end of that UTC day)","example":"2026-01-01"},"required":false,"name":"createdBefore","in":"query"},{"schema":{"type":"string","enum":["true","false"],"description":"Include stage moves that were later reverted (backward-move corrections). Defaults to false, so only effective transitions are returned.","example":"false"},"required":false,"name":"includeReverted","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":25,"description":"Items per page (max 100).","example":25},"required":false,"name":"pageSize","in":"query"},{"schema":{"type":"string","format":"date-time","description":"Keyset pagination cursor: the `pagination.nextCursor.cursorDate` returned by the previous request. Send together with `cursorId` to fetch the next page in stable order that stays O(pageSize) at any depth. Omit for the first page.","example":"2026-01-05T12:00:00.000Z"},"required":false,"name":"cursorDate","in":"query"},{"schema":{"type":"string","format":"uuid","description":"Keyset pagination cursor: the `pagination.nextCursor.cursorId` returned by the previous request. Must be sent together with `cursorDate`.","example":"550e8400-e29b-41d4-a716-446655440000"},"required":false,"name":"cursorId","in":"query"}],"responses":{"200":{"description":"Paginated candidate stage transitions","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["ok"]},"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Stable identifier for this stage-move event."},"type":{"type":"string","enum":["candidate_stage_moved"]},"candidate":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"The candidacy (candidate row on a project) this move belongs to."},"person":{"type":["object","null"],"properties":{"id":{"type":"string","format":"uuid"},"firstName":{"type":["string","null"],"example":"Michael"},"lastName":{"type":["string","null"],"example":"Scott"}},"required":["id","firstName","lastName"],"description":"The person behind the candidacy. Null if the person could not be resolved."}},"required":["id","person"],"description":"The candidacy that moved, with its person."},"project":{"type":["object","null"],"properties":{"id":{"type":"string","format":"uuid"},"jobRole":{"type":"string","description":"The project job role / title.","example":"Senior Engineer"},"company":{"type":["object","null"],"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string","example":"Acme Corp"}},"required":["id","name"],"description":"Company the project belongs to, when set."}},"required":["id","jobRole","company"],"description":"Project the candidacy belongs to, with its company. Null when the move carried no project."},"stageFrom":{"type":["object","null"],"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":["string","null"],"description":"Stage name (e.g. \"Interviewing\"). Null if the stage could not be resolved (e.g. it was deleted).","example":"Interviewing"}},"required":["id","name"],"description":"Stage the candidate moved from. Null on the first move into the pipeline."},"stageTo":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":["string","null"],"description":"Stage name (e.g. \"Interviewing\"). Null if the stage could not be resolved (e.g. it was deleted).","example":"Interviewing"}},"required":["id","name"],"description":"Stage the candidate moved to."},"movedBy":{"type":["object","null"],"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string","example":"Jane Recruiter"},"email":{"type":"string","example":"jane@agency.com"}},"required":["id","name","email"],"description":"User who performed the move, when known (null for system/automated moves)."},"movedAt":{"type":"string","description":"UTC ISO 8601 time the move occurred. Use this value as the cursor horizon for `createdAfter` polling."},"isReverted":{"type":"boolean","description":"Whether this move was later reverted. Only present when `includeReverted=true`; otherwise always false."}},"required":["id","type","candidate","project","stageFrom","stageTo","movedBy","movedAt","isReverted"]}},"pagination":{"type":"object","properties":{"pageSize":{"type":"integer","example":25},"hasMore":{"type":"boolean","description":"Whether more rows exist beyond this page. `true` means at least one further page is available — advance the `nextCursor` until it is `false`.","example":false},"nextCursor":{"type":["object","null"],"properties":{"cursorDate":{"type":"string","description":"Pass back as `cursorDate` to fetch the next page."},"cursorId":{"type":"string","format":"uuid","description":"Pass back as `cursorId` to fetch the next page."}},"required":["cursorDate","cursorId"],"description":"Keyset cursor for the next page. Non-null when `hasMore` is `true` — send `cursorDate`/`cursorId` on the next request to page in stable order that stays O(pageSize) at any depth."}},"required":["pageSize","hasMore","nextCursor"]}},"required":["status","data","pagination"]}}}},"401":{"description":"Unauthorized - missing or invalid API key","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["error"]},"error":{"type":"string","description":"Human-readable error message"}},"required":["status","error"]},"example":{"status":"error","error":"Unauthorized"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["error"]},"error":{"type":"string","description":"Human-readable error message"}},"required":["status","error"]},"example":{"status":"error","error":"Not found"}}}},"422":{"description":"Validation error - the request body or query parameters failed validation","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["error"]},"errors":{"type":"object","properties":{"formErrors":{"type":"array","items":{"type":"string"},"description":"Top-level validation errors"},"fieldErrors":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Per-field validation errors keyed by field name"}},"required":["formErrors","fieldErrors"]}},"required":["status","errors"]},"example":{"status":"error","errors":{"formErrors":[],"fieldErrors":{"email":["Invalid email"]}}}}}},"429":{"description":"Too many requests - the caller has exceeded the per-agency rate limit for the tier this endpoint counts against (default per minute: 1200 read / 400 write / 60 upload). Inspect the `RateLimit-*` headers — returned on every response, not only on 429s — and back off until the window resets. See the \"Rate limits\" section of the introduction for details.","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}},"content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["error"]},"error":{"type":"string","description":"Human-readable error message"},"tier":{"type":"string","enum":["read","write","upload"],"description":"The rate-limit tier whose quota was exceeded. GET endpoints count against `read`, POST/PUT/PATCH/DELETE against `write`, and multipart file uploads against `upload` — each tier has an independent counter."},"retryAfterSec":{"type":"integer","description":"Number of seconds after which the rate-limit window resets and requests will be accepted again. Prefer this (or the `RateLimit-Reset` header) over the `Retry-After` header, which is not guaranteed to be present."}},"required":["status","error","tier","retryAfterSec"]},"example":{"status":"error","error":"Rate limit exceeded","tier":"read","retryAfterSec":60}}}}}}},"/api/v1/spec-cv-events":{"get":{"summary":"List spec CV sends","description":"Returns a keyset-paginated, agency-wide feed of speculative (\"spec\") CV sends (`spec_cv_sent`), oldest first — one row each time a candidate CV is emailed to a contact, whether via a direct Float send or a spec campaign email step. Each row records the candidate (person id and name), the contact it went to, the opportunity it belongs to (id and name), the user who sent it (name and email), the spec campaign id when applicable, and when. Nested references are resolved even when the underlying record was later deleted; a reference is null only when it could not be resolved.\n\n**Pagination (keyset):** Responses carry `pagination.hasMore` and `pagination.nextCursor` rather than a page number or total count. Request the first page without a cursor, then send the returned `nextCursor.cursorDate`/`cursorId` on each subsequent request. This stays O(pageSize) at any depth, so it is safe for large historical backfills.\n\n**Backfill:** Loop the cursor until `hasMore` is `false`; optionally bound with `createdAfter` to cap the horizon.\n\n**Incremental sync:** Poll with `createdAfter` (the max `sentAt` from the previous run) and page the cursor within each poll. Overlap slightly and dedupe by `id` so a row written exactly at the boundary is never missed.\n\n**Dual-sync with `/api/v1/prospects`:** Rows exist only from the feature go-live onward — spec CVs floated before that date have no event here. For a complete picture, backfill the legacy state from `GET /api/v1/prospects` first, then poll this feed with `createdAfter` for increments.\n\n**Access:** Requires a key with BOTH `Prospects` and `Users` read scopes, since each row is enriched with the sending user (name and email).\n\n**Notes:** Reverted sends (e.g. the speculative candidate was deleted) are excluded unless `includeReverted=true`. Repeat sends of the same candidate to the same contact on one opportunity are deduplicated at emit time, so they do not produce extra rows. This feed is eventually consistent (populated asynchronously).","tags":["Spec CV events"],"security":[{"BearerAuth":[]}],"parameters":[{"schema":{"anyOf":[{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},{"type":"string","format":"date-time"}],"description":"Only spec CV events created after this point (inclusive). Accepts an ISO 8601 datetime or a date-only YYYY-MM-DD value (covering from the start of that UTC day)","example":"2025-01-01"},"required":false,"name":"createdAfter","in":"query"},{"schema":{"anyOf":[{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},{"type":"string","format":"date-time"}],"description":"Only spec CV events created before this point (inclusive). Accepts an ISO 8601 datetime or a date-only YYYY-MM-DD value (covering through the end of that UTC day)","example":"2026-01-01"},"required":false,"name":"createdBefore","in":"query"},{"schema":{"type":"string","enum":["true","false"],"description":"Include sends that were later reverted (e.g. the speculative candidate was deleted). Defaults to false, so only effective sends are returned.","example":"false"},"required":false,"name":"includeReverted","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":25,"description":"Items per page (max 100).","example":25},"required":false,"name":"pageSize","in":"query"},{"schema":{"type":"string","format":"date-time","description":"Keyset pagination cursor: the `pagination.nextCursor.cursorDate` returned by the previous request. Send together with `cursorId` to fetch the next page in stable order that stays O(pageSize) at any depth. Omit for the first page.","example":"2026-01-05T12:00:00.000Z"},"required":false,"name":"cursorDate","in":"query"},{"schema":{"type":"string","format":"uuid","description":"Keyset pagination cursor: the `pagination.nextCursor.cursorId` returned by the previous request. Must be sent together with `cursorDate`.","example":"550e8400-e29b-41d4-a716-446655440000"},"required":false,"name":"cursorId","in":"query"}],"responses":{"200":{"description":"Paginated spec CV sends","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["ok"]},"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Stable identifier for this spec CV send event."},"type":{"type":"string","enum":["spec_cv_sent"]},"candidate":{"type":["object","null"],"properties":{"id":{"type":"string","format":"uuid"},"firstName":{"type":["string","null"],"example":"Michael"},"lastName":{"type":["string","null"],"example":"Scott"}},"required":["id","firstName","lastName"],"description":"The candidate (person) whose CV was sent. Null if the person could not be resolved."},"contact":{"type":["object","null"],"properties":{"id":{"type":"string","format":"uuid"},"firstName":{"type":["string","null"],"example":"Michael"},"lastName":{"type":["string","null"],"example":"Scott"}},"required":["id","firstName","lastName"],"description":"The contact (person) the CV was sent to. Null if the person could not be resolved."},"opportunity":{"type":["object","null"],"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string","description":"The opportunity name.","example":"Connecting with Acme Corp"}},"required":["id","name"],"description":"The opportunity the send belongs to. Null if it could not be resolved."},"sentBy":{"type":["object","null"],"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string","example":"Jane Recruiter"},"email":{"type":"string","example":"jane@agency.com"}},"required":["id","name","email"],"description":"User who sent the spec CV, when known (null for system/automated sends)."},"sentAt":{"type":"string","description":"UTC ISO 8601 time the spec CV was sent. Use this value as the cursor horizon for `createdAfter` polling."},"campaignId":{"type":["string","null"],"format":"uuid","description":"The spec campaign the send came from. Null for direct Float sends."},"isReverted":{"type":"boolean","description":"Whether this send was later reverted (e.g. the speculative candidate was deleted). Only present when `includeReverted=true`; otherwise always false."}},"required":["id","type","candidate","contact","opportunity","sentBy","sentAt","campaignId","isReverted"]}},"pagination":{"type":"object","properties":{"pageSize":{"type":"integer","example":25},"hasMore":{"type":"boolean","description":"Whether more rows exist beyond this page. `true` means at least one further page is available — advance the `nextCursor` until it is `false`.","example":false},"nextCursor":{"type":["object","null"],"properties":{"cursorDate":{"type":"string","description":"Pass back as `cursorDate` to fetch the next page."},"cursorId":{"type":"string","format":"uuid","description":"Pass back as `cursorId` to fetch the next page."}},"required":["cursorDate","cursorId"],"description":"Keyset cursor for the next page. Non-null when `hasMore` is `true` — send `cursorDate`/`cursorId` on the next request to page in stable order that stays O(pageSize) at any depth."}},"required":["pageSize","hasMore","nextCursor"]}},"required":["status","data","pagination"]}}}},"401":{"description":"Unauthorized - missing or invalid API key","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["error"]},"error":{"type":"string","description":"Human-readable error message"}},"required":["status","error"]},"example":{"status":"error","error":"Unauthorized"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["error"]},"error":{"type":"string","description":"Human-readable error message"}},"required":["status","error"]},"example":{"status":"error","error":"Not found"}}}},"422":{"description":"Validation error - the request body or query parameters failed validation","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["error"]},"errors":{"type":"object","properties":{"formErrors":{"type":"array","items":{"type":"string"},"description":"Top-level validation errors"},"fieldErrors":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Per-field validation errors keyed by field name"}},"required":["formErrors","fieldErrors"]}},"required":["status","errors"]},"example":{"status":"error","errors":{"formErrors":[],"fieldErrors":{"email":["Invalid email"]}}}}}},"429":{"description":"Too many requests - the caller has exceeded the per-agency rate limit for the tier this endpoint counts against (default per minute: 1200 read / 400 write / 60 upload). Inspect the `RateLimit-*` headers — returned on every response, not only on 429s — and back off until the window resets. See the \"Rate limits\" section of the introduction for details.","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}},"content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["error"]},"error":{"type":"string","description":"Human-readable error message"},"tier":{"type":"string","enum":["read","write","upload"],"description":"The rate-limit tier whose quota was exceeded. GET endpoints count against `read`, POST/PUT/PATCH/DELETE against `write`, and multipart file uploads against `upload` — each tier has an independent counter."},"retryAfterSec":{"type":"integer","description":"Number of seconds after which the rate-limit window resets and requests will be accepted again. Prefer this (or the `RateLimit-Reset` header) over the `Retry-After` header, which is not guaranteed to be present."}},"required":["status","error","tier","retryAfterSec"]},"example":{"status":"error","error":"Rate limit exceeded","tier":"read","retryAfterSec":60}}}}}}},"/api/v1/users":{"get":{"summary":"List active users","description":"Use this endpoint to retrieve a list of all active users (consultants) in your Atlas account.\n\nIn Atlas, a **user** is a member of your team who has a login - for example, a recruiter, a researcher, or an admin. This endpoint is useful when you need to look up a user's ID before using it in another API call - for example, when creating a note on a person (which requires the ID of the user the note is attributed to), or when filtering projects by owner or member.\n\n**What you can filter by:**\n- `email` - pass an email address to find a specific user. This is the most common use case: if you know the email address of a consultant, you can use this endpoint to look up their Atlas user ID.\n\n**Pagination:**\nResults are returned in pages. The response includes a `pagination` object telling you the current page, how many results are per page, the total number of users, and the total number of pages. Use the `page` and `pageSize` query parameters to navigate through results.\n\n**What you get back:**\nEach user includes their Atlas user ID, full name, email address, and the date their account was created. Only active (non-deactivated) users are returned.","tags":["Users"],"security":[{"BearerAuth":[]}],"parameters":[{"schema":{"type":"integer","minimum":1,"default":1,"description":"Page number (1-indexed)","example":1},"required":false,"name":"page","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":100,"description":"Items per page (max 100)","example":100},"required":false,"name":"pageSize","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":100,"description":"Alias for pageSize","deprecated":true},"required":false,"name":"perPage","in":"query"},{"schema":{"type":"string","format":"email","description":"Filter by exact email address","example":"user@agency.com"},"required":false,"name":"email","in":"query"}],"responses":{"200":{"description":"Paginated list of active users","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["ok"]},"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"email":{"type":"string","format":"email"},"createdAt":{"type":"string","format":"date-time"},"created_at":{"type":"string","format":"date-time","description":"Use createdAt instead","deprecated":true}},"required":["id","name","email","createdAt","created_at"]}},"pagination":{"type":"object","properties":{"page":{"type":"integer","description":"Current page number","example":1},"pageSize":{"type":"integer","description":"Items per page","example":100},"per_page":{"type":"integer","description":"Use pageSize instead","deprecated":true},"total":{"type":"integer","description":"Total matching items","example":10},"totalPages":{"type":"integer","description":"Total number of pages","example":1},"total_pages":{"type":"integer","description":"Use totalPages instead","deprecated":true}},"required":["page","pageSize","per_page","total","totalPages","total_pages"]}},"required":["status","data","pagination"]}}}},"401":{"description":"Unauthorized - missing or invalid API key","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["error"]},"error":{"type":"string","description":"Human-readable error message"}},"required":["status","error"]},"example":{"status":"error","error":"Unauthorized"}}}},"422":{"description":"Validation error - the request body or query parameters failed validation","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["error"]},"errors":{"type":"object","properties":{"formErrors":{"type":"array","items":{"type":"string"},"description":"Top-level validation errors"},"fieldErrors":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Per-field validation errors keyed by field name"}},"required":["formErrors","fieldErrors"]}},"required":["status","errors"]},"example":{"status":"error","errors":{"formErrors":[],"fieldErrors":{"email":["Invalid email"]}}}}}},"429":{"description":"Too many requests - the caller has exceeded the per-agency rate limit for the tier this endpoint counts against (default per minute: 1200 read / 400 write / 60 upload). Inspect the `RateLimit-*` headers — returned on every response, not only on 429s — and back off until the window resets. See the \"Rate limits\" section of the introduction for details.","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}},"content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["error"]},"error":{"type":"string","description":"Human-readable error message"},"tier":{"type":"string","enum":["read","write","upload"],"description":"The rate-limit tier whose quota was exceeded. GET endpoints count against `read`, POST/PUT/PATCH/DELETE against `write`, and multipart file uploads against `upload` — each tier has an independent counter."},"retryAfterSec":{"type":"integer","description":"Number of seconds after which the rate-limit window resets and requests will be accepted again. Prefer this (or the `RateLimit-Reset` header) over the `Retry-After` header, which is not guaranteed to be present."}},"required":["status","error","tier","retryAfterSec"]},"example":{"status":"error","error":"Rate limit exceeded","tier":"read","retryAfterSec":60}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["error"]},"error":{"type":"string","description":"Human-readable error message"}},"required":["status","error"]},"example":{"status":"error","error":"Internal Server error"}}}}}}},"/api/v1/opportunities":{"get":{"summary":"List opportunities","description":"Returns a paginated list of opportunities with optional filtering.\n\n**Date filters:**\n- `createdAfter` / `createdBefore` - only return opportunities created within a specific date range (ISO 8601)\n- `updatedAfter` / `updatedBefore` - only return opportunities last modified within a specific date range (ISO 8601). Filters on the `updatedAt` field\n\n**Incremental sync:**\nTo keep an external copy in sync, use `updatedAfter` as a cursor: on each run, request `updatedAfter=`, page through the results, and persist the maximum `updatedAt` across the rows you receive. Pass that stored value as `updatedAfter` on the next run to fetch only records that changed since. Because the bound is inclusive you may re-receive the boundary row — upsert by `id` to stay idempotent.\n\n**Deletions (tombstones):**\nSoft-deleted opportunities are excluded by default. Pass `includeDeleted=true` to also receive deleted opportunities as tombstones — each carries a populated `deletedAt` (live rows have `deletedAt: null`). Combine `includeDeleted=true` with `updatedAfter` to incrementally pick up deletions: a soft-delete bumps `updatedAt`, so the deleted row resurfaces in the next poll with `deletedAt` set.","tags":["Opportunities"],"security":[{"BearerAuth":[]}],"parameters":[{"schema":{"type":"integer","minimum":1,"default":1,"description":"Page number (min: 1)","example":1},"required":false,"name":"page","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":25,"description":"Items per page (min: 1, max: 100)","example":25},"required":false,"name":"pageSize","in":"query"},{"schema":{"type":"boolean","description":"Show archived opportunities only. Applies to live rows; when `includeDeleted=true`, soft-deleted opportunities are always returned as tombstones regardless of their archived state.","example":false},"required":false,"name":"archived","in":"query"},{"schema":{"type":"string","description":"Case-insensitive partial match on opportunity name"},"required":false,"name":"name","in":"query"},{"schema":{"type":"string","description":"Comma-separated pipeline stage ID(s)"},"required":false,"name":"stageId","in":"query"},{"schema":{"type":"string","description":"Comma-separated owner email(s)"},"required":false,"name":"ownerEmail","in":"query"},{"schema":{"type":"string","enum":["regular","speculative"],"description":"Filter by opportunity type","example":"regular"},"required":false,"name":"type","in":"query"},{"schema":{"type":"string","enum":["open","won","lost"],"description":"Filter by opportunity status","example":"open"},"required":false,"name":"status","in":"query"},{"schema":{"type":"string","format":"uuid","description":"Filter by associated candidate (person) ID"},"required":false,"name":"candidateId","in":"query"},{"schema":{"anyOf":[{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},{"type":"string","format":"date-time"}],"description":"Only opportunities created after this point (inclusive). Accepts an ISO 8601 datetime or a date-only YYYY-MM-DD value (covering from the start of that UTC day)","example":"2025-01-01"},"required":false,"name":"createdAfter","in":"query"},{"schema":{"anyOf":[{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},{"type":"string","format":"date-time"}],"description":"Only opportunities created before this point (inclusive). Accepts an ISO 8601 datetime or a date-only YYYY-MM-DD value (covering through the end of that UTC day)","example":"2026-01-01"},"required":false,"name":"createdBefore","in":"query"},{"schema":{"anyOf":[{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},{"type":"string","format":"date-time"}],"description":"Only opportunities updated after this point (inclusive). Accepts an ISO 8601 datetime or a date-only YYYY-MM-DD value (covering from the start of that UTC day)","example":"2025-06-01"},"required":false,"name":"updatedAfter","in":"query"},{"schema":{"anyOf":[{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},{"type":"string","format":"date-time"}],"description":"Only opportunities updated before this point (inclusive). Accepts an ISO 8601 datetime or a date-only YYYY-MM-DD value (covering through the end of that UTC day)","example":"2026-06-01"},"required":false,"name":"updatedBefore","in":"query"},{"schema":{"type":"string","enum":["true","false"],"description":"Include soft-deleted opportunities as tombstones (with a populated `deletedAt`). Defaults to false. Pair with `updatedAfter` to incrementally sync deletions.","example":"false"},"required":false,"name":"includeDeleted","in":"query"}],"responses":{"200":{"description":"List of opportunities","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["ok"]},"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"type":{"type":"string","enum":["regular","speculative"]},"status":{"type":"string","enum":["open","won","lost"]},"value":{"type":["integer","null"]},"archived":{"type":"boolean"},"conversionLikelihood":{"type":["integer","null"]},"conversionReasoning":{"type":["string","null"]},"conversionUpdatedAt":{"type":["string","null"],"format":"date-time"},"stage":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"position":{"type":"integer"},"type":{"type":"string","enum":["default_stage","converted"]}},"required":["id","name","position","type"]},"stageUpdatedAt":{"type":["string","null"],"format":"date-time"},"owner":{"type":["object","null"],"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"email":{"type":"string","format":"email"}},"required":["id","name","email"]},"speculativePersonId":{"type":["string","null"],"format":"uuid"},"rejectionReason":{"type":["string","null"]},"rejectedAt":{"type":["string","null"],"format":"date-time"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"deletedAt":{"type":["string","null"],"format":"date-time","description":"ISO 8601 soft-delete timestamp. `null` for live opportunities; populated for tombstones (only returned when `includeDeleted=true`)"}},"required":["id","name","type","status","value","archived","conversionLikelihood","conversionReasoning","conversionUpdatedAt","stage","stageUpdatedAt","owner","rejectionReason","rejectedAt","createdAt","updatedAt","deletedAt"]}},"total":{"type":"integer","description":"Total number of opportunities matching the filter, across all pages"},"page":{"type":"integer","description":"1-based page index that produced this response"},"pageSize":{"type":"integer","description":"Maximum number of items per page (echoed back from the request)"},"hasMore":{"type":"boolean"}},"required":["status","data","total","page","pageSize","hasMore"]}}}},"401":{"description":"Unauthorized - missing or invalid API key","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["error"]},"error":{"type":"string","description":"Human-readable error message"}},"required":["status","error"]},"example":{"status":"error","error":"Unauthorized"}}}},"422":{"description":"Validation error - the request body or query parameters failed validation","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["error"]},"errors":{"type":"object","properties":{"formErrors":{"type":"array","items":{"type":"string"},"description":"Top-level validation errors"},"fieldErrors":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Per-field validation errors keyed by field name"}},"required":["formErrors","fieldErrors"]}},"required":["status","errors"]},"example":{"status":"error","errors":{"formErrors":[],"fieldErrors":{"email":["Invalid email"]}}}}}},"429":{"description":"Too many requests - the caller has exceeded the per-agency rate limit for the tier this endpoint counts against (default per minute: 1200 read / 400 write / 60 upload). Inspect the `RateLimit-*` headers — returned on every response, not only on 429s — and back off until the window resets. See the \"Rate limits\" section of the introduction for details.","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}},"content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["error"]},"error":{"type":"string","description":"Human-readable error message"},"tier":{"type":"string","enum":["read","write","upload"],"description":"The rate-limit tier whose quota was exceeded. GET endpoints count against `read`, POST/PUT/PATCH/DELETE against `write`, and multipart file uploads against `upload` — each tier has an independent counter."},"retryAfterSec":{"type":"integer","description":"Number of seconds after which the rate-limit window resets and requests will be accepted again. Prefer this (or the `RateLimit-Reset` header) over the `Retry-After` header, which is not guaranteed to be present."}},"required":["status","error","tier","retryAfterSec"]},"example":{"status":"error","error":"Rate limit exceeded","tier":"read","retryAfterSec":60}}}}}},"post":{"summary":"Create an opportunity","description":"Creates a new opportunity with optional relations (prospects, companies, job leads). When candidateId is provided the opportunity type is set to speculative; otherwise it is regular. The first pipeline stage is assigned automatically. When no name is provided and the opportunity has more than one prospect or any target company / job lead, a title is generated by the AI title service; otherwise a deterministic default name is used. AI title generation failures are logged and the deterministic name is kept — the create still succeeds.\n\n**Target companies.** The opportunity's target companies are the union of the explicit `companyIds` you pass and the current company resolved for each prospect (resolved in order: an explicit per-person company, then the prospect's `headlineCompanyId`, then their existing company-contact link). Companies are deduplicated by ID, so a prospect whose company is already in `companyIds` does not produce a second entry. Because prospect companies are resolved by ID, linking your contacts to a real company up front (via `headline.companyId` on POST /api/v1/people) is what keeps duplicate stub companies off the opportunity. Every resolved company must belong to your agency or the request fails.","tags":["Opportunities"],"security":[{"BearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateOpportunityPayload"}}}},"responses":{"201":{"description":"Opportunity created","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["ok"]},"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"type":{"type":"string","enum":["regular","speculative"]},"notes":{"type":["string","null"]},"aiSummary":{"type":["string","null"]},"value":{"type":["integer","null"]},"stageId":{"type":"string","format":"uuid"},"ownerId":{"type":"string","format":"uuid"},"owner":{"type":["object","null"],"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"email":{"type":"string","format":"email"}},"required":["id","name","email"]},"candidateId":{"type":["string","null"],"format":"uuid"},"createdById":{"type":"string","format":"uuid"},"createdBy":{"type":["object","null"],"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"email":{"type":"string","format":"email"}},"required":["id","name","email"]},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"prospectIds":{"type":"array","items":{"type":"string","format":"uuid"},"description":"Resolved prospect person IDs that were attached (merged IDs rewritten to targets)"},"companyIds":{"type":"array","items":{"type":"string","format":"uuid"},"description":"Target companies attached"},"jobLeadIds":{"type":"array","items":{"type":"string","format":"uuid"},"description":"Projects linked as job leads"}},"required":["id","name","type","notes","aiSummary","value","stageId","ownerId","owner","candidateId","createdById","createdBy","createdAt","updatedAt","prospectIds","companyIds","jobLeadIds"]}},"required":["status","data"]}}}},"400":{"description":"A referenced person is currently being merged. Retry after the merge completes.","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["error"]},"error":{"type":"string","description":"Human-readable error message"}},"required":["status","error"]},"example":{"status":"error","error":"Some people are currently being merged..."}}}},"401":{"description":"Unauthorized - missing or invalid API key","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["error"]},"error":{"type":"string","description":"Human-readable error message"}},"required":["status","error"]},"example":{"status":"error","error":"Unauthorized"}}}},"409":{"description":"Agency has no opportunity pipeline configured...","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["error"]},"error":{"type":"string","description":"Human-readable error message"}},"required":["status","error"]},"example":{"status":"error","error":"No opportunity pipeline configured for this agency. Create at least one opportunity stage before creating opportunities."}}}},"415":{"description":"Unsupported Media Type. The request body must be sent with `Content-Type: application/json` (charset parameters are accepted). Other content types are rejected up front to avoid silently discarding the payload.","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["error"]},"error":{"type":"string","description":"Human-readable error message"}},"required":["status","error"]},"example":{"status":"error","error":"No opportunity pipeline configured for this agency. Create at least one opportunity stage before creating opportunities."}}}},"422":{"description":"Validation error - the request body or query parameters failed validation","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["error"]},"errors":{"type":"object","properties":{"formErrors":{"type":"array","items":{"type":"string"},"description":"Top-level validation errors"},"fieldErrors":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Per-field validation errors keyed by field name"}},"required":["formErrors","fieldErrors"]}},"required":["status","errors"]},"example":{"status":"error","errors":{"formErrors":[],"fieldErrors":{"email":["Invalid email"]}}}}}},"429":{"description":"Too many requests - the caller has exceeded the per-agency rate limit for the tier this endpoint counts against (default per minute: 1200 read / 400 write / 60 upload). Inspect the `RateLimit-*` headers — returned on every response, not only on 429s — and back off until the window resets. See the \"Rate limits\" section of the introduction for details.","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}},"content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["error"]},"error":{"type":"string","description":"Human-readable error message"},"tier":{"type":"string","enum":["read","write","upload"],"description":"The rate-limit tier whose quota was exceeded. GET endpoints count against `read`, POST/PUT/PATCH/DELETE against `write`, and multipart file uploads against `upload` — each tier has an independent counter."},"retryAfterSec":{"type":"integer","description":"Number of seconds after which the rate-limit window resets and requests will be accepted again. Prefer this (or the `RateLimit-Reset` header) over the `Retry-After` header, which is not guaranteed to be present."}},"required":["status","error","tier","retryAfterSec"]},"example":{"status":"error","error":"Rate limit exceeded","tier":"read","retryAfterSec":60}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["error"]},"error":{"type":"string","description":"Human-readable error message"}},"required":["status","error"]},"example":{"status":"error","error":"Internal Server error"}}}}}}},"/api/v1/opportunities/stages":{"get":{"summary":"List opportunity stages","description":"Returns the pipeline stages configured for the authenticated agency, ordered by `position` ASC. Soft-deleted stages are excluded.","tags":["Opportunities"],"security":[{"BearerAuth":[]}],"responses":{"200":{"description":"List of opportunity stages","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["ok"]},"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"position":{"type":"integer"},"type":{"type":"string","enum":["default_stage","converted"]}},"required":["id","name","position","type"]}}},"required":["status","data"]}}}},"401":{"description":"Unauthorized - missing or invalid API key","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["error"]},"error":{"type":"string","description":"Human-readable error message"}},"required":["status","error"]},"example":{"status":"error","error":"Unauthorized"}}}},"429":{"description":"Too many requests - the caller has exceeded the per-agency rate limit for the tier this endpoint counts against (default per minute: 1200 read / 400 write / 60 upload). Inspect the `RateLimit-*` headers — returned on every response, not only on 429s — and back off until the window resets. See the \"Rate limits\" section of the introduction for details.","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}},"content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["error"]},"error":{"type":"string","description":"Human-readable error message"},"tier":{"type":"string","enum":["read","write","upload"],"description":"The rate-limit tier whose quota was exceeded. GET endpoints count against `read`, POST/PUT/PATCH/DELETE against `write`, and multipart file uploads against `upload` — each tier has an independent counter."},"retryAfterSec":{"type":"integer","description":"Number of seconds after which the rate-limit window resets and requests will be accepted again. Prefer this (or the `RateLimit-Reset` header) over the `Retry-After` header, which is not guaranteed to be present."}},"required":["status","error","tier","retryAfterSec"]},"example":{"status":"error","error":"Rate limit exceeded","tier":"read","retryAfterSec":60}}}}}}},"/api/v1/opportunities/{id}":{"get":{"summary":"Get opportunity details","description":"Returns a single opportunity including its current stage, owner, creator, speculative candidate (for speculative opportunities), attached prospects, target companies, and linked job leads. The `status` field is computed from the stage type and rejection state.","tags":["Opportunities"],"security":[{"BearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid","description":"Opportunity ID","example":"550e8400-e29b-41d4-a716-446655440000"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Opportunity details","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["ok"]},"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"type":{"type":"string","enum":["regular","speculative"]},"status":{"type":"string","enum":["open","lost","won"],"description":"Computed from stage type + rejection state"},"value":{"type":["integer","null"]},"notes":{"type":["string","null"],"description":"Single free-text notes blob stored on the opportunity itself (set via the `notes` field on POST). Not related to `opportunityNotes`, which is the list of individual note records added by users in Atlas."},"aiSummary":{"type":["string","null"]},"archived":{"type":"boolean"},"conversionLikelihood":{"type":["integer","null"],"description":"AI-computed conversion likelihood as a percentage integer (0–100)"},"conversionReasoning":{"type":["string","null"]},"conversionUpdatedAt":{"type":["string","null"],"format":"date-time"},"stage":{"type":["object","null"],"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"position":{"type":"integer"},"type":{"type":"string","enum":["converted","default_stage"]},"opportunitiesCount":{"type":"integer","description":"Number of non-archived, non-rejected opportunities in this stage"},"opportunitiesTotalSum":{"type":"integer","description":"Summed monetary value of non-archived, non-rejected opportunities in this stage"}},"required":["id","name","position","type","opportunitiesCount","opportunitiesTotalSum"]},"stageId":{"type":"string","format":"uuid"},"stageUpdatedAt":{"type":["string","null"],"format":"date-time"},"owner":{"type":["object","null"],"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"email":{"type":"string"}},"required":["id","name","email"]},"ownerId":{"type":"string","format":"uuid"},"createdBy":{"type":["object","null"],"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"email":{"type":"string"}},"required":["id","name","email"]},"speculativePersonId":{"type":["string","null"],"format":"uuid"},"speculativePerson":{"type":["object","null"],"properties":{"personId":{"type":"string","format":"uuid"},"firstName":{"type":["string","null"]},"lastName":{"type":["string","null"]},"avatar":{"type":["string","null"]},"email":{"type":["string","null"]},"headlineRole":{"type":["string","null"]},"headlineCompanyName":{"type":["string","null"]},"headlineCompanyId":{"type":["string","null"],"format":"uuid"}},"required":["personId","firstName","lastName","avatar","email","headlineRole","headlineCompanyName","headlineCompanyId"],"description":"Populated when type is \"speculative\"; null otherwise"},"candidate":{"type":["object","null"],"properties":{"personId":{"type":"string","format":"uuid"},"firstName":{"type":["string","null"]},"lastName":{"type":["string","null"]},"avatar":{"type":["string","null"]},"email":{"type":["string","null"]},"headlineRole":{"type":["string","null"]},"headlineCompanyName":{"type":["string","null"]},"headlineCompanyId":{"type":["string","null"],"format":"uuid"}},"required":["personId","firstName","lastName","avatar","email","headlineRole","headlineCompanyName","headlineCompanyId"],"description":"Alias of speculativePerson retained for REST-consumer parity"},"rejectionReason":{"type":["string","null"],"enum":["cancelled","went_cold","uncompetitive_fees","candidate_no_longer_available","no_longer_relevant","position_filled","went_with_competitor","hired_internally","no_reason","moved_company","no_longer_interesting","reduced_spending"]},"rejectedAt":{"type":["string","null"],"format":"date-time"},"rejectedBy":{"type":["object","null"],"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"email":{"type":"string"}},"required":["id","name","email"]},"createdAt":{"type":["string","null"],"format":"date-time"},"updatedAt":{"type":["string","null"],"format":"date-time"},"leadCount":{"type":"integer"},"activeCandidateCampaignsCount":{"type":"integer"},"jobLeads":{"type":"array","items":{"type":"object","properties":{"jobId":{"type":"string","format":"uuid"},"roleName":{"type":"string"},"companyName":{"type":["string","null"]},"companyId":{"type":["string","null"],"format":"uuid"},"companyLogo":{"type":["string","null"]}},"required":["jobId","roleName","companyName","companyId","companyLogo"]}},"companies":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"TargetCompany row ID"},"companyId":{"type":"string","format":"uuid"},"company":{"type":["object","null"],"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"logo":{"type":["string","null"]},"employeeCount":{"type":["integer","null"]},"size":{"type":["string","null"]},"summary":{"type":["string","null"]},"industry":{"type":["array","null"],"items":{"type":"string"}},"location":{"type":["object","null"],"properties":{"raw":{"type":["string","null"],"description":"Unstructured location string (e.g. provider-normalized address text)"},"streetAddress":{"type":["string","null"],"description":"Street address line 1"},"addressLine2":{"type":["string","null"],"description":"Street address line 2"},"city":{"type":["string","null"],"description":"City / locality"},"region":{"type":["string","null"],"description":"Region / state"},"postalCode":{"type":["string","null"],"description":"Postal / ZIP code"},"country":{"type":["string","null"],"description":"Country"},"metro":{"type":["string","null"],"description":"Metro area (US only)"},"formattedAddress":{"type":["string","null"],"description":"Provider-normalized \"city, region, country\" string"},"latitude":{"type":["number","null"],"description":"Latitude in decimal degrees"},"longitude":{"type":["number","null"],"description":"Longitude in decimal degrees"}},"required":["raw","streetAddress","addressLine2","city","region","postalCode","country","metro","formattedAddress","latitude","longitude"],"description":"Null when the company has no usable location data; otherwise the shared REST location DTO shared with companies/projects/people endpoints"}},"required":["id","name","logo","employeeCount","size","summary","industry","location"]}},"required":["id","companyId","company"]}},"prospects":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Opportunity-person row ID — identifies this prospect link only. Not a person ID, and NOT valid as a `companyContactIds` value on POST /api/v1/projects (use `companyContact.id` from GET /api/v1/people for that)."},"personId":{"type":"string","format":"uuid","description":"Atlas person ID — use this for person endpoints and as a `prospectIds` value."},"contactId":{"type":"string","format":"uuid","description":"Alias of `id` (the opportunity-person row) — retained for REST-consumer parity. Despite the name, this is not a CompanyContact junction ID."},"createdAt":{"type":["string","null"],"format":"date-time"},"firstName":{"type":["string","null"]},"lastName":{"type":["string","null"]},"avatar":{"type":["string","null"]},"email":{"type":["string","null"]},"headlineRole":{"type":["string","null"]},"headlineCompanyName":{"type":["string","null"]},"headlineCompanyId":{"type":["string","null"],"format":"uuid"}},"required":["id","personId","contactId","createdAt","firstName","lastName","avatar","email","headlineRole","headlineCompanyName","headlineCompanyId"]}},"opportunityNotes":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"text":{"type":"string"},"createdAt":{"type":["string","null"],"format":"date-time"},"createdBy":{"type":["object","null"],"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"}},"required":["id","name"]}},"required":["id","text","createdAt","createdBy"]},"description":"Individual note records added to the opportunity by users in Atlas, each with its own author and timestamp. Not related to the top-level `notes` string, which is the free-text blob stored on the opportunity itself."},"users":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"OpportunityUser row ID"},"userId":{"type":"string","format":"uuid"},"user":{"type":["object","null"],"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"}},"required":["id","name"]}},"required":["id","userId","user"]},"description":"Opportunity members/collaborators"},"outreachCampaigns":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"status":{"type":"string"},"type":{"type":"string"},"projectId":{"type":["string","null"],"format":"uuid"},"createdAt":{"type":["string","null"],"format":"date-time"},"updatedAt":{"type":["string","null"],"format":"date-time"},"owner":{"type":["object","null"],"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"}},"required":["id","name"]}},"required":["id","name","status","type","projectId","createdAt","updatedAt","owner"]}}},"required":["id","name","type","status","value","notes","aiSummary","archived","conversionLikelihood","conversionReasoning","conversionUpdatedAt","stage","stageId","stageUpdatedAt","owner","ownerId","createdBy","speculativePersonId","speculativePerson","candidate","rejectionReason","rejectedAt","rejectedBy","createdAt","updatedAt","leadCount","activeCandidateCampaignsCount","jobLeads","companies","prospects","opportunityNotes","users","outreachCampaigns"]}},"required":["status","data"]}}}},"401":{"description":"Unauthorized - missing or invalid API key","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["error"]},"error":{"type":"string","description":"Human-readable error message"}},"required":["status","error"]},"example":{"status":"error","error":"Unauthorized"}}}},"404":{"description":"Opportunity not found or belongs to a different agency","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["error"]},"error":{"type":"string","description":"Human-readable error message"}},"required":["status","error"]},"example":{"status":"fail","error":"Opportunity not found"}}}},"422":{"description":"Validation error - the request body or query parameters failed validation","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["error"]},"errors":{"type":"object","properties":{"formErrors":{"type":"array","items":{"type":"string"},"description":"Top-level validation errors"},"fieldErrors":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Per-field validation errors keyed by field name"}},"required":["formErrors","fieldErrors"]}},"required":["status","errors"]},"example":{"status":"error","errors":{"formErrors":[],"fieldErrors":{"email":["Invalid email"]}}}}}},"429":{"description":"Too many requests - the caller has exceeded the per-agency rate limit for the tier this endpoint counts against (default per minute: 1200 read / 400 write / 60 upload). Inspect the `RateLimit-*` headers — returned on every response, not only on 429s — and back off until the window resets. See the \"Rate limits\" section of the introduction for details.","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}},"content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["error"]},"error":{"type":"string","description":"Human-readable error message"},"tier":{"type":"string","enum":["read","write","upload"],"description":"The rate-limit tier whose quota was exceeded. GET endpoints count against `read`, POST/PUT/PATCH/DELETE against `write`, and multipart file uploads against `upload` — each tier has an independent counter."},"retryAfterSec":{"type":"integer","description":"Number of seconds after which the rate-limit window resets and requests will be accepted again. Prefer this (or the `RateLimit-Reset` header) over the `Retry-After` header, which is not guaranteed to be present."}},"required":["status","error","tier","retryAfterSec"]},"example":{"status":"error","error":"Rate limit exceeded","tier":"read","retryAfterSec":60}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["error"]},"error":{"type":"string","description":"Human-readable error message"}},"required":["status","error"]},"example":{"status":"error","error":"Internal Server error"}}}}}},"patch":{"summary":"Add linkages to an opportunity","description":"Additively links prospects (person IDs), target companies, and job-lead projects to an existing opportunity. All body fields are optional but at least one must be provided. Existing linkages are never removed, and re-adding an already-linked ID is a no-op (still returns 200). Merged person IDs are resolved to their canonical person automatically. Linking a job-lead project also adds its company as a target company, and attaching a prospect adds their current company as a target company — mirroring the create endpoint. The response echoes the full current linkage sets (not just the additions).","tags":["Opportunities"],"security":[{"BearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid","description":"Opportunity ID","example":"550e8400-e29b-41d4-a716-446655440000"},"required":true,"name":"id","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateOpportunityPayload"}}}},"responses":{"200":{"description":"Linkages added","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["ok"]},"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"prospectIds":{"type":"array","items":{"type":"string","format":"uuid"},"description":"All prospect person IDs currently linked to the opportunity"},"companyIds":{"type":"array","items":{"type":"string","format":"uuid"},"description":"All target company IDs currently linked to the opportunity"},"jobLeadIds":{"type":"array","items":{"type":"string","format":"uuid"},"description":"All job-lead project IDs currently linked to the opportunity"}},"required":["id","prospectIds","companyIds","jobLeadIds"]}},"required":["status","data"]}}}},"401":{"description":"Unauthorized - missing or invalid API key","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["error"]},"error":{"type":"string","description":"Human-readable error message"}},"required":["status","error"]},"example":{"status":"error","error":"Unauthorized"}}}},"404":{"description":"Opportunity not found or belongs to a different agency","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["error"]},"error":{"type":"string","description":"Human-readable error message"}},"required":["status","error"]},"example":{"status":"fail","error":"Opportunity not found"}}}},"422":{"description":"Validation error - the request body or query parameters failed validation","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["error"]},"errors":{"type":"object","properties":{"formErrors":{"type":"array","items":{"type":"string"},"description":"Top-level validation errors"},"fieldErrors":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Per-field validation errors keyed by field name"}},"required":["formErrors","fieldErrors"]}},"required":["status","errors"]},"example":{"status":"error","errors":{"formErrors":[],"fieldErrors":{"email":["Invalid email"]}}}}}},"429":{"description":"Too many requests - the caller has exceeded the per-agency rate limit for the tier this endpoint counts against (default per minute: 1200 read / 400 write / 60 upload). Inspect the `RateLimit-*` headers — returned on every response, not only on 429s — and back off until the window resets. See the \"Rate limits\" section of the introduction for details.","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}},"content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["error"]},"error":{"type":"string","description":"Human-readable error message"},"tier":{"type":"string","enum":["read","write","upload"],"description":"The rate-limit tier whose quota was exceeded. GET endpoints count against `read`, POST/PUT/PATCH/DELETE against `write`, and multipart file uploads against `upload` — each tier has an independent counter."},"retryAfterSec":{"type":"integer","description":"Number of seconds after which the rate-limit window resets and requests will be accepted again. Prefer this (or the `RateLimit-Reset` header) over the `Retry-After` header, which is not guaranteed to be present."}},"required":["status","error","tier","retryAfterSec"]},"example":{"status":"error","error":"Rate limit exceeded","tier":"read","retryAfterSec":60}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["error"]},"error":{"type":"string","description":"Human-readable error message"}},"required":["status","error"]},"example":{"status":"error","error":"Internal Server error"}}}}}}},"/api/v1/prospects":{"get":{"summary":"List prospects","description":"Returns a paginated, agency-scoped list of prospects — people attached to opportunities (`opportunity_people` rows) — as a flat list, not nested under a single opportunity.\n\n**Relationship to the Spec CV / float workflow.** A prospect is created whenever a person is attached to an opportunity. The Spec CV workflow (speculatively sending a candidate CV to a client with no active role) creates a *speculative* opportunity plus a prospect on float/send, so filtering with `opportunityType=speculative` surfaces spec-CV prospects, while `opportunityType=regular` returns prospects on standard business-development opportunities.\n\n**Filters:**\n- `opportunityType` — `regular` | `speculative` (the parent opportunity type)\n- `opportunityId` — restrict to a single opportunity\n- `createdAfter` / `createdBefore` — filter on when the prospect was added (ISO 8601 or YYYY-MM-DD)\n- `updatedAfter` / `updatedBefore` — filter on when the prospect was last modified (ISO 8601 or YYYY-MM-DD). Use `updatedAfter` as an incremental-sync cursor: persist the max `updatedAt` you receive and pass it back on the next poll to fetch only what changed (upsert by `id`).\n- `includeDeleted` — when `true`, soft-deleted prospects are included as tombstones (with a populated `deletedAt`). Pair with `updatedAfter` to incrementally sync deletions: a soft-delete bumps `updatedAt`, so the removed prospect resurfaces on the next poll with `deletedAt` set.\n\n`addedBy` is populated from the prospect creator where recorded; it is `null` for legacy rows that predate creator attribution.","tags":["Prospects"],"security":[{"BearerAuth":[]}],"parameters":[{"schema":{"type":"string","enum":["regular","speculative"],"description":"Filter by the type of the parent opportunity. `speculative` opportunities are created by the Spec CV / float workflow (sending a candidate CV to a client with no active role); `regular` opportunities are standard business-development opportunities.","example":"regular"},"required":false,"name":"opportunityType","in":"query"},{"schema":{"type":"string","format":"uuid","description":"Only return prospects belonging to this opportunity"},"required":false,"name":"opportunityId","in":"query"},{"schema":{"anyOf":[{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},{"type":"string","format":"date-time"}],"description":"Only prospects created after this point (inclusive). Accepts an ISO 8601 datetime or a date-only YYYY-MM-DD value (covering from the start of that UTC day)","example":"2025-01-01"},"required":false,"name":"createdAfter","in":"query"},{"schema":{"anyOf":[{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},{"type":"string","format":"date-time"}],"description":"Only prospects created before this point (inclusive). Accepts an ISO 8601 datetime or a date-only YYYY-MM-DD value (covering through the end of that UTC day)","example":"2026-01-01"},"required":false,"name":"createdBefore","in":"query"},{"schema":{"anyOf":[{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},{"type":"string","format":"date-time"}],"description":"Only prospects updated after this point (inclusive). Accepts an ISO 8601 datetime or a date-only YYYY-MM-DD value (covering from the start of that UTC day)","example":"2025-06-01"},"required":false,"name":"updatedAfter","in":"query"},{"schema":{"anyOf":[{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},{"type":"string","format":"date-time"}],"description":"Only prospects updated before this point (inclusive). Accepts an ISO 8601 datetime or a date-only YYYY-MM-DD value (covering through the end of that UTC day)","example":"2026-06-01"},"required":false,"name":"updatedBefore","in":"query"},{"schema":{"type":"string","enum":["true","false"],"description":"Include soft-deleted prospects as tombstones (with a populated `deletedAt`). Defaults to false. Pair with `updatedAfter` to incrementally sync deletions.","example":"false"},"required":false,"name":"includeDeleted","in":"query"},{"schema":{"type":"integer","minimum":1,"default":1,"description":"Page number (1-indexed)","example":1},"required":false,"name":"page","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":100,"description":"Items per page (max 100)","example":25},"required":false,"name":"pageSize","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":100,"description":"Alias for pageSize","deprecated":true},"required":false,"name":"perPage","in":"query"}],"responses":{"200":{"description":"List of prospects","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["ok"]},"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"OpportunityPerson row ID (the prospect link)"},"personId":{"type":"string","format":"uuid","description":"The linked person ID"},"firstName":{"type":["string","null"]},"lastName":{"type":["string","null"]},"headlineRole":{"type":["string","null"],"description":"The person's current headline role"},"headlineCompanyName":{"type":["string","null"],"description":"The person's current headline company name"},"opportunity":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"type":{"type":"string","enum":["regular","speculative"]}},"required":["id","name","type"]},"addedBy":{"type":["object","null"],"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"email":{"type":"string"}},"required":["id","name","email"],"description":"The user who added the prospect. `null` for legacy rows created before attribution was recorded."},"createdAt":{"type":"string","format":"date-time","description":"When the prospect was added to the opportunity (ISO 8601)"},"updatedAt":{"type":"string","format":"date-time","description":"When the prospect was last modified (ISO 8601)"},"deletedAt":{"type":["string","null"],"format":"date-time","description":"Soft-delete timestamp (ISO 8601). `null` for live prospects; populated for tombstones (only returned when `includeDeleted=true`)."}},"required":["id","personId","firstName","lastName","headlineRole","headlineCompanyName","opportunity","addedBy","createdAt","updatedAt","deletedAt"]}},"pagination":{"type":"object","properties":{"page":{"type":"integer","description":"Current page number (1-indexed)"},"pageSize":{"type":"integer","description":"Items per page"},"total":{"type":"integer","description":"Total prospects matching the filter, across all pages"},"totalPages":{"type":"integer","description":"Total number of pages"}},"required":["page","pageSize","total","totalPages"]}},"required":["status","data","pagination"]}}}},"401":{"description":"Unauthorized - missing or invalid API key","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["error"]},"error":{"type":"string","description":"Human-readable error message"}},"required":["status","error"]},"example":{"status":"error","error":"Unauthorized"}}}},"422":{"description":"Validation error - the request body or query parameters failed validation","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["error"]},"errors":{"type":"object","properties":{"formErrors":{"type":"array","items":{"type":"string"},"description":"Top-level validation errors"},"fieldErrors":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Per-field validation errors keyed by field name"}},"required":["formErrors","fieldErrors"]}},"required":["status","errors"]},"example":{"status":"error","errors":{"formErrors":[],"fieldErrors":{"email":["Invalid email"]}}}}}},"429":{"description":"Too many requests - the caller has exceeded the per-agency rate limit for the tier this endpoint counts against (default per minute: 1200 read / 400 write / 60 upload). Inspect the `RateLimit-*` headers — returned on every response, not only on 429s — and back off until the window resets. See the \"Rate limits\" section of the introduction for details.","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}},"content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["error"]},"error":{"type":"string","description":"Human-readable error message"},"tier":{"type":"string","enum":["read","write","upload"],"description":"The rate-limit tier whose quota was exceeded. GET endpoints count against `read`, POST/PUT/PATCH/DELETE against `write`, and multipart file uploads against `upload` — each tier has an independent counter."},"retryAfterSec":{"type":"integer","description":"Number of seconds after which the rate-limit window resets and requests will be accepted again. Prefer this (or the `RateLimit-Reset` header) over the `Retry-After` header, which is not guaranteed to be present."}},"required":["status","error","tier","retryAfterSec"]},"example":{"status":"error","error":"Rate limit exceeded","tier":"read","retryAfterSec":60}}}}}}},"/api/v1/campaigns":{"get":{"summary":"List campaigns","description":"Returns a paginated list of active outreach campaigns for a given project or opportunity.","tags":["Campaigns"],"security":[{"BearerAuth":[]}],"parameters":[{"schema":{"type":"string","enum":["project","opportunity"],"description":"Type of parent entity","example":"project"},"required":true,"name":"entityType","in":"query"},{"schema":{"type":"string","format":"uuid","description":"ID of the project or opportunity","example":"550e8400-e29b-41d4-a716-446655440000"},"required":true,"name":"entityId","in":"query"},{"schema":{"type":"integer","minimum":1,"default":1,"description":"Page number","example":1},"required":false,"name":"page","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":25,"description":"Items per page","example":25},"required":false,"name":"pageSize","in":"query"}],"responses":{"200":{"description":"Paginated list of campaigns","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["ok"]},"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Campaign ID"},"name":{"type":"string","description":"Campaign name","example":"Q1 Outreach"},"status":{"type":"string","enum":["active"],"description":"Campaign status","example":"active"},"type":{"type":"string","enum":["candidate_outreach","prospect_outreach","speculative"],"description":"Campaign type","example":"candidate_outreach"},"ownerId":{"type":"string","format":"uuid","description":"Owner user ID"},"createdAt":{"type":["string","null"],"description":"ISO 8601 creation date","example":"2025-01-01T00:00:00.000Z"}},"required":["id","name","status","type","ownerId","createdAt"]}},"pagination":{"type":"object","properties":{"page":{"type":"integer","description":"Current page number","example":1},"pageSize":{"type":"integer","description":"Items per page","example":25},"total":{"type":"integer","description":"Total number of matching campaigns","example":1},"totalPages":{"type":"integer","description":"Total number of pages","example":1}},"required":["page","pageSize","total","totalPages"]}},"required":["status","data","pagination"]}}}},"401":{"description":"Unauthorized - missing or invalid API key","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["error"]},"error":{"type":"string","description":"Human-readable error message"}},"required":["status","error"]},"example":{"status":"error","error":"Unauthorized"}}}},"422":{"description":"Validation error - the request body or query parameters failed validation","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["error"]},"errors":{"type":"object","properties":{"formErrors":{"type":"array","items":{"type":"string"},"description":"Top-level validation errors"},"fieldErrors":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Per-field validation errors keyed by field name"}},"required":["formErrors","fieldErrors"]}},"required":["status","errors"]},"example":{"status":"error","errors":{"formErrors":[],"fieldErrors":{"email":["Invalid email"]}}}}}},"429":{"description":"Too many requests - the caller has exceeded the per-agency rate limit for the tier this endpoint counts against (default per minute: 1200 read / 400 write / 60 upload). Inspect the `RateLimit-*` headers — returned on every response, not only on 429s — and back off until the window resets. See the \"Rate limits\" section of the introduction for details.","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}},"content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["error"]},"error":{"type":"string","description":"Human-readable error message"},"tier":{"type":"string","enum":["read","write","upload"],"description":"The rate-limit tier whose quota was exceeded. GET endpoints count against `read`, POST/PUT/PATCH/DELETE against `write`, and multipart file uploads against `upload` — each tier has an independent counter."},"retryAfterSec":{"type":"integer","description":"Number of seconds after which the rate-limit window resets and requests will be accepted again. Prefer this (or the `RateLimit-Reset` header) over the `Retry-After` header, which is not guaranteed to be present."}},"required":["status","error","tier","retryAfterSec"]},"example":{"status":"error","error":"Rate limit exceeded","tier":"read","retryAfterSec":60}}}}}},"post":{"summary":"Create a campaign","description":"Creates a reusable **outreach campaign template** — a named sequence of 1–20 steps — under a project (`entityType: \"project\"` → candidate outreach) or an opportunity (`entityType: \"opportunity\"` → prospect outreach). The campaign **type is derived from the parent**; do not send it.\n\nStep `subject`/`body` may contain `{{variable}}` placeholders (see the **Campaigns** tag for the full variable reference). Standard placeholders are validated at create time — an unknown name is rejected with 422. `{{ai:...}}` variables are stored verbatim and returned per step under `aiVariables` for you to resolve before launch. `{{manual:...}}` is not supported and is rejected with 422.\n\nThis endpoint **does not resolve variables and does not send anything**. To launch the template at a person, use `POST /api/v1/campaigns/{id}/launch`.","tags":["Campaigns"],"security":[{"BearerAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":255,"description":"Campaign name","example":"Q1 Senior Engineers Outreach"},"entityType":{"type":"string","enum":["project","opportunity"],"description":"Parent entity type","example":"project"},"entityId":{"type":"string","format":"uuid","description":"Parent id — a project id when entityType is \"project\", otherwise an opportunity id.","example":"550e8400-e29b-41d4-a716-446655440000"},"ownerEmail":{"type":"string","maxLength":255,"format":"email","description":"Email of the campaign owner. Must match an active user in your agency, otherwise 404.","example":"recruiter@agency.com"},"steps":{"type":"array","items":{"type":"object","properties":{"position":{"type":"integer","minimum":1,"description":"Step order — 1, 2, 3… unique and contiguous within the campaign, no skipping numbers","example":1},"type":{"type":"string","enum":["email","li_inmail","li_request","phone_call","todo"],"description":"The channel: email, li_inmail (LinkedIn InMail), li_request (LinkedIn connection request), phone_call, or todo.","example":"email"},"dispatchType":{"type":"string","enum":["new_thread","reply_to"],"description":"Email steps only, and required for them. new_thread = start a brand new email; reply_to = reply on the same thread as the previous email step.","example":"new_thread"},"subject":{"type":"string","minLength":1,"maxLength":2000,"description":"Email subject. Required for new_thread email steps. May contain the same {{placeholder}} and {{ai:...}} tokens as body.","example":"Exciting {{job_role}} role at {{client_name}}"},"body":{"type":"string","maxLength":50000,"description":"The message text. Required for every step type except phone_call. May contain {{static}}, {{ai:prompt}}, and time-sensitive placeholders — see the Campaigns tag.\n\nPlain text by default: a blank line between sentences starts a new paragraph; a single line break becomes a line break within the same paragraph. There is no automatic bullet-point support — a leading dash or asterisk shows up literally.\n\nFor real bullet points, bold, or links, write actual HTML tags: paragraphs (

), line breaks (
), bold (), italics (), underline (), links (), bullet/numbered lists (