Reference · Lists

Upload a list

POST /api/v1/lists

Stores rows as a list (it shows up in the app). Then run find-contacts, verify or deep-search on it with listId. Most integrations skip this and send rows directly.

Credits: Free.

Body (JSON)

Name	Type	Required	What it is
`name`	string		default `"API List"`
`rows`	array of objects	yes	up to 50,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

Example request

Shell

curl -X POST "https://moleman.io/api/v1/lists" \
  -H "Authorization: Bearer $MOLEMAN_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"name":"Austin dentists","rows":[{"company":"Bright Smile Dental","website":"brightsmiledental.com","firstName":"Sarah","lastName":"Miller"}]}'

Example answer

JSON

{
  "listId": 381,
  "rowCount": 1,
  "contactIds": [
    4110
  ],
  "livemode": true
}

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.