{"openapi":"3.1.0","info":{"title":"Rotto API","version":"1.0.0","description":"Find anyone's work email, personal email and phone number from a LinkedIn profile link or an email address, and search Rotto's candidates from a plain-English brief, from your own code.\n\nThe API runs the same lookups and searches as the Rotto app and the [Rotto MCP server](https://rotto.com/mcp): the same prices, the same balance and the same contacts. Anything you look up here shows in your workspace, and anything you looked up there you can read here for free.\n\n## Quickstart\n\n1. **Create a key.** In Rotto, open [Settings](https://rotto.com/candidates/settings?tab=apps), then Connected apps, then Create API key. Copy it: it is shown once.\n2. **Check your balance.**\n\n```bash\ncurl https://rotto.com/api/v1/balance \\\n  -H \"Authorization: Bearer $ROTTO_API_KEY\"\n```\n\n3. **Look someone up.** You pay only for the details that are found.\n\n```bash\ncurl https://rotto.com/api/v1/contacts/lookup \\\n  -H \"Authorization: Bearer $ROTTO_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"input\": \"https://www.linkedin.com/in/ada-lovelace\", \"max_credits\": 20}'\n```\n\n## Authentication\n\nSend your key on every call as `Authorization: Bearer rcl_live_...`. Each key carries its own permissions, chosen when you create it:\n\n- `lookup`: look people up and spend from your balance. Needed to look people up, reveal extras and reveal a candidate's details.\n- `search`: search rotto's candidates and export them. Needed for searches and candidate profiles. A new key leaves it unticked: choose it to search from code. Anything that spends (an export, or a search answer past its free people) needs `lookup` as well.\n- `read`: see your balance and contacts. Needed for the balance, estimates, lookups and contacts.\n\nKeep keys on your server. Never put one in a web page or a mobile app, where anyone can read it. Revoke a key in Settings, Connected apps: it stops working at once. The same key also connects the MCP server.\n\nThe **Test request** button on this page sends real requests from your browser straight to Rotto with the key you type. They spend real credits, exactly as your code would. The key is not saved.\n\n## Pricing\n\nYou pay in credits from your Rotto balance (10 credits = $1), and **only for details that are found**. A miss is free, a detail you already hold is free, and a person repeated in one call is charged once. Every amount the API returns comes in credits (`*_credits`) and in US dollars (`*_usd`). Every account pays the same price for each detail:\n\n| Work email | Personal email | Phone | LinkedIn find | Profile only |\n| --- | --- | --- | --- | --- |\n| 1 credit ($0.10) | 3 credits ($0.30) | 9 credits ($0.90) | 1 credit ($0.10) | 1 credit ($0.10) |\n\nAn email input first finds the LinkedIn profile behind it: that is the LinkedIn find, charged only on a match.\n\n## Profiles\n\nEvery found person comes with their name, headline, current company, location and LinkedIn URL. For more, pass `\"include_profile\": true` on a lookup (or `?include_profile=true` on `GET /lookups/{lookup_id}` and `GET /contacts`), and each found person also carries `profile`: their About, skills, work history (title, company, dates, location, description) and education, with `as_of`, when it was read from LinkedIn. `GET /contacts/{contact_id}` always returns it. The profile is free: it is what the lookup already holds.\n\nTo get the profile with no contact details, send `\"channels\": []`. That costs a profile's price per person found (1 credit ($0.10), the same as the LinkedIn find), for a LinkedIn URL and an email alike, and nothing for a person not found or one you already hold. A stored profile older than 30 days is read from LinkedIn again on that person's next lookup, at no cost to you.\n\nA bigger top-up earns extra credits, by the size of that one top-up:\n\n| One top-up of | Extra credits | That top-up buys |\n| --- | --- | --- |\n| $100 or more | 10% | 1,100 credits |\n| $500 or more | 15% | 5,750 credits |\n| $2,500 or more | 25% | 31,250 credits |\n\nBefore a lookup runs, the most it could cost (every detail found for everyone) is reserved from your balance; the unused part is released as it settles. If your balance cannot cover that, the call is refused with `402 insufficient_balance` and nothing is spent. With auto top-up on, your card tops the balance up first. Top up at [https://rotto.com/candidates/settings#balance](https://rotto.com/candidates/settings#balance).\n\nTwo guards help you control spend: `POST /estimate` prices a lookup without running it, and `max_credits` (or `max_usd`; send both and the lower applies) on any spending call refuses (with `422 over_max_usd`, spending nothing) when the most it could cost is over your limit.\n\n## Waiting for results\n\nMost lookups finish within a minute or two. A spending call waits up to 4 minutes and answers `200` with the results, so **set your HTTP client's timeout to at least 5 minutes**. If it is still running after that, it answers `202` with `status: \"running\"` and a `lookup_id`: poll `GET /lookups/{lookup_id}` every 5 to 10 seconds until `status` is `done`. Polls count toward the 30 calls a minute.\n\nTo never wait (or if your client cannot hold a request open that long), pass `\"wait\": false`: you get the `202` and the `lookup_id` within seconds, and the lookup runs on.\n\nA list can also answer `202` with `status: \"paused\"` when an auto top-up could not run. `paused.message` says why and `paused.resume_url` is where you resume it.\n\n## Searching candidates\n\nDescribe who you want in plain English and Rotto finds them, as the app's search does. Your key needs the `search` permission: a new key leaves it unticked, so tick it when you create the key.\n\n1. **Start a search** with `POST /searches` and a `brief` (\"Senior backend engineers in London who have worked at a fintech\"). You get the first matches and a `search_id`.\n2. **Get more people** with `POST /searches/{search_id}/candidates`: the next `page`, or on a plan any slice of the ranking with `offset` and `limit` (up to 1,000 people deep).\n3. **Refine it** in plain English with `POST /searches/{search_id}/refine` (\"only people in London\"). It keeps its `search_id`.\n4. **Open someone** with `GET /candidates/{candidate_id}` for their full profile, and **reveal their details** with `POST /candidates/{candidate_id}/reveal`, charged as a lookup is: only what is found, never twice.\n5. **Export** the search as a CSV with `POST /searches/{search_id}/export`.\n\n`GET /searches` lists your saved searches and `GET /searches/{search_id}` reopens one, both free. A search started here is in your Rotto app too, and the other way round.\n\nSearching spends no credits. On the Free plan: 5 free searches. 15 people per page. Each extra page or refinement uses a search. A plan searches without a limit and gets 40 people a call for free. An answer of more than 40 people charges the people past the first 100 of a search at the export's price, 1 credit per 10, once a day: the same call again costs nothing more. An export costs the same per person, plus any contact details it finds, and needs a plan: the Free plan cannot export. A search takes up to a minute or two, so keep your HTTP client's timeout at 5 minutes. Search results never include contact details.\n\n## Extras\n\nSome people have more than one email or phone. Every result lists those under `extras`, each with a `key` and its `price_credits` (and `price_usd`). Reveal one with `POST /contacts/{contact_id}/extras`. It is charged once: revealing it again is free.\n\n## Limits\n\n| Limit | Value |\n| --- | --- |\n| Calls per key | 30 a minute, shared with the same key's MCP calls |\n| People looked up per account | 5,000 a day (UTC), across the API and MCP |\n| Inputs per batch call | 50 |\n| Lookups running at once | 2 per account |\n| Request body | 64 KB |\n\nEvery answer carries `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` headers. A `429` carries `Retry-After` in seconds.\n\nLookups that need a fresh search are paced across all accounts. At busy times a large batch takes longer to finish, but nothing fails or is charged for waiting.\n\n## Errors\n\nEvery error is JSON with one shape (the one exception is a `405` for a method an endpoint does not take). `type` is stable: branch on it, not on `message`.\n\n```json\n{\n  \"error\": {\n    \"type\": \"insufficient_balance\",\n    \"message\": \"Your balance does not cover this lookup: it needs 13 credits if every detail is found and you have 5 credits. Top up at https://rotto.com/candidates/settings#balance. Nothing was spent.\",\n    \"request_id\": \"0b6c1f0e-5d7a-4a3b-9f61-2c8e4d1a7b90\",\n    \"required_usd\": 1.3,\n    \"required_credits\": 13,\n    \"available_usd\": 0.5,\n    \"available_credits\": 5,\n    \"load_url\": \"https://rotto.com/candidates/settings#balance\"\n  }\n}\n```\n\n| Status | `type` | When |\n| --- | --- | --- |\n| 400 | `invalid_request` | The body or query is not valid JSON or does not match the schema. `issues` says where. |\n| 400 | `invalid_input` | Nothing to look up, an extra key that is not one of the person's extras, or a search brief Rotto cannot search (`code` says `unsearchable` or `brief_too_vague`). |\n| 401 | `missing_api_key` | No `Authorization: Bearer` header. |\n| 401 | `invalid_api_key` | The key is unknown, revoked, or not an API key. |\n| 402 | `insufficient_balance` | Your balance does not cover the most this could cost. Nothing was spent. `load_url` says where to add money. |\n| 403 | `insufficient_scope` | The key was created without the scope this endpoint needs. |\n| 403 | `account_frozen` | Your account is paused while a payment is reviewed. |\n| 403 | `plan_limit` | Your plan does not include this, or the Free plan's candidate searches are used up. `upgrade_url` says where to choose a plan. |\n| 403 | `forbidden_origin` | A browser on another website sent the request. Call the API from your server. |\n| 404 | `not_found` | No such lookup, contact, search or candidate that your account can open. |\n| 413 | `payload_too_large` | The body is over 64 KB. |\n| 422 | `over_max_usd` | The most this could cost is over your `max_credits` or `max_usd`. Nothing was spent. |\n| 429 | `rate_limited` | Too many calls a minute, people a day, or lookups running at once. See `Retry-After`. |\n| 500 | `server_error` | Something went wrong on our side. Retry with backoff. |\n| 503 | `service_unavailable` | We could not check your key just now. Retry with backoff. |\n| 504 | `search_timeout` | A search took longer than one call can wait. `search_id` names it: get its people with POST /searches/{search_id}/candidates. |\n\n## Retries\n\nRetrying is safe for your balance: a detail you already hold is never charged again and a miss is never charged. Retry `429`, `500` and `503` with exponential backoff, honoring `Retry-After`. To pick up a lookup that answered `202`, poll its `lookup_id` rather than sending it again.\n\n## Versioning\n\nThe version is in the path (`/v1`). We may add fields to responses, so ignore fields you do not know. Anything that would break your code ships as a new version.\n\n## Use with AI tools\n\nPress **Copy for LLM** at the top of this page to copy these docs, every endpoint and the MCP server as one Markdown file, ready to paste into an AI assistant. Tools that read docs themselves can fetch [llms.txt](https://rotto.com/docs/api/llms.txt) for an index or [llms-full.txt](https://rotto.com/docs/api/llms-full.txt) for everything.","contact":{"name":"Rotto","url":"https://rotto.com/contact-lookup"}},"servers":[{"url":"https://rotto.com/api/v1","description":"Production"}],"security":[{"apiKey":[]}],"tags":[{"name":"Lookups","description":"Find people's details. These spend from your balance."},{"name":"Contacts","description":"The people you have looked up, and their extra details."},{"name":"Search","description":"Search Rotto's candidates from a plain-English brief, page through, refine and export. Needs the `search` permission."},{"name":"Candidates","description":"One person from a search: their full profile, and their contact details."},{"name":"Account","description":"Your balance, prices and estimates. Free."},{"name":"MCP server","description":"Use Rotto from Claude, ChatGPT, Cursor, Claude Code, VS Code or any MCP client. The assistant finds people and looks them up for you, with the same plan, balance, prices and contacts as the app and the REST API.\n\n## Server URL\n\n```text\nhttps://rotto.com/mcp\n```\n\nEvery app takes this one URL. Apps that support OAuth sign you in to Rotto the first time they connect, and you choose what they may do. Anything else can send an API key instead.\n\n## Connect your app\n\n### Claude\n\n1. In Claude on the web or the desktop app, open **Customize**, then **Connectors**.\n2. Press **Add custom connector**.\n3. Name it **Rotto** and paste the server URL.\n\n```text\nhttps://rotto.com/mcp\n```\n\n4. Under authentication choose **OAuth**, and leave it to register automatically.\n5. Press **Connect**, sign in to Rotto and press **Allow**.\n\n### ChatGPT\n\n1. In ChatGPT, open **Plugins** and press **Create custom MCP server**.\n2. Name it **Rotto** and paste the server URL.\n\n```text\nhttps://rotto.com/mcp\n```\n\n3. Sign in to Rotto when asked, and press **Allow**.\n\n### Claude Code\n\n1. Run this in your terminal:\n\n```bash\nclaude mcp add --transport http rotto https://rotto.com/mcp\n```\n\n2. Then type **/mcp** in Claude Code, choose **rotto** and sign in to Rotto.\n3. Or use an API key from Settings: set ROTTO_API_KEY to it and add this to your project's **.mcp.json**.\n\n```json\n{\n  \"mcpServers\": {\n    \"rotto\": {\n      \"type\": \"http\",\n      \"url\": \"https://rotto.com/mcp\",\n      \"headers\": {\n        \"Authorization\": \"Bearer ${ROTTO_API_KEY}\"\n      }\n    }\n  }\n}\n```\n\n\n### Cursor\n\n1. [Add to Cursor](https://rotto.com/mcp): the one-click button is on the setup page.\n2. Or add this to **~/.cursor/mcp.json** yourself:\n\n```json\n{\n  \"mcpServers\": {\n    \"rotto\": {\n      \"url\": \"https://rotto.com/mcp\"\n    }\n  }\n}\n```\n\n3. Cursor asks you to sign in to Rotto the first time it connects.\n\n### VS Code\n\n1. [Add to VS Code](https://vscode.dev/redirect/mcp/install?name=rotto&config=%7B%22type%22%3A%22http%22%2C%22url%22%3A%22https%3A%2F%2Frotto.com%2Fmcp%22%7D)\n2. Or add this to **.vscode/mcp.json** in your project:\n\n```json\n{\n  \"servers\": {\n    \"rotto\": {\n      \"type\": \"http\",\n      \"url\": \"https://rotto.com/mcp\"\n    }\n  }\n}\n```\n\n3. Start the server from the file, then sign in to Rotto when VS Code asks.\n\n### Other\n\n1. Give your app the server URL. If it supports OAuth, it asks you to sign in to Rotto the first time it connects.\n\n```text\nhttps://rotto.com/mcp\n```\n\n2. If it does not, create an API key in **Settings** under Connected apps, and send it with every request:\n\n```text\nAuthorization: Bearer rcl_live_YOUR_KEY\n```\n\n\nThen ask it: *Get the work email for linkedin.com/in/jane-doe*\n\n## Tools\n\n| Tool | What it does | Cost | Permission |\n| --- | --- | --- | --- |\n| `lookup_contact` | Look up a contact | Paid | `lookup` |\n| `lookup_contacts` | Look up several contacts | Paid | `lookup` |\n| `reveal_extra` | Reveal an extra detail | Paid | `lookup` |\n| `search_candidates` | Search candidates | Free | `search` |\n| `refine_search` | Refine a search | Free | `search` |\n| `reveal_candidate_contact` | Reveal a candidate's contact details | Paid | `lookup` |\n| `create_shortlist` | Create a shortlist | Free | `search` |\n| `rename_shortlist` | Rename a shortlist | Free | `search` |\n| `delete_shortlist` | Delete a shortlist | Free | `search` |\n| `add_to_shortlist` | Add someone to a shortlist | Free | `search` |\n| `remove_from_shortlist` | Take someone off a shortlist | Free | `search` |\n| `move_candidate` | Move someone to a stage | Free | `search` |\n| `set_candidate_status` | Save or unsave someone | Free | `search` |\n| `save_note` | Write a note on someone | Free | `search` |\n| `delete_note` | Delete your note on someone | Free | `search` |\n| `dismiss_candidate` | Mark someone not a fit | Free | `search` |\n| `export_candidates` | Export candidates | Paid | `search` |\n| `list_searches` | List your searches | Free | `search` |\n| `get_search` | Open a search | Free | `search` |\n| `get_candidate` | Open a candidate's profile | Free | `search` |\n| `list_shortlists` | List your shortlists | Free | `search` |\n| `get_shortlist` | Open a shortlist | Free | `search` |\n| `get_pipeline` | Show your pipeline | Free | `search` |\n| `get_note` | Read your note on someone | Free | `search` |\n| `estimate_cost` | Estimate the cost of a lookup | Free | `read` |\n| `get_balance` | Get the balance | Free | `read` |\n| `get_lookup` | Check a lookup | Free | `read` |\n| `list_contacts` | List contacts | Free | `read` |\n| `get_contact` | Get a contact | Free | `read` |\n\nPaid tools spend from your balance only on the details they find. A miss, or a detail you already hold, is free. An export also costs 1 credit per 10 people in it.\n\n### lookup_contact\n\nFind one person's work email, personal email and phone number from their LinkedIn profile link or their email address, or just who they are (channels []): their LinkedIn, current role and location, and with include_profile their work history, education and About. This spends credits from the user's Rotto balance, but only for details that are found: a work email is 1 credit, a personal email 3 credits and a phone 9 credits, plus a work email's price to find the LinkedIn behind an email when it is found; the profile alone (channels []) is 1 credit per person found. Details the user already holds cost nothing. Call estimate_cost first when unsure, or pass max_credits. Usually answers within a minute; if not, it returns a lookup_id for get_lookup. Talk about cost in credits only, never in dollars: what a credit costs depends on the user's top-up. Each detail has one fixed price, charged only if it is found, so say \"It costs 9 credits, and only if a number is found\", never \"up to\" or \"at most\". In ChatGPT, personal emails can't be returned: OpenAI doesn't let apps share personal email addresses in ChatGPT. There, don't ask for personal_email. Instead say, in these words: \"Rotto can get <their name>'s personal email, but OpenAI doesn't let apps share personal email addresses in ChatGPT. You can get it in Rotto in one click:\" then link https://rotto.com/candidates/lookup?run=1&url= followed by the person's LinkedIn link (they sign in with their Rotto email), and mention the Rotto API at https://rotto.com/docs/api for using it in their own tools.\n\n| Argument | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `input` | string | Yes | A LinkedIn profile link (linkedin.com/in/...) or an email address. |\n| `channels` | array of `work_email`, `personal_email`, `phone` | No | Which details to get. Leave out for all three: work_email, personal_email, phone. Pass an empty list for the profile alone (their LinkedIn, current role and location, no contact details), charged a profile's price per person found. estimate_cost lists each price. |\n| `include_profile` | boolean | No | Also return each found person's LinkedIn profile under `profile`: their About, skills, work history and education, with `as_of`, when it was read. Free; it is what the lookup already holds. Leave out for the short answer. |\n| `max_usd` | number | No | For older integrations: max_credits in US dollars. Use max_credits. With both, the lower limit applies. |\n| `max_credits` | integer | No | Refuse, spending nothing, if this would cost more than this many credits with every detail found (for example 500). |\n\n### lookup_contacts\n\nFind work emails, personal emails and phone numbers for up to 50 people at once, each given as a LinkedIn profile link or an email address, or just who they are (channels []): each person's LinkedIn, current role and location, and with include_profile their work history, education and About. Use it to fill the gaps in a list: send only the rows that need details, with your own id on each, and write the answers back by id. This spends credits from the user's Rotto balance, only for details that are found: a work email is 1 credit, a personal email 3 credits and a phone 9 credits, plus a work email's price per email whose LinkedIn is found; the profile alone (channels []) is 1 credit per person found. Details the user already holds cost nothing, and a repeated person is charged once. Call estimate_cost first, or pass max_credits. If it is still running after four minutes it returns a lookup_id for get_lookup. With auto top-up on, the user's card tops the balance up as the list runs; if a top-up cannot run, the list pauses and the answer says why and where the user can resume it. Talk about cost in credits only, never in dollars: what a credit costs depends on the user's top-up. Each detail has one fixed price, charged only if it is found, so say \"It costs 9 credits, and only if a number is found\", never \"up to\" or \"at most\". In ChatGPT, personal emails can't be returned: OpenAI doesn't let apps share personal email addresses in ChatGPT. There, don't ask for personal_email. Instead say, in these words: \"Rotto can get <their name>'s personal email, but OpenAI doesn't let apps share personal email addresses in ChatGPT. You can get it in Rotto in one click:\" then link https://rotto.com/candidates/lookup?run=1&url= followed by the person's LinkedIn link (they sign in with their Rotto email), and mention the Rotto API at https://rotto.com/docs/api for using it in their own tools.\n\n| Argument | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `inputs` | array of objects | Yes | Up to 50 people. |\n| `inputs[].id` | string | No | Your own key for this row, returned with its result. |\n| `inputs[].input` | string | Yes | A LinkedIn profile link or an email address. |\n| `channels` | array of `work_email`, `personal_email`, `phone` | No | Which details to get. Leave out for all three: work_email, personal_email, phone. Pass an empty list for the profile alone (their LinkedIn, current role and location, no contact details), charged a profile's price per person found. estimate_cost lists each price. |\n| `include_profile` | boolean | No | Also return each found person's LinkedIn profile under `profile`: their About, skills, work history and education, with `as_of`, when it was read. Free; it is what the lookup already holds. Leave out for the short answer. |\n| `max_usd` | number | No | For older integrations: max_credits in US dollars. Use max_credits. With both, the lower limit applies. |\n| `max_credits` | integer | No | Refuse, spending nothing, if this would cost more than this many credits with every detail found (for example 500). |\n\n### reveal_extra\n\nReveal one more of a looked-up person's details, listed under `extras` in a lookup or list_contacts result: another personal email, another work email or a WhatsApp number that is not their phone. Each extra lists its price_credits. This spends credits from the user's Rotto balance, once: revealing it again costs nothing. Pass max_credits to refuse anything pricier.\n\n| Argument | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `contact_id` | string | Yes | The contact_id a lookup or list_contacts returned for the person. |\n| `key` | string | Yes | The extra's key from that result's `extras`, like \"email:1\", \"work_email:1\" or \"whatsapp\". |\n| `max_usd` | number | No | For older integrations: max_credits in US dollars. Use max_credits. With both, the lower limit applies. |\n| `max_credits` | integer | No | Refuse, spending nothing, if this would cost more than this many credits with every detail found (for example 500). |\n\n### search_candidates\n\nSearch Rotto's candidates from a plain-English brief and get a page of matches: each person's name, current title and company, location, candidate_id and Rotto profile link, plus a search_id. Pass that search_id with page to get the next page. No contact details: get_candidate opens one in full, reveal_candidate_contact gets their email, phone or LinkedIn, and export_candidates takes the search_id for a CSV with LinkedIn URLs (and contact details if asked). Searching spends no credits. On the Free plan: 5 free searches. 15 people per page. Each extra page or refinement uses a search. get_balance says how many are left. A plan searches without a limit and pages 40 at a time for free; `limit` returns up to 1,000 people in one call, and in an answer of more than 40, people past the first 100 of a search cost 1 credit per 10 (the same call again that day costs nothing more). A large answer that does not fit says the next_offset to pass for the rest. Takes up to a minute or two.\n\n| Argument | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `brief` | string | No | Who to find, in plain English, as you would type it into Rotto: the role, seniority, location, skills, companies or industries (for example \"Senior backend engineers in New York who have worked at a fintech\"). A pasted job description works too. Leave it out to get another page of a search you already ran (search_id and page). |\n| `search_id` | string | No | A search_id this tool returned earlier, to get another page of that search. Use it with page; leave out brief. |\n| `page` | integer | No | Which page to return, from 1. A new search returns page 1; pass search_id and page 2 for the next one. |\n| `limit` | integer | No | Paid plans: how many people to return, up to 1,000 (default 40, free). Above 40, people past the first 100 of a search cost 1 credit per 10, like an export. The Free plan always returns 15 a page and ignores this. |\n| `offset` | integer | No | Paid plans: where to start in the search's ranking, from 0, with search_id. A large answer that did not fit says the next_offset to pass. Use either offset or page, not both. |\n| `broaden` | boolean | No | With search_id: page on through the broadened list a refine_search with broaden made. Keep it the same on every page. |\n| `hide_viewed` | boolean | No | With search_id: leave out people you have opened, in any search, this one included, as a refine_search with hide_viewed did. Keep it the same on every page. |\n\n### refine_search\n\nChange one of your searches in plain English (\"only people in London\", \"must have startup experience\") and get its new first page, as Rotto's refine box does: the change is added to the search, which keeps its search_id. Spends no credits. On the Free plan a refined search is a new run: 5 free searches. 15 people per page. Each extra page or refinement uses a search. Retrying the same refinement is free. A plan may pass limit, as with search_candidates (people past the first 100 cost 1 credit per 10). Page on with search_candidates and the same search_id (with the same broaden and hide_viewed). Takes up to a minute or two.\n\n| Argument | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `search_id` | string | Yes | The search to change: a search_id from search_candidates or list_searches. |\n| `instruction` | string | Yes | What to change, in plain English, as you would type it into Rotto's refine box (for example \"only people in London\", \"must have worked at a startup\", \"drop the Python requirement\"). It is added to the search, not a new search. |\n| `broaden` | boolean | No | Show more people by loosening the nice-to-haves (location stays), like Rotto's \"see more\". Default false. |\n| `hide_viewed` | boolean | No | Leave out people you have already opened, in any search, this one included. Default false. |\n| `limit` | integer | No | Paid plans: how many people to return, up to 1,000 (default 40), priced as search_candidates prices it. The Free plan always returns 15 and ignores this. |\n\n### list_searches\n\nYour saved Rotto searches, as Rotto's Recents lists them: pinned first, then the most recently worked in, each with its search_id, name, brief and how many people matched. Free, and runs no search. Use a search_id with search_candidates for its people, refine_search to change it, get_search to read it, or export_candidates for a CSV.\n\n| Argument | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `before` | string | No | For older searches: the next_before value the last answer gave. Leave out for the most recent. |\n\n### get_search\n\nOne saved search, as Rotto reopens it: its brief, summary, how many people matched, and its first page of people as stored when it last ran. Free, and never runs the search. Use search_candidates with the search_id for more people or a fresh run, refine_search to change it, export_candidates for a CSV.\n\n| Argument | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `search_id` | string | Yes | A search_id from search_candidates or list_searches. |\n\n### get_candidate\n\nOne person from search_candidates, in full: their work history, education, skills and LinkedIn About, `as_of` (when Rotto got this profile, so an older one may have changed since), which contact details Rotto holds for them (and which you already own, so are free to read again), and with search_id and include_match_reasons, which parts of that search's brief they meet. Free. No contact details: reveal_candidate_contact gets those, charged only when found. On the Free plan only people your own searches showed you can be opened.\n\n| Argument | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `candidate_id` | string | Yes | A candidate_id from search_candidates. |\n| `search_id` | string | No | The search they came from, to say why they match it (with include_match_reasons). |\n| `include_bio` | boolean | No | Include their LinkedIn About. Default true. |\n| `include_match_reasons` | boolean | No | Say which parts of the search's brief they meet, as the Rotto card does. Needs search_id. Default false. |\n\n### reveal_candidate_contact\n\nGet a search result's work email, personal email, phone number or LinkedIn link, as the Rotto card does: details Rotto holds are revealed now, and ones it does not are looked up (it waits up to four minutes, then answers running; call again later). Charged in credits per detail found, never for a miss, and never twice for the same detail, here or in the app. Pass max_credits to refuse anything dearer. get_candidate says which details Rotto holds and which you already own. On the Free plan only people your own searches showed you can be revealed.\n\n| Argument | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `candidate_id` | string | Yes | A candidate_id from search_candidates. |\n| `channels` | array of `work_email`, `personal_email`, `phone`, `linkedin` | No | Which details to get. Leave out for work_email, personal_email and phone. A work email is 1 credit, a personal email 3, a phone 9; LinkedIn is free. Charged only when found, and never twice. |\n| `all_details` | boolean | No | Reveal every detail Rotto holds in each channel (another email, a WhatsApp number), each at its price. Default: the first of each. |\n| `max_credits` | integer | No | Refuse, spending nothing, if this would cost more than this many credits with every detail found (for example 500). |\n\n### list_shortlists\n\nYour shortlists (the lists in Rotto's sidebar and pipeline), each with its list_id, name and how many people are on it. Free. Paid plans only.\n\nNo arguments.\n\n### create_shortlist\n\nMake a new shortlist, optionally with a first person on it. It appears in Rotto's sidebar and pipeline. Free. Paid plans only.\n\n| Argument | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `name` | string | Yes | The shortlist's name, up to 60 characters. |\n| `candidate_id` | string | No | Someone to put on it straight away. |\n| `search_id` | string | No | The search that person came from, as Rotto records it. Optional. |\n\n### get_shortlist\n\nOne shortlist: its name and the candidate_id of everyone on it, newest first, with their pipeline stage. Free. get_pipeline shows the same people with their names and roles; get_candidate opens one. Paid plans only.\n\n| Argument | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `list_id` | string | Yes | A list_id from list_shortlists or create_shortlist. |\n\n### rename_shortlist\n\nRename one of your shortlists. Free. Paid plans only.\n\n| Argument | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `list_id` | string | Yes | A list_id from list_shortlists or create_shortlist. |\n| `name` | string | Yes | The shortlist's name, up to 60 characters. |\n\n### delete_shortlist\n\nDelete one of your shortlists and take everyone off it, in Rotto too. The people themselves, their notes and statuses stay. Cannot be undone. Paid plans only.\n\n| Argument | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `list_id` | string | Yes | A list_id from list_shortlists or create_shortlist. |\n\n### add_to_shortlist\n\nPut a candidate on one of your shortlists, keeping any other shortlists they are on. Free. Paid plans only.\n\n| Argument | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `list_id` | string | Yes | A list_id from list_shortlists or create_shortlist. |\n| `candidate_id` | string | Yes | A candidate_id from search_candidates, get_shortlist or get_pipeline. |\n| `search_id` | string | No | The search they came from, as Rotto records a save. Optional. |\n\n### remove_from_shortlist\n\nTake a candidate off one of your shortlists (their notes and status stay, and so do their other shortlists). Paid plans only.\n\n| Argument | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `list_id` | string | Yes | A list_id from list_shortlists or create_shortlist. |\n| `candidate_id` | string | Yes | A candidate_id from search_candidates, get_shortlist or get_pipeline. |\n| `search_id` | string | No | The search they came from, as Rotto records a save. Optional. |\n\n### get_pipeline\n\nYour Rotto pipeline: everyone you have saved, with their name, title, stage and the search they came from, as the app's board shows them. Narrow it to one shortlist, one search or one stage. Free. Paid plans only.\n\n| Argument | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `list_id` | string | No | Only the people on this shortlist (with its own stages, when it has custom columns). |\n| `search_id` | string | No | Only the people saved from this search. |\n| `stage` | string | No | Only the people in this stage, by key: shortlisted, contacted, replied, scheduled_call, screened, submitted, stage_1, stage_2, offer, hired, rejected, stay_in_touch, backburner, archived (or a shortlist's own column key). |\n\n### move_candidate\n\nMove a saved candidate to another pipeline stage (Contacted, Replied, Offer, Hired and so on), as dragging their card in Rotto does. They must be in your pipeline already: set_candidate_status or add_to_shortlist puts them there. Free. Paid plans only.\n\n| Argument | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `candidate_id` | string | Yes | A candidate_id from search_candidates, get_pipeline or get_shortlist. |\n| `stage` | string | Yes | The stage to move them to, by key: shortlisted, contacted, replied, scheduled_call, screened, submitted, stage_1, stage_2, offer, hired, rejected, stay_in_touch, backburner, archived. On a shortlist with custom columns, its own column key. |\n| `search_id` | string | No | The search they were saved from, as Rotto keeps one status per search. Leave out for their status outside any search. |\n| `list_id` | string | No | The shortlist whose board they are moved on (needed for its custom columns). |\n\n### set_candidate_status\n\nPut a candidate in your pipeline (shortlisted), mark them contacted, or take them off the board (none), as the save and contacted buttons on a Rotto card do. Kept per search when search_id is given. Free. Paid plans only.\n\n| Argument | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `candidate_id` | string | Yes | A candidate_id from search_candidates, get_pipeline or get_shortlist. |\n| `status` | `shortlisted`, `contacted`, `none` | Yes | shortlisted puts them in your pipeline, contacted marks them contacted, none takes them off the board (a note stays). |\n| `search_id` | string | No | The search they were saved from, as Rotto keeps one status per search. Leave out for their status outside any search. |\n\n### get_note\n\nYour private note on a candidate, as written on their Rotto card. Free. Paid plans only.\n\n| Argument | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `candidate_id` | string | Yes | A candidate_id from search_candidates, get_pipeline or get_shortlist. |\n\n### save_note\n\nWrite your private note on a candidate (one per person, so it replaces any note already there; get_note reads it first). It shows on their Rotto card. Free. Paid plans only.\n\n| Argument | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `candidate_id` | string | Yes | A candidate_id from search_candidates, get_pipeline or get_shortlist. |\n| `text` | string | Yes | The note, up to 2,000 characters. It replaces any note you have on them. |\n\n### delete_note\n\nDelete your private note on a candidate. Cannot be undone. Paid plans only.\n\n| Argument | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `candidate_id` | string | Yes | A candidate_id from search_candidates, get_pipeline or get_shortlist. |\n\n### dismiss_candidate\n\nMark a candidate not a fit for one search, as dismissing their card in Rotto does, so the app hides them in that search and its exports; dismissed false brings them back. Free. Paid plans only.\n\n| Argument | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `candidate_id` | string | Yes | A candidate_id from search_candidates, get_pipeline or get_shortlist. |\n| `search_id` | string | Yes | The search they are not a fit for (dismissing is per search, as in the app). |\n| `dismissed` | boolean | No | false brings them back. Default true. |\n\n### export_candidates\n\nExport people from one of the user's searches (search_candidates' search_id) as a CSV: its top N matches or chosen candidate_ids, with their name, title, company, location, LinkedIn URL and Rotto profile. Exporting needs a Rotto plan: on the Free plan it is refused with the plans link. This spends credits from the user's Rotto balance: 1 credit per 10 people exported (9 people is 1 credit, 11 is 2), plus, only if work_email, personal_email or phone are among the columns, each contact detail found at its price (estimate_cost lists them). Pass estimate: true first to see the cost without spending, or max_credits to refuse anything pricier. Free columns answer the CSV at once (inline and as a download link for a browser signed in to Rotto); contact columns start a run whose progress get_lookup reports by the returned lookup_id, and the same link downloads the CSV once it finishes. Talk about cost in credits only.\n\n| Argument | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `search_id` | string | Yes | The search_id search_candidates returned, or the id of a search in the Rotto app (yours only). |\n| `top` | integer | No | Export the search's top N matches in ranked order, up to 1,000. Give this or candidate_ids. |\n| `candidate_ids` | array of strings | No | Or export just these people from the search's results, by the candidate_id search_candidates returned. |\n| `columns` | array of `first_name`, `last_name`, `title`, `company`, `location`, `linkedin_url`, `headline`, `years_experience`, `rotto_profile`, `work_email`, `personal_email`, `phone` | No | The CSV's columns. Leave out for every free one: first_name, last_name, title, company, location, linkedin_url, headline, years_experience, rotto_profile. work_email, personal_email and phone are contact details, each charged at its price when found. |\n| `estimate` | boolean | No | Say what this export would cost and whether the balance covers it, spending nothing. Use it before a large export. |\n| `max_credits` | integer | No | Refuse, spending nothing, if this would cost more than this many credits with every detail found (for example 500). |\n\n### estimate_cost\n\nFree. What a lookup_contact or lookup_contacts call with these inputs and channels costs in credits if every detail is found, each detail's price (and the profile-only price, for channels []), the user's available balance, and whether it fits. A detail that isn't found costs nothing. For one person and one detail, that is simply the detail's price, charged only if found.\n\n| Argument | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `inputs` | array of objects | Yes | Up to 50 people. |\n| `inputs[].id` | string | No | Your own key for this row, returned with its result. |\n| `inputs[].input` | string | Yes | A LinkedIn profile link or an email address. |\n| `channels` | array of `work_email`, `personal_email`, `phone` | No | Which details to get. Leave out for all three: work_email, personal_email, phone. Pass an empty list for the profile alone (their LinkedIn, current role and location, no contact details), charged a profile's price per person found. estimate_cost lists each price. |\n\n### get_balance\n\nFree. The user's Rotto balance in credits: what they can spend now, what each detail costs (one price list for everyone), the extra credits a bigger top-up earns, auto top-up, and a link to top up. Also their plan (Free, Starter, Professional or Business), the credits it adds each month, and on Free how many of the free candidate searches are left.\n\nNo arguments.\n\n### get_lookup\n\nFree. The current state of one of the user's lookups by its lookup_id: whether it is still running, and each person with the details found so far. Pass include_profile for each found person's work history, education and About.\n\n| Argument | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `lookup_id` | string | Yes | The lookup_id a lookup tool returned. |\n| `include_profile` | boolean | No | Also return each found person's LinkedIn profile under `profile`: their About, skills, work history and education, with `as_of`, when it was read. Free; it is what the lookup already holds. Leave out for the short answer. |\n\n### list_contacts\n\nFree. The people the user has already looked up on Rotto, newest first, with the emails and phone numbers they already hold. Re-reading these never costs anything. Pass include_profile for each person's work history, education and About.\n\n| Argument | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `query` | string | No | Words to match in a name, headline, company or location. |\n| `limit` | integer | No | How many to return, newest first (default 20, at most 100). |\n| `include_profile` | boolean | No | Also return each found person's LinkedIn profile under `profile`: their About, skills, work history and education, with `as_of`, when it was read. Free; it is what the lookup already holds. Leave out for the short answer. |\n\n### get_contact\n\nFree. One person the user has already looked up, by contact_id: who they are, the emails and phone numbers the user holds, their extras, and their LinkedIn profile (About, skills, work history, education). Re-reading never costs anything.\n\n| Argument | Type | Required | What it is |\n| --- | --- | --- | --- |\n| `contact_id` | string | Yes | The contact_id a lookup or list_contacts returned for the person. |\n\n## MCP authentication\n\n- **OAuth**: the app opens Rotto, you sign in and press Allow. Access lasts until you revoke it.\n- **API key**: the same keys the REST API uses, sent as `Authorization: Bearer rcl_live_YOUR_KEY`.\n\nEither way, a connection only does what you allowed:\n\n- `lookup`: look people up and spend from your balance. On the MCP server it also allows searching, as it always has.\n- `search`: search rotto's candidates and export them, and work with shortlists, the pipeline and notes.\n- `read`: see your balance and contacts.\n\nRevoke any app or key in [Settings](https://rotto.com/contact-lookup/settings), under Connected apps. It stops at once.\n\n## MCP pricing and limits\n\nThe MCP server and the REST API are one product with one balance: the same prices (see **Pricing** above) and the same limits (see **Limits** above). A key's calls a minute and an account's people a day are shared between them, not counted twice."}],"x-tagGroups":[{"name":"REST API","tags":["Lookups","Contacts","Search","Candidates","Account"]},{"name":"MCP","tags":["MCP server"]}],"paths":{"/contacts/lookup":{"post":{"operationId":"lookupContact","summary":"Look up one person","description":"Find one person's work email, personal email and phone number from their LinkedIn profile link or their email address. This spends credits from your balance (10 credits = $1), but only for details that are found. The price is the same for every account: a work email is 1 credit, a personal email 3 credits and a phone 9 credits. An email input also pays a work email's price to find the LinkedIn profile behind it, only when one is found; the profile alone (channels []) is 1 credit per person found. Details you already hold cost nothing. Pass `channels: []` for the profile alone (their LinkedIn, current role and location, no contact details), and `include_profile: true` to get each found person's work history, education and About under `profile`. Pass `max_credits` (or `max_usd`) to refuse anything pricier, or call POST /estimate first. Usually answers within a minute. If it is still running after 4 minutes (or you pass `wait: false`) it answers 202 with a `lookup_id` to poll.","tags":["Lookups"],"x-scope":"lookup","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"input":{"type":"string","minLength":3,"maxLength":500,"description":"A LinkedIn profile link (linkedin.com/in/...) or an email address."},"channels":{"description":"Which details to get. Leave out for all three: work_email, personal_email, phone. Pass an empty list for the profile alone (their LinkedIn, current role and location, no contact details), charged a profile's price per person found. POST /estimate lists each price.","maxItems":3,"type":"array","items":{"type":"string","enum":["work_email","personal_email","phone"]}},"include_profile":{"description":"Also return each found person's LinkedIn profile under `profile`: their About, skills, work history and education, with `as_of`, when it was read. Free. Leave out for the short answer.","type":"boolean"},"max_usd":{"description":"For older integrations: max_credits in US dollars. Use max_credits. With both, the lower limit applies.","type":"number","minimum":0,"maximum":100000},"max_credits":{"description":"Refuse, spending nothing, if this would cost more than this many credits with every detail found (for example 500).","type":"integer","minimum":0,"maximum":1000000},"wait":{"description":"Wait up to 4 minutes for the lookup to finish (the default). Pass false to get a 202 with a lookup_id at once and poll GET /lookups/{lookup_id}.","type":"boolean"}},"required":["input"],"additionalProperties":false},"example":{"input":"https://www.linkedin.com/in/ada-lovelace","channels":["work_email","phone"],"include_profile":true,"max_credits":20}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["done","failed","running","paused"],"description":"done or failed: settled. running: still going (poll GET /lookups/{lookup_id}). paused: waiting on you."},"lookup_id":{"type":"string","description":"Poll it with GET /lookups/{lookup_id} while status is running."},"rotto_url":{"type":"string","description":"This lookup in the Rotto app, where every person's details can be revealed and copied."},"spent_usd":{"type":"number","description":"What this lookup has spent so far. Only found details are charged."},"spent_credits":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"What this lookup has spent so far. In credits (10 = $1)."},"balance_usd":{"anyOf":[{"type":"number","description":"What you can spend now, after this lookup."},{"type":"null"}]},"balance_credits":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"What you can spend now, after this lookup. In credits (10 = $1)."},{"type":"null"}]},"found":{"type":"boolean"},"person":{"anyOf":[{"type":"object","properties":{"name":{"type":"string"},"headline":{"type":["string","null"]},"company":{"type":["string","null"]},"location":{"type":["string","null"]},"linkedin_url":{"type":["string","null"]},"photo_url":{"description":"Their photo, where we hold one.","type":["string","null"]}},"required":["name","headline","company","location","linkedin_url","photo_url"],"additionalProperties":false,"description":"Who the person is."},{"type":"null"}]},"values":{"type":"object","properties":{"work_email":{"type":"string"},"personal_email":{"type":"string"},"phone":{"type":"string"}},"additionalProperties":false,"description":"Only the details your account holds: paid for now or before. A detail that was not found is absent."},"channels":{"type":"object","properties":{"work_email":{"type":"string","enum":["revealed","not_found","pending","not_requested"]},"personal_email":{"type":"string","enum":["revealed","not_found","pending","not_requested"]},"phone":{"type":"string","enum":["revealed","not_found","pending","not_requested"]}},"additionalProperties":false,"description":"Where each detail stands: revealed (yours, in `values`), not_found (free), pending, or not_requested."},"contact_id":{"type":"string"},"extras":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string","description":"Pass this to the reveal extra endpoint, for example \"email:1\" or \"whatsapp\"."},"label":{"type":"string"},"price_usd":{"type":"number","description":"What revealing it costs."},"price_credits":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"What revealing it costs. In credits (10 = $1)."},"revealed":{"type":"boolean"},"value":{"description":"Present once you have revealed it.","type":"string"}},"required":["key","label","price_usd","price_credits","revealed"],"additionalProperties":false,"description":"A further detail we hold for this person, bought one at a time."}},"reason":{"type":"string"},"profile":{"description":"With `include_profile`: their profile, or null when nobody was found.","anyOf":[{"type":"object","properties":{"about":{"description":"Their LinkedIn About section.","type":["string","null"]},"skills":{"type":"array","items":{"type":"string"}},"experience":{"type":"array","items":{"type":"object","properties":{"title":{"type":["string","null"]},"company":{"type":["string","null"]},"start":{"description":"When it started, as LinkedIn shows it (\"Aug 2020\", \"2020\").","type":["string","null"]},"end":{"description":"When it ended; null while current, as LinkedIn shows it (\"Aug 2020\", \"2020\").","type":["string","null"]},"current":{"type":"boolean"},"location":{"type":["string","null"]},"description":{"type":["string","null"]}},"required":["title","company","start","end","current","location","description"],"additionalProperties":false},"description":"Their work history, newest first as LinkedIn lists it."},"education":{"type":"array","items":{"type":"object","properties":{"school":{"type":["string","null"]},"degree":{"type":["string","null"]},"field":{"type":["string","null"]},"start":{"description":"When it started, as LinkedIn shows it (\"Aug 2020\", \"2020\").","type":["string","null"]},"end":{"description":"When it ended, as LinkedIn shows it (\"Aug 2020\", \"2020\").","type":["string","null"]}},"required":["school","degree","field","start","end"],"additionalProperties":false}},"as_of":{"description":"When this profile was read from LinkedIn (ISO 8601). A copy older than 30 days is read again on the next lookup.","type":["string","null"]}},"required":["about","skills","experience","education","as_of"],"additionalProperties":false,"description":"The person's LinkedIn profile. Present only when you ask for it (`include_profile`), and always on GET /contacts/{contact_id}."},{"type":"null"}]}},"required":["status","lookup_id","rotto_url","spent_usd","spent_credits","balance_usd","balance_credits","found","person","values","channels","extras"],"additionalProperties":false},"example":{"status":"done","lookup_id":"9b2e4d6f-1a3c-4e5b-8d7f-0c2a4e6b8d1f","rotto_url":"https://rotto.com/contact-lookup/app?job=9b2e4d6f-1a3c-4e5b-8d7f-0c2a4e6b8d1f","spent_usd":1,"spent_credits":10,"balance_usd":19,"balance_credits":190,"found":true,"person":{"name":"Ada Lovelace","headline":"Head of Engineering at Analytical Engines","company":"Analytical Engines","location":"London, United Kingdom","linkedin_url":"https://www.linkedin.com/in/ada-lovelace","photo_url":"https://ndlmmsqcjdzyjsfwbrgb.supabase.co/storage/v1/object/public/profile-photos/ada-lovelace_profile_photo.jpg"},"values":{"work_email":"ada@analyticalengines.com","phone":"+44 20 7946 0958"},"channels":{"work_email":"revealed","personal_email":"not_requested","phone":"revealed"},"contact_id":"3f1c2b7e-8d4a-4c1e-9b2f-6a5d4c3b2a10","extras":[{"key":"email:1","label":"Personal email 2","price_usd":0.3,"price_credits":3,"revealed":false}],"profile":{"about":"Mathematician. Wrote the first program for a machine that did not exist yet.","skills":["Mathematics","Analytical engines","Translation"],"experience":[{"title":"Head of Engineering","company":"Analytical Engines","start":"Jan 2024","end":null,"current":true,"location":"London, United Kingdom","description":"Runs the engine programme."},{"title":"Mathematician","company":"Independent","start":"1833","end":"1852","current":false,"location":null,"description":null}],"education":[{"school":"Home tutoring","degree":null,"field":"Mathematics","start":null,"end":null}],"as_of":"2026-10-20T09:00:00.000Z"}}}}},"202":{"description":"Still running (or paused). Poll GET /lookups/{lookup_id}.","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["done","failed","running","paused"],"description":"done or failed: settled. running: still going (poll GET /lookups/{lookup_id}). paused: waiting on you."},"lookup_id":{"type":"string","description":"Poll it with GET /lookups/{lookup_id} while status is running."},"rotto_url":{"type":"string","description":"This lookup in the Rotto app, where every person's details can be revealed and copied."},"spent_usd":{"type":"number","description":"What this lookup has spent so far. Only found details are charged."},"spent_credits":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"What this lookup has spent so far. In credits (10 = $1)."},"balance_usd":{"anyOf":[{"type":"number","description":"What you can spend now, after this lookup."},{"type":"null"}]},"balance_credits":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"What you can spend now, after this lookup. In credits (10 = $1)."},{"type":"null"}]},"found":{"type":"boolean"},"person":{"anyOf":[{"type":"object","properties":{"name":{"type":"string"},"headline":{"type":["string","null"]},"company":{"type":["string","null"]},"location":{"type":["string","null"]},"linkedin_url":{"type":["string","null"]},"photo_url":{"description":"Their photo, where we hold one.","type":["string","null"]}},"required":["name","headline","company","location","linkedin_url","photo_url"],"additionalProperties":false,"description":"Who the person is."},{"type":"null"}]},"values":{"type":"object","properties":{"work_email":{"type":"string"},"personal_email":{"type":"string"},"phone":{"type":"string"}},"additionalProperties":false,"description":"Only the details your account holds: paid for now or before. A detail that was not found is absent."},"channels":{"type":"object","properties":{"work_email":{"type":"string","enum":["revealed","not_found","pending","not_requested"]},"personal_email":{"type":"string","enum":["revealed","not_found","pending","not_requested"]},"phone":{"type":"string","enum":["revealed","not_found","pending","not_requested"]}},"additionalProperties":false,"description":"Where each detail stands: revealed (yours, in `values`), not_found (free), pending, or not_requested."},"contact_id":{"type":"string"},"extras":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string","description":"Pass this to the reveal extra endpoint, for example \"email:1\" or \"whatsapp\"."},"label":{"type":"string"},"price_usd":{"type":"number","description":"What revealing it costs."},"price_credits":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"What revealing it costs. In credits (10 = $1)."},"revealed":{"type":"boolean"},"value":{"description":"Present once you have revealed it.","type":"string"}},"required":["key","label","price_usd","price_credits","revealed"],"additionalProperties":false,"description":"A further detail we hold for this person, bought one at a time."}},"reason":{"type":"string"},"profile":{"description":"With `include_profile`: their profile, or null when nobody was found.","anyOf":[{"type":"object","properties":{"about":{"description":"Their LinkedIn About section.","type":["string","null"]},"skills":{"type":"array","items":{"type":"string"}},"experience":{"type":"array","items":{"type":"object","properties":{"title":{"type":["string","null"]},"company":{"type":["string","null"]},"start":{"description":"When it started, as LinkedIn shows it (\"Aug 2020\", \"2020\").","type":["string","null"]},"end":{"description":"When it ended; null while current, as LinkedIn shows it (\"Aug 2020\", \"2020\").","type":["string","null"]},"current":{"type":"boolean"},"location":{"type":["string","null"]},"description":{"type":["string","null"]}},"required":["title","company","start","end","current","location","description"],"additionalProperties":false},"description":"Their work history, newest first as LinkedIn lists it."},"education":{"type":"array","items":{"type":"object","properties":{"school":{"type":["string","null"]},"degree":{"type":["string","null"]},"field":{"type":["string","null"]},"start":{"description":"When it started, as LinkedIn shows it (\"Aug 2020\", \"2020\").","type":["string","null"]},"end":{"description":"When it ended, as LinkedIn shows it (\"Aug 2020\", \"2020\").","type":["string","null"]}},"required":["school","degree","field","start","end"],"additionalProperties":false}},"as_of":{"description":"When this profile was read from LinkedIn (ISO 8601). A copy older than 30 days is read again on the next lookup.","type":["string","null"]}},"required":["about","skills","experience","education","as_of"],"additionalProperties":false,"description":"The person's LinkedIn profile. Present only when you ask for it (`include_profile`), and always on GET /contacts/{contact_id}."},{"type":"null"}]}},"required":["status","lookup_id","rotto_url","spent_usd","spent_credits","balance_usd","balance_credits","found","person","values","channels","extras"],"additionalProperties":false}}}},"400":{"description":"`invalid_request`, `invalid_input`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`missing_api_key`, `invalid_api_key`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"`insufficient_balance`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`account_frozen`, `insufficient_scope`, `forbidden_origin`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"`payload_too_large`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"`over_max_usd`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"`server_error`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"`service_unavailable`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/contacts/lookup-batch":{"post":{"operationId":"lookupContacts","summary":"Look up up to 50 people","description":"Find details for up to 50 people at once, each a LinkedIn profile link or an email address with an optional `id` of yours (a row number, say). Send only the rows that need details and write the answers back by id. Same prices and rules as looking up one person: The price is the same for every account: a work email is 1 credit, a personal email 3 credits and a phone 9 credits. An email input also pays a work email's price to find the LinkedIn profile behind it, only when one is found; the profile alone (channels []) is 1 credit per person found. A repeated person is looked up and charged once. Pass `channels: []` for the profile alone (their LinkedIn, current role and location, no contact details), and `include_profile: true` to get each found person's work history, education and About under `profile`. It runs as one list in your Rotto workspace. With auto top-up on, your card tops the balance up as the list runs; if a top-up cannot run, the list pauses and the answer says why (`paused`) and where you resume it.","tags":["Lookups"],"x-scope":"lookup","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"inputs":{"minItems":1,"maxItems":50,"type":"array","items":{"type":"object","properties":{"id":{"description":"Your own key for this row, returned with its result.","type":"string","maxLength":100},"input":{"type":"string","minLength":3,"maxLength":500,"description":"A LinkedIn profile link or an email address."}},"required":["input"]},"description":"Up to 50 people."},"channels":{"description":"Which details to get. Leave out for all three: work_email, personal_email, phone. Pass an empty list for the profile alone (their LinkedIn, current role and location, no contact details), charged a profile's price per person found. POST /estimate lists each price.","maxItems":3,"type":"array","items":{"type":"string","enum":["work_email","personal_email","phone"]}},"include_profile":{"description":"Also return each found person's LinkedIn profile under `profile`: their About, skills, work history and education, with `as_of`, when it was read. Free. Leave out for the short answer.","type":"boolean"},"max_usd":{"description":"For older integrations: max_credits in US dollars. Use max_credits. With both, the lower limit applies.","type":"number","minimum":0,"maximum":100000},"max_credits":{"description":"Refuse, spending nothing, if this would cost more than this many credits with every detail found (for example 500).","type":"integer","minimum":0,"maximum":1000000},"wait":{"description":"Wait up to 4 minutes for the lookup to finish (the default). Pass false to get a 202 with a lookup_id at once and poll GET /lookups/{lookup_id}.","type":"boolean"}},"required":["inputs"],"additionalProperties":false},"example":{"inputs":[{"id":"row-1","input":"https://www.linkedin.com/in/ada-lovelace"},{"id":"row-2","input":"charles@analyticalengines.com"}],"channels":["work_email"],"max_credits":10}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["done","failed","running","paused"],"description":"done or failed: settled. running: still going (poll GET /lookups/{lookup_id}). paused: waiting on you."},"lookup_id":{"type":"string","description":"Poll it with GET /lookups/{lookup_id} while status is running."},"rotto_url":{"type":"string","description":"This lookup in the Rotto app, where every person's details can be revealed and copied."},"spent_usd":{"type":"number","description":"What this lookup has spent so far. Only found details are charged."},"spent_credits":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"What this lookup has spent so far. In credits (10 = $1)."},"balance_usd":{"anyOf":[{"type":"number","description":"What you can spend now, after this lookup."},{"type":"null"}]},"balance_credits":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"What you can spend now, after this lookup. In credits (10 = $1)."},{"type":"null"}]},"paused":{"type":"object","properties":{"reason":{"type":"string","enum":["card_declined","auth_required","cap_reached","frozen","no_card"]},"message":{"type":"string"},"resume_url":{"type":"string","description":"Where you resume the list in the app (a card or a limit needs you)."}},"required":["reason","message","resume_url"],"additionalProperties":false,"description":"Present when a list paused because an auto top-up could not run."},"results":{"type":"array","items":{"type":"object","properties":{"id":{"description":"Your own id for this row, echoed back.","type":"string"},"input":{"type":"string","description":"The input as you sent it."},"status":{"type":"string","enum":["found","not_found","running","failed","invalid_input"]},"reason":{"description":"Why nobody was found, or why the input was not read.","type":"string"},"lookup_id":{"type":"string"},"person":{"anyOf":[{"type":"object","properties":{"name":{"type":"string"},"headline":{"type":["string","null"]},"company":{"type":["string","null"]},"location":{"type":["string","null"]},"linkedin_url":{"type":["string","null"]},"photo_url":{"description":"Their photo, where we hold one.","type":["string","null"]}},"required":["name","headline","company","location","linkedin_url","photo_url"],"additionalProperties":false,"description":"Who the person is."},{"type":"null"}]},"values":{"type":"object","properties":{"work_email":{"type":"string"},"personal_email":{"type":"string"},"phone":{"type":"string"}},"additionalProperties":false,"description":"Only the details your account holds: paid for now or before. A detail that was not found is absent."},"channels":{"type":"object","properties":{"work_email":{"type":"string","enum":["revealed","not_found","pending","not_requested"]},"personal_email":{"type":"string","enum":["revealed","not_found","pending","not_requested"]},"phone":{"type":"string","enum":["revealed","not_found","pending","not_requested"]}},"additionalProperties":false,"description":"Where each detail stands: revealed (yours, in `values`), not_found (free), pending, or not_requested."},"contact_id":{"description":"The person's id, for the reveal extra endpoint. Absent when nobody was found.","type":"string"},"extras":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string","description":"Pass this to the reveal extra endpoint, for example \"email:1\" or \"whatsapp\"."},"label":{"type":"string"},"price_usd":{"type":"number","description":"What revealing it costs."},"price_credits":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"What revealing it costs. In credits (10 = $1)."},"revealed":{"type":"boolean"},"value":{"description":"Present once you have revealed it.","type":"string"}},"required":["key","label","price_usd","price_credits","revealed"],"additionalProperties":false,"description":"A further detail we hold for this person, bought one at a time."}},"profile":{"description":"With `include_profile`: their profile, or null when nobody was found.","anyOf":[{"type":"object","properties":{"about":{"description":"Their LinkedIn About section.","type":["string","null"]},"skills":{"type":"array","items":{"type":"string"}},"experience":{"type":"array","items":{"type":"object","properties":{"title":{"type":["string","null"]},"company":{"type":["string","null"]},"start":{"description":"When it started, as LinkedIn shows it (\"Aug 2020\", \"2020\").","type":["string","null"]},"end":{"description":"When it ended; null while current, as LinkedIn shows it (\"Aug 2020\", \"2020\").","type":["string","null"]},"current":{"type":"boolean"},"location":{"type":["string","null"]},"description":{"type":["string","null"]}},"required":["title","company","start","end","current","location","description"],"additionalProperties":false},"description":"Their work history, newest first as LinkedIn lists it."},"education":{"type":"array","items":{"type":"object","properties":{"school":{"type":["string","null"]},"degree":{"type":["string","null"]},"field":{"type":["string","null"]},"start":{"description":"When it started, as LinkedIn shows it (\"Aug 2020\", \"2020\").","type":["string","null"]},"end":{"description":"When it ended, as LinkedIn shows it (\"Aug 2020\", \"2020\").","type":["string","null"]}},"required":["school","degree","field","start","end"],"additionalProperties":false}},"as_of":{"description":"When this profile was read from LinkedIn (ISO 8601). A copy older than 30 days is read again on the next lookup.","type":["string","null"]}},"required":["about","skills","experience","education","as_of"],"additionalProperties":false,"description":"The person's LinkedIn profile. Present only when you ask for it (`include_profile`), and always on GET /contacts/{contact_id}."},{"type":"null"}]}},"required":["input","status","person","values","channels"],"additionalProperties":false},"description":"One per input, in your order, keyed by your ids."}},"required":["status","lookup_id","rotto_url","spent_usd","spent_credits","balance_usd","balance_credits","results"],"additionalProperties":false},"example":{"status":"done","lookup_id":"9b2e4d6f-1a3c-4e5b-8d7f-0c2a4e6b8d1f","rotto_url":"https://rotto.com/contact-lookup/app?job=9b2e4d6f-1a3c-4e5b-8d7f-0c2a4e6b8d1f","spent_usd":0.1,"spent_credits":1,"balance_usd":19.9,"balance_credits":199,"results":[{"id":"row-1","input":"https://www.linkedin.com/in/ada-lovelace","status":"found","lookup_id":"9b2e4d6f-1a3c-4e5b-8d7f-0c2a4e6b8d1f","person":{"name":"Ada Lovelace","headline":"Head of Engineering at Analytical Engines","company":"Analytical Engines","location":"London, United Kingdom","linkedin_url":"https://www.linkedin.com/in/ada-lovelace","photo_url":"https://ndlmmsqcjdzyjsfwbrgb.supabase.co/storage/v1/object/public/profile-photos/ada-lovelace_profile_photo.jpg"},"values":{"work_email":"ada@analyticalengines.com"},"channels":{"work_email":"revealed"},"contact_id":"3f1c2b7e-8d4a-4c1e-9b2f-6a5d4c3b2a10","extras":[]},{"id":"row-2","input":"charles@analyticalengines.com","status":"not_found","reason":"No LinkedIn profile was found for this email.","lookup_id":"9b2e4d6f-1a3c-4e5b-8d7f-0c2a4e6b8d1f","person":null,"values":{},"channels":{},"extras":[]}]}}}},"202":{"description":"Still running (or paused). Poll GET /lookups/{lookup_id}.","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["done","failed","running","paused"],"description":"done or failed: settled. running: still going (poll GET /lookups/{lookup_id}). paused: waiting on you."},"lookup_id":{"type":"string","description":"Poll it with GET /lookups/{lookup_id} while status is running."},"rotto_url":{"type":"string","description":"This lookup in the Rotto app, where every person's details can be revealed and copied."},"spent_usd":{"type":"number","description":"What this lookup has spent so far. Only found details are charged."},"spent_credits":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"What this lookup has spent so far. In credits (10 = $1)."},"balance_usd":{"anyOf":[{"type":"number","description":"What you can spend now, after this lookup."},{"type":"null"}]},"balance_credits":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"What you can spend now, after this lookup. In credits (10 = $1)."},{"type":"null"}]},"paused":{"type":"object","properties":{"reason":{"type":"string","enum":["card_declined","auth_required","cap_reached","frozen","no_card"]},"message":{"type":"string"},"resume_url":{"type":"string","description":"Where you resume the list in the app (a card or a limit needs you)."}},"required":["reason","message","resume_url"],"additionalProperties":false,"description":"Present when a list paused because an auto top-up could not run."},"results":{"type":"array","items":{"type":"object","properties":{"id":{"description":"Your own id for this row, echoed back.","type":"string"},"input":{"type":"string","description":"The input as you sent it."},"status":{"type":"string","enum":["found","not_found","running","failed","invalid_input"]},"reason":{"description":"Why nobody was found, or why the input was not read.","type":"string"},"lookup_id":{"type":"string"},"person":{"anyOf":[{"type":"object","properties":{"name":{"type":"string"},"headline":{"type":["string","null"]},"company":{"type":["string","null"]},"location":{"type":["string","null"]},"linkedin_url":{"type":["string","null"]},"photo_url":{"description":"Their photo, where we hold one.","type":["string","null"]}},"required":["name","headline","company","location","linkedin_url","photo_url"],"additionalProperties":false,"description":"Who the person is."},{"type":"null"}]},"values":{"type":"object","properties":{"work_email":{"type":"string"},"personal_email":{"type":"string"},"phone":{"type":"string"}},"additionalProperties":false,"description":"Only the details your account holds: paid for now or before. A detail that was not found is absent."},"channels":{"type":"object","properties":{"work_email":{"type":"string","enum":["revealed","not_found","pending","not_requested"]},"personal_email":{"type":"string","enum":["revealed","not_found","pending","not_requested"]},"phone":{"type":"string","enum":["revealed","not_found","pending","not_requested"]}},"additionalProperties":false,"description":"Where each detail stands: revealed (yours, in `values`), not_found (free), pending, or not_requested."},"contact_id":{"description":"The person's id, for the reveal extra endpoint. Absent when nobody was found.","type":"string"},"extras":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string","description":"Pass this to the reveal extra endpoint, for example \"email:1\" or \"whatsapp\"."},"label":{"type":"string"},"price_usd":{"type":"number","description":"What revealing it costs."},"price_credits":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"What revealing it costs. In credits (10 = $1)."},"revealed":{"type":"boolean"},"value":{"description":"Present once you have revealed it.","type":"string"}},"required":["key","label","price_usd","price_credits","revealed"],"additionalProperties":false,"description":"A further detail we hold for this person, bought one at a time."}},"profile":{"description":"With `include_profile`: their profile, or null when nobody was found.","anyOf":[{"type":"object","properties":{"about":{"description":"Their LinkedIn About section.","type":["string","null"]},"skills":{"type":"array","items":{"type":"string"}},"experience":{"type":"array","items":{"type":"object","properties":{"title":{"type":["string","null"]},"company":{"type":["string","null"]},"start":{"description":"When it started, as LinkedIn shows it (\"Aug 2020\", \"2020\").","type":["string","null"]},"end":{"description":"When it ended; null while current, as LinkedIn shows it (\"Aug 2020\", \"2020\").","type":["string","null"]},"current":{"type":"boolean"},"location":{"type":["string","null"]},"description":{"type":["string","null"]}},"required":["title","company","start","end","current","location","description"],"additionalProperties":false},"description":"Their work history, newest first as LinkedIn lists it."},"education":{"type":"array","items":{"type":"object","properties":{"school":{"type":["string","null"]},"degree":{"type":["string","null"]},"field":{"type":["string","null"]},"start":{"description":"When it started, as LinkedIn shows it (\"Aug 2020\", \"2020\").","type":["string","null"]},"end":{"description":"When it ended, as LinkedIn shows it (\"Aug 2020\", \"2020\").","type":["string","null"]}},"required":["school","degree","field","start","end"],"additionalProperties":false}},"as_of":{"description":"When this profile was read from LinkedIn (ISO 8601). A copy older than 30 days is read again on the next lookup.","type":["string","null"]}},"required":["about","skills","experience","education","as_of"],"additionalProperties":false,"description":"The person's LinkedIn profile. Present only when you ask for it (`include_profile`), and always on GET /contacts/{contact_id}."},{"type":"null"}]}},"required":["input","status","person","values","channels"],"additionalProperties":false},"description":"One per input, in your order, keyed by your ids."}},"required":["status","lookup_id","rotto_url","spent_usd","spent_credits","balance_usd","balance_credits","results"],"additionalProperties":false}}}},"400":{"description":"`invalid_request`, `invalid_input`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`missing_api_key`, `invalid_api_key`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"`insufficient_balance`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`account_frozen`, `insufficient_scope`, `forbidden_origin`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"`payload_too_large`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"`over_max_usd`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"`server_error`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"`service_unavailable`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/lookups/{lookup_id}":{"get":{"operationId":"getLookup","summary":"Check a lookup","description":"Free. Where one of your lookups stands, by the `lookup_id` a lookup returned (or any lookup you made in the app), with each person and the details found so far. Poll it every few seconds while `status` is `running`. Add `?include_profile=true` for each found person's profile.","tags":["Lookups"],"x-scope":"read","parameters":[{"name":"lookup_id","in":"path","required":true,"description":"The lookup_id a lookup returned.","schema":{"type":"string","format":"uuid"}},{"name":"include_profile","in":"query","required":false,"description":"`true` also returns each person's LinkedIn profile (About, skills, work history, education) under `profile`. Free.","schema":{"type":"string","enum":["0","1","true","false"]}}],"responses":{"200":{"description":"OK.","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["done","failed","running","paused"],"description":"done or failed: settled. running: still going (poll GET /lookups/{lookup_id}). paused: waiting on you."},"lookup_id":{"type":"string","description":"Poll it with GET /lookups/{lookup_id} while status is running."},"rotto_url":{"type":"string","description":"This lookup in the Rotto app, where every person's details can be revealed and copied."},"spent_usd":{"type":"number","description":"What this lookup has spent so far. Only found details are charged."},"spent_credits":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"What this lookup has spent so far. In credits (10 = $1)."},"paused":{"type":"object","properties":{"reason":{"type":"string","enum":["card_declined","auth_required","cap_reached","frozen","no_card"]},"message":{"type":"string"},"resume_url":{"type":"string","description":"Where you resume the list in the app (a card or a limit needs you)."}},"required":["reason","message","resume_url"],"additionalProperties":false,"description":"Present when a list paused because an auto top-up could not run."},"results":{"type":"array","items":{"type":"object","properties":{"id":{"description":"Your own id for this row, echoed back.","type":"string"},"input":{"type":"string","description":"The input as you sent it."},"status":{"type":"string","enum":["found","not_found","running","failed","invalid_input"]},"reason":{"description":"Why nobody was found, or why the input was not read.","type":"string"},"lookup_id":{"type":"string"},"person":{"anyOf":[{"type":"object","properties":{"name":{"type":"string"},"headline":{"type":["string","null"]},"company":{"type":["string","null"]},"location":{"type":["string","null"]},"linkedin_url":{"type":["string","null"]},"photo_url":{"description":"Their photo, where we hold one.","type":["string","null"]}},"required":["name","headline","company","location","linkedin_url","photo_url"],"additionalProperties":false,"description":"Who the person is."},{"type":"null"}]},"values":{"type":"object","properties":{"work_email":{"type":"string"},"personal_email":{"type":"string"},"phone":{"type":"string"}},"additionalProperties":false,"description":"Only the details your account holds: paid for now or before. A detail that was not found is absent."},"channels":{"type":"object","properties":{"work_email":{"type":"string","enum":["revealed","not_found","pending","not_requested"]},"personal_email":{"type":"string","enum":["revealed","not_found","pending","not_requested"]},"phone":{"type":"string","enum":["revealed","not_found","pending","not_requested"]}},"additionalProperties":false,"description":"Where each detail stands: revealed (yours, in `values`), not_found (free), pending, or not_requested."},"contact_id":{"description":"The person's id, for the reveal extra endpoint. Absent when nobody was found.","type":"string"},"extras":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string","description":"Pass this to the reveal extra endpoint, for example \"email:1\" or \"whatsapp\"."},"label":{"type":"string"},"price_usd":{"type":"number","description":"What revealing it costs."},"price_credits":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"What revealing it costs. In credits (10 = $1)."},"revealed":{"type":"boolean"},"value":{"description":"Present once you have revealed it.","type":"string"}},"required":["key","label","price_usd","price_credits","revealed"],"additionalProperties":false,"description":"A further detail we hold for this person, bought one at a time."}},"profile":{"description":"With `include_profile`: their profile, or null when nobody was found.","anyOf":[{"type":"object","properties":{"about":{"description":"Their LinkedIn About section.","type":["string","null"]},"skills":{"type":"array","items":{"type":"string"}},"experience":{"type":"array","items":{"type":"object","properties":{"title":{"type":["string","null"]},"company":{"type":["string","null"]},"start":{"description":"When it started, as LinkedIn shows it (\"Aug 2020\", \"2020\").","type":["string","null"]},"end":{"description":"When it ended; null while current, as LinkedIn shows it (\"Aug 2020\", \"2020\").","type":["string","null"]},"current":{"type":"boolean"},"location":{"type":["string","null"]},"description":{"type":["string","null"]}},"required":["title","company","start","end","current","location","description"],"additionalProperties":false},"description":"Their work history, newest first as LinkedIn lists it."},"education":{"type":"array","items":{"type":"object","properties":{"school":{"type":["string","null"]},"degree":{"type":["string","null"]},"field":{"type":["string","null"]},"start":{"description":"When it started, as LinkedIn shows it (\"Aug 2020\", \"2020\").","type":["string","null"]},"end":{"description":"When it ended, as LinkedIn shows it (\"Aug 2020\", \"2020\").","type":["string","null"]}},"required":["school","degree","field","start","end"],"additionalProperties":false}},"as_of":{"description":"When this profile was read from LinkedIn (ISO 8601). A copy older than 30 days is read again on the next lookup.","type":["string","null"]}},"required":["about","skills","experience","education","as_of"],"additionalProperties":false,"description":"The person's LinkedIn profile. Present only when you ask for it (`include_profile`), and always on GET /contacts/{contact_id}."},{"type":"null"}]}},"required":["input","status","person","values","channels"],"additionalProperties":false}}},"required":["status","lookup_id","rotto_url","spent_usd","spent_credits","results"],"additionalProperties":false},"example":{"status":"running","lookup_id":"9b2e4d6f-1a3c-4e5b-8d7f-0c2a4e6b8d1f","rotto_url":"https://rotto.com/contact-lookup/app?job=9b2e4d6f-1a3c-4e5b-8d7f-0c2a4e6b8d1f","spent_usd":0.1,"spent_credits":1,"results":[{"input":"https://www.linkedin.com/in/ada-lovelace","status":"found","lookup_id":"9b2e4d6f-1a3c-4e5b-8d7f-0c2a4e6b8d1f","person":{"name":"Ada Lovelace","headline":"Head of Engineering at Analytical Engines","company":"Analytical Engines","location":"London, United Kingdom","linkedin_url":"https://www.linkedin.com/in/ada-lovelace","photo_url":"https://ndlmmsqcjdzyjsfwbrgb.supabase.co/storage/v1/object/public/profile-photos/ada-lovelace_profile_photo.jpg"},"values":{"work_email":"ada@analyticalengines.com"},"channels":{"work_email":"revealed","phone":"pending"},"contact_id":"3f1c2b7e-8d4a-4c1e-9b2f-6a5d4c3b2a10","extras":[]}]}}}},"400":{"description":"`invalid_request`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`missing_api_key`, `invalid_api_key`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `forbidden_origin`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"`server_error`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"`service_unavailable`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/contacts":{"get":{"operationId":"listContacts","summary":"List your contacts","description":"Free. The people you have already looked up, newest first, optionally searched, with the details you hold for each. Re-reading them never costs anything. Add `?include_profile=true` for each person's profile.","tags":["Contacts"],"x-scope":"read","parameters":[{"name":"query","in":"query","required":false,"description":"Words to match in a name, headline, company or location.","schema":{"type":"string","maxLength":200}},{"name":"limit","in":"query","required":false,"description":"How many to return, newest first (default 20, at most 100).","schema":{"type":"integer","minimum":1,"maximum":100}},{"name":"include_profile","in":"query","required":false,"description":"`true` also returns each person's LinkedIn profile (About, skills, work history, education) under `profile`. Free.","schema":{"type":"string","enum":["0","1","true","false"]}}],"responses":{"200":{"description":"OK.","content":{"application/json":{"schema":{"type":"object","properties":{"total":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"How many contacts match, of which `contacts` is the newest page."},"contacts":{"type":"array","items":{"type":"object","properties":{"person":{"anyOf":[{"type":"object","properties":{"name":{"type":"string"},"headline":{"type":["string","null"]},"company":{"type":["string","null"]},"location":{"type":["string","null"]},"linkedin_url":{"type":["string","null"]},"photo_url":{"description":"Their photo, where we hold one.","type":["string","null"]}},"required":["name","headline","company","location","linkedin_url","photo_url"],"additionalProperties":false,"description":"Who the person is."},{"type":"null"}]},"values":{"type":"object","properties":{"work_email":{"type":"string"},"personal_email":{"type":"string"},"phone":{"type":"string"}},"additionalProperties":false,"description":"Only the details your account holds: paid for now or before. A detail that was not found is absent."},"channels":{"type":"object","properties":{"work_email":{"type":"string","enum":["revealed","not_found","pending","not_requested"]},"personal_email":{"type":"string","enum":["revealed","not_found","pending","not_requested"]},"phone":{"type":"string","enum":["revealed","not_found","pending","not_requested"]}},"additionalProperties":false,"description":"Where each detail stands: revealed (yours, in `values`), not_found (free), pending, or not_requested."},"contact_id":{"type":"string"},"extras":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string","description":"Pass this to the reveal extra endpoint, for example \"email:1\" or \"whatsapp\"."},"label":{"type":"string"},"price_usd":{"type":"number","description":"What revealing it costs."},"price_credits":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"What revealing it costs. In credits (10 = $1)."},"revealed":{"type":"boolean"},"value":{"description":"Present once you have revealed it.","type":"string"}},"required":["key","label","price_usd","price_credits","revealed"],"additionalProperties":false,"description":"A further detail we hold for this person, bought one at a time."}},"looked_up_at":{"type":"string","description":"When you last looked them up or revealed one of their details (ISO 8601)."},"profile":{"description":"With `include_profile`: their profile, or null when none is stored.","anyOf":[{"type":"object","properties":{"about":{"description":"Their LinkedIn About section.","type":["string","null"]},"skills":{"type":"array","items":{"type":"string"}},"experience":{"type":"array","items":{"type":"object","properties":{"title":{"type":["string","null"]},"company":{"type":["string","null"]},"start":{"description":"When it started, as LinkedIn shows it (\"Aug 2020\", \"2020\").","type":["string","null"]},"end":{"description":"When it ended; null while current, as LinkedIn shows it (\"Aug 2020\", \"2020\").","type":["string","null"]},"current":{"type":"boolean"},"location":{"type":["string","null"]},"description":{"type":["string","null"]}},"required":["title","company","start","end","current","location","description"],"additionalProperties":false},"description":"Their work history, newest first as LinkedIn lists it."},"education":{"type":"array","items":{"type":"object","properties":{"school":{"type":["string","null"]},"degree":{"type":["string","null"]},"field":{"type":["string","null"]},"start":{"description":"When it started, as LinkedIn shows it (\"Aug 2020\", \"2020\").","type":["string","null"]},"end":{"description":"When it ended, as LinkedIn shows it (\"Aug 2020\", \"2020\").","type":["string","null"]}},"required":["school","degree","field","start","end"],"additionalProperties":false}},"as_of":{"description":"When this profile was read from LinkedIn (ISO 8601). A copy older than 30 days is read again on the next lookup.","type":["string","null"]}},"required":["about","skills","experience","education","as_of"],"additionalProperties":false,"description":"The person's LinkedIn profile. Present only when you ask for it (`include_profile`), and always on GET /contacts/{contact_id}."},{"type":"null"}]}},"required":["person","values","channels","extras","looked_up_at"],"additionalProperties":false}}},"required":["total","contacts"],"additionalProperties":false},"example":{"total":1,"contacts":[{"person":{"name":"Ada Lovelace","headline":"Head of Engineering at Analytical Engines","company":"Analytical Engines","location":"London, United Kingdom","linkedin_url":"https://www.linkedin.com/in/ada-lovelace","photo_url":"https://ndlmmsqcjdzyjsfwbrgb.supabase.co/storage/v1/object/public/profile-photos/ada-lovelace_profile_photo.jpg"},"values":{"work_email":"ada@analyticalengines.com","personal_email":"ada.lovelace@gmail.com","phone":"+44 20 7946 0958"},"channels":{"work_email":"revealed","personal_email":"revealed","phone":"revealed"},"contact_id":"3f1c2b7e-8d4a-4c1e-9b2f-6a5d4c3b2a10","extras":[{"key":"email:1","label":"Personal email 2","price_usd":0.3,"price_credits":3,"revealed":false}],"looked_up_at":"2026-10-08T14:03:11.000Z"}]}}}},"400":{"description":"`invalid_request`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`missing_api_key`, `invalid_api_key`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `forbidden_origin`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"`server_error`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"`service_unavailable`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/contacts/{contact_id}":{"get":{"operationId":"getContact","summary":"Get one contact and their profile","description":"Free. One person you have already looked up, by the `contact_id` a lookup or the contacts list returned: who they are, the details you hold, their extras, and their LinkedIn profile (About, skills, work history, education). Re-reading never costs anything. The profile is what the lookup stored; a copy older than 30 days is read again on the person's next lookup.","tags":["Contacts"],"x-scope":"read","parameters":[{"name":"contact_id","in":"path","required":true,"description":"The contact_id a lookup or the contacts list returned.","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK.","content":{"application/json":{"schema":{"type":"object","properties":{"person":{"anyOf":[{"type":"object","properties":{"name":{"type":"string"},"headline":{"type":["string","null"]},"company":{"type":["string","null"]},"location":{"type":["string","null"]},"linkedin_url":{"type":["string","null"]},"photo_url":{"description":"Their photo, where we hold one.","type":["string","null"]}},"required":["name","headline","company","location","linkedin_url","photo_url"],"additionalProperties":false,"description":"Who the person is."},{"type":"null"}]},"values":{"type":"object","properties":{"work_email":{"type":"string"},"personal_email":{"type":"string"},"phone":{"type":"string"}},"additionalProperties":false,"description":"Only the details your account holds: paid for now or before. A detail that was not found is absent."},"channels":{"type":"object","properties":{"work_email":{"type":"string","enum":["revealed","not_found","pending","not_requested"]},"personal_email":{"type":"string","enum":["revealed","not_found","pending","not_requested"]},"phone":{"type":"string","enum":["revealed","not_found","pending","not_requested"]}},"additionalProperties":false,"description":"Where each detail stands: revealed (yours, in `values`), not_found (free), pending, or not_requested."},"contact_id":{"type":"string"},"extras":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string","description":"Pass this to the reveal extra endpoint, for example \"email:1\" or \"whatsapp\"."},"label":{"type":"string"},"price_usd":{"type":"number","description":"What revealing it costs."},"price_credits":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"What revealing it costs. In credits (10 = $1)."},"revealed":{"type":"boolean"},"value":{"description":"Present once you have revealed it.","type":"string"}},"required":["key","label","price_usd","price_credits","revealed"],"additionalProperties":false,"description":"A further detail we hold for this person, bought one at a time."}},"looked_up_at":{"type":"string","description":"When you last looked them up or revealed one of their details (ISO 8601)."},"profile":{"anyOf":[{"type":"object","properties":{"about":{"description":"Their LinkedIn About section.","type":["string","null"]},"skills":{"type":"array","items":{"type":"string"}},"experience":{"type":"array","items":{"type":"object","properties":{"title":{"type":["string","null"]},"company":{"type":["string","null"]},"start":{"description":"When it started, as LinkedIn shows it (\"Aug 2020\", \"2020\").","type":["string","null"]},"end":{"description":"When it ended; null while current, as LinkedIn shows it (\"Aug 2020\", \"2020\").","type":["string","null"]},"current":{"type":"boolean"},"location":{"type":["string","null"]},"description":{"type":["string","null"]}},"required":["title","company","start","end","current","location","description"],"additionalProperties":false},"description":"Their work history, newest first as LinkedIn lists it."},"education":{"type":"array","items":{"type":"object","properties":{"school":{"type":["string","null"]},"degree":{"type":["string","null"]},"field":{"type":["string","null"]},"start":{"description":"When it started, as LinkedIn shows it (\"Aug 2020\", \"2020\").","type":["string","null"]},"end":{"description":"When it ended, as LinkedIn shows it (\"Aug 2020\", \"2020\").","type":["string","null"]}},"required":["school","degree","field","start","end"],"additionalProperties":false}},"as_of":{"description":"When this profile was read from LinkedIn (ISO 8601). A copy older than 30 days is read again on the next lookup.","type":["string","null"]}},"required":["about","skills","experience","education","as_of"],"additionalProperties":false,"description":"The person's LinkedIn profile. Present only when you ask for it (`include_profile`), and always on GET /contacts/{contact_id}."},{"type":"null"}],"description":"Their profile. Null only when nothing is stored for them any more."},"rotto_url":{"type":"string","description":"Your contacts in the Rotto app."}},"required":["person","values","channels","extras","looked_up_at","profile","rotto_url"],"additionalProperties":false},"example":{"person":{"name":"Ada Lovelace","headline":"Head of Engineering at Analytical Engines","company":"Analytical Engines","location":"London, United Kingdom","linkedin_url":"https://www.linkedin.com/in/ada-lovelace","photo_url":"https://ndlmmsqcjdzyjsfwbrgb.supabase.co/storage/v1/object/public/profile-photos/ada-lovelace_profile_photo.jpg"},"values":{"work_email":"ada@analyticalengines.com","personal_email":"ada.lovelace@gmail.com","phone":"+44 20 7946 0958"},"channels":{"work_email":"revealed","personal_email":"revealed","phone":"revealed"},"contact_id":"3f1c2b7e-8d4a-4c1e-9b2f-6a5d4c3b2a10","extras":[{"key":"email:1","label":"Personal email 2","price_usd":0.3,"price_credits":3,"revealed":false}],"looked_up_at":"2026-10-08T14:03:11.000Z","profile":{"about":"Mathematician. Wrote the first program for a machine that did not exist yet.","skills":["Mathematics","Analytical engines","Translation"],"experience":[{"title":"Head of Engineering","company":"Analytical Engines","start":"Jan 2024","end":null,"current":true,"location":"London, United Kingdom","description":"Runs the engine programme."},{"title":"Mathematician","company":"Independent","start":"1833","end":"1852","current":false,"location":null,"description":null}],"education":[{"school":"Home tutoring","degree":null,"field":"Mathematics","start":null,"end":null}],"as_of":"2026-10-20T09:00:00.000Z"},"rotto_url":"https://rotto.com/contact-lookup/app?view=contacts"}}}},"400":{"description":"`invalid_request`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`missing_api_key`, `invalid_api_key`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `forbidden_origin`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"`server_error`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"`service_unavailable`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/contacts/{contact_id}/extras":{"post":{"operationId":"revealExtra","summary":"Reveal an extra detail","description":"Reveal one more of a person's details, listed under `extras` in a lookup or a contact: another personal email, another work email, or a WhatsApp number that is not their phone. Each extra lists its `price_credits` (and `price_usd`). This spends credits from your balance (10 credits = $1) once: revealing it again costs nothing.","tags":["Contacts"],"x-scope":"lookup","parameters":[{"name":"contact_id","in":"path","required":true,"description":"The contact_id a lookup or the contacts list returned.","schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"key":{"type":"string","maxLength":40,"description":"The extra's key from that result's `extras`, like \"email:1\", \"work_email:1\" or \"whatsapp\"."},"max_usd":{"description":"For older integrations: max_credits in US dollars. Use max_credits. With both, the lower limit applies.","type":"number","minimum":0,"maximum":100000},"max_credits":{"description":"Refuse, spending nothing, if this would cost more than this many credits with every detail found (for example 500).","type":"integer","minimum":0,"maximum":1000000}},"required":["key"],"additionalProperties":false},"example":{"key":"email:1","max_credits":10}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"key":{"type":"string"},"label":{"type":"string"},"value":{"type":"string"},"cost_usd":{"type":"number","description":"What this call spent: 0 when you already held it."},"cost_credits":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"What this call spent: 0 when you already held it. In credits (10 = $1)."},"balance_usd":{"anyOf":[{"type":"number","description":"What you can spend now."},{"type":"null"}]},"balance_credits":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"What you can spend now. In credits (10 = $1)."},{"type":"null"}]}},"required":["key","label","value","cost_usd","cost_credits","balance_usd","balance_credits"],"additionalProperties":false},"example":{"key":"email:1","label":"Personal email 2","value":"ada@lovelace.org","cost_usd":0.3,"cost_credits":3,"balance_usd":19.7,"balance_credits":197}}}},"400":{"description":"`invalid_request`, `invalid_input`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`missing_api_key`, `invalid_api_key`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"`insufficient_balance`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`account_frozen`, `insufficient_scope`, `forbidden_origin`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"`payload_too_large`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"`over_max_usd`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"`server_error`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"`service_unavailable`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/searches":{"post":{"operationId":"searchCandidates","summary":"Start a search","description":"Search Rotto's candidates from a plain-English brief and get the first matches: each person's name, current title and company, location and candidate_id, plus a search_id for the next page, a refinement or an export. No contact details: reveal them with POST /candidates/{candidate_id}/reveal. Searching spends no credits. On the Free plan: 5 free searches. 15 people per page. Each extra page or refinement uses a search. A plan searches without a limit and gets 40 people a call for free; `limit` asks for up to 1,000, and in an answer of more than 40, people past the first 100 of a search cost 1 credit per 10, as an export does (the same call again that day costs nothing more), and need the `lookup` permission as well as `search`. Takes up to a minute or two. Needs the `search` permission.","tags":["Search"],"x-scope":"search","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"brief":{"type":"string","minLength":3,"maxLength":15000,"description":"Who to find, in plain English, as you would type it into Rotto: the role, seniority, location, skills, companies or industries (for example \"Senior backend engineers in New York who have worked at a fintech\"). A pasted job description works too."},"limit":{"description":"Paid plans: how many people to return, up to 1,000 (default 40). People past the first 100 of a search cost 1 credit per 10. The Free plan always returns 15 and ignores this.","type":"integer","minimum":1,"maximum":1000}},"required":["brief"],"additionalProperties":false},"example":{"brief":"Senior backend engineers in London who have worked at a fintech"}}}},"responses":{"200":{"description":"OK.","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","const":"done"},"search_id":{"type":"string","description":"The search, for its next page, a refinement or an export."},"rotto_url":{"type":"string","description":"This search in the Rotto app."},"summary":{"description":"What Rotto understood the brief to ask for.","type":["string","null"]},"page":{"description":"Which page this is, on the Free plan and on a plan that asked for a page.","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"offset":{"description":"Where this answer starts in the search's ranking, from 0, on a plan.","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"limit":{"description":"How many people this answer was asked for, on a plan.","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"returned":{"description":"How many people this answer carries, on a plan.","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"candidates":{"type":"array","items":{"type":"object","properties":{"candidate_id":{"type":"string","description":"Their id, for GET /candidates/{candidate_id} and the reveal endpoint."},"name":{"type":"string"},"title":{"description":"Their current job title.","type":["string","null"]},"company":{"description":"Their current company.","type":["string","null"]},"location":{"type":["string","null"]},"rotto_url":{"description":"Their profile in the Rotto app. Left out of an answer of more than 100 people: it is https://rotto.com/candidates/{candidate_id}.","type":"string"}},"required":["candidate_id","name","title","company","location"],"additionalProperties":false,"description":"One match. No contact details: reveal them with POST /candidates/{candidate_id}/reveal."}},"total_matches":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}],"description":"How many people match in all. Null when it is still being counted, or past the first page."},"more_available":{"type":"boolean"},"next_offset":{"description":"On a plan: the offset to ask for next, or null at the end.","anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"spent_usd":{"type":"number","description":"What this answer cost: people past the first 100 of a search, at the export's price."},"spent_credits":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"What this answer cost. In credits (10 = $1)."},"plan":{"description":"Present on the Free plan.","type":"string","const":"Free"},"free_searches":{"type":"object","properties":{"kind":{"type":"string","const":"free"},"limit":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"used":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"remaining":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["kind","limit","used","remaining"],"additionalProperties":false,"description":"On the Free plan: your candidate searches, used and left."},"upgrade_url":{"description":"On the Free plan: where to choose a plan.","type":"string"}},"required":["status","search_id","rotto_url","summary","candidates","total_matches","more_available"],"additionalProperties":false},"example":{"status":"done","search_id":"5d2c8e1a-7b3f-4c6d-9e0a-1f2b3c4d5e6f","rotto_url":"https://rotto.com/candidates?s=5d2c8e1a-7b3f-4c6d-9e0a-1f2b3c4d5e6f","summary":"Senior backend engineers in London with fintech experience","offset":0,"limit":40,"returned":1,"candidates":[{"candidate_id":"c4a1e2b3-6d5f-4a7b-8c9d-0e1f2a3b4c5d","name":"Ada Lovelace","title":"Senior Backend Engineer","company":"Analytical Engines","location":"London, United Kingdom","rotto_url":"https://rotto.com/candidates/c4a1e2b3-6d5f-4a7b-8c9d-0e1f2a3b4c5d"}],"total_matches":120,"more_available":true,"next_offset":1}}}},"400":{"description":"`invalid_request`, `invalid_input`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`missing_api_key`, `invalid_api_key`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"`insufficient_balance`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`plan_limit`, `insufficient_scope`, `forbidden_origin`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"`payload_too_large`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"`server_error`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"`service_unavailable`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"504":{"description":"`search_timeout`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"get":{"operationId":"listSearches","summary":"List your searches","description":"Free. Your saved searches, as Rotto's Recents lists them: pinned first, then the most recently worked in, each with its search_id, name, brief and how many people matched. Older ones come a page at a time with `before`. Runs no search.","tags":["Search"],"x-scope":"search","parameters":[{"name":"before","in":"query","required":false,"description":"For older searches: the next_before value the last answer gave. Leave out for the most recent.","schema":{"type":"string","maxLength":64}}],"responses":{"200":{"description":"OK.","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","const":"done"},"searches":{"type":"array","items":{"type":"object","properties":{"search_id":{"type":"string"},"name":{"type":"string","description":"Its name, as Rotto's Recents shows it."},"brief":{"description":"The brief it was started from.","type":["string","null"]},"summary":{"type":["string","null"]},"result_count":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}],"description":"How many people matched when it last ran."},"pinned":{"type":"boolean"},"last_activity_at":{"type":"string","description":"When it was last worked in (ISO 8601)."},"rotto_url":{"type":"string"}},"required":["search_id","name","brief","summary","result_count","pinned","last_activity_at","rotto_url"],"additionalProperties":false},"description":"Pinned first, then the most recently worked in."},"more_available":{"type":"boolean"},"next_before":{"description":"Pass it as `before` for older searches. Null at the end.","type":["string","null"]}},"required":["status","searches","more_available","next_before"],"additionalProperties":false},"example":{"status":"done","searches":[{"search_id":"5d2c8e1a-7b3f-4c6d-9e0a-1f2b3c4d5e6f","name":"Senior backend engineers in London with fintech experience","brief":"Senior backend engineers in London who have worked at a fintech","summary":"Senior backend engineers in London with fintech experience","result_count":120,"pinned":false,"last_activity_at":"2026-11-16T10:12:00.000Z","rotto_url":"https://rotto.com/candidates?s=5d2c8e1a-7b3f-4c6d-9e0a-1f2b3c4d5e6f"}],"more_available":false,"next_before":null}}}},"400":{"description":"`invalid_request`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`missing_api_key`, `invalid_api_key`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`plan_limit`, `insufficient_scope`, `forbidden_origin`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"`server_error`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"`service_unavailable`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/searches/{search_id}/candidates":{"post":{"operationId":"getSearchCandidates","summary":"Get more people from a search","description":"The next page of a search you started, or any slice of its ranking on a plan (`offset` and `limit`), or the first page of a saved search whose people are not stored. A POST because it can spend: on the Free plan each page is one of your searches, and on a plan people past the first 100 of a search are charged as an export is. Pass the same `broaden` and `hide_viewed` on every page.","tags":["Search"],"x-scope":"search","parameters":[{"name":"search_id","in":"path","required":true,"description":"A search_id that starting a search or the searches list returned.","schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"page":{"description":"Which page to return, from 1. Use page or offset, not both.","type":"integer","minimum":1,"maximum":100},"offset":{"description":"Paid plans: where to start in the search's ranking, from 0. An answer that did not fit says the next_offset to pass. Use page or offset, not both.","type":"integer","minimum":0,"maximum":999},"limit":{"description":"Paid plans: how many people to return, up to 1,000 (default 40). People past the first 100 of a search cost 1 credit per 10. The Free plan always returns 15 and ignores this.","type":"integer","minimum":1,"maximum":1000},"broaden":{"description":"Loosen the nice-to-haves to show more people (location stays), like Rotto's \"see more\". Keep it the same on every page of a search.","type":"boolean"},"hide_viewed":{"description":"Leave out people you have opened, in any search, this one included. Keep it the same on every page of a search.","type":"boolean"}},"additionalProperties":false},"example":{"offset":40,"limit":40}}}},"responses":{"200":{"description":"OK.","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","const":"done"},"search_id":{"type":"string","description":"The search, for its next page, a refinement or an export."},"rotto_url":{"type":"string","description":"This search in the Rotto app."},"summary":{"description":"What Rotto understood the brief to ask for.","type":["string","null"]},"page":{"description":"Which page this is, on the Free plan and on a plan that asked for a page.","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"offset":{"description":"Where this answer starts in the search's ranking, from 0, on a plan.","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"limit":{"description":"How many people this answer was asked for, on a plan.","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"returned":{"description":"How many people this answer carries, on a plan.","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"candidates":{"type":"array","items":{"type":"object","properties":{"candidate_id":{"type":"string","description":"Their id, for GET /candidates/{candidate_id} and the reveal endpoint."},"name":{"type":"string"},"title":{"description":"Their current job title.","type":["string","null"]},"company":{"description":"Their current company.","type":["string","null"]},"location":{"type":["string","null"]},"rotto_url":{"description":"Their profile in the Rotto app. Left out of an answer of more than 100 people: it is https://rotto.com/candidates/{candidate_id}.","type":"string"}},"required":["candidate_id","name","title","company","location"],"additionalProperties":false,"description":"One match. No contact details: reveal them with POST /candidates/{candidate_id}/reveal."}},"total_matches":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}],"description":"How many people match in all. Null when it is still being counted, or past the first page."},"more_available":{"type":"boolean"},"next_offset":{"description":"On a plan: the offset to ask for next, or null at the end.","anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"spent_usd":{"type":"number","description":"What this answer cost: people past the first 100 of a search, at the export's price."},"spent_credits":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"What this answer cost. In credits (10 = $1)."},"plan":{"description":"Present on the Free plan.","type":"string","const":"Free"},"free_searches":{"type":"object","properties":{"kind":{"type":"string","const":"free"},"limit":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"used":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"remaining":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["kind","limit","used","remaining"],"additionalProperties":false,"description":"On the Free plan: your candidate searches, used and left."},"upgrade_url":{"description":"On the Free plan: where to choose a plan.","type":"string"}},"required":["status","search_id","rotto_url","summary","candidates","total_matches","more_available"],"additionalProperties":false},"example":{"status":"done","search_id":"5d2c8e1a-7b3f-4c6d-9e0a-1f2b3c4d5e6f","rotto_url":"https://rotto.com/candidates?s=5d2c8e1a-7b3f-4c6d-9e0a-1f2b3c4d5e6f","summary":"Senior backend engineers in London with fintech experience","offset":40,"limit":40,"returned":1,"candidates":[{"candidate_id":"c4a1e2b3-6d5f-4a7b-8c9d-0e1f2a3b4c5d","name":"Ada Lovelace","title":"Senior Backend Engineer","company":"Analytical Engines","location":"London, United Kingdom","rotto_url":"https://rotto.com/candidates/c4a1e2b3-6d5f-4a7b-8c9d-0e1f2a3b4c5d"}],"total_matches":null,"more_available":true,"next_offset":41}}}},"400":{"description":"`invalid_request`, `invalid_input`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`missing_api_key`, `invalid_api_key`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"`insufficient_balance`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`plan_limit`, `insufficient_scope`, `forbidden_origin`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"`payload_too_large`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"`server_error`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"`service_unavailable`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"504":{"description":"`search_timeout`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/searches/{search_id}":{"get":{"operationId":"getSearch","summary":"Open a search","description":"Free. One saved search, as Rotto reopens it: its brief, summary, how many people matched, and its first page of people as stored when it last ran. Never runs the search: POST /searches/{search_id}/candidates does.","tags":["Search"],"x-scope":"search","parameters":[{"name":"search_id","in":"path","required":true,"description":"A search_id that starting a search or the searches list returned.","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK.","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","const":"done"},"search_id":{"type":"string"},"name":{"type":"string"},"brief":{"type":["string","null"]},"summary":{"type":["string","null"]},"notes":{"description":"Your notes on this search in the app.","type":["string","null"]},"total_matches":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"created_at":{"type":["string","null"]},"candidates":{"type":"array","items":{"type":"object","properties":{"candidate_id":{"type":"string","description":"Their id, for GET /candidates/{candidate_id} and the reveal endpoint."},"name":{"type":"string"},"title":{"description":"Their current job title.","type":["string","null"]},"company":{"description":"Their current company.","type":["string","null"]},"location":{"type":["string","null"]},"rotto_url":{"description":"Their profile in the Rotto app. Left out of an answer of more than 100 people: it is https://rotto.com/candidates/{candidate_id}.","type":"string"}},"required":["candidate_id","name","title","company","location"],"additionalProperties":false,"description":"One match. No contact details: reveal them with POST /candidates/{candidate_id}/reveal."},"description":"Its first page, as stored when it last ran. Empty when nothing is stored."},"people_stored":{"type":"boolean","description":"False when no page is stored: POST /searches/{search_id}/candidates runs it."},"broadened":{"description":"Present when the stored page is the broadened list.","type":"boolean","const":true},"rotto_url":{"type":"string"}},"required":["status","search_id","name","brief","summary","notes","total_matches","created_at","candidates","people_stored","rotto_url"],"additionalProperties":false},"example":{"status":"done","search_id":"5d2c8e1a-7b3f-4c6d-9e0a-1f2b3c4d5e6f","name":"Senior backend engineers in London with fintech experience","brief":"Senior backend engineers in London who have worked at a fintech","summary":"Senior backend engineers in London with fintech experience","notes":null,"total_matches":120,"created_at":"2026-11-16T10:02:00.000Z","candidates":[{"candidate_id":"c4a1e2b3-6d5f-4a7b-8c9d-0e1f2a3b4c5d","name":"Ada Lovelace","title":"Senior Backend Engineer","company":"Analytical Engines","location":"London, United Kingdom","rotto_url":"https://rotto.com/candidates/c4a1e2b3-6d5f-4a7b-8c9d-0e1f2a3b4c5d"}],"people_stored":true,"rotto_url":"https://rotto.com/candidates?s=5d2c8e1a-7b3f-4c6d-9e0a-1f2b3c4d5e6f"}}}},"400":{"description":"`invalid_request`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`missing_api_key`, `invalid_api_key`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`plan_limit`, `insufficient_scope`, `forbidden_origin`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"`server_error`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"`service_unavailable`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/searches/{search_id}/refine":{"post":{"operationId":"refineSearch","summary":"Refine a search","description":"Change one of your searches in plain English (\"only people in London\", \"must have startup experience\") and get its new first page, as Rotto's refine box does: the change is added to the search, which keeps its search_id. Spends no credits. On the Free plan a refined search is a new run: 5 free searches. 15 people per page. Each extra page or refinement uses a search. Retrying the same refinement is free. Takes up to a minute or two.","tags":["Search"],"x-scope":"search","parameters":[{"name":"search_id","in":"path","required":true,"description":"A search_id that starting a search or the searches list returned.","schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"instruction":{"type":"string","minLength":3,"maxLength":15000,"description":"What to change, in plain English, as you would type it into Rotto's refine box (for example \"only people in London\", \"must have worked at a startup\", \"drop the Python requirement\"). It is added to the search, not a new search."},"broaden":{"description":"Loosen the nice-to-haves to show more people (location stays), like Rotto's \"see more\". Keep it the same on every page of a search.","type":"boolean"},"hide_viewed":{"description":"Leave out people you have opened, in any search, this one included. Keep it the same on every page of a search.","type":"boolean"},"limit":{"description":"Paid plans: how many people to return, up to 1,000 (default 40). People past the first 100 of a search cost 1 credit per 10. The Free plan always returns 15 and ignores this.","type":"integer","minimum":1,"maximum":1000}},"required":["instruction"],"additionalProperties":false},"example":{"instruction":"only people who have worked at a startup"}}}},"responses":{"200":{"description":"OK.","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","const":"done"},"search_id":{"type":"string","description":"The search, for its next page, a refinement or an export."},"rotto_url":{"type":"string","description":"This search in the Rotto app."},"summary":{"description":"What Rotto understood the brief to ask for.","type":["string","null"]},"page":{"description":"Which page this is, on the Free plan and on a plan that asked for a page.","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"offset":{"description":"Where this answer starts in the search's ranking, from 0, on a plan.","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"limit":{"description":"How many people this answer was asked for, on a plan.","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"returned":{"description":"How many people this answer carries, on a plan.","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"candidates":{"type":"array","items":{"type":"object","properties":{"candidate_id":{"type":"string","description":"Their id, for GET /candidates/{candidate_id} and the reveal endpoint."},"name":{"type":"string"},"title":{"description":"Their current job title.","type":["string","null"]},"company":{"description":"Their current company.","type":["string","null"]},"location":{"type":["string","null"]},"rotto_url":{"description":"Their profile in the Rotto app. Left out of an answer of more than 100 people: it is https://rotto.com/candidates/{candidate_id}.","type":"string"}},"required":["candidate_id","name","title","company","location"],"additionalProperties":false,"description":"One match. No contact details: reveal them with POST /candidates/{candidate_id}/reveal."}},"total_matches":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}],"description":"How many people match in all. Null when it is still being counted, or past the first page."},"more_available":{"type":"boolean"},"next_offset":{"description":"On a plan: the offset to ask for next, or null at the end.","anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"spent_usd":{"type":"number","description":"What this answer cost: people past the first 100 of a search, at the export's price."},"spent_credits":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"What this answer cost. In credits (10 = $1)."},"plan":{"description":"Present on the Free plan.","type":"string","const":"Free"},"free_searches":{"type":"object","properties":{"kind":{"type":"string","const":"free"},"limit":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"used":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"remaining":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["kind","limit","used","remaining"],"additionalProperties":false,"description":"On the Free plan: your candidate searches, used and left."},"upgrade_url":{"description":"On the Free plan: where to choose a plan.","type":"string"}},"required":["status","search_id","rotto_url","summary","candidates","total_matches","more_available"],"additionalProperties":false},"example":{"status":"done","search_id":"5d2c8e1a-7b3f-4c6d-9e0a-1f2b3c4d5e6f","rotto_url":"https://rotto.com/candidates?s=5d2c8e1a-7b3f-4c6d-9e0a-1f2b3c4d5e6f","summary":"Senior backend engineers in London with fintech experience, startup experience","offset":0,"limit":40,"returned":1,"candidates":[{"candidate_id":"c4a1e2b3-6d5f-4a7b-8c9d-0e1f2a3b4c5d","name":"Ada Lovelace","title":"Senior Backend Engineer","company":"Analytical Engines","location":"London, United Kingdom","rotto_url":"https://rotto.com/candidates/c4a1e2b3-6d5f-4a7b-8c9d-0e1f2a3b4c5d"}],"total_matches":48,"more_available":true,"next_offset":1}}}},"400":{"description":"`invalid_request`, `invalid_input`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`missing_api_key`, `invalid_api_key`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"`insufficient_balance`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`plan_limit`, `insufficient_scope`, `forbidden_origin`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"`payload_too_large`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"`server_error`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"`service_unavailable`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"504":{"description":"`search_timeout`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/searches/{search_id}/export":{"post":{"operationId":"exportCandidates","summary":"Export a search as a CSV","description":"People from one of your searches as a CSV: its top N matches or chosen candidate_ids, with their name, title, company, location, LinkedIn URL and Rotto profile. This spends credits from your balance (10 credits = $1): 1 credit per 10 people exported, plus, only if `columns` asks for work_email, personal_email or phone, each detail found at its price. Pass `estimate: true` to price it without spending, and `max_credits` to refuse anything dearer. A small CSV comes back in `csv`; every one also downloads from `download_url` for anyone signed in to your Rotto account. With contact columns it answers 202 while they are found: poll GET /lookups/{lookup_id}. Needs the `search` permission, and `lookup` too unless it is an estimate, because it spends.","tags":["Search"],"x-scope":"search","parameters":[{"name":"search_id","in":"path","required":true,"description":"A search_id that starting a search or the searches list returned.","schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"top":{"description":"Export the search's top N matches in ranked order, up to 1,000. Give this or candidate_ids.","type":"integer","minimum":1,"maximum":1000},"candidate_ids":{"description":"Or export just these people from the search's results, by their candidate_id.","minItems":1,"maxItems":1000,"type":"array","items":{"type":"string"}},"columns":{"description":"The CSV's columns. Leave out for every free one: first_name, last_name, title, company, location, linkedin_url, headline, years_experience, rotto_profile. work_email, personal_email and phone are contact details, each charged at its price when found.","minItems":1,"type":"array","items":{"type":"string","enum":["first_name","last_name","title","company","location","linkedin_url","headline","years_experience","rotto_profile","work_email","personal_email","phone"]}},"estimate":{"description":"Say what this export would cost and whether the balance covers it, spending nothing. Use it before a large export.","type":"boolean"},"max_credits":{"description":"Refuse, spending nothing, if this would cost more than this many credits with every detail found (for example 500).","type":"integer","minimum":0,"maximum":1000000}},"additionalProperties":false},"example":{"top":40,"max_credits":10}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"oneOf":[{"type":"object","properties":{"status":{"type":"string","const":"estimate"},"people":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"fee_credits":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"The export's own fee."},"contact_columns":{"type":"boolean","description":"Whether contact details were asked for, each charged at its price when found."},"max_cost_usd":{"type":"number","description":"The most it could cost."},"max_cost_credits":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"The most it could cost. In credits (10 = $1)."},"available_usd":{"type":"number","description":"What you can spend."},"available_credits":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"What you can spend. In credits (10 = $1)."},"fits":{"type":"boolean"},"frozen":{"type":"boolean"},"load_url":{"description":"Where to top up, when it does not fit.","type":"string"}},"required":["status","people","fee_credits","contact_columns","max_cost_usd","max_cost_credits","available_usd","available_credits","fits","frozen"],"additionalProperties":false},{"type":"object","properties":{"status":{"type":"string","const":"running"},"export_id":{"type":"string"},"lookup_id":{"type":"string","description":"Poll GET /lookups/{lookup_id} while the contact details are found."},"people":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"to_find":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"How many people contact details are being found for."},"omitted":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"People left out because they are no longer available."},"fee_credits":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"download_url":{"type":"string","description":"The CSV, once it finishes, for anyone signed in to your Rotto account."},"rotto_url":{"type":"string"}},"required":["status","export_id","lookup_id","people","to_find","omitted","fee_credits","download_url","rotto_url"],"additionalProperties":false},{"type":"object","properties":{"status":{"type":"string","const":"done"},"export_id":{"type":"string"},"people":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"omitted":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"fee_credits":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"spent_usd":{"type":"number","description":"What this export spent."},"spent_credits":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"What this export spent. In credits (10 = $1)."},"balance_usd":{"anyOf":[{"type":"number","description":"What you can spend now."},{"type":"null"}]},"balance_credits":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"What you can spend now. In credits (10 = $1)."},{"type":"null"}]},"file_name":{"type":"string"},"download_url":{"type":"string","description":"The CSV, for 30 days, for anyone signed in to your Rotto account."},"csv":{"description":"The CSV itself, when it is small enough to send.","type":"string"},"csv_inline":{"description":"Present when the CSV was too big to send: download it instead.","type":"boolean","const":false}},"required":["status","export_id","people","omitted","fee_credits","spent_usd","spent_credits","file_name","download_url"],"additionalProperties":false}],"description":"estimate: priced, nothing spent. running: contact details are being found (202). done: the CSV is ready."},"example":{"status":"done","export_id":"e7f8a9b0-1c2d-4e3f-8a5b-6c7d8e9f0a1b","people":40,"omitted":0,"fee_credits":4,"spent_usd":0.4,"spent_credits":4,"balance_usd":19.6,"balance_credits":196,"file_name":"rotto-senior-backend-engineers.csv","download_url":"https://rotto.com/api/candidates/exports/e7f8a9b0-1c2d-4e3f-8a5b-6c7d8e9f0a1b/csv","csv":"first_name,last_name,title,company,location,linkedin_url\nAda,Lovelace,Senior Backend Engineer,Analytical Engines,London,https://www.linkedin.com/in/ada-lovelace\n"}}}},"202":{"description":"Still running (or paused). Poll GET /lookups/{lookup_id}.","content":{"application/json":{"schema":{"oneOf":[{"type":"object","properties":{"status":{"type":"string","const":"estimate"},"people":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"fee_credits":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"The export's own fee."},"contact_columns":{"type":"boolean","description":"Whether contact details were asked for, each charged at its price when found."},"max_cost_usd":{"type":"number","description":"The most it could cost."},"max_cost_credits":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"The most it could cost. In credits (10 = $1)."},"available_usd":{"type":"number","description":"What you can spend."},"available_credits":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"What you can spend. In credits (10 = $1)."},"fits":{"type":"boolean"},"frozen":{"type":"boolean"},"load_url":{"description":"Where to top up, when it does not fit.","type":"string"}},"required":["status","people","fee_credits","contact_columns","max_cost_usd","max_cost_credits","available_usd","available_credits","fits","frozen"],"additionalProperties":false},{"type":"object","properties":{"status":{"type":"string","const":"running"},"export_id":{"type":"string"},"lookup_id":{"type":"string","description":"Poll GET /lookups/{lookup_id} while the contact details are found."},"people":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"to_find":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"How many people contact details are being found for."},"omitted":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"People left out because they are no longer available."},"fee_credits":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"download_url":{"type":"string","description":"The CSV, once it finishes, for anyone signed in to your Rotto account."},"rotto_url":{"type":"string"}},"required":["status","export_id","lookup_id","people","to_find","omitted","fee_credits","download_url","rotto_url"],"additionalProperties":false},{"type":"object","properties":{"status":{"type":"string","const":"done"},"export_id":{"type":"string"},"people":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"omitted":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"fee_credits":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"spent_usd":{"type":"number","description":"What this export spent."},"spent_credits":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"What this export spent. In credits (10 = $1)."},"balance_usd":{"anyOf":[{"type":"number","description":"What you can spend now."},{"type":"null"}]},"balance_credits":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"What you can spend now. In credits (10 = $1)."},{"type":"null"}]},"file_name":{"type":"string"},"download_url":{"type":"string","description":"The CSV, for 30 days, for anyone signed in to your Rotto account."},"csv":{"description":"The CSV itself, when it is small enough to send.","type":"string"},"csv_inline":{"description":"Present when the CSV was too big to send: download it instead.","type":"boolean","const":false}},"required":["status","export_id","people","omitted","fee_credits","spent_usd","spent_credits","file_name","download_url"],"additionalProperties":false}],"description":"estimate: priced, nothing spent. running: contact details are being found (202). done: the CSV is ready."}}}},"400":{"description":"`invalid_request`, `invalid_input`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`missing_api_key`, `invalid_api_key`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"`insufficient_balance`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`account_frozen`, `plan_limit`, `insufficient_scope`, `forbidden_origin`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"`payload_too_large`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"`over_max_usd`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"`server_error`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"`service_unavailable`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/candidates/{candidate_id}":{"get":{"operationId":"getCandidate","summary":"Get a candidate's profile","description":"Free. One person from a search, in full: their work history, education, skills and LinkedIn About, `as_of` (when Rotto got this profile), and which contact details Rotto holds for them (and which you already own, so are free to read again). With `search_id` and `include_match_reasons=true`, which parts of that search's brief they meet. No contact details. On the Free plan only people your own searches showed you can be opened.","tags":["Candidates"],"x-scope":"search","parameters":[{"name":"candidate_id","in":"path","required":true,"description":"A candidate_id from a search.","schema":{"type":"string","format":"uuid"}},{"name":"search_id","in":"query","required":false,"description":"The search they came from, to say why they match it (with include_match_reasons).","schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},{"name":"include_bio","in":"query","required":false,"description":"`false` leaves out their LinkedIn About. Default true.","schema":{"type":"string","enum":["0","1","true","false"]}},{"name":"include_match_reasons","in":"query","required":false,"description":"`true` says which parts of that search's brief they meet, as the Rotto card does. Needs search_id.","schema":{"type":"string","enum":["0","1","true","false"]}}],"responses":{"200":{"description":"OK.","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","const":"done"},"candidate_id":{"type":"string"},"name":{"type":"string"},"title":{"type":["string","null"]},"company":{"type":["string","null"]},"location":{"type":["string","null"]},"open_to_work":{"type":["boolean","null"]},"years_of_experience":{"type":["number","null"]},"work_history":{"type":"array","items":{"type":"object","properties":{"title":{"type":["string","null"]},"company":{"type":["string","null"]},"start":{"type":["string","null"]},"end":{"description":"Null while current.","type":["string","null"]},"current":{"type":"boolean"}},"required":["title","company","start","end","current"],"additionalProperties":false}},"education":{"type":"array","items":{"type":"object","properties":{"school":{"type":["string","null"]},"degree":{"type":["string","null"]},"field":{"type":["string","null"]},"start":{"type":["string","null"]},"end":{"type":["string","null"]}},"required":["school","degree","field","start","end"],"additionalProperties":false}},"skills":{"type":"array","items":{"type":"string"}},"as_of":{"description":"When Rotto got this profile (ISO 8601), so an older one may have changed since.","type":["string","null"]},"rotto_url":{"type":"string"},"bio":{"description":"Their LinkedIn About. Left out with `include_bio=false`.","type":["string","null"]},"contact":{"description":"Which contact details Rotto holds for them, never the values.","type":"object","properties":{"details":{"type":"array","items":{"type":"object","properties":{"kind":{"type":"string"},"label":{"type":"string"},"owned":{"type":"boolean","description":"You already hold it, so revealing it again is free."},"verified":{"type":"boolean"}},"required":["kind","label","owned","verified"],"additionalProperties":false}},"looking_up":{"type":"array","items":{"type":"string"},"description":"Details a lookup is still running for."},"none_found":{"type":"array","items":{"type":"string"},"description":"Details a finished lookup found nothing for."}},"required":["details","looking_up","none_found"],"additionalProperties":false},"match":{"description":"With `search_id` and `include_match_reasons`: which parts of that search's brief they meet. Null when the search is not yours.","anyOf":[{"type":"array","items":{"type":"object","properties":{"criterion":{"type":"string"},"met":{"type":"boolean"},"partial":{"type":"boolean","const":true}},"required":["criterion","met"],"additionalProperties":false}},{"type":"null"}]},"search_url":{"type":["string","null"]}},"required":["status","candidate_id","name","title","company","location","open_to_work","years_of_experience","work_history","education","skills","as_of","rotto_url"],"additionalProperties":false},"example":{"status":"done","candidate_id":"c4a1e2b3-6d5f-4a7b-8c9d-0e1f2a3b4c5d","name":"Ada Lovelace","title":"Senior Backend Engineer","company":"Analytical Engines","location":"London, United Kingdom","open_to_work":false,"years_of_experience":9,"work_history":[{"title":"Senior Backend Engineer","company":"Analytical Engines","start":"Mar 2021","end":null,"current":true},{"title":"Backend Engineer","company":"Difference Ltd","start":"Jun 2016","end":"Feb 2021","current":false}],"education":[{"school":"University of London","degree":"BSc","field":"Mathematics","start":"2012","end":"2015"}],"skills":["Go","PostgreSQL","Kafka"],"as_of":"2026-10-30T00:00:00.000Z","rotto_url":"https://rotto.com/candidates/c4a1e2b3-6d5f-4a7b-8c9d-0e1f2a3b4c5d","bio":"I build payment systems that do not fall over.","contact":{"details":[{"kind":"work_email","label":"Work email","owned":false,"verified":true},{"kind":"phone","label":"Phone","owned":false,"verified":false}],"looking_up":[],"none_found":[]}}}}},"400":{"description":"`invalid_request`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`missing_api_key`, `invalid_api_key`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`plan_limit`, `insufficient_scope`, `forbidden_origin`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"`server_error`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"`service_unavailable`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/candidates/{candidate_id}/reveal":{"post":{"operationId":"revealCandidateContact","summary":"Reveal a candidate's contact details","description":"A search result's work email, personal email, phone number or LinkedIn link, as the Rotto card gets them: details Rotto holds are revealed now, and ones it does not are looked up. This spends credits from your balance (10 credits = $1) per detail found, never for a miss, and never twice for the same detail, here, in the app or through a lookup. LinkedIn is free. The price is the same for every account: a work email is 1 credit, a personal email 3 credits and a phone 9 credits. Pass `max_credits` to refuse anything dearer. It waits up to 4 minutes for a lookup, then answers 202 with `status: \"running\"`: call it again later, and anything already revealed comes back free. Needs the `lookup` permission.","tags":["Candidates"],"x-scope":"lookup","parameters":[{"name":"candidate_id","in":"path","required":true,"description":"A candidate_id from a search.","schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"channels":{"description":"Which details to get. Leave out for work_email, personal_email and phone. A work email is 1 credit, a personal email 3, a phone 9; LinkedIn is free. Charged only when found, and never twice.","minItems":1,"type":"array","items":{"type":"string","enum":["work_email","personal_email","phone","linkedin"]}},"all_details":{"description":"Reveal every detail Rotto holds in each channel (another email, a WhatsApp number), each at its price. Default: the first of each.","type":"boolean"},"max_credits":{"description":"Refuse, spending nothing, if this would cost more than this many credits with every detail found (for example 500).","type":"integer","minimum":0,"maximum":1000000}},"additionalProperties":false},"example":{"channels":["work_email","phone"],"max_credits":10}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["done","running"],"description":"running: a lookup is still finding a detail. Call again later; anything revealed is free to read again."},"candidate_id":{"type":"string"},"revealed":{"type":"array","items":{"type":"object","properties":{"channel":{"type":"string","enum":["work_email","personal_email","phone","linkedin"]},"label":{"type":"string"},"value":{"type":"string"},"verified":{"type":"boolean"},"charged_credits":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"What this detail cost on this call: 0 when you already held it, and for LinkedIn."}},"required":["channel","label","value","verified","charged_credits"],"additionalProperties":false}},"not_found":{"type":"array","items":{"type":"string"},"description":"Details looked for and not found. Free."},"still_looking":{"type":"array","items":{"type":"string"}},"charged_when_found_usd":{"type":"number","description":"What the details still being looked for will cost if found."},"charged_when_found_credits":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"What the details still being looked for will cost if found. In credits (10 = $1)."},"could_not_look_up":{"type":"array","items":{"type":"object","properties":{"channel":{"type":"string"},"reason":{"type":"string"}},"required":["channel","reason"],"additionalProperties":false}},"left_out_over_max_credits":{"description":"Details left out because they would pass your `max_credits`.","type":"array","items":{"type":"string"}},"left_out":{"type":"array","items":{"type":"string"}},"rotto_url":{"type":"string"},"spent_usd":{"type":"number","description":"What this call spent."},"spent_credits":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"What this call spent. In credits (10 = $1)."},"balance_usd":{"anyOf":[{"type":"number","description":"What you can spend now."},{"type":"null"}]},"balance_credits":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"What you can spend now. In credits (10 = $1)."},{"type":"null"}]}},"required":["status","candidate_id","revealed","not_found","still_looking","spent_usd","spent_credits"],"additionalProperties":false},"example":{"status":"done","candidate_id":"c4a1e2b3-6d5f-4a7b-8c9d-0e1f2a3b4c5d","revealed":[{"channel":"work_email","label":"Work email","value":"ada@analyticalengines.com","verified":true,"charged_credits":1}],"not_found":["phone"],"still_looking":[],"spent_usd":0.1,"spent_credits":1,"balance_usd":19.9,"balance_credits":199}}}},"202":{"description":"A detail is still being looked up. Call this again later: anything already revealed is free to read again.","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["done","running"],"description":"running: a lookup is still finding a detail. Call again later; anything revealed is free to read again."},"candidate_id":{"type":"string"},"revealed":{"type":"array","items":{"type":"object","properties":{"channel":{"type":"string","enum":["work_email","personal_email","phone","linkedin"]},"label":{"type":"string"},"value":{"type":"string"},"verified":{"type":"boolean"},"charged_credits":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"What this detail cost on this call: 0 when you already held it, and for LinkedIn."}},"required":["channel","label","value","verified","charged_credits"],"additionalProperties":false}},"not_found":{"type":"array","items":{"type":"string"},"description":"Details looked for and not found. Free."},"still_looking":{"type":"array","items":{"type":"string"}},"charged_when_found_usd":{"type":"number","description":"What the details still being looked for will cost if found."},"charged_when_found_credits":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"What the details still being looked for will cost if found. In credits (10 = $1)."},"could_not_look_up":{"type":"array","items":{"type":"object","properties":{"channel":{"type":"string"},"reason":{"type":"string"}},"required":["channel","reason"],"additionalProperties":false}},"left_out_over_max_credits":{"description":"Details left out because they would pass your `max_credits`.","type":"array","items":{"type":"string"}},"left_out":{"type":"array","items":{"type":"string"}},"rotto_url":{"type":"string"},"spent_usd":{"type":"number","description":"What this call spent."},"spent_credits":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"What this call spent. In credits (10 = $1)."},"balance_usd":{"anyOf":[{"type":"number","description":"What you can spend now."},{"type":"null"}]},"balance_credits":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"What you can spend now. In credits (10 = $1)."},{"type":"null"}]}},"required":["status","candidate_id","revealed","not_found","still_looking","spent_usd","spent_credits"],"additionalProperties":false}}}},"400":{"description":"`invalid_request`, `invalid_input`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`missing_api_key`, `invalid_api_key`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"`insufficient_balance`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`account_frozen`, `plan_limit`, `insufficient_scope`, `forbidden_origin`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"`payload_too_large`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"`over_max_usd`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"`server_error`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"`service_unavailable`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/estimate":{"post":{"operationId":"estimateCost","summary":"Estimate a lookup's cost","description":"Free. The most a lookup of these inputs and details could cost, each detail's price, what you can spend, and whether it fits. Only found details are ever charged, so the real cost is usually lower.","tags":["Account"],"x-scope":"read","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"inputs":{"minItems":1,"maxItems":50,"type":"array","items":{"type":"object","properties":{"id":{"description":"Your own key for this row, returned with its result.","type":"string","maxLength":100},"input":{"type":"string","minLength":3,"maxLength":500,"description":"A LinkedIn profile link or an email address."}},"required":["input"]},"description":"Up to 50 people."},"channels":{"description":"Which details to get. Leave out for all three: work_email, personal_email, phone. Pass an empty list for the profile alone (their LinkedIn, current role and location, no contact details), charged a profile's price per person found. POST /estimate lists each price.","maxItems":3,"type":"array","items":{"type":"string","enum":["work_email","personal_email","phone"]}}},"required":["inputs"],"additionalProperties":false},"example":{"inputs":[{"input":"https://www.linkedin.com/in/ada-lovelace"},{"input":"charles@analyticalengines.com"}]}}}},"responses":{"200":{"description":"OK.","content":{"application/json":{"schema":{"type":"object","properties":{"people":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Distinct people (repeats are looked up and charged once)."},"max_cost_usd":{"type":"number","description":"The most it could cost: every detail found for everyone. Usually less."},"max_cost_credits":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"The most it could cost: every detail found for everyone. Usually less. In credits (10 = $1)."},"available_usd":{"type":"number","description":"What you can spend now."},"available_credits":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"What you can spend now. In credits (10 = $1)."},"fits":{"type":"boolean"},"prices_usd":{"type":"object","properties":{"work_email":{"type":"number"},"personal_email":{"type":"number"},"phone":{"type":"number"},"linkedin_from_email":{"type":"number","description":"Finding the LinkedIn profile behind an email input, charged only on a match."},"profile":{"type":"number","description":"The profile alone (a lookup with `channels: []`), per person found; the same as the LinkedIn find."}},"required":["work_email","personal_email","phone","linkedin_from_email","profile"],"additionalProperties":false,"description":"Each detail's price in US dollars, the same for every account."},"prices_credits":{"type":"object","properties":{"work_email":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"personal_email":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"phone":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"linkedin_from_email":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Finding the LinkedIn profile behind an email input, charged only on a match."},"profile":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"The profile alone (a lookup with `channels: []`), per person found; the same as the LinkedIn find."}},"required":["work_email","personal_email","phone","linkedin_from_email","profile"],"additionalProperties":false,"description":"Each detail's price in credits, the same for every account."},"load_url":{"description":"Where to add money, when it does not fit.","type":"string"},"invalid":{"description":"Inputs that are not a LinkedIn profile link or an email address. They are never charged.","type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"input":{"type":"string"},"reason":{"type":"string"}},"required":["input"],"additionalProperties":false}}},"required":["people","max_cost_usd","max_cost_credits","available_usd","available_credits","fits","prices_usd","prices_credits"],"additionalProperties":false},"example":{"people":2,"max_cost_usd":2.7,"max_cost_credits":27,"available_usd":20,"available_credits":200,"fits":true,"prices_usd":{"work_email":0.1,"personal_email":0.3,"phone":0.9,"linkedin_from_email":0.1,"profile":0.1},"prices_credits":{"work_email":1,"personal_email":3,"phone":9,"linkedin_from_email":1,"profile":1}}}}},"400":{"description":"`invalid_request`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`missing_api_key`, `invalid_api_key`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `forbidden_origin`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"`payload_too_large`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"`server_error`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"`service_unavailable`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/balance":{"get":{"operationId":"getBalance","summary":"Get your balance","description":"Free. Your balance in credits (and US dollars), what each detail costs (the same price list for every account), the extra credits a bigger top-up earns, auto top-up, and the link to top up. Also your plan (Free, Starter, Professional or Business), the credits it adds each month, and on Free how many free candidate searches are left.","tags":["Account"],"x-scope":"read","responses":{"200":{"description":"OK.","content":{"application/json":{"schema":{"type":"object","properties":{"available_usd":{"type":"number","description":"What you can spend now: the balance less running lookups' reservations and any debt."},"available_credits":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"What you can spend now: the balance less running lookups' reservations and any debt. In credits (10 = $1)."},"balance_usd":{"type":"number","description":"The settled balance."},"balance_credits":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"The settled balance. In credits (10 = $1)."},"frozen":{"type":"boolean","description":"True while a payment is reviewed. Lookups are refused until it clears."},"prices_usd":{"type":"object","properties":{"work_email":{"type":"number"},"personal_email":{"type":"number"},"phone":{"type":"number"},"linkedin_from_email":{"type":"number","description":"Finding the LinkedIn profile behind an email input, charged only on a match."},"profile":{"type":"number","description":"The profile alone (a lookup with `channels: []`), per person found; the same as the LinkedIn find."}},"required":["work_email","personal_email","phone","linkedin_from_email","profile"],"additionalProperties":false,"description":"Each detail's price in US dollars, the same for every account."},"prices_credits":{"type":"object","properties":{"work_email":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"personal_email":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"phone":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"linkedin_from_email":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Finding the LinkedIn profile behind an email input, charged only on a match."},"profile":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"The profile alone (a lookup with `channels: []`), per person found; the same as the LinkedIn find."}},"required":["work_email","personal_email","phone","linkedin_from_email","profile"],"additionalProperties":false,"description":"Each detail's price in credits, the same for every account."},"top_up_bonus":{"type":"array","items":{"type":"object","properties":{"from_usd":{"type":"number","description":"A single top-up of at least this much..."},"percent":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"...earns this percent extra credits."}},"required":["from_usd","percent"],"additionalProperties":false},"description":"Bigger top-ups earn extra credits, by the size of that one top-up."},"auto_reload":{"type":"object","properties":{"enabled":{"type":"boolean"},"status":{"type":"string","enum":["off","ok","paused_declined","paused_auth_required","paused_cap"]},"amount_usd":{"type":"number","description":"What one auto top-up charges: $20, $100, $500 or $2,500."},"floor_usd":{"type":"number","description":"A top-up fires when the balance drops under this."},"floor_credits":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"A top-up fires when the balance drops under this. In credits (10 = $1)."},"monthly_limit_usd":{"type":["number","null"]},"spent_this_month_usd":{"type":"number"}},"required":["enabled","status","amount_usd","floor_usd","floor_credits","monthly_limit_usd","spent_this_month_usd"],"additionalProperties":false},"load_url":{"type":"string","description":"Where to top up (only you can, in the browser)."},"plan":{"description":"Your plan, as rotto.com names it.","type":"string","enum":["Free","Starter","Professional","Business"]},"plan_status":{"description":"How you hold it: the Free plan, a paid month, a free trial, complimentary access, or Rotto staff.","type":"string","enum":["free","paid","trial","complimentary","staff"]},"monthly_credits":{"description":"The credits your plan adds each paid month (Starter 200, Professional 400). Null without a paid month.","anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"free_searches":{"description":"On the Free plan, your candidate searches: how many there are, used and left. Null on a plan, which has no limit.","anyOf":[{"type":"object","properties":{"limit":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"used":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"remaining":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["limit","used","remaining"],"additionalProperties":false},{"type":"null"}]}},"required":["available_usd","available_credits","balance_usd","balance_credits","frozen","prices_usd","prices_credits","top_up_bonus","auto_reload","load_url"],"additionalProperties":false},"example":{"available_usd":20,"available_credits":200,"balance_usd":20,"balance_credits":200,"frozen":false,"prices_usd":{"work_email":0.1,"personal_email":0.3,"phone":0.9,"linkedin_from_email":0.1,"profile":0.1},"prices_credits":{"work_email":1,"personal_email":3,"phone":9,"linkedin_from_email":1,"profile":1},"top_up_bonus":[{"from_usd":100,"percent":10},{"from_usd":500,"percent":15},{"from_usd":2500,"percent":25}],"auto_reload":{"enabled":false,"status":"off","amount_usd":20,"floor_usd":5,"floor_credits":50,"monthly_limit_usd":null,"spent_this_month_usd":0},"load_url":"https://rotto.com/contact-lookup/checkout","plan":"Starter","plan_status":"paid","monthly_credits":200,"free_searches":null}}}},"401":{"description":"`missing_api_key`, `invalid_api_key`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`insufficient_scope`, `forbidden_origin`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"`server_error`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"`service_unavailable`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"components":{"securitySchemes":{"apiKey":{"type":"http","scheme":"bearer","bearerFormat":"rcl_live_...","description":"Your API key, from Settings, Connected apps. It also connects the MCP server (https://rotto.com/mcp)."}},"schemas":{"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["invalid_request","invalid_input","missing_api_key","invalid_api_key","insufficient_balance","insufficient_scope","account_frozen","plan_limit","forbidden_origin","not_found","payload_too_large","over_max_usd","rate_limited","server_error","service_unavailable","search_timeout"]},"message":{"type":"string","description":"What happened, in plain words."},"request_id":{"type":"string","description":"Quote it if you contact us."},"required_usd":{"type":"number"},"required_credits":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"available_usd":{"type":"number"},"available_credits":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"max_usd":{"description":"The limit that applied (the lower of `max_usd` and `max_credits` when you sent both).","type":"number"},"max_credits":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"load_url":{"type":"string"},"required_scope":{"type":"string","enum":["lookup","search","read"]},"upgrade_url":{"description":"Where to choose a plan.","type":"string"},"free_searches":{"type":"object","properties":{"kind":{"type":"string","const":"free"},"limit":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"used":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"remaining":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["kind","limit","used","remaining"],"additionalProperties":false,"description":"On the Free plan: your candidate searches, used and left."},"search_id":{"description":"The search this was about, when one was started.","type":"string"},"reason":{"type":"string"},"retry_after_seconds":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"resets_at":{"description":"When an export's hourly or daily cap lifts (ISO 8601).","type":"string"},"finds_today":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"daily_limit":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"running":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"running_limit":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"code":{"type":"string"},"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string"},"message":{"type":"string"}},"required":["path","message"],"additionalProperties":false}},"results":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"input":{"type":"string"},"reason":{"type":"string"}},"required":["input"],"additionalProperties":false}}},"required":["type","message","request_id"],"additionalProperties":false,"description":"Only the fields that apply to the error's type are present."}},"required":["error"],"additionalProperties":false}}}}