OrbiSearch

https://orbisearch.com/docs
Admin
OrbiSearch is an email verification API that helps you confirm whether email addresses are...
Tokens:50,529
Snippets:331
Trust Score:5.3
Update:4 months ago
Show doc for...
Tokens:
Raw
### 401 Unauthorized cURL Example

Source: https://orbisearch.com/docs/api-reference/errors

Example of how to make a request with the required X-API-Key header using cURL.

```bash
curl --request GET \
  --url "https://api.orbisearch.com/v1/verify?email=jane.doe%40acme.com" \
  --header "X-API-Key: YOUR_API_KEY"
```

--------------------------------

### Bulk Verification Job Response Example

Source: https://orbisearch.com/docs/guides/bulk-verification

An example of the JSON response structure for a completed bulk verification job, detailing individual email verification statuses.

```json
{
  "job_id": "job_abc123",
  "status": "complete",
  "total_results": 500,
  "results": [
    {
      "email": "jane.doe@acme.com",
      "status": "safe",
      "substatus": "deliverable",
      "explanation": "The mailbox exists and is accepting mail.",
      "email_provider": "Google Workspace",
      "mx_record": "aspmx.l.google.com",
      "is_domain_catch_all": false,
      "is_secure_email_gateway": false,
      "is_disposable": false,
      "is_role_account": false,
      "is_free": false
    }
  ],
  "pending_retries": [],
  "retry_count": 0
}
```

--------------------------------

### Verify Email with Python

Source: https://orbisearch.com/docs/guides/single-verification

Use the requests library to send a GET request to the /v1/verify endpoint. Include the email address in params and the API key in headers. Parse the JSON response to get the status and substatus.

```python
import requests

response = requests.get(
    "https://api.orbisearch.com/v1/verify",
    params={"email": "jane.doe@acme.com"},
    headers={"X-API-Key": "YOUR_API_KEY"},
)

result = response.json()
print(result["status"], result["substatus"])
```

--------------------------------

### Verify Email with JavaScript

Source: https://orbisearch.com/docs/guides/single-verification

Use the fetch API to send a GET request to the /v1/verify endpoint. Include the email address in the URL and the API key in the headers. Parse the JSON response to get the status and substatus.

```javascript
const response = await fetch(
  "https://api.orbisearch.com/v1/verify?email=jane.doe%40acme.com",
  {
    headers: {
      "X-API-Key": "YOUR_API_KEY",
    },
  }
);

const result = await response.json();
console.log(result.status, result.substatus);
```

--------------------------------

### Complete Bulk Verification Workflow in JavaScript

Source: https://orbisearch.com/docs/guides/bulk-verification

Submits a list of emails for bulk verification, polls for completion, and then retrieves and prints the results using async/await. This example uses the Fetch API.

```javascript
const API_KEY = "YOUR_API_KEY";
const BASE_URL = "https://api.orbisearch.com";
const HEADERS = {
  "X-API-Key": API_KEY,
  "Content-Type": "application/json",
};

const emails = [
  "jane.doe@acme.com",
  "info@example.com",
  "user@domain.org",
  // ... more addresses
];

async function sleep(ms) {
  return new Promise((resolve) => setTimeout(resolve, ms));
}

async function runBulkVerification() {
  // Step 1: Submit the job
  const submitRes = await fetch(`${BASE_URL}/v1/bulk`, {
    method: "POST",
    headers: HEADERS,
    body: JSON.stringify(emails),
  });
  const job = await submitRes.json();
  const { job_id } = job;
  console.log(`Job submitted: ${job_id} (${job.total_emails} emails, estimated cost: ${job.estimated_cost} credits)`);

  // Step 2: Poll until complete
  while (true) {
    const statusRes = await fetch(`${BASE_URL}/v1/bulk/${job_id}`, {
      headers: HEADERS,
    });
    const status = await statusRes.json();
    console.log(`Status: ${status.status} — ${status.emails_processed}/${status.total_emails} processed`);

    if (status.status === "complete") break;
    if (status.status === "failed") throw new Error(`Job ${job_id} failed.`);

    await sleep(15000); // poll every 15 seconds
  }

  // Step 3: Retrieve results
  const resultsRes = await fetch(`${BASE_URL}/v1/bulk/${job_id}/results`, {
    headers: HEADERS,
  });
  const data = await resultsRes.json();

  for (const result of data.results) {
    console.log(`${result.email}: ${result.status} (${result.substatus})`);
  }
}

runBulkVerification().catch(console.error);
```

--------------------------------

### Data Enrichment Example

Source: https://orbisearch.com/docs/guides/handling-results

This JSON object shows an example of data enrichment, including status, substatus, and boolean flags for an email address. It's useful for analytics and building datasets.

```json
{
  "email": "info@company.com",
  "status": "risky",
  "substatus": "role_account",
  "is_role_account": true,
  "is_free": false
}
```

--------------------------------

### Verify Email with JavaScript (fetch)

Source: https://orbisearch.com/docs/quickstart

This JavaScript example uses the fetch API to verify an email address. It logs the status and substatus from the response.

```javascript
const response = await fetch(
    "https://api.orbisearch.com/v1/verify?email=jane.doe%40acme.com",
    {
      headers: {
        "X-API-Key": "YOUR_API_KEY"
      }
    }
  );

  const result = await response.json();
  console.log(result.status);     // safe | risky | invalid | unknown
  console.log(result.substatus);  // e.g. deliverable, catch_all, mailbox_not_found
```

--------------------------------

### 400 Bad Request Example

Source: https://orbisearch.com/docs/api-reference/errors

Returned when the request is structurally valid but semantically rejected. Inspect the 'detail' message to identify the specific issue.

```json
{
  "detail": "Email list cannot be empty"
}
```

--------------------------------

### Email Lookup Request Example

Source: https://orbisearch.com/docs/api-reference/email-lookup

Use this snippet to find an email address by providing the first name, last name, and domain. The timeout parameter is optional and defaults to 90 seconds.

```yaml
POST /v1/email-lookup
openapi: 3.1.0
info:
  title: OrbiSearch Public API
  version: 1.0.0
  description: >-
    Email verification API for developers and agents. [Get your API key
    →](https://orbisearch.com/dashboard/api-keys)
  contact:
    name: Get API Key
    url: https://orbisearch.com/dashboard/api-keys
servers:
  - url: https://api.orbisearch.com
    description: OrbiSearch Public API
security:
  - ApiKeyAuth: []
paths:
  /v1/email-lookup:
    post:
      tags:
        - Public API v1
      summary: Find Email by Name and Domain
      description: >-
        Find a person's deliverable email address from their first name, last
        name,

        and company domain. Returns the discovered email together with the same

        enrichment fields as `/v1/verify` (`status`, `substatus`, `explanation`,

        `email_provider`, `mx_record`, `is_domain_catch_all`,

        `is_secure_email_gateway`, `is_disposable`, `is_role_account`,
        `is_free`).


        Timeout parameter (optional):

        - Range: 30-120 seconds

        - Default: 90 seconds


        Costs 1 credit per returned response. Refunds are issued only when

        OrbiSearch infrastructure cannot complete the request (HTTP 502).

        Every returned response is charged. Results are cached for 24 hours;

        identical queries within that window are returned from cache at no

        credit cost.


        Rate limit: 20 requests per second per API key, shared with `/v1/verify`

        and `/v1/bulk`. For verifying a list of email addresses you already
        have,

        use the asynchronous `/v1/bulk` endpoint instead.
      operationId: lookup_email_v1_email_lookup_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Body_lookup_email_v1_email_lookup_post'
            example:
              first_name: Jane
              last_name: Doe
              domain: acme.com
              timeout: 90
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EmailLookupResponse'
              example:
                email: jane.doe@acme.com
                status: safe
                substatus: deliverable
                explanation: Safe to email. The mailbox exists and is deliverable.
                email_provider: Google Workspace
                mx_record: aspmx.l.google.com
                is_domain_catch_all: false
                is_secure_email_gateway: false
                is_disposable: false
                is_role_account: false
                is_free: false
                credits_consumed: 1
                first_name: Jane
                last_name: Doe
                domain: acme.com
                confidence: 99
        '401':
          description: Invalid or missing API key
          content:
            application/json:
              example:
                detail: API key required in X-API-Key header
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
        '403':
          description: Insufficient credits
          content:
            application/json:
              example:
                detail: Insufficient credits. You have 0.15 credits but need 0.2.
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
        '422':
          description: Invalid request parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
              example:
                detail: 'Invalid request body field ''0'': Input should be a valid string'
        '429':
          description: Rate limit exceeded
          headers:
            Retry-After:
              description: >-
                Seconds the client should wait before retrying. Currently always
                1; future versions may return a longer back-off.
              schema:
                type: integer
                examples:
                  - 1
          content:
            application/json:
              example:
                detail: >-
                  Rate limit exceeded. Maximum 20 requests per second per API
                  key. Contact us to discuss higher limits.
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
        '503':
          description: Email-lookup service not configured
          content:
            application/json:
              schema:

```

--------------------------------

### Complete Bulk Verification Workflow in Python

Source: https://orbisearch.com/docs/guides/bulk-verification

Submits a list of emails for bulk verification, polls for completion, and then retrieves and prints the results. Ensure you have the 'requests' library installed.

```python
import time
import requests

API_KEY = "YOUR_API_KEY"
BASE_URL = "https://api.orbisearch.com"
HEADERS = {"X-API-Key": API_KEY, "Content-Type": "application/json"}

emails = [
    "jane.doe@acme.com",
    "info@example.com",
    "user@domain.org",
    # ... more addresses
]

# Step 1: Submit the job
submit_response = requests.post(
    f"{BASE_URL}/v1/bulk",
    headers=HEADERS,
    json=emails,
)
submit_response.raise_for_status()
job = submit_response.json()
job_id = job["job_id"]
print(f"Job submitted: {job_id} ({job['total_emails']} emails, estimated cost: {job['estimated_cost']} credits)")

# Step 2: Poll until complete
while True:
    status_response = requests.get(
        f"{BASE_URL}/v1/bulk/{job_id}",
        headers=HEADERS,
    )
    status_response.raise_for_status()
    status = status_response.json()

    print(f"Status: {status['status']} — {status['emails_processed']}/{status['total_emails']} processed")

    if status["status"] == "complete":
        break
    elif status["status"] == "failed":
        raise RuntimeError(f"Job {job_id} failed.")

    time.sleep(15)  # poll every 15 seconds

# Step 3: Retrieve results
results_response = requests.get(
    f"{BASE_URL}/v1/bulk/{job_id}/results",
    headers=HEADERS,
)
results_response.raise_for_status()
data = results_response.json()

for result in data["results"]:
    print(f"{result['email']}: {result['status']} ({result['substatus']})")
```

--------------------------------

### Find Email with JavaScript

Source: https://orbisearch.com/docs/guides/email-lookup

This JavaScript example shows how to use the fetch API to perform an email lookup. It constructs the request with the necessary headers and JSON body, then logs the email and status from the response.

```javascript
const response = await fetch(
  "https://api.orbisearch.com/v1/email-lookup",
  {
    method: "POST",
    headers: {
      "X-API-Key": "YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      first_name: "Jane",
      last_name: "Doe",
      domain: "acme.com",
    }),
  }
);

const result = await response.json();
console.log(result.email, result.status);
```

--------------------------------

### cURL Request for Bulk Job Status

Source: https://orbisearch.com/docs/api-reference/bulk-status

Example cURL command to fetch the status of a bulk job. Replace 'YOUR_API_KEY' with your actual API key.

```cURL
curl --request GET \
  --url 'https://api.orbisearch.com/v1/bulk/123e4567-e89b-12d3-a456-426614174000' \
  --header 'X-API-Key: YOUR_API_KEY'
```

--------------------------------

### POST /v1/bulk-lookup

Source: https://orbisearch.com/docs/api-reference/bulk-lookup-submit

Submit a list of (first_name, last_name, domain) tuples for asynchronous bulk email lookup. The API returns a job_id immediately. You can then poll GET /v1/bulk-lookup/{job_id} until the status reaches 'complete', and fetch results via GET /v1/bulk-lookup/{job_id}/results.

```APIDOC
## POST /v1/bulk-lookup

### Description
Submit a list of (first_name, last_name, domain) tuples for asynchronous bulk email lookup. Rows are deduplicated (case-insensitive) before billing; credits are deducted upfront at 1 credit per unique row.

Returns a `job_id` immediately. Poll `GET /v1/bulk-lookup/{job_id}` until `status` reaches `complete`, then fetch results via `GET /v1/bulk-lookup/{job_id}/results`.

Every returned row is charged. Refunds are issued only when OrbiSearch infrastructure cannot accept or process the submission itself (the upfront charge is reversed in that case).

### Method
POST

### Endpoint
/v1/bulk-lookup

### Parameters
#### Request Body
- **input** (array) - Required - List of (first_name, last_name, domain) tuples to look up. Duplicate tuples are deduplicated before billing. Maximum 10,000 rows per submission.
  - **domain** (string) - Required - Domain name.
  - **first_name** (string) - Required - First name.
  - **last_name** (string) - Required - Last name.

### Request Example
```json
{
  "input": [
    {
      "domain": "acme.com",
      "first_name": "Jane",
      "last_name": "Doe"
    },
    {
      "domain": "bigcorp.io",
      "first_name": "John"
    }
  ]
}
```

### Response
#### Success Response (202)
- **job_id** (string) - The ID of the submitted job.

#### Response Example
```json
{
  "job_id": "a1b2c3d4-e5f6-7890-1234-567890abcdef"
}
```

### Error Handling
- **401**: Invalid or missing API key.
- **403**: Insufficient credits.
- **422**: Invalid request parameters.
- **429**: Rate limit exceeded. (20 requests per second per API key, shared with `/v1/verify`, `/v1/bulk`, and `/v1/email-lookup`)
- **503**: Email-lookup service not configured.
```

--------------------------------

### Bulk Verification Job Status - In Progress

Source: https://orbisearch.com/docs/guides/bulk-verification

An example response while a job is actively being processed. It shows the job ID, current status, total emails to process, and the number of emails already processed.

```json
{
  "job_id": "job_abc123",
  "status": "in_progress",
  "total_emails": 500,
  "emails_processed": 243,
  "retry_status": "pending",
  "submitted_at": "2024-01-15T10:00:00Z",
  "completed_at": null
}
```

--------------------------------

### Check Credit Balance via API

Source: https://orbisearch.com/docs/concepts/credits

Retrieve your current credit balance and user ID by making a GET request to the /v1/credits endpoint. Ensure you include your API key in the request headers.

```bash
curl "https://api.orbisearch.com/v1/credits" \
  -H "X-API-Key: YOUR_API_KEY"
```

--------------------------------

### Verify Email with cURL

Source: https://orbisearch.com/docs/guides/single-verification

Send a GET request to the /v1/verify endpoint with the email address as a query parameter and your API key in the header.

```bash
curl --request GET \
  --url "https://api.orbisearch.com/v1/verify?email=jane.doe@acme.com" \
  --header "X-API-Key: YOUR_API_KEY"
```

--------------------------------

### Get Credits

Source: https://orbisearch.com/docs/api-reference/credits

Retrieve your current OrbiSearch credit balance. Each email verification costs 0.2 credits; cached results within 24 hours are free.

```APIDOC
## GET /v1/credits

### Description
Get your current credit balance. Returns your available credits for API usage.

### Method
GET

### Endpoint
/v1/credits

### Parameters
#### Query Parameters
None

#### Request Body
None

### Request Example
None

### Response
#### Success Response (200)
- **credits** (number) - Current available credits.
- **user_id** (string) - User identifier.

#### Response Example
```json
{
  "credits": 1250.5,
  "user_id": "user_2NXKxQjF8KhZHwH3JqRpYXxV"
}
```

#### Error Response (401)
- **detail** (string) - API key required in X-API-Key header

#### Error Response (429)
- **detail** (string) - Rate limit exceeded. Maximum 20 requests per second per API key. Contact us to discuss higher limits.

### Headers
#### Request Headers
- **X-API-Key** (string) - Required - Your OrbiSearch API key.
```

--------------------------------

### Successful Email Lookup Response

Source: https://orbisearch.com/docs/api-reference/email-lookup

This is an example of a successful response when an email address is found. It includes the email, status, and various enrichment fields.

```json
{
  "email": "jane.doe@acme.com",
  "status": "safe",
  "substatus": "deliverable",
  "explanation": "Safe to email. The mailbox exists and is deliverable.",
  "email_provider": "Google Workspace",
  "mx_record": "aspmx.l.google.com",
  "is_domain_catch_all": false,
  "is_secure_email_gateway": false,
  "is_disposable": false,
  "is_role_account": false,
  "is_free": false,
  "credits_consumed": 1,
  "first_name": "Jane",
  "last_name": "Doe",
  "domain": "acme.com",
  "confidence": 99
}
```

--------------------------------

### Verify Email Address

Source: https://orbisearch.com/docs/guides/single-verification

Send a GET request to /v1/verify with the email address as a query parameter and your API key in the X-API-Key header to check email deliverability.

```APIDOC
## GET /v1/verify

### Description
Checks if a single email address is deliverable in real-time. Results are cached for 24 hours.

### Method
GET

### Endpoint
/v1/verify

### Parameters
#### Query Parameters
- **email** (string) - Required - The email address to verify.

#### Headers
- **X-API-Key** (string) - Required - Your OrbiSearch API key.

### Request Example
```bash
curl --request GET \
  --url "https://api.orbisearch.com/v1/verify?email=jane.doe@acme.com" \
  --header "X-API-Key: YOUR_API_KEY"
```

### Response
#### Success Response (200)
- **email** (string) - The verified email address.
- **status** (string) - The deliverability status (e.g., "safe", "risky", "invalid").
- **substatus** (string) - A more specific deliverability status (e.g., "deliverable", "undeliverable").
- **explanation** (string) - An explanation of the status and substatus.
- **email_provider** (string) - The email service provider (e.g., "Google Workspace").
- **mx_record** (string) - The Mail Exchanger record for the domain.
- **is_domain_catch_all** (boolean) - Indicates if the domain has a catch-all address.
- **is_secure_email_gateway** (boolean) - Indicates if a secure email gateway is in use.
- **is_disposable** (boolean) - Indicates if the email address is from a disposable email provider.
- **is_role_account** (boolean) - Indicates if the email address is a role account (e.g., "support@").
- **is_free** (boolean) - Indicates if the email address is from a free email provider (e.g., "gmail.com").

#### Response Example
```json
{
  "email": "jane.doe@acme.com",
  "status": "safe",
  "substatus": "deliverable",
  "explanation": "The mailbox exists and is accepting mail.",
  "email_provider": "Google Workspace",
  "mx_record": "aspmx.l.google.com",
  "is_domain_catch_all": false,
  "is_secure_email_gateway": false,
  "is_disposable": false,
  "is_role_account": false,
  "is_free": false
}
```
```

--------------------------------

### OpenAPI Specification for Verify Email

Source: https://orbisearch.com/docs/api-reference/verify-email

This OpenAPI 3.1.0 specification defines the GET /v1/verify endpoint for single email verification. It includes request parameters, response schemas, and example error responses.

```yaml
GET /v1/verify
openapi: 3.1.0
info:
  title: OrbiSearch Public API
  version: 1.0.0
  description: >-
    Email verification API for developers and agents. [Get your API key
    →](https://orbisearch.com/dashboard/api-keys)
  contact:
    name: Get API Key
    url: https://orbisearch.com/dashboard/api-keys
servers:
  - url: https://api.orbisearch.com
    description: OrbiSearch Public API
security:
  - ApiKeyAuth: []
paths:
  /v1/verify:
    get:
      tags:
        - Public API v1
      summary: Verify Single Email
      description: >-
        Verify a single email address in real-time.


        Returns verification results immediately. Costs 0.2 credits per
        verification.

        Results are cached for 24 hours - subsequent requests for the same email
        return

        cached results at no additional cost.


        Timeout parameter (optional):

        - Range: 3-90 seconds

        - Default: 70 seconds


        Rate limit: 20 requests per second per API key. Contact us to discuss
        higher limits.


        For bulk verification, we recommend using the /v1/bulk endpoint where
        possible.
      operationId: verify_single_email_v1_verify_get
      parameters:
        - name: email
          in: query
          required: true
          schema:
            type: string
            maxLength: 320
            description: Email address to verify.
            examples:
              - jane.doe@acme.com
            title: Email
            x-default: jane.doe@acme.com
          description: Email address to verify.
          example: jane.doe@acme.com
        - name: timeout
          in: query
          required: false
          schema:
            type: integer
            maximum: 90
            minimum: 3
            description: Timeout in seconds (3-90).
            examples:
              - 70
            default: 70
            title: Timeout
          description: Timeout in seconds (3-90).
          example: 70
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EmailVerificationResponse'
              example:
                email: jane.doe@acme.com
                status: safe
                substatus: deliverable
                explanation: Safe to email. The mailbox exists and is deliverable.
                email_provider: Google Workspace
                mx_record: aspmx.l.google.com
                is_domain_catch_all: false
                is_secure_email_gateway: false
                is_disposable: false
                is_role_account: false
                is_free: false
                confidence: 99
        '401':
          description: Invalid or missing API key
          content:
            application/json:
              example: { "detail": "API key required in X-API-Key header" }
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
        '403':
          description: Insufficient credits
          content:
            application/json:
              example: { "detail": "Insufficient credits. You have 0.15 credits but need 0.2." }
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
        '422':
          description: Invalid request parameters
          content:
            application/json:
              example: { "detail": "Missing required query parameter: email" }
              schema:

```

--------------------------------

### OpenAPI Specification for Bulk Job Results

Source: https://orbisearch.com/docs/api-reference/bulk-results

This OpenAPI 3.1.0 specification defines the GET /v1/bulk/{job_id}/results endpoint for retrieving bulk job verification results. It includes request parameters, response schemas, and example responses for various scenarios.

```yaml
openapi: 3.1.0
info:
  title: OrbiSearch Public API
  version: 1.0.0
  description: >-
    Email verification API for developers and agents. [Get your API key
    →](https://orbisearch.com/dashboard/api-keys)
  contact:
    name: Get API Key
    url: https://orbisearch.com/dashboard/api-keys
servers:
  - url: https://api.orbisearch.com
    description: OrbiSearch Public API
security:
  - ApiKeyAuth: []
paths:
  /v1/bulk/{job_id}/results:
    get:
      tags:
        - Public API v1
      summary: Get Bulk Job Results
      description: Get the results of a completed bulk verification job.
      operationId: get_bulk_job_results_v1_bulk__job_id__results_get
      parameters:
        - name: job_id
          in: path
          required: true
          schema:
            type: string
            title: Job Id
            x-default: 123e4567-e89b-12d3-a456-426614174000
          example: 123e4567-e89b-12d3-a456-426614174000
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BulkJobResultsResponse'
              example:
                job_id: 123e4567-e89b-12d3-a456-426614174000
                status: complete
                total_results: 500
                results:
                  - email: jane.doe@acme.com
                    status: safe
                    substatus: deliverable
                    explanation: Safe to email. The mailbox exists and is deliverable.
                    email_provider: Google Workspace
                    mx_record: aspmx.l.google.com
                    is_domain_catch_all: false
                    is_secure_email_gateway: false
                    is_disposable: false
                    is_role_account: false
                    is_free: false
                    confidence: 99
                pending_retries: []
                retry_count: 0
        '400':
          description: Invalid request parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
              example:
                detail: Email list cannot be empty
        '401':
          description: Invalid or missing API key
          content:
            application/json:
              example:
                detail: API key required in X-API-Key header
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
        '404':
          description: Job not found or does not belong to this API key
          content:
            application/json:
              example:
                detail: Job not found
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
        '409':
          description: Job has not completed yet
          content:
            application/json:
              example:
                detail: 'Job is not completed yet. Current status: in_progress'
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
        '422':
          description: Invalid request parameters
          content:
            application/json:
              example:
                detail: 'Missing required query parameter: email'
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
        '429':
          description: Rate limit exceeded
          headers:
            Retry-After:
              description: >-

```

--------------------------------

### Complete Bulk Lookup Example in Python

Source: https://orbisearch.com/docs/guides/bulk-lookup

This script submits a list of individuals to the OrbiSearch Bulk Lookup API, polls for job completion, and then retrieves and prints the results. Ensure you replace 'YOUR_API_KEY' with your actual API key. The script handles job submission, status polling with a 15-second delay, and result pagination.

```Python
import time
import requests

API_KEY = "YOUR_API_KEY"
BASE_URL = "https://api.orbisearch.com"
HEADERS = {"X-API-Key": API_KEY, "Content-Type": "application/json"}

people = [
    {"first_name": "Jane",  "last_name": "Doe",   "domain": "acme.com"},
    {"first_name": "John",  "last_name": "Smith", "domain": "bigcorp.io"},
    {"first_name": "Priya", "last_name": "Patel", "domain": "studio.xyz"},
    # ... up to 10,000 rows
]

# 1. Submit
submit = requests.post(f"{BASE_URL}/v1/bulk-lookup", headers=HEADERS, json={"input": people})
submit.raise_for_status()
job = submit.json()
job_id = job["job_id"]
print(f"Submitted: {job_id} ({job['total_rows']} unique rows, {job['credits_consumed']} credits charged)")

# 2. Poll until complete
while True:
    status = requests.get(f"{BASE_URL}/v1/bulk-lookup/{job_id}", headers=HEADERS).json()
    print(f"  {status['status']}: {status['total_processed']}/{status['total_rows']}")
    if status["status"] == "completed":
        break
    time.sleep(15)

# 3. Page through results
offset = 0
while True:
    page = requests.get(
        f"{BASE_URL}/v1/bulk-lookup/{job_id}/results",
        params={"limit": 500, "offset": offset},
        headers=HEADERS,
    ).json()
    if not page["results"]:
        break
    for row in page["results"]:
        if row["status"] == "safe":
            print(f"{row['first_name']} {row['last_name']} → {row['email']}")
        else:
            print(f"{row['first_name']} {row['last_name']} → not found")
    offset += len(page["results"])
```

--------------------------------

### EmailVerificationResponse Schema

Source: https://orbisearch.com/docs/api-reference/response-schema

The EmailVerificationResponse object is returned by both the single verification endpoint (GET /v1/verify) and the bulk results endpoint (GET /v1/bulk/{job_id}/results). It provides comprehensive details about the email verification outcome.

```APIDOC
## EmailVerificationResponse Schema

### Description
This schema describes the structure of the response object returned by email verification endpoints. It includes details about the verified email address, its verification status, and various enrichment data.

### Fields

- **email** (string) - The email address that was verified. Reflects the address from your request.
- **status** (string) - Overall verification result. One of `safe`, `risky`, `invalid`, or `unknown`.
- **substatus** (string) - The specific reason behind the status. Provides more granular detail than `status` alone.
- **explanation** (string) - A plain-English sentence describing the verification outcome. Suitable for logs, dashboards, and debugging.
- **email_provider** (string) - The email service provider associated with the address domain. Examples: `Google Workspace`, `Gmail`, `Microsoft Outlook`.
- **mx_record** (string | null) - The main mail server the domain uses to receive email. `null` if the domain has no mail server configured.
- **is_domain_catch_all** (boolean | null) - `true` if the domain accepts mail for any username (catch-all). `null` if we could not determine whether the domain is catch-all.
- **is_secure_email_gateway** (boolean) - `true` if the domain is protected by a secure email gateway.
- **is_disposable** (boolean | null) - `true` if the address belongs to a known temporary or disposable email service. `false` if it is not. `null` if the provider could not be determined.
- **is_role_account** (boolean | null) - `true` if the address is a generic role-based account such as `info@`, `support@`, or `sales@`. `null` if it could not be determined.
- **is_free** (boolean | null) - `true` if the address is from a free consumer email provider. `null` if the provider could not be determined.
- **confidence** (integer | null) - How confident we are in the result, on a 0–100 scale. Returned for `safe` results only. `null` for `risky`, `invalid`, and `unknown` results.
```

--------------------------------

### Get Bulk Lookup Status

Source: https://orbisearch.com/docs/api-reference/bulk-lookup-status

Check the status and progress of a bulk lookup job. Returns the current status (running or completed), per-outcome counts, and row totals. Poll this until status=completed, then fetch results via GET /v1/bulk-lookup/{job_id}/results.

```APIDOC
## GET /v1/bulk-lookup/{job_id}

### Description
Check the status and progress of a bulk lookup job. Returns the current `status` (`running` or `completed`), per-outcome counts, and row totals.

Poll this until `status=completed`, then fetch results via `GET /v1/bulk-lookup/{job_id}/results`.

All rows are charged per the bulk-lookup billing policy: refunds happen only when OrbiSearch infrastructure cannot accept the submission itself, not on a per-row outcome basis.

### Method
GET

### Endpoint
/v1/bulk-lookup/{job_id}

### Parameters
#### Path Parameters
- **job_id** (string) - Required - Unique job identifier.

### Responses
#### Success Response (200)
- **job_id** (string) - Unique job identifier.
- **status** (string) - Job status: running (still processing) or completed (all rows done).
- **total_rows** (integer) - Total rows submitted.
- **total_processed** (integer) - Rows processed so far.
- **summary** (object) - Per-outcome counts.
- **created_at** (string) - Job submission timestamp (UTC).
- **finished_at** (string or null) - Job completion timestamp (UTC).

#### Error Responses
- **401** - Invalid or missing API key
- **404** - Job not found or does not belong to this API key
- **422** - Invalid request parameters
- **429** - Rate limit exceeded
- **503** - Email-lookup service not configured
```

--------------------------------

### Get Bulk Job Results

Source: https://orbisearch.com/docs/api-reference/bulk-results

Retrieves the verification results for a specified bulk job. This endpoint can be called before the job is fully complete to get partial results. The response includes the job status, total results count, and a list of individual email verification results.

```APIDOC
## GET /v1/bulk/{job_id}/results

### Description
Get the results of a completed bulk verification job. Returns an array of EmailVerificationResponse objects for every email processed so far.

### Method
GET

### Endpoint
/v1/bulk/{job_id}/results

### Parameters
#### Path Parameters
- **job_id** (string) - Required - The ID of the bulk job.

### Request Example
(No request body for GET request)

### Response
#### Success Response (200)
- **job_id** (string) - The ID of the bulk job.
- **status** (string) - The current status of the job (e.g., "complete", "in_progress").
- **total_results** (integer) - The number of results in the current response.
- **results** (array) - An array of EmailVerificationResponse objects.
  - **email** (string) - The email address that was verified.
  - **status** (string) - The verification status (e.g., "safe", "risky", "unknown").
  - **substatus** (string) - A more specific status (e.g., "deliverable", "undeliverable").
  - **explanation** (string) - A human-readable explanation of the result.
  - **email_provider** (string) - The email provider of the address.
  - **mx_record** (string) - The MX record for the email's domain.
  - **is_domain_catch_all** (boolean) - Indicates if the domain has a catch-all address.
  - **is_secure_email_gateway** (boolean) - Indicates if the email is behind a secure gateway.
  - **is_disposable** (boolean) - Indicates if the email address is disposable.
  - **is_role_account** (boolean) - Indicates if the email is a role account (e.g., admin@).
  - **is_free** (boolean) - Indicates if the email is from a free email provider.
  - **confidence** (integer) - The confidence score of the verification result.
- **pending_retries** (array) - An array of email addresses still queued for retry.
- **retry_count** (integer) - The number of retries performed for the job.

#### Response Example
```json
{
  "job_id": "123e4567-e89b-12d3-a456-426614174000",
  "status": "complete",
  "total_results": 500,
  "results": [
    {
      "email": "jane.doe@acme.com",
      "status": "safe",
      "substatus": "deliverable",
      "explanation": "Safe to email. The mailbox exists and is deliverable.",
      "email_provider": "Google Workspace",
      "mx_record": "aspmx.l.google.com",
      "is_domain_catch_all": false,
      "is_secure_email_gateway": false,
      "is_disposable": false,
      "is_role_account": false,
      "is_free": false,
      "confidence": 99
    }
  ],
  "pending_retries": [],
  "retry_count": 0
}
```

### Error Handling
- **400 Bad Request**: Invalid request parameters.
- **401 Unauthorized**: Invalid or missing API key.
- **404 Not Found**: Job not found or does not belong to this API key.
- **409 Conflict**: Job has not completed yet.
- **422 Unprocessable Entity**: Invalid request parameters.
- **429 Too Many Requests**: Rate limit exceeded.
```

--------------------------------

### Get Bulk Lookup Job Status

Source: https://orbisearch.com/docs/api-reference/bulk-lookup-status

Use this endpoint to check the status and progress of a bulk lookup job. Poll this endpoint until the status is 'completed', then fetch results via `GET /v1/bulk-lookup/{job_id}/results`. All rows are charged per the bulk-lookup billing policy.

```yaml
GET /v1/bulk-lookup/{job_id}
openapi: 3.1.0
info:
  title: OrbiSearch Public API
  version: 1.0.0
  description: >-
    Email verification API for developers and agents. [Get your API key
    →](https://orbisearch.com/dashboard/api-keys)
  contact:
    name: Get API Key
    url: https://orbisearch.com/dashboard/api-keys
servers:
  - url: https://api.orbisearch.com
    description: OrbiSearch Public API
security:
  - ApiKeyAuth: []
paths:
  /v1/bulk-lookup/{job_id}:
    get:
      tags:
        - Public API v1
      summary: Get Bulk Lookup Status
      description: |- 
        Check the status and progress of a bulk lookup job. Returns the current
        `status` (`running` or `completed`), per-outcome counts, and row totals.

        Poll this until `status=completed`, then fetch results via
        `GET /v1/bulk-lookup/{job_id}/results`.

        All rows are charged per the bulk-lookup billing policy: refunds happen
        only when OrbiSearch infrastructure cannot accept the submission itself,
        not on a per-row outcome basis.
      operationId: get_bulk_lookup_status_v1_bulk_lookup__job_id__get
      parameters:
        - name: job_id
          in: path
          required: true
          schema:
            type: string
            title: Job Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BulkLookupStatusResponse'
        '401':
          description: Invalid or missing API key
          content:
            application/json:
              example:
                detail: API key required in X-API-Key header
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
        '404':
          description: Job not found or does not belong to this API key
          content:
            application/json:
              example:
                detail: Job not found
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
        '422':
          description: Invalid request parameters
          content:
            application/json:
              example:
                detail: 'Missing required query parameter: email'
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
        '429':
          description: Rate limit exceeded
          headers:
            Retry-After:
              description: >-
                Seconds the client should wait before retrying. Currently always
                1; future versions may return a longer back-off.
              schema:
                type: integer
                examples:
                  - 1
          content:
            application/json:
              example:
                detail: >-
                  Rate limit exceeded. Maximum 20 requests per second per API
                  key. Contact us to discuss higher limits.
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
        '503':
          description: Email-lookup service not configured
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
              example:
                detail: Email lookup is not available in this environment
      security:
        - ApiKeyAuth: []
components:
  schemas:
    BulkLookupStatusResponse:
      properties:
        job_id:
          type: string
          format: uuid
          title: Job Id
          description: Unique job identifier.
          examples:
            - 123e4567-e89b-12d3-a456-426614174000
        status:
          type: string
          enum:
            - running
            - completed
          title: Status
          description: 'Job status: running (still processing) or completed (all rows done).'
          examples:
            - running
        total_rows:
          type: integer
          title: Total Rows
          description: Total rows submitted.
          examples:
            - 500
        total_processed:
          type: integer
          title: Total Processed
          description: Rows processed so far.
          examples:
            - 237
        summary:
          $ref: '#/components/schemas/BulkLookupSummary'
          description: Per-outcome counts.
        created_at:
          type: string
          title: Created At
          description: Job submission timestamp (UTC).
          examples:
            - '2026-04-21T14:30:00Z'
        finished_at:
          anyOf:
            - type: string
            - type: 'null'
          title: Finished At

```

--------------------------------

### Verify Email with Python

Source: https://orbisearch.com/docs/quickstart

This Python script demonstrates how to use the requests library to verify an email address. It prints the status and substatus from the JSON response.

```python
import requests

response = requests.get(
    "https://api.orbisearch.com/v1/verify",
    params={"email": "jane.doe@acme.com"},
    headers={"X-API-Key": "YOUR_API_KEY"}
)

result = response.json()
print(result["status"])      # safe | risky | invalid | unknown
print(result["substatus"])   # e.g. deliverable, catch_all, mailbox_not_found
```

--------------------------------

### 409 Conflict — job not ready

Source: https://orbisearch.com/docs/api-reference/errors

Returned by GET /v1/bulk/{job_id}/results when the job hasn't finished yet.

```APIDOC
## 409 Conflict — job not ready

### Description
Returned by `GET /v1/bulk/{job_id}/results` when the job hasn't finished yet. The `detail` includes the job's current status.

### Response Example
```json
{
  "detail": "Job is not completed yet. Current status: in_progress"
}
```

### How to fix
Poll `GET /v1/bulk/{job_id}` until `status` is `complete` (or `partial_complete_retrying` if you want partial results) before fetching results. Partial results can also be fetched directly — see [bulk results](/api-reference/bulk-results) for partial-fetch behaviour.
```
Tokens:
Raw