> ## Documentation Index > Fetch the complete documentation index at: https://developer.lemlist.com/llms.txt > Use this file to discover all available pages before exploring further. > Starts an AI contact-sourcing run for one or more accounts. # Run Contact Sourcing Contact sourcing finds the **buying committee** of an account: it sources the company's employees from the People Database, then classifies each one as a `decision_maker`, a `user` or an `influencer`, with an ICP fit score and a short reason. One account or two hundred — same call, pass a list of one. ## The run is asynchronous You get a `runId` per account immediately; the classification itself takes from a few seconds to a couple of minutes depending on how many employees the company has. Two ways to collect the result: * **Poll** [Get Contact Sourcing Run](/api-reference/endpoints/contact-sourcing/get-contact-sourcing-run). It answers `202` while a run is going and `200` once it is done. * **Subscribe** to the `contactSourcingDone` webhook and let lemlist call you. Subscribe to `contactSourcingFailed` too, or a failed run leaves you waiting. ## One answer per account The call responds `200` even when some accounts could not be started — with 200 accounts in a request, one unrunnable account is not a reason to fail the other 199\. Read both arrays: ```json theme={"theme":"dracula"} { "results": [ { "companyId": "cpn_K4tRm2Qw9Yb7Xz1Ns", "runId": "air_H2nQv7Bs4Jm1Ty8Wk", "status": "started" }, { "companyId": "cpn_G7yFs4Nc1Vd8Bh3Zp", "runId": "air_D5cLp3Xg9Rn6Vt2Fs", "status": "reused" } ], "errors": [ { "companyId": "cpn_M9jTx6Rw2Kf5Cq0Ld", "code": "ABS_CONTACT_SOURCING_COMPANY_NOT_IDENTIFIED", "message": "Add this account's website or public LinkedIn URL before searching for leads." } ] } ``` Entries come back in the order you sent them, so you can zip them against your own list. Only a malformed body or more than 200 ids is refused outright (`400`). ## Re-running an account By default an account that already has a committee is **not** re-run: you get the previous run back with `status: "reused"` and nothing is charged. Pass `overwrite: true` to force a fresh run and replace the previous result. `overwrite` never stacks a second run on one that is **still going**: you get that run back as `reused`, and nothing is charged. So retrying a request that timed out on your side is always safe — you cannot pay twice for one account by retrying. Each run costs one credit, charged when the run succeeds. A reused run is free. Accounts left out by the workspace's daily limit come back in `errors` with `ABS_CONTACT_SOURCING_TEAM_DAILY_CAP_REACHED` — retry them the next day. ## Starting from a domain or a LinkedIn URL This endpoint takes lemlist company IDs. If you hold a domain or a LinkedIn page instead, resolve it first with [Get Many Companies](/api-reference/endpoints/companies/get-many-companies): ```bash theme={"theme":"dracula"} curl -u :$LEMLIST_API_KEY \ "https://api.lemlist.com/api/companies?idsOrDomains=acme.com" ``` ## Before your first run The team needs its **AI Context** filled in — in the lemlist app, open **Settings → AI Context Center** (lemlist uses it to know what a good fit looks like) — and the account needs a website or a LinkedIn URL — a company name alone matches every company that shares it, so the run is refused rather than sourcing people from the wrong company. ## OpenAPI ````yaml post /contact-sourcing openapi: 3.0.0 info: title: lemlist API version: 1.0.0 description: >- Welcome to the lemlist Developer Documentation. lemlist is very customizable and open. You'll find on this page all the API and integration you can do with lemlist. # Rate Limit lemlist's API rate limits requests in order to prevent abuse and overload of our services. Rate limits are applied on all routes and per API key performing the request. The rate limits are **20** requests per **2** seconds. The response provides any information you may need about it: | Header | Description | | --- | --- | | Retry-After | The number of seconds in which you can retry | | X-RateLimit-Limit | The maximum requests in that time | | X-RateLimit-Remaining | The number of remaining requests you can make | | X-RateLimit-Reset | The date when the rate limit will reset | _Example of values for the rate limit headers_ ``` json { "Retry-After": 2, "X-RateLimit-Limit": 20, "X-RateLimit-Remaining": 7, "X-RateLimit-Reset" : "Tue Feb 16 2021 09:02:42 GMT+0100 (Central European Standard Time)" } ``` # Definitions ## Team A team is the entity of lemlist that can handle users and billing. ## Credits Credits are the coins a team uses to enrich emails, LinkedIn URLs, etc. via the enrich route. Each enrichment feature needs a certain amount of credits to run. ## User You use a user account to connect to lemlist and send messages via the connected emails or LinkedIn account. ## Campaign A campaign is the entity to automate outreach. A campaign has multiple sequences composed of steps. ## Lead A lead is a person that you try to contact via a campaign. ## Activity An activity is the history of all the steps. ## Unsubscribe An unsubscribe occurs when a person decides they don't want to receive emails from you anymore. # Authentication All API routes use the dedicated subdomain `api.lemlist.com`. lemlist uses API keys to allow access to the API. You can get your lemlist API key at our [integration page](https://app.lemlist.com/settings/integrations). You need to add the `Authorization` header using the `Basic` authentication type. `login:password` **where the login is always empty and the password is the API key**. ⚠️ **Don't forget to add the semicolon (**`:`**) before your API key in curl command.** > To authorize, use this code: ``` shell curl https://api.lemlist.com/api/team \ --user ":YourApiKey" ``` **Make sure to replace** **`YourApiKey`** **with your API key.** # Give feedback If you want to report a bug, ask for data, or share with us a use case, please fill this [form](https://lemlist.typeform.com/to/mfVlkyGf). It will help us centralize your needs! servers: - url: https://api.lemlist.com/api security: - basicAuth: [] paths: /contact-sourcing: post: tags: - Contact sourcing summary: Run Contact Sourcing description: >- Starts an AI contact-sourcing run for one or more accounts: sources each company's employees from the People Database and classifies them into a buying committee (decision maker / user / influencer) with an ICP fit score. One account or two hundred, same call — pass a list of one. Runs are asynchronous: the response carries a `runId` per account. Poll `GET /contact-sourcing` or subscribe to the `contactSourcingDone` webhook for the result. The call answers `200` even when some accounts could not be started — one unrunnable account among 200 is not a reason to fail the rest. Read both `results` and `errors`. By default an account that already has a committee is not re-run: its previous run comes back with `status: "reused"` and nothing is charged. `overwrite: true` forces a fresh run, but never stacks a second one on a run still going — that one is returned as `reused` instead, so retrying a timed-out request cannot charge you twice. Takes lemlist company ids only. To start from a domain or LinkedIn URL, resolve it first with `GET /companies?idsOrDomains=`. requestBody: required: true content: application/json: schema: type: object required: - companyIds properties: companyIds: type: array maxItems: 200 items: type: string description: Accounts to source contacts for (`cpn_xxx` format). example: - cpn_K4tRm2Qw9Yb7Xz1Ns overwrite: type: boolean default: false responses: '200': description: One entry per account, in the order they were given. content: application/json: schema: type: object properties: results: type: array items: type: object properties: companyId: type: string runId: type: string status: type: string enum: - started - reused errors: type: array items: type: object properties: companyId: type: string code: type: string example: ABS_CONTACT_SOURCING_TEAM_DAILY_CAP_REACHED message: type: string '400': description: >- The body is not a non-empty list of company IDs, contains something other than a `cpn_` id, asks for more than 200 accounts, or `overwrite` is not a boolean. '403': description: The workspace does not have contact sourcing enabled. '422': description: >- The team has no AI Context set up, so there is nothing to judge fit against. In the lemlist app, open Settings > AI Context Center. Per-account problems — no website or LinkedIn URL, no credits, daily limit reached — are not this: they come back inside `errors`. components: securitySchemes: basicAuth: type: http scheme: basic ````