API Documentation

Welcome to the Bullio API. You can use this API to verify email addresses, find emails by name and domain, process bulk requests, look up phone numbers, and manage customers programmatically.

The API is organized around REST. All requests should be made over HTTPS. All request and response bodies, including errors, are encoded in JSON.

Authentication

Authenticate your API requests by including your API key as a query parameter on every request. You can find your API key in your Dashboard.

Response Format

All responses are returned as JSON. Successful responses include a state or status field set to true.

{
  "state": true,
  "result": { ... },
  "remain_credits": 9500,
  "credits_consumed": 1
}

Error Codes

Credit System

Every API call consumes credits from your account balance. The number of credits varies by operation:

Remaining credits are returned in the remain_credits field of most responses.

Submit a single email address for verification. Returns an ID that you can use to poll for the result via /email/status.

Parameters

Response

{
  "state": true,
  "id": 12345
}

Errors

// 403 — Invalid API key
{
  "result": "failed",
  "errors": ["Wrong API key"]
}

// 429 — Insufficient credits
{
  "result": "failed",
  "errors": ["Not enough credits"]
}

Retrieve the result of a previously submitted email verification by its ID.

Parameters

Response

{
  "state": true,
  "result": {
    "id": 12345,
    "email": "john@example.com",
    "result": "deliverable",
    "verify_at": {
      "date": "2025-01-15 10:30:00.000000",
      "timezone_type": 3,
      "timezone": "Europe/Helsinki"
    }
  },
  "remain_credits": 9500,
  "credits_consumed": 2
}

Submit a list of email addresses for bulk verification. Send a JSON array of emails in the request body.

Parameters

Request

POST /api/v1/email/bulk/verify?api_key=YOUR_API_KEY
Content-Type: application/json

{
  "emails": [
    "alice@example.com",
    "bob@company.org",
    "carol@startup.io"
  ],
  "webhook": "https://yourserver.com/webhook"
}

Response

{
  "state": true,
  "id": 789
}

Errors

// 400 — Invalid input
{
  "result": "failed",
  "errors": ["Emails must be an array"]
}

// 429 — Insufficient credits
{
  "result": "failed",
  "errors": ["Not enough credits"]
}

Find an email address by first name, last name, and company domain. Returns instantly from the database without deliverability verification. Costs 1 credit.

Parameters

Response

{
  "email": "john@apple.com",
  "remain_credits": 9500,
  "credits_consumed": 1
}

Returns an empty array if no email is found.

Find an email address and verify its deliverability. This is an asynchronous operation — use the returned ID with /email/status to retrieve the result. Costs 2 credits.

Parameters

Response

{
  "state": true,
  "id": 12345
}

Poll /email/status with the returned id to get the final result.

Submit up to 1,000 contacts for bulk email lookup. Each contact should include a name and one or more domains.

Parameters

Request

POST /api/v1/email/bulk?api_key=YOUR_API_KEY
Content-Type: application/json

{
  "contacts": [
    {
      "id": "c1",
      "first_name": "John",
      "last_name": "Doe",
      "domains": ["apple.com"]
    },
    {
      "id": "c2",
      "first_name": "Jane",
      "last_name": "Smith",
      "domains": ["google.com", "alphabet.com"]
    }
  ],
  "mode": "regular",
  "webhook": "https://yourserver.com/webhook"
}

Response

{
  "status": true,
  "process": 456
}

Errors

// 403 — Contacts empty or exceeds 1000
{
  "result": "failed",
  "errors": ["Too many contacts. Maximum is 1000"]
}

Check the processing status of a bulk email finder request.

Parameters

Response

{
  "status": true,
  "worker": {
    "id": 456,
    "status": "completed",
    "total": 2,
    "processed": 2
  }
}

Retrieve the results of a completed bulk email finder process.

Parameters

Response

{
  "status": true,
  "results": [
    {
      "id": "c1",
      "email": "john@apple.com",
      "result": "deliverable"
    },
    {
      "id": "c2",
      "email": "jane@google.com",
      "result": "deliverable"
    }
  ]
}

Submit up to 1,000 contacts for bulk phone number lookup.

Parameters

Request

POST /api/v1/phone/bulk?api_key=YOUR_API_KEY
Content-Type: application/json

{
  "items": [
    {
      "id": "p1",
      "full_name": "John Doe",
      "position": "CEO"
    },
    {
      "id": "p2",
      "full_name": "Jane Smith",
      "position": "CTO"
    }
  ],
  "webhook": "https://yourserver.com/webhook"
}

Response

{
  "status": true,
  "process": 789
}

Errors

// 403 — Items empty or exceeds 1000
{
  "result": "failed",
  "errors": ["Too many items. Maximum is 1000"]
}

Retrieve a paginated list of your customers.

Parameters

Response

{
  "result": [
    {
      "id": 1,
      "email": "customer@example.com",
      "active": true
    }
  ],
  "pages": 5,
  "page": 1
}

Create a new customer or update an existing one. If a customer with the given email already exists, the record is updated.

Parameters

Request

POST /api/v1/customer/create?api_key=YOUR_API_KEY
Content-Type: application/json

{
  "data": {
    "email": "newcustomer@example.com"
  }
}

Response

{
  "id": 42,
  "active": true
}

Errors

// 403 — Invalid API key
{
  "result": "failed",
  "errors": ["Wrong API key"]
}