Name: ListCheck API: Screen Emails, Phones and Cards in Bulk
Brand: visionwell
SKU: api-visionwell-listcheck
Availability: InStock
Author: API Market

binbin7418-dotcom

# ListCheck List Screening API

## Overview

The ListCheck API screens a whole contact list in one call. It checks email addresses at domain level (syntax, domain, MX records, disposable and role addresses, typos and domain age), phone numbers at numbering-plan level (validity, country, line type and standard formats), and card numbers at format level (Luhn checksum, length and card network). Each list comes back with per-item results and a summary.

It is built for marketing, CRM and data teams who clean imported lists before using them. It does not contact mailboxes or phones and does not check whether a card is active: the response states the scope of each check, so you know what a result means.

## Features

*   **3 endpoints**: batch screening, single item screening and a health check.
*   **Emails**: syntax, domain, MX, disposable, role, free provider, typo and domain age.
*   **Phones**: valid and possible flags, country, line type, E.164 and national formats.
*   **Cards**: Luhn checksum, length, network and test card flag.
*   **Up to 100 per list**: for each of emails, phones and cards.
*   **Rate limit**: up to 10 requests per second on every plan.

## Use Cases

*   **List imports**: clean a CSV before loading it into a CRM.
*   **Email campaigns**: remove disposable and invalid addresses.
*   **Sign-up forms**: screen one value at a time.
*   **Data quality**: report how many records in a list are usable.

## API Documentation

### Base URL

All requests go through the API.market proxy at this base URL:

```
https://prod.api.market/api/v1/visionwell/listcheck
```

### Authentication

Every request must include your API.market key in the `x-api-market-key` header:

```
x-api-market-key: YOUR_API_KEY
```

Replace `YOUR_API_KEY` with your actual API key.

### Endpoints

#### 1. Screen a list

Screens lists of emails, phones and card numbers in one call and returns per-item results and summaries.

**Method:** `POST`

**Endpoint:** `/screen/batch`

**Parameters:**

| Name | In | Description | Type | Required | Default | Max Value |
|---|---|---|---|---|---|---|
| emails | body | Email addresses to screen | array of strings | No | - | 100 |
| phones | body | Phone numbers to screen, ideally in international format | array of strings | No | - | 100 |
| cards | body | Card numbers to screen | array of strings | No | - | 100 |

**Example Request:**

```bash
curl -X POST 'https://prod.api.market/api/v1/visionwell/listcheck/screen/batch' \
  -H 'x-api-market-key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "emails": [
    "someone@gmail.com",
    "bad@@x"
  ],
  "phones": [
    "+442071838750",
    "123"
  ],
  "cards": [
    "4242424242424242",
    "4242424242424241"
  ]
}'
```

**Example Response (200 OK):**

```json
{
  "scope": "ListCheck screens list health at three levels: email is checked at domain level (syntax, domain and MX existence, disposable and risk signals - never whether a mailbox exists), phone numbers at numbering-plan level (correctly formed for the...",
  "emails": {
    "results": [
      {
        "email": "someone@gmail.com",
        "valid": true,
        "score": 100,
        "verdict": "valid",
        "checks": {
          "syntax": true,
          "domainExists": true,
          "mxFound": true,
          "disposable": false,
          "roleAccount": false,
          "freeProvider": true
        },
        "mxRecords": [
          "alt3.gmail-smtp-in.l.google.com"
        ],
        "suggestion": null,
        "typoLikely": false,
        "domainAgeDays": 11409,
        "domainAgeSource": "RDAP",
        "catchAllRisk": "low",
        "note": "Checks domain mail routing (MX) and risk signals. Does not probe individual mailbox existence. Catch-all risk is a risk signal based on MX/provider patterns, not a probing conclusion."
      }
    ],
    "summary": {
      "total": 2,
      "valid": {
        "count": 1,
        "percent": 50
      },
      "risky": {
        "count": 0,
        "percent": 0
      },
      "invalid": {
        "count": 1,
        "percent": 50
      },
      "disposable": {
        "count": 0,
        "percent": 0
      },
      "typoLikely": {
        "count": 0,
        "percent": 0
      }
    }
  },
  "phones": {
    "results": [
      {
        "input": "+442071838750",
        "valid": true,
        "possible": true,
        "country": "GB",
        "countryCallingCode": "+44",
        "nationalNumber": "2071838750",
        "e164": "+442071838750",
        "internationalFormat": "+44 20 7183 8750",
        "nationalFormat": "020 7183 8750",
        "type": "FIXED_LINE",
        "uri": "tel:+442071838750",
        "note": "Type is inferred from numbering plans (MOBILE / FIXED_LINE / TOLL_FREE / etc.). Carrier lookup is not included."
      }
    ],
    "summary": {
      "total": 2,
      "valid_count": 1,
      "invalid_count": 1,
      "valid_rate": 0.5,
      "invalid_numbers": [
        "123"
      ],
      "by_country": {
        "GB": 1,
        "UNKNOWN": 1
      },
      "by_type": {
        "FIXED_LINE": 1,
        "UNKNOWN": 1
      },
      "duplicates": [],
      "duplicate_count": 0
    }
  },
  "cards": {
    "results": [
      {
        "number": "424242••••••4242",
        "bin": "424242",
        "last4": "4242",
        "length": 16,
        "valid": true,
        "possible": true,
        "checks": {
          "luhn": true,
          "length": true,
          "networkKnown": true
        },
        "network": "Visa",
        "networkId": "visa",
        "expectedLengths": [
          13
        ],
        "testCard": true
      }
    ],
    "summary": {
      "total": 2,
      "valid": 1,
      "invalid": 1
    }
  },
  "summary": {
    "total": 6,
    "valid": 3,
    "notValid": 3,
    "legs": {
      "email": {
        "total": 2,
        "valid": 1,
        "flagged": 0,
        "invalid": 1,
        "disposable": 0,
        "typoLikely": 0
      },
      "phone": {
        "total": 2,
        "valid": 1,
        "invalid": 1,
        "valid_rate": 0.5,
        "duplicate_count": 0
      },
      "card": {
        "total": 2,
        "valid": 1,
        "invalid": 1,
        "testCards": 1
      }
    },
    "note": "'valid' uses each leg's own verdict: email verdict 'valid' (risky counts as not valid here, see the email leg's summary for the split), phone numbering-plan valid, card format valid. See 'scope' for what each verdict does and does not mean."
  }
}
```

#### 2. Screen one item

Screens a single email, phone or card number.

**Method:** `POST`

**Endpoint:** `/screen/single`

**Parameters:**

| Name | In | Description | Type | Required | Default | Max Value |
|---|---|---|---|---|---|---|
| type | body | What to screen: `email`, `phone` or `card` | string | Yes | - | - |
| value | body | The value to screen | string | Yes | - | - |

**Example Request:**

```bash
curl -X POST 'https://prod.api.market/api/v1/visionwell/listcheck/screen/single' \
  -H 'x-api-market-key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "type": "email",
  "value": "someone@gmail.com"
}'
```

**Example Response (200 OK):**

```json
{
  "type": "email",
  "input": "someone@gmail.com",
  "result": {
    "email": "someone@gmail.com",
    "valid": true,
    "score": 100,
    "verdict": "valid",
    "checks": {
      "syntax": true,
      "domainExists": true,
      "mxFound": true,
      "disposable": false,
      "roleAccount": false,
      "freeProvider": true
    },
    "mxRecords": [
      "alt4.gmail-smtp-in.l.google.com",
      "gmail-smtp-in.l.google.com",
      "alt3.gmail-smtp-in.l.google.com"
    ],
    "suggestion": null,
    "typoLikely": false,
    "domainAgeDays": 11409,
    "domainAgeSource": "RDAP",
    "catchAllRisk": "low",
    "note": "Checks domain mail routing (MX) and risk signals. Does not probe individual mailbox existence. Catch-all risk is a risk signal based on MX/provider patterns, not a probing conclusion."
  },
  "scope": "ListCheck screens list health at three levels: email is checked at domain level (syntax, domain and MX existence, disposable and risk signals - never whether a mailbox exists), phone numbers at numbering-plan level (correctly formed for the..."
}
```

#### 3. Health check

Returns the service status. It is a quick way to check that your key and the ListCheck service are working.

**Method:** `GET`

**Endpoint:** `/health`

**Parameters:** None.

**Example Request:**

```bash
curl -X GET 'https://prod.api.market/api/v1/visionwell/listcheck/health' \
  -H 'x-api-market-key: YOUR_API_KEY'
```

**Example Response (200 OK):**

```json
{
  "ok": true,
  "service": "ListCheck",
  "version": 1
}
```

## Status Codes

| Code | Status | Description |
|---|---|---|
| 200 | OK | The request succeeded and the response body holds the result. |
| 400 | Bad Request | A required parameter is missing or a value is invalid. Check the parameter table for the endpoint. |
| 401 | Unauthorized | The `x-api-market-key` header is missing or the key is not valid. |
| 403 | Forbidden | Your key is valid but your subscription does not allow this request, for example an endpoint outside your plan. |
| 404 | Not Found | The path does not exist, or the resource you asked for was not found. |
| 429 | Too Many Requests | You sent more than 10 requests per second. Slow down and retry, honouring the `Retry-After` header. |
| 500 | Internal Server Error | Something went wrong while processing the request. Retry after a short wait. |
| 503 | Service Unavailable | The service or its upstream data source is temporarily unavailable. Retry with backoff. |

## Rate Limits

Every plan allows up to 10 requests per second. Subscription plans also have a monthly call quota shown on the pricing page. Sending more than 10 requests per second returns `429 Too Many Requests`. Throttle your client to stay under 10 requests per second, back off and retry when you get a 429, and honour the `Retry-After` header when it is present.

## FAQ

*   **Does it check whether a mailbox exists?**

    No. Email checks are at domain level: syntax, domain, MX records and risk signals. A valid result means the domain can receive mail.

*   **Does it check whether a card is active?**

    No. Card checks are format checks: Luhn checksum, length and network. Use test card numbers when trying the API, and follow your own card data rules before sending real numbers.

*   **Do I have to send all three lists?**

    No. Send any one or more of `emails`, `phones` and `cards`.

## Contact Us

If you have any questions or need assistance, you can reach out to us through the embedded chat on the bottom right corner of the page or send an email to hello@magicapi.com.


Screen lists of emails, phone numbers and card numbers in one call: MX and disposable checks, phone formats and Luhn checks.

ListCheck API: Screen Emails, Phones and Cards in Bulk