Reference · Deep Search

Company summary and first line

POST /api/v1/deep-search

Reads each business's own website and writes a short summary, why your offer could matter to them (set "What you sell" in the app) and a personal first line. For GB and AU businesses it adds official company-registry facts. Registry data is never used to find or guess emails.

Credits: 0.5 credits per business we write a summary for (you only pay when we write the report). Rows your account already got an answer for in the last 30 days are answered again for free (cached30d).

Body (JSON)

Name	Type	What it is
`listId`	integer	Run on a list you already have (from POST /api/v1/lists or a search) instead of `rows`.
`contactIds`	array of integer	With listId: only these rows (default: all rows of the list). up to 50,000
`name`	string	Name of the new list (shown in the app). Default: "API ()".
`rows`	array of objects	Up to 10,000 businesses (company + website). up to 10,000
`rows[].company`	string	Business name.
`rows[].website`	string	Website (any form: https://acme.com, acme.com/contact, www.acme.com).
`rows[].domain`	string	Domain, if you have it instead of a website.
`rows[].firstName`	string
`rows[].lastName`	string
`rows[].fullName`	string	Used when first and last name are not given separately.
`rows[].jobTitle`	string
`rows[].email`	string	The email to check (verify).
`rows[].phone`	string
`rows[].city`	string
`rows[].state`	string
`rows[].country`	string	Two-letter country code, e.g. US, CA, GB.
`rows[].address`	string	Business address. For US businesses it decides which state rules apply.
`rows[].category`	string
`webhookUrl`	string	Public https URL we POST the result to when the job is done (see the webhooks guide).
`webhookSecret`	string	Optional: sign this webhook with your own secret instead of the account signing secret.
`wait`	integer	Seconds to wait for the job to finish before answering (0–30). Handy for Zapier, Make and Clay: small jobs come back done, with results. default `0`, 0–30

Example request

Shell

curl -X POST "https://moleman.io/api/v1/deep-search" \
  -H "Authorization: Bearer $MOLEMAN_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"rows":[{"company":"Bright Smile Dental","website":"brightsmiledental.com","city":"Austin","country":"US"}]}'

Example answer

JSON

{
  "jobId": 983,
  "listId": 379,
  "status": "queued",
  "livemode": true,
  "queued": 1,
  "skipped": [],
  "cached30d": 0,
  "maxCreditsHeld": 0.5,
  "pollUrl": "/api/v1/jobs/983"
}

Errors

Status	Code	When
401	`missing_api_key`	The request has no API key.
401	`invalid_api_key`	The API key is not one of ours (a typo, a cut-off copy, or a key from another account that was deleted).
401	`revoked_api_key`	The API key was revoked on the API page. Revoking takes effect at once.
429	`rate_limited`	More than 120 requests in one minute with this key.
500	`server_error`	Something broke on our side. Nothing was charged for it.
400	`invalid_request`	A parameter is missing, has the wrong type or is out of range. `details` lists every problem with its path.
400	`invalid_json`	The body is not valid JSON.
409	`idempotency_in_progress`	A request with the same Idempotency-Key is still running.
422	`idempotency_key_reused`	The Idempotency-Key was already used in the last 24 hours with a different request.
400	`no_eligible_rows`	None of the rows can run this action (for example: no website or domain to find an email for, or no email to check).
402	`insufficient_credits`	The account has fewer credits than this request could use at most. We hold the maximum while the job runs and give back what it does not use.
404	`not_found`	The job or list does not exist, belongs to another account, or was deleted.
400	`invalid_webhook_url`	The webhook URL is not a public https address (private networks and other schemes are refused).
403	`wrong_key_mode`	A test key asked for something made with a live key, or the other way round. Test and live data never mix.