# 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

```bash
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`](/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. |