GoodVerify API

https://goodverify.dev/api/v1/
Admin
GoodVerify is a unified API for email, phone, and address verification with real-time validation,...
Tokens:6,937
Snippets:61
Trust Score:2.5
Update:4 months ago
Show doc for...
Tokens:
Raw
### Get Usage

Source: https://goodverify.dev/api/v1/docs

Retrieves information about the API usage, such as credits consumed or limits reached.

```APIDOC
## GET /api/v1/usage

### Description
Get usage

### Method
GET

### Endpoint
/api/v1/usage
```

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

### Get Account Usage

Source: https://goodverify.dev/api/v1/openapi

Retrieves information about the current account's plan, usage, and rate limits.

```APIDOC
## GET /usage

### Description
Retrieves information about the current account's plan, usage, and rate limits.

### Method
GET

### Endpoint
/usage

### Response
#### Success Response (200)
- **plan** (string) - The current account plan name.
- **billing_period** (object) - Information about the current billing period.
- **usage** (object) - Verification usage in the current period.
- **rate_limit** (object) - Rate limiting information.

#### Response Example
```json
{
  "plan": "premium",
  "billing_period": {
    "start_date": "2024-01-01T00:00:00Z",
    "end_date": "2024-01-31T23:59:59Z"
  },
  "usage": {
    "verifications_used": 5000,
    "verifications_limit": 10000
  },
  "rate_limit": {
    "requests_per_minute": 100
  }
}
```
```

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

### Get Account Usage

Source: https://goodverify.dev/api/v1/openapi

Retrieves API usage statistics for the current billing period, including credit balance and limits.

```APIDOC
## GET /usage

### Description
Retrieves API usage statistics for the current billing period.

### Method
GET

### Endpoint
/usage

### Response
#### Success Response (200)
- **plan** (string) - Current subscription plan.
- **billing_period** (object) - Current billing period boundaries.
  - **start** (string) - Start of the billing period (ISO 8601 UTC).
  - **end** (string) - End of the billing period (ISO 8601 UTC).
- **credits** (object) - Credit balance information.
  - **balance** (integer) - Current credit balance. Minimum: 0.
  - **used_this_period** (integer) - Credits used in the current billing period. Minimum: 0.
- **usage** (object) - Usage details.
  - **verifications_limit** (integer) - Total verifications allowed in the period.
  - **verifications_used** (integer) - Verifications used in the current period.
- **rate_limit** (object) - Rate limit information.
  - **requests_per_minute** (integer) - Maximum requests allowed per minute.
```

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

### Get Usage Statistics

Source: https://goodverify.dev/api/v1/openapi

Retrieves usage statistics for the current billing period. Requires authentication.

```APIDOC
## GET /api/v1/usage

### Description
Returns usage statistics for the current billing period.

### Method
GET

### Endpoint
/api/v1/usage

### Parameters
No parameters.

### Response
#### Success Response (200)
- **UsageResponse** (object) - Contains the usage data.

#### Error Response
- **401** - Authentication required
```

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

### Get batch job results

Source: https://goodverify.dev/api/v1/openapi

Returns paginated results for a batch job. Results can be filtered by status and can be downloaded in CSV format using the `format=csv` query parameter.

```APIDOC
## GET /api/v1/batch/{id}/results

### Description
Returns paginated results for a batch job. Use `format=csv` for CSV download.
Use `status` parameter to filter by result status.

### Method
GET

### Endpoint
/api/v1/batch/{id}/results

### Parameters
#### Path Parameters
- **id** (string) - Required - Batch job ID

#### Query Parameters
- **page** (integer) - Optional - Page number (default: 1)
- **per_page** (integer) - Optional - Items per page (default: 25)
- **format** (string) - Optional - If set to `csv`, returns results in CSV format.
- **status** (string) - Optional - Filters results by status.
```

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

### Get Batch Results

Source: https://goodverify.dev/api/v1/docs

Retrieves the results of a completed batch verification job using its ID.

```APIDOC
## GET /api/v1/batch/{id}/results

### Description
Get batch results

### Method
GET

### Endpoint
/api/v1/batch/{id}/results

### Parameters
#### Path Parameters
- **id** (string) - Required - The ID of the batch job
```

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

### Get Batch Results

Source: https://goodverify.dev/api/v1/openapi

Retrieves the results of a batch verification job. Supports filtering by status and pagination. The response format can be JSON or CSV.

```APIDOC
## GET /api/v1/batch/{batch_id}/results

### Description
Retrieves the results of a batch verification job.

### Method
GET

### Endpoint
/api/v1/batch/{batch_id}/results

### Parameters
#### Query Parameters
- **per_page** (integer) - Optional - Number of results per page (max 100).
- **status** (string) - Optional - Filter by status (pending, verified, failed, skipped).
- **format** (string) - Optional - Response format: json (default) or csv.

### Response
#### Success Response (200)
- **BatchResultsListResponse** (object) - Contains the batch results.

#### Error Response
- **401** - Authentication required
- **404** - Batch not found
```

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

### Get Batch Job Status

Source: https://goodverify.dev/api/v1/docs

Retrieves the current status of a specific batch verification job using its ID.

```APIDOC
## GET /api/v1/batch/{id}

### Description
Get batch job status

### Method
GET

### Endpoint
/api/v1/batch/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The ID of the batch job
```

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

### Download Sample CSV

Source: https://goodverify.dev/api/v1/docs

Downloads a sample CSV file that can be used as a template for batch verification jobs.

```APIDOC
## GET /api/v1/batch/sample.csv

### Description
Download sample CSV

### Method
GET

### Endpoint
/api/v1/batch/sample.csv
```

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

### Create Batch Verification Job

Source: https://goodverify.dev/api/v1/docs

Initiates a new batch verification job by uploading a file or providing data.

```APIDOC
## POST /api/v1/batch

### Description
Create a batch verification job

### Method
POST

### Endpoint
/api/v1/batch
```

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

### Batch Verification Job Creation

Source: https://goodverify.dev/api/v1/openapi

Initiates a batch verification job by uploading a file containing multiple verification requests.

```APIDOC
## POST /batch

### Description
Initiates a batch verification job by uploading a file containing multiple verification requests.

### Method
POST

### Endpoint
/batch

### Parameters
#### Request Body
- **file** (file) - Required - A CSV or JSON file containing the verification data. Each row should represent a single verification request.
- **verification_type** (string) - Required - The type of verification to perform for all items in the batch (e.g., 'phone', 'address').

### Request Example
(File upload is typically handled via multipart/form-data)
```
--boundary
Content-Disposition: form-data; name="verification_type"

phone
--boundary
Content-Disposition: form-data; name="file"; filename="verifications.csv"
Content-Type: text/csv

phone_number,country_code
+12025551234,US
+442071234567,GB
```

### Response
#### Success Response (202)
- **id** (string) - The unique identifier for the batch job.
- **status** (string) - The initial status of the batch job (e.g., 'pending', 'processing').
- **inserted_at** (string) - Timestamp when the batch job was created.

#### Response Example
```json
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "pending",
  "inserted_at": "2026-03-13T12:00:00Z"
}
```
```

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

### List batch jobs

Source: https://goodverify.dev/api/v1/openapi

Returns a paginated list of batch jobs for the authenticated account. You can specify the page number and the number of items per page.

```APIDOC
## GET /api/v1/batch

### Description
Returns a paginated list of batch jobs for the authenticated account.

### Method
GET

### Endpoint
/api/v1/batch

### Parameters
#### Query Parameters
- **page** (integer) - Optional - Page number (default: 1)
- **per_page** (integer) - Optional - Items per page (default: 25, max: 100)

### Response
#### Success Response (200)
- **BatchListResponse** (object) - Schema describing the batch job list

#### Error Response (401)
- **ErrorResponse** (object) - Schema describing an authentication error
```

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

### MCP Server Configuration

Source: https://goodverify.dev

Configuration for MCP servers, specifying the GoodVerify endpoint URL and authorization headers. Includes a list of available tools.

```json
{
  "mcpServers": {
    "goodverify": {
      "url": "https://goodverify.dev/mcp",
      "headers": {
        "Authorization": "Bearer sk_live_..."
      }
    }
  }
}

// 5 tools available:
// verify_email, verify_phone,
// verify_address, get_usage, ping

```

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

### Create Batch Job

Source: https://goodverify.dev/api/v1/openapi

Submits a batch job for processing. The response includes a job ID and status.

```APIDOC
## POST /batch

### Description
Accepts a batch job for processing. Returns a job ID and its initial status.

### Method
POST

### Endpoint
/batch

### Response
#### Success Response (200)
- **id** (string) - Batch job ID. Format: uuid.
- **status** (string) - Job status (always 'pending').
- **total_rows** (integer) - Number of items to process.
- **credit_cost** (integer) - Credits reserved for this batch.
```

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

### List Batch Jobs

Source: https://goodverify.dev/api/v1/docs

Retrieves a list of all batch verification jobs associated with the account.

```APIDOC
## GET /api/v1/batch

### Description
List batch jobs

### Method
GET

### Endpoint
/api/v1/batch
```

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

### Verify Address

Source: https://goodverify.dev/api/v1/docs

Verifies a single-line address string.

```APIDOC
## POST /api/v1/verify/address

### Description
Verify a single-line address

### Method
POST

### Endpoint
/api/v1/verify/address
```

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

### Verify Single-Line Address

Source: https://goodverify.dev/api/v1/openapi

Verifies an address provided as a single string and returns standardized components. Requires authentication.

```APIDOC
## POST /api/v1/verify/address

### Description
Verify an address provided as a single string and return standardized components.

### Method
POST

### Endpoint
/api/v1/verify/address

### Parameters
#### Request Body
- **AddressSingleRequest** (object) - Required - Address to verify.

### Response
#### Success Response (200)
- **AddressVerifyResponse** (object) - Address verification result.

#### Error Response
- **400** - Invalid input
- **422** - Validation error
- **429** - Rate limit exceeded
- **503** - Provider unavailable
```

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

### Verify Email

Source: https://goodverify.dev/api/v1/openapi

Verifies an email address and returns deliverability, flags, domain info, and risk score. Requires authentication.

```APIDOC
## POST /api/v1/verify/email

### Description
Verify an email address and return deliverability, flags, domain info, and risk score.

### Method
POST

### Endpoint
/api/v1/verify/email

### Parameters
#### Request Body
- **EmailVerifyRequest** (object) - Required - Email address to verify.

### Response
#### Success Response (200)
- **EmailVerifyResponse** (object) - Email verification result.

#### Error Response
- **400** - Invalid input
- **422** - Validation error
- **429** - Rate limit exceeded
```

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

### Verify Address by Components

Source: https://goodverify.dev/api/v1/docs

Verifies an address by providing its individual components (e.g., street, city, zip code).

```APIDOC
## POST /api/v1/verify/address/fields

### Description
Verify address by components

### Method
POST

### Endpoint
/api/v1/verify/address/fields
```

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

### Verify Email Address

Source: https://goodverify.dev/api/v1/docs

Verifies the deliverability and validity of an email address.

```APIDOC
## POST /api/v1/verify/email

### Description
Verify an email address

### Method
POST

### Endpoint
/api/v1/verify/email
```

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

### Verify Email via REST API

Source: https://goodverify.dev

Use this endpoint to perform real-time email verification, including DNS lookups and risk scoring. Requires an API key for authentication.

```curl
curl -X POST https://goodverify.dev/api/v1/verify/email \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"email": "user@example.com"}'
```

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

### Email Verification

Source: https://goodverify.dev

Verifies an email address by performing real-time DNS lookups, checking MX records and SPF policies, and detecting disposable providers. It also returns a risk score.

```APIDOC
## POST /verify/email

### Description
Verifies an email address.

### Method
POST

### Endpoint
/verify/email

### Request Body
- **email** (string) - Required - The email address to verify.

### Request Example
```json
{
  "email": "user@example.com"
}
```

### Response
#### Success Response (200)
- **deliverability** (string) - Deliverability status.
- **risk_score** (integer) - A score from 0-100 indicating the risk associated with the email.
- **domain** (string) - The domain of the email address.

### Response Example
```json
{
  "deliverability": "Deliverable",
  "risk_score": 12,
  "domain": "example.com"
}
```
```

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

### Batch Verification

Source: https://goodverify.dev/api/v1/openapi

Submits a batch of verification requests. Supports email, phone, and address verifications in a single request.

```APIDOC
## POST /verify/batch

### Description
Submits a batch of verification requests. Supports email, phone, and address verifications in a single request.

### Method
POST

### Endpoint
/verify/batch

### Request Body
- **verifications** (array) - Required - Array of verification requests (1-10,000 items)
  - **type** (string) - Required - Verification type (email, phone, address)
  - **email** (string) - Optional - Email address (for type: email)
  - **phone** (string) - Optional - Phone number (for type: phone)
  - **address** (string) - Optional - Single-line address (for type: address)
  - **street** (string) - Optional - Street address (for type: address with fields)
  - **city** (string) - Optional - City (for type: address with fields)
  - **state** (string) - Optional - State (for type: address with fields)
  - **zip** (string) - Optional - ZIP code (for type: address with fields)

### Request Example
{
  "verifications": [
    {
      "email": "test@example.com",
      "type": "email"
    },
    {
      "phone": "+12025551234",
      "type": "phone"
    },
    {
      "address": "123 Main St, Springfield, IL 62704",
      "type": "address"
    }
  ]
}

### Response
#### Success Response (200)
- **id** (string) - Batch job ID.
- **status** (string) - Current job status (pending, processing, completed, failed).

#### Response Example
{
  "id": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
  "status": "pending"
}
```

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

### Address Verification

Source: https://goodverify.dev/api/v1/openapi

Verifies a single address provided as a string. It can optionally filter by country code.

```APIDOC
## POST /addresses

### Description
Verifies a single address provided as a string. It can optionally filter by country code.

### Method
POST

### Endpoint
/addresses

### Request Body
- **address** (string) - Required - Full address string to verify
- **country_code** (string) - Optional - ISO 3166-1 alpha-2 country code

### Request Example
```json
{
  "address": "123 Main St, Springfield, IL 62704",
  "country_code": "US"
}
```

### Response
#### Success Response (200)
- **address** (object) - Details of the verified address, including formatted address, components, and coordinates.
- **country** (object) - Country information for the address.
- **formatted** (object) - Formatted address variants.
- **metadata** (object) - Metadata about the verification.
- **valid** (boolean) - Indicates if the address is valid.

#### Response Example
```json
{
  "address": {
    "components": {
      "city": "Springfield",
      "state": "IL",
      "zip_code": "62704",
      "country": "US"
    },
    "formatted_address": "123 Main St, Springfield, IL 62704, USA"
  },
  "country": {
    "calling_code": "+1",
    "code": "US",
    "name": "United States"
  },
  "formatted": {
    "street_address": "123 Main St",
    "city": "Springfield",
    "state": "IL",
    "zip_code": "62704",
    "country": "USA"
  },
  "metadata": {
    "geocoded_at": "2024-01-15T12:00:00Z"
  },
  "valid": true
}
```
```

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

### Verify Phone Number

Source: https://goodverify.dev/api/v1/openapi

Verifies a phone number and returns formatted variants, carrier, and location information.

```APIDOC
## POST /api/v1/verify/phone

### Description
Verifies a phone number and returns formatted variants, carrier, and location info.

### Method
POST

### Endpoint
/api/v1/verify/phone

### Request Body
- **phoneNumber** (string) - Required - The phone number to verify.

### Response
#### Success Response (200)
- **phoneNumber** (string) - The verified phone number.
- **formattedPhoneNumber** (string) - The formatted phone number.
- **carrier** (string) - The carrier of the phone number.
- **location** (string) - The location associated with the phone number.

#### Response Example
```json
{
  "phoneNumber": "+15551234567",
  "formattedPhoneNumber": "(555) 123-4567",
  "carrier": "Example Carrier",
  "location": "Example City, USA"
}
```
```

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

### Verify Phone Number

Source: https://goodverify.dev/api/v1/openapi

Verifies a given phone number. Requires the phone number and optionally a country code.

```APIDOC
## POST /phone/verify

### Description
Verifies a phone number. You can provide a country code for better accuracy.

### Method
POST

### Endpoint
/phone/verify

### Parameters
#### Request Body
- **phone_number** (string) - Required - Phone number to verify. Max length 20. Pattern: ^\+?[0-9 ()-]+$.
- **country_code** (string) - Optional - ISO 3166-1 alpha-2 country code. Max length 2. Pattern: ^[A-Z]{2}$.
```

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

### Phone Verification

Source: https://goodverify.dev/api/v1/openapi

Verifies a given phone number to check its validity, type, and associated carrier and location information.

```APIDOC
## POST /phones

### Description
Verifies a given phone number to check its validity, type, and associated carrier and location information.

### Method
POST

### Endpoint
/phones

### Parameters
#### Request Body
- **phone_number** (string) - Required - The phone number to verify (e.g., +12025551234).

### Request Example
```json
{
  "phone_number": "+12025551234"
}
```

### Response
#### Success Response (200)
- **phone_number** (string) - The phone number that was verified.
- **valid** (boolean) - Whether the phone number is valid.
- **phone_type** (string) - Phone line type (e.g., MOBILE, FIXED_LINE).
- **country** (object) - Country information for the phone number.
- **formatted** (object) - Formatted phone number variants.
- **carrier** (object) - Carrier information.
- **location** (object) - Geographic location associated with the phone number.
- **compliance** (object) - Compliance information (DNC, TCPA, reachability).
- **metadata** (object) - Metadata about the verification.

#### Response Example
```json
{
  "phone_number": "+12025551234",
  "valid": true,
  "phone_type": "MOBILE",
  "country": {
    "calling_code": "+1",
    "code": "US",
    "name": "United States"
  },
  "formatted": {
    "e164": "+12025551234",
    "international": "+1 202-555-1234",
    "national": "(202) 555-1234"
  },
  "carrier": {
    "name": "Verizon",
    "type": "wireless"
  },
  "location": {
    "city": "Washington",
    "state": "DC",
    "country": "United States"
  },
  "compliance": null,
  "metadata": {
    "verified_at": "2024-01-15T12:00:00Z"
  }
}
```
```

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

### Verify Address via REST API

Source: https://goodverify.dev

Standardize and validate physical addresses using this endpoint. It provides USPS standardization and deliverability determination. An API key is required.

```curl
curl -X POST https://goodverify.dev/api/v1/verify/address \
  -H "Authorization: Bearer sk_live_..." \
  -d '{"address": "123 Main St, Springfield, IL"}'
```

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

### Phone Verification

Source: https://goodverify.dev

Validates phone numbers across 200+ countries, providing carrier identification, line type detection, and compliance flags.

```APIDOC
## POST /verify/phone

### Description
Validates a phone number.

### Method
POST

### Endpoint
/verify/phone

### Parameters
#### Request Body
- **phone** (string) - Required - The phone number to validate in E.164 or national format.

### Request Example
```json
{
  "phone": "+14155552671"
}
```

### Response
#### Success Response (200)
- **line_type** (string) - The type of phone line (e.g., Mobile, Landline).
- **carrier** (string) - The carrier providing the phone service.
- **line_status** (string) - The status of the line (e.g., Active).
- **dnc_registry** (string) - Indicates if the number is on the Do Not Call registry.
- **tcpa_litigation** (string) - Indicates TCPA litigation status.

### Response Example
```json
{
  "line_type": "Mobile",
  "carrier": "T-Mobile USA",
  "line_status": "Active",
  "dnc_registry": "Listed",
  "tcpa_litigation": "Clean"
}
```
```

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

### Address Verification

Source: https://goodverify.dev

Standardizes and validates physical addresses, providing USPS standardization, property classification, and geolocation data.

```APIDOC
## POST /verify/address

### Description
Validates and standardizes a physical address.

### Method
POST

### Endpoint
/verify/address

### Parameters
#### Request Body
- **address** (string) - Required - The physical address to validate.

### Request Example
```json
{
  "address": "123 Main St, Springfield, IL"
}
```

### Response
#### Success Response (200)
- **usps_standardized** (string) - The address standardized according to USPS.
- **property_type** (string) - The type of property.
- **lat_long** (object) - Geolocation data including latitude and longitude.
- **deliverability** (string) - Determination of deliverability.

### Response Example
```json
{
  "usps_standardized": "123 Main St, Springfield, IL 62701",
  "property_type": "Residential",
  "lat_long": {
    "latitude": 39.7817,
    "longitude": -89.6501
  },
  "deliverability": "Deliverable"
}
```
```

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

### Health Check

Source: https://goodverify.dev/api/v1/openapi

Checks the current health status of the GoodVerify service. Returns a 200 status if healthy, or 503 if degraded.

```APIDOC
## GET /api/v1/health

### Description
Returns the current health status of the service.

### Method
GET

### Endpoint
/api/v1/health

### Parameters
No parameters.

### Response
#### Success Response (200)
- **HealthResponse** (object) - Indicates the service is healthy.

#### Error Response (503)
- **HealthResponse** (object) - Indicates the service is degraded.
```

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

### Verify Phone Number via REST API

Source: https://goodverify.dev

Validate phone numbers globally with carrier identification and compliance flags. This endpoint requires an API key.

```curl
curl -X POST https://goodverify.dev/api/v1/verify/phone \
  -H "Authorization: Bearer sk_live_..." \
  -d '{"phone": "+14155552671"}'
```

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

### Verify Phone Number

Source: https://goodverify.dev/api/v1/docs

Verifies a phone number, providing details about its type, carrier, and compliance.

```APIDOC
## POST /api/v1/verify/phone

### Description
Verify a phone number

### Method
POST

### Endpoint
/api/v1/verify/phone
```

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

### Health Check

Source: https://goodverify.dev/api/v1/openapi

Checks the health status of the GoodVerify service. Returns 'healthy' or 'degraded' status along with a timestamp.

```APIDOC
## GET /health

### Description
Checks the health status of the GoodVerify service.

### Method
GET

### Endpoint
/health

### Response
#### Success Response (200)
- **status** (string) - Overall service health status. Enum: [healthy, degraded]
- **timestamp** (string) - Time of the health check (ISO 8601 UTC)
```

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

### Health Check

Source: https://goodverify.dev/api/v1/docs

Performs a health check on the API to ensure it is operational. This endpoint does not require authentication.

```APIDOC
## GET /api/v1/health

### Description
Health check

### Method
GET

### Endpoint
/api/v1/health
```
Tokens:
Raw