---
title: "Endpoints"
description: "All SignupSieve API endpoints with request and response examples: single check, bulk check, feedback and model stats."
canonical_url: "https://signupsieve.pages.dev/docs/endpoints"
---

> Index of every page on this site: [llms.txt](https://signupsieve.pages.dev/llms.txt)

# Endpoints

<table>
<thead>
  <tr>
    <th>
      Method
    </th>
    
    <th>
      Path
    </th>
    
    <th>
      What it does
    </th>
    
    <th>
      Billed
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        POST
      </code>
    </td>
    
    <td>
      <code>
        /v1/check
      </code>
    </td>
    
    <td>
      Check one address
    </td>
    
    <td>
      1 email
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        GET
      </code>
    </td>
    
    <td>
      <code>
        /v1/check?email=...
      </code>
    </td>
    
    <td>
      Same, using the query string
    </td>
    
    <td>
      1 email
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        POST
      </code>
    </td>
    
    <td>
      <code>
        /v1/check/bulk
      </code>
    </td>
    
    <td>
      Check up to 1,000 addresses
    </td>
    
    <td>
      1 per address answered
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        POST
      </code>
    </td>
    
    <td>
      <code>
        /v1/feedback
      </code>
    </td>
    
    <td>
      Report what happened to a checked address
    </td>
    
    <td>
      Free
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        GET
      </code>
    </td>
    
    <td>
      <code>
        /v1/model
      </code>
    </td>
    
    <td>
      Live accuracy of the model
    </td>
    
    <td>
      Free
    </td>
  </tr>
</tbody>
</table>

## `POST /v1/check`

<table>
<thead>
  <tr>
    <th>
      Field
    </th>
    
    <th>
      Type
    </th>
    
    <th>
      Required
    </th>
    
    <th>
      Description
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        email
      </code>
    </td>
    
    <td>
      string
    </td>
    
    <td>
      Yes
    </td>
    
    <td>
      The address to check. Max 254 characters.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        ip
      </code>
    </td>
    
    <td>
      string
    </td>
    
    <td>
      No
    </td>
    
    <td>
      The user's public IP (IPv4 or IPv6). Adds cloud-server, Tor and same-IP checks. Never stored.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        explain
      </code>
    </td>
    
    <td>
      boolean
    </td>
    
    <td>
      No
    </td>
    
    <td>
      <code>
        true
      </code>
      
       adds an <code>
        evidence
      </code>
      
       list showing how each signal moved the score.
    </td>
  </tr>
</tbody>
</table>

Prefer `POST` over `GET`: addresses then stay out of URLs and server logs. The `GET` version takes the same fields as query parameters.

## `POST /v1/check/bulk`

```json
{ "emails": ["a.lee@gmail.com", "not-an-email", "test@mailinator.com"] }
```

Returns one entry per input, **in the same order**. An invalid input returns an error entry instead of failing the whole request:

```json
{
  "results": [
    { "email": "a.lee@gmail.com", "human_score": 94, "verdict": "allow", "...": "..." },
    { "input": "not-an-email", "error": "not a valid email address" },
    { "email": "test@mailinator.com", "human_score": 0, "verdict": "block", "...": "..." }
  ]
}
```

Addresses are checked in parallel, and addresses at the same domain share one lookup, so a bulk call is much faster than many single calls.

## `POST /v1/feedback`

```json
{ "check_id": "chk_AXDmekmC35NL1mpGtCtC...", "outcome": "fake" }
```

Or skip the `check_id` and send the address. It labels your latest check of that inbox:

```json
{ "email": "maria.santos@gmail.com", "outcome": "confirmed" }
```

Returns `202 Accepted`. See [Teach the model with feedback](https://signupsieve.pages.dev/docs/feedback).

## `GET /v1/model`

Shows how accurate the model is, measured on real feedback before the model learned from each example. Example response (your numbers will differ):

```json
{
  "mode": "auto",
  "serving": "baseline",
  "healthy": false,
  "learned_version": 12,
  "feedback_examples": 140,
  "customers": 3,
  "baseline": { "accuracy": 0.91, "log_loss": 0.27, "recent_log_loss": 0.25 },
  "learned":  { "accuracy": 0.93, "log_loss": 0.22, "recent_log_loss": 0.21 },
  "recommendation": "keep collecting feedback"
}
```

## Sitemap

See the full [sitemap](https://signupsieve.pages.dev/sitemap.md) for all pages.