> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.dealsignal.com/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.dealsignal.com/_mcp/server. # Create and launch an LE job POST https://app.dealsignal.com/api/v1/lead_enrichments Content-Type: application/json Creates a new Lead Enrichment job and immediately launches it. The job runs asynchronously — poll `GET /api/v1/lead_enrichments/{id}` for status or provide a `webhook` to be notified on completion. Reference: https://docs.dealsignal.com/api-reference/lead-enrichment/create-lead-enrichment-job ## Request ### Query parameters - `api_key` (string, required) — Your Dealsignal API key. Obtain it from the Dealsignal dashboard. ### Body (application/json) This endpoint expects a LeadEnrichmentCreateRequest. - `lead_enrichments` (LeadEnrichmentCreateRequestLeadEnrichments, required) ## Response ### 200 Job created and launched. - `message` (string, optional) - `id` (integer, optional) — ID of the new job. Use it to poll status and fetch results. ## Errors ### 401 Unauthorized Error Invalid key, inactive account, or expired subscription. - `message` (string, required) - `authorization_failure` (boolean, optional) - `inactive` (boolean, optional) ### 422 Unprocessable Entity Error Invalid input, job limit reached, or not enough credits for the job. - `message` (string, required) - `authorization_failure` (boolean, optional) - `inactive` (boolean, optional) ## Types ### LeadEnrichmentCreateRequestLeadEnrichments - `name` (string, required) — Name for the job. Must be unique: a name that's already taken returns `422` — include something distinctive, such as a date or your own ID. - `source_type` (enum, required) — Always `from_json` for API-submitted jobs. - Allowed values: `from_json` - `match_field` (enum, required) — Field used to match leads against Dealsignal's database. - `name` — matches on `first_name`, `last_name`, and `company_name` - `email` — matches on `email` - `linkedin_url` — matches on `linkedin_url` - Allowed values: `name`, `email`, `linkedin_url` - `lead_data` (LeadData, required) — Columnar format for lead input data. `keys` defines the field names; each array in `values` is one lead's data in the same order. - `append_company_data` (boolean, optional, default: false) — Include enriched company data alongside contact data. - `contact_profile_only` (boolean, optional, default: false) — Enrich the contact profile only — no email or phone enrichment (`profile_type` `Contact Profile`). Don't combine it with `is_full_prospect_profile` or `direct_dial`. - `is_full_prospect_profile` (boolean, optional, default: false) — Also enrich phone numbers (`profile_type` `Full Prospect Profile`). Without this flag, `direct_dial` and `contact_profile_only`, the job enriches the contact profile and work email (`Lead Profile`). - `direct_dial` (boolean, optional, default: false) — Also enrich phone numbers, including direct dials (`profile_type` `Full Prospect Profile With Direct Dial`). Turns on `is_full_prospect_profile`. - `contact_refresh_time` (integer, optional, default: 30) — Freshness threshold in days. Contacts whose LinkedIn profile was verified within this many days before the job are returned without a refresh; older ones are refreshed first. Defaults to 30. - `flag_if_lead_changed_company` (boolean, optional, default: false) — Compute `changed_company` for each lead: whether the contact's primary employer changed within about the last month before the job (many position dates are only month-precise). It is not a comparison with the values you submitted. `false` also covers leads that couldn't be assessed, so it isn't proof the contact stayed. - `flag_if_lead_changed_title` (boolean, optional, default: false) — Compute `changed_title` for each lead: whether the contact's primary title changed within about the last month before the job. It is not a comparison with the values you submitted. `false` also covers leads that couldn't be assessed. - `webhook` (string, optional) — URL to receive a POST when the job completes. The body is the job object — the same fields as `lead_enrichment` in the `GET /api/v1/lead_enrichments/{id}` response, without the wrapper; it does not carry the leads. It is sent once, while the job is being finalized, so the payload shows `status: "Completion Running"` and `is_completed: false` — treat the webhook's arrival as the completion signal. If `final_result` then returns a `message` instead of results, retry after a few seconds. If the job reads `is_completed: true` and `final_result` still returns a `message`, stop retrying and check `page` / `page_size`. ### LeadData Columnar format for lead input data. `keys` defines the field names; each array in `values` is one lead's data in the same order. - `keys` (list of enum, required) - Allowed values: `first_name`, `last_name`, `company_name`, `email`, `linkedin_url`, `title`, `city`, `state`, `country`, `unique_identifier` - `values` (list of list of any, required) ## Examples **Request** ```json { "lead_enrichments": { "name": "YOUR_UNIQUE_JOB_NAME", "source_type": "from_json", "match_field": "linkedin_url", "lead_data": { "keys": [ "first_name", "last_name", "company_name", "email", "linkedin_url", "unique_identifier" ], "values": [ [ "Jane", "Smith", "Acme Corp", "jane@acme.example", "https://www.linkedin.com/in/jane-smith-example", "1" ], [ "John", "Doe", "Globex Inc", "john@globex.example", "https://www.linkedin.com/in/john-doe-example", "2" ] ] }, "append_company_data": true, "contact_profile_only": true, "contact_refresh_time": 30, "flag_if_lead_changed_company": true, "flag_if_lead_changed_title": true, "webhook": "https://your-server.com/webhooks/dealsignal" } } ``` **Response** ```json { "message": "LeadEnrichment Job Launched Successfully!", "id": 652 } ``` **SDK Code** ```python import requests url = "https://app.dealsignal.com/api/v1/lead_enrichments" querystring = {"api_key":"YOUR_API_KEY"} payload = { "lead_enrichments": { "name": "YOUR_UNIQUE_JOB_NAME", "source_type": "from_json", "match_field": "linkedin_url", "lead_data": { "keys": ["first_name", "last_name", "company_name", "email", "linkedin_url", "unique_identifier"], "values": [["Jane", "Smith", "Acme Corp", "jane@acme.example", "https://www.linkedin.com/in/jane-smith-example", "1"], ["John", "Doe", "Globex Inc", "john@globex.example", "https://www.linkedin.com/in/john-doe-example", "2"]] }, "append_company_data": True, "contact_profile_only": True, "contact_refresh_time": 30, "flag_if_lead_changed_company": True, "flag_if_lead_changed_title": True, "webhook": "https://your-server.com/webhooks/dealsignal" } } headers = {"Content-Type": "application/json"} response = requests.post(url, json=payload, headers=headers, params=querystring) print(response.json()) ``` ```javascript const url = 'https://app.dealsignal.com/api/v1/lead_enrichments?api_key=YOUR_API_KEY'; const options = { method: 'POST', headers: {'Content-Type': 'application/json'}, body: '{"lead_enrichments":{"name":"YOUR_UNIQUE_JOB_NAME","source_type":"from_json","match_field":"linkedin_url","lead_data":{"keys":["first_name","last_name","company_name","email","linkedin_url","unique_identifier"],"values":[["Jane","Smith","Acme Corp","jane@acme.example","https://www.linkedin.com/in/jane-smith-example","1"],["John","Doe","Globex Inc","john@globex.example","https://www.linkedin.com/in/john-doe-example","2"]]},"append_company_data":true,"contact_profile_only":true,"contact_refresh_time":30,"flag_if_lead_changed_company":true,"flag_if_lead_changed_title":true,"webhook":"https://your-server.com/webhooks/dealsignal"}}' }; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```go package main import ( "fmt" "strings" "net/http" "io" ) func main() { url := "https://app.dealsignal.com/api/v1/lead_enrichments?api_key=YOUR_API_KEY" payload := strings.NewReader("{\n \"lead_enrichments\": {\n \"name\": \"YOUR_UNIQUE_JOB_NAME\",\n \"source_type\": \"from_json\",\n \"match_field\": \"linkedin_url\",\n \"lead_data\": {\n \"keys\": [\n \"first_name\",\n \"last_name\",\n \"company_name\",\n \"email\",\n \"linkedin_url\",\n \"unique_identifier\"\n ],\n \"values\": [\n [\n \"Jane\",\n \"Smith\",\n \"Acme Corp\",\n \"jane@acme.example\",\n \"https://www.linkedin.com/in/jane-smith-example\",\n \"1\"\n ],\n [\n \"John\",\n \"Doe\",\n \"Globex Inc\",\n \"john@globex.example\",\n \"https://www.linkedin.com/in/john-doe-example\",\n \"2\"\n ]\n ]\n },\n \"append_company_data\": true,\n \"contact_profile_only\": true,\n \"contact_refresh_time\": 30,\n \"flag_if_lead_changed_company\": true,\n \"flag_if_lead_changed_title\": true,\n \"webhook\": \"https://your-server.com/webhooks/dealsignal\"\n }\n}") req, _ := http.NewRequest("POST", url, payload) req.Header.Add("Content-Type", "application/json") res, _ := http.DefaultClient.Do(req) defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res) fmt.Println(string(body)) } ``` ```ruby require 'uri' require 'net/http' url = URI("https://app.dealsignal.com/api/v1/lead_enrichments?api_key=YOUR_API_KEY") http = Net::HTTP.new(url.host, url.port) http.use_ssl = true request = Net::HTTP::Post.new(url) request["Content-Type"] = 'application/json' request.body = "{\n \"lead_enrichments\": {\n \"name\": \"YOUR_UNIQUE_JOB_NAME\",\n \"source_type\": \"from_json\",\n \"match_field\": \"linkedin_url\",\n \"lead_data\": {\n \"keys\": [\n \"first_name\",\n \"last_name\",\n \"company_name\",\n \"email\",\n \"linkedin_url\",\n \"unique_identifier\"\n ],\n \"values\": [\n [\n \"Jane\",\n \"Smith\",\n \"Acme Corp\",\n \"jane@acme.example\",\n \"https://www.linkedin.com/in/jane-smith-example\",\n \"1\"\n ],\n [\n \"John\",\n \"Doe\",\n \"Globex Inc\",\n \"john@globex.example\",\n \"https://www.linkedin.com/in/john-doe-example\",\n \"2\"\n ]\n ]\n },\n \"append_company_data\": true,\n \"contact_profile_only\": true,\n \"contact_refresh_time\": 30,\n \"flag_if_lead_changed_company\": true,\n \"flag_if_lead_changed_title\": true,\n \"webhook\": \"https://your-server.com/webhooks/dealsignal\"\n }\n}" response = http.request(request) puts response.read_body ``` ```java import com.mashape.unirest.http.HttpResponse; import com.mashape.unirest.http.Unirest; HttpResponse response = Unirest.post("https://app.dealsignal.com/api/v1/lead_enrichments?api_key=YOUR_API_KEY") .header("Content-Type", "application/json") .body("{\n \"lead_enrichments\": {\n \"name\": \"YOUR_UNIQUE_JOB_NAME\",\n \"source_type\": \"from_json\",\n \"match_field\": \"linkedin_url\",\n \"lead_data\": {\n \"keys\": [\n \"first_name\",\n \"last_name\",\n \"company_name\",\n \"email\",\n \"linkedin_url\",\n \"unique_identifier\"\n ],\n \"values\": [\n [\n \"Jane\",\n \"Smith\",\n \"Acme Corp\",\n \"jane@acme.example\",\n \"https://www.linkedin.com/in/jane-smith-example\",\n \"1\"\n ],\n [\n \"John\",\n \"Doe\",\n \"Globex Inc\",\n \"john@globex.example\",\n \"https://www.linkedin.com/in/john-doe-example\",\n \"2\"\n ]\n ]\n },\n \"append_company_data\": true,\n \"contact_profile_only\": true,\n \"contact_refresh_time\": 30,\n \"flag_if_lead_changed_company\": true,\n \"flag_if_lead_changed_title\": true,\n \"webhook\": \"https://your-server.com/webhooks/dealsignal\"\n }\n}") .asString(); ``` ```php request('POST', 'https://app.dealsignal.com/api/v1/lead_enrichments?api_key=YOUR_API_KEY', [ 'body' => '{ "lead_enrichments": { "name": "YOUR_UNIQUE_JOB_NAME", "source_type": "from_json", "match_field": "linkedin_url", "lead_data": { "keys": [ "first_name", "last_name", "company_name", "email", "linkedin_url", "unique_identifier" ], "values": [ [ "Jane", "Smith", "Acme Corp", "jane@acme.example", "https://www.linkedin.com/in/jane-smith-example", "1" ], [ "John", "Doe", "Globex Inc", "john@globex.example", "https://www.linkedin.com/in/john-doe-example", "2" ] ] }, "append_company_data": true, "contact_profile_only": true, "contact_refresh_time": 30, "flag_if_lead_changed_company": true, "flag_if_lead_changed_title": true, "webhook": "https://your-server.com/webhooks/dealsignal" } }', 'headers' => [ 'Content-Type' => 'application/json', ], ]); echo $response->getBody(); ``` ```csharp using RestSharp; var client = new RestClient("https://app.dealsignal.com/api/v1/lead_enrichments?api_key=YOUR_API_KEY"); var request = new RestRequest(Method.POST); request.AddHeader("Content-Type", "application/json"); request.AddParameter("application/json", "{\n \"lead_enrichments\": {\n \"name\": \"YOUR_UNIQUE_JOB_NAME\",\n \"source_type\": \"from_json\",\n \"match_field\": \"linkedin_url\",\n \"lead_data\": {\n \"keys\": [\n \"first_name\",\n \"last_name\",\n \"company_name\",\n \"email\",\n \"linkedin_url\",\n \"unique_identifier\"\n ],\n \"values\": [\n [\n \"Jane\",\n \"Smith\",\n \"Acme Corp\",\n \"jane@acme.example\",\n \"https://www.linkedin.com/in/jane-smith-example\",\n \"1\"\n ],\n [\n \"John\",\n \"Doe\",\n \"Globex Inc\",\n \"john@globex.example\",\n \"https://www.linkedin.com/in/john-doe-example\",\n \"2\"\n ]\n ]\n },\n \"append_company_data\": true,\n \"contact_profile_only\": true,\n \"contact_refresh_time\": 30,\n \"flag_if_lead_changed_company\": true,\n \"flag_if_lead_changed_title\": true,\n \"webhook\": \"https://your-server.com/webhooks/dealsignal\"\n }\n}", ParameterType.RequestBody); IRestResponse response = client.Execute(request); ``` ```swift import Foundation let headers = ["Content-Type": "application/json"] let parameters = ["lead_enrichments": [ "name": "YOUR_UNIQUE_JOB_NAME", "source_type": "from_json", "match_field": "linkedin_url", "lead_data": [ "keys": ["first_name", "last_name", "company_name", "email", "linkedin_url", "unique_identifier"], "values": [["Jane", "Smith", "Acme Corp", "jane@acme.example", "https://www.linkedin.com/in/jane-smith-example", "1"], ["John", "Doe", "Globex Inc", "john@globex.example", "https://www.linkedin.com/in/john-doe-example", "2"]] ], "append_company_data": true, "contact_profile_only": true, "contact_refresh_time": 30, "flag_if_lead_changed_company": true, "flag_if_lead_changed_title": true, "webhook": "https://your-server.com/webhooks/dealsignal" ]] as [String : Any] let postData = JSONSerialization.data(withJSONObject: parameters, options: []) let request = NSMutableURLRequest(url: NSURL(string: "https://app.dealsignal.com/api/v1/lead_enrichments?api_key=YOUR_API_KEY")! as URL, cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0) request.httpMethod = "POST" request.allHTTPHeaderFields = headers request.httpBody = postData as Data let session = URLSession.shared let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in if (error != nil) { print(error as Any) } else { let httpResponse = response as? HTTPURLResponse print(httpResponse) } }) dataTask.resume() ```