# Find people at companies People who work at up to 25 companies, filtered on title, seniority, department and country. One call reads one page across all the companies and returns at most 25 people, so a big company can fill it: set `per_company` to search each company on its own and get its top people in one call. Each person costs 1 credit. A company that cannot be matched, and a page with nobody on it, cost nothing. Name a company by `id` (`cmp_…` from an earlier row), `domain`, or `linkedin_url`. A domain without a known LinkedIn page is looked up by its name; when that finds nothing, GET /companies/lookup finds the page for free. Send `next_cursor` back as `cursor` with the same companies and filters. No profile is fetched: use POST /person/enrich with `person_ids` for the full profile and a work email. This is not a buying signal. `signal_type` on each row is null. The person did not do anything; they hold a role at a company you named. ## Authentication Send `Authorization: Bearer gtk_…`. Create the key under **Connect assistant → API keys**. A missing, invalid or revoked key is **401**. A valid key while this API is not enabled for your organization answers **403** `api_not_enabled`, with what the key can do instead. Every response includes `mySDR-Api-Version`, `mySDR-Request-Id` and `Cache-Control: no-store`, and a response to an accepted key also `X-RateLimit-*` (so not a 401, a 405, an OPTIONS or a 404 for an unknown path). ### Body parameters - **`companies`** `object[]` · **required** — 1 to 25 companies. Each object has exactly one of `id`, `domain` or `linkedin_url`. - **`filters`** `object` · **required** — At least one of `titles` (job titles, up to 10), `seniority` (`c_level`, `vp`, `director`, `manager`) or `departments` (`ceo`, `sales`, `marketing`, `finance`, `operations`, `hr`, `it`, `talent_acquisition`, `engineering`, `product`, `customer_success`, `data`, `procurement`, `legal`). `countries` is ISO alpha-2, up to 20. Titles rank people but do not exclude them. Departments, seniority and countries do: a department filters on LinkedIn's own function of the role (`engineering` keeps engineering and IT), except `ceo` and `chief_of_staff`, which only rank on title (`ceo` alone looks at C-level and owners). Values in one list are alternatives. `roles` is the earlier name of `titles` and still works. - **`per_company`** `integer | null` — At most this many people per company, 1 to 25: each company is searched on its own and the call returns their top people, in the order of `companies`, without a next page. Not together with `cursor`. - **`limit`** `integer` — At most this many people, 1 to 100. Without `per_company` one call still returns at most 25. Defaults to 25. - **`cursor`** `string | null` — `next_cursor` of the previous response, with the same companies and filters. - **`max_credits`** `integer | null` — Stop before the next person would pass this. ## Response - **`object`** `string` · **required** — Always `list`. - **`data`** `object[]` · **required** — People. `id` is `per_…` (send it to POST /person/enrich as `person_ids`). `from_company_id` is the company they were found at. `signals` is the current role. - **`companies`** `object[]` · **required** — One entry per company you sent, in order: `status` `matched`, `not_found` or `invalid`, `company_id`, `rows`, `message`. `company_id` is set once people of the company were delivered (now or in the last 30 days): send it as `id` later. A matched company without anyone has none; send its domain or page again. - **`next_cursor`** `string | null` · **required** — The next page. Always null with `per_company`. - **`credits_used`** `integer` · **required** — People delivered times 1. - **`truncated_by`** `string | null` · **required** — `max_credits` when the cap left people out. ## Credits 1 credit per person delivered. Misses are free. Errors and empty lookups are free. A call that spent credits puts that number in `credits_used`, in `X-Credits-Used` and in `X-Credits-Charged`. When the wallet can be read, the response also sends `X-Credits-Remaining`. ## Errors - **503** `service_unavailable` — A company could not be looked up just now. `param` names `companies[i]`. Nothing was charged. - **400** `invalid_request` — The body is not valid JSON, a field is unknown or has the wrong type, or a value is not allowed. - **401** `authentication_error` — The Authorization header is missing, or the key is unknown or revoked. - **403** `permission_error` — API access is not part of your plan, or your account is suspended. - **403** `api_not_enabled` — The key is valid, but the Signals API or the Company API is not enabled for your organization yet. The error says what this key can do. - **429** `rate_limit_error` — More than 60 requests per minute, or more than 3 at the same time, on one key. Wait for the Retry-After header. - **429** `daily_limit_reached` — The request could take your organization over its daily credit limit. The limit resets at midnight (Europe/Brussels). - **402** `insufficient_credits` — The credit balance is lower than this request could cost. Nothing was charged. Add credits, or send a smaller request. The error includes code, fix and a link to the credits docs. - **502** `upstream_error` — The data source did not answer. Retry later. - **503** `service_unavailable` — The API is temporarily unavailable. Retry later. - **500** `internal_error` — Something went wrong on our side. - **402** `max_credits_exceeded` — max_credits is lower than the credits of the first row, so nothing could be returned. Nothing was charged; raise max_credits or ask for fewer rows. ## Example ### cURL ```bash curl -X POST "https://mysdr.app/api/v1/leads" \ -H "Authorization: Bearer $MYSDR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "companies": [ { "linkedin_url": "https://www.linkedin.com/company/acme-analytics" } ], "filters": { "titles": [ "CFO", "Head of Finance" ], "seniority": [ "c_level", "vp" ], "countries": [ "BE" ] }, "limit": 3, "max_credits": 15 }' ``` ### JavaScript ```javascript const response = await fetch('https://mysdr.app/api/v1/leads', { method: 'POST', headers: { Authorization: `Bearer ${process.env.MYSDR_API_KEY}`, 'Content-Type': 'application/json' }, body: JSON.stringify({ "companies": [ { "linkedin_url": "https://www.linkedin.com/company/acme-analytics" } ], "filters": { "titles": [ "CFO", "Head of Finance" ], "seniority": [ "c_level", "vp" ], "countries": [ "BE" ] }, "limit": 3, "max_credits": 15 }) }); const body = await response.json(); ``` ### Python ```python import json import os import urllib.request payload = { "companies": [ { "linkedin_url": "https://www.linkedin.com/company/acme-analytics" } ], "filters": { "titles": [ "CFO", "Head of Finance" ], "seniority": [ "c_level", "vp" ], "countries": [ "BE" ] }, "limit": 3, "max_credits": 15 } request = urllib.request.Request( "https://mysdr.app/api/v1/leads", headers={ "Authorization": f"Bearer {os.environ['MYSDR_API_KEY']}", "Content-Type": "application/json" }, data=json.dumps(payload).encode(), method="POST", ) with urllib.request.urlopen(request) as response: body = json.load(response) ``` ### Example response ```json { "object": "list", "data": [ { "id": "per_01J9Z6P8C8V0K3W6T2N8R5M1XK", "object": "person", "signal_type": null, "from_company_id": "cmp_01J9Z6P8C8V0K3W6T2N8R5M1XB", "credits_charged": 1, "person": { "full_name": "Jane Example", "title": "Chief Financial Officer", "linkedin_url": "https://www.linkedin.com/in/jane-example" } } ], "companies": [ { "input": { "linkedin_url": "https://www.linkedin.com/company/acme-analytics" }, "status": "matched", "company_id": "cmp_01J9Z6P8C8V0K3W6T2N8R5M1XB", "rows": 1, "message": null } ], "next_cursor": null, "credits_used": 1, "truncated_by": null, "sources": [ "linkedin" ], "notes": [] } ```