# 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 | Required | 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 <action> (<date>)". |
| `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://example.com, example.com/contact, www.example.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

```bash
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":"Example Dental","website":"example.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`](/docs/errors#missing_api_key) | The request has no API key. |
| 401 | [`invalid_api_key`](/docs/errors#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`](/docs/errors#revoked_api_key) | The API key was revoked on the API page. Revoking takes effect at once. |
| 429 | [`rate_limited`](/docs/errors#rate_limited) | More than 120 requests in one minute with this key. |
| 500 | [`server_error`](/docs/errors#server_error) | Something broke on our side. Nothing was charged for it. |
| 400 | [`invalid_request`](/docs/errors#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`](/docs/errors#invalid_json) | The body is not valid JSON. |
| 409 | [`idempotency_in_progress`](/docs/errors#idempotency_in_progress) | A request with the same Idempotency-Key is still running. |
| 422 | [`idempotency_key_reused`](/docs/errors#idempotency_key_reused) | The Idempotency-Key was already used in the last 24 hours with a different request. |
| 400 | [`no_eligible_rows`](/docs/errors#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`](/docs/errors#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`](/docs/errors#not_found) | The job or list does not exist, belongs to another account, or was deleted. |
| 400 | [`invalid_webhook_url`](/docs/errors#invalid_webhook_url) | The webhook URL is not a public https address (private networks and other schemes are refused). |
| 403 | [`wrong_key_mode`](/docs/errors#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. |