Rotto API
Find anyone's work email, personal email and phone number from a LinkedIn URL or an email address, from your own code. Pay only for what is found.
Base URL: https://rotto.com/api/v1. Every endpoint takes Authorization: Bearer <API key> and answers JSON.
Also available as an OpenAPI document and as Markdown for AI tools.
Lookups
Look up one person
POST https://rotto.com/api/v1/contacts/lookup
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.
Look up up to 50 people
POST https://rotto.com/api/v1/contacts/lookup-batch
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.
Check a lookup
GET https://rotto.com/api/v1/lookups/{lookup_id}
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.
Contacts
List your contacts
GET https://rotto.com/api/v1/contacts
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.
Get one contact and their profile
GET https://rotto.com/api/v1/contacts/{contact_id}
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.
Reveal an extra detail
POST https://rotto.com/api/v1/contacts/{contact_id}/extras
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.
Search
Start a search
POST https://rotto.com/api/v1/searches
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.
Get more people from a search
POST https://rotto.com/api/v1/searches/{search_id}/candidates
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.
List your searches
GET https://rotto.com/api/v1/searches
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.
Open a search
GET https://rotto.com/api/v1/searches/{search_id}
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.
Refine a search
POST https://rotto.com/api/v1/searches/{search_id}/refine
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.
Export a search as a CSV
POST https://rotto.com/api/v1/searches/{search_id}/export
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.
Candidates
Get a candidate's profile
GET https://rotto.com/api/v1/candidates/{candidate_id}
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.
Reveal a candidate's contact details
POST https://rotto.com/api/v1/candidates/{candidate_id}/reveal
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.
Account
Estimate a lookup's cost
POST https://rotto.com/api/v1/estimate
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.
Get your balance
GET https://rotto.com/api/v1/balance
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.