---
title: Bulk Phone Validation API - Validate and Verify Numbers and Carrier in Batches
version: 1.0.0
description: Validate up to 100 phone numbers in a single POST request. Each number is processed independently — invalid entries return per-number results without affecting the rest of the batch. Returns an array of validation results with the same structure as the single Phone Validation API.
openapi: 3.1.1
servers:
  - https://api.apifreaks.com/v1.0
paths: 1
operations: 1
schemas: 7
---

## Table of Contents

- [Bulk Phone Validation API - Validate and Verify Numbers and Carrier in Batches v1.0.0](#bulk-phone-validation-api-validate-and-verify-numbers-and-carrier-in-batches-v100)
  - [Authentication](#authentication)
  - [Phone Validation APIs](#phone-validation-apis)
    - [bulkValidatePhoneNumbers](#bulkvalidatephonenumbers)
      - [Parameters](#parameters)
      - [Responses](#responses)
  - [Schemas](#schemas)
    - [BulkPhoneValidationResponse](#bulkphonevalidationresponse)
    - [PhoneValidationResponse](#phonevalidationresponse)
    - [PhoneRawInput](#phonerawinput)
    - [PhoneFormats](#phoneformats)
    - [BulkPhoneValidationRequest](#bulkphonevalidationrequest)
    - [BulkPhoneNumberItem](#bulkphonenumberitem)
    - [ErrorResponse](#errorresponse)



# Bulk Phone Validation API - Validate and Verify Numbers and Carrier in Batches v1.0.0

Validate up to 100 phone numbers in a single POST request. Each number is processed independently — invalid entries return per-number results without affecting the rest of the batch. Returns an array of validation results with the same structure as the single Phone Validation API.

Base URLs:

* [https://api.apifreaks.com/v1.0](https://api.apifreaks.com/v1.0)

## Authentication

* API Key (ApiKeyAuthHeader)
    - Parameter Name: **X-apiKey**, in: header. Pass your API key via the X-apiKey request header.

* API Key (ApiKeyAuthQuery)
    - Parameter Name: **apiKey**, in: query. Pass your API key via the apiKey query parameter.

## Phone Validation APIs

### bulkValidatePhoneNumbers

`POST /phone/validation/bulk`

*Bulk validate phone numbers*

Validates up to 100 phone numbers in a single request. Each number is processed independently — invalid entries return per-number errors without affecting the rest of the batch.

> Body parameter

```json
{
  "numbers": [
    {
      "number": "+14155552671"
    },
    {
      "number": "+447911123456"
    },
    {
      "number": "+919876543210"
    }
  ]
}
```

#### Parameters

|Name|In|Type|Required|Description|
|---|---|---|---|---|
|format|query|string|false|Specifies the desired format for the API response. Choose 'json' for a JSON object. If not provided, the API defaults to JSON format.|
|body|body|[BulkPhoneValidationRequest](#bulkphonevalidationrequest)|true|Send a JSON object with a `numbers` array. Each item must have `number` and optionally `region` **or** `dialer_region` — never both at the same time.|

##### Detailed descriptions

**body**: Send a JSON object with a `numbers` array. Each item must have `number` and optionally `region` **or** `dialer_region` — never both at the same time.

- **International format** (`+` prefix): provide `number` only.
- **Local format** (no `+`): provide `number` + `region`.
- **IDD format** (exit code): provide `number` + `dialer_region`.

##### Enumerated Values

|Parameter|Value|
|---|---|
|format|json|
|format|xml|

> Example responses

> Array of phone validation results, one entry per requested number, in the same order. A number that fails validation is not a separate error object — it's the same result shape with error/message added and possible/valid set to false. An item missing the required number field is silently omitted from the array rather than causing an error.

```json
[
  {
    "raw_input": {
      "number": "+14155552671"
    },
    "possible": true,
    "valid": true,
    "country_prefix": 1,
    "national_number": 4155552671,
    "country_code": "US",
    "location": "San Francisco, CA",
    "time_zones": [
      "America/Los_Angeles"
    ],
    "line_type": "FIXED_LINE_OR_MOBILE",
    "formats": {
      "E164": "+14155552671",
      "International": "+1 415-555-2671",
      "National": "(415) 555-2671",
      "RFC3966": "tel:+1-415-555-2671"
    },
    "area_code_length": 3,
    "ndc_length": 3,
    "can_be_internationally_dialled": true
  }
]
```

```json
[
  {
    "raw_input": {
      "number": "+14155552671"
    },
    "possible": true,
    "valid": true,
    "country_prefix": 1,
    "national_number": 4155552671,
    "country_code": "US",
    "location": "San Francisco, CA",
    "time_zones": [
      "America/Los_Angeles"
    ],
    "line_type": "FIXED_LINE_OR_MOBILE",
    "formats": {
      "E164": "+14155552671",
      "International": "+1 415-555-2671",
      "National": "(415) 555-2671",
      "RFC3966": "tel:+1-415-555-2671"
    },
    "area_code_length": 3,
    "ndc_length": 3,
    "can_be_internationally_dialled": true
  },
  {
    "raw_input": {
      "number": "abcdefg"
    },
    "possible": false,
    "valid": false,
    "error": "Invalid Number Format",
    "message": "The input does not match the expected structure of a phone number."
  }
]
```

> Bad Request – Missing or malformed request body

```json
{
  "error": "Invalid request body Exception",
  "message": "Please provide data in required format in request body",
  "path": "/v1.0/phone/validation/bulk",
  "status": 400,
  "timestamp": "2026-07-27T12:56:50.387Z"
}
```

> Not Found – Wrong HTTP method used on the endpoint (e.g. GET instead of POST)

```json
{
  "error": "Resource Not Found",
  "message": "The requested resource could not be found. Please verify the URL and try again.",
  "path": "/v1.0/phone/validation/bulk",
  "status": 404,
  "timestamp": "2026-07-27T12:58:41.535Z"
}
```

> Request Timeout – Timed out while connecting to the remote server

```json
{
  "timestamp": "2026-06-06T14:00:00.000Z",
  "path": "/v1.0/phone/validation/bulk",
  "status": 408,
  "error": "Request Timeout",
  "message": "Timed out while connecting to the remote URL."
}
```

> Payload Too Large – Request body exceeds the size limit

```json
{
  "error": "Payload too large Exception",
  "message": "Maximum request body size limit exceeded",
  "path": "/v1.0/phone/validation/bulk",
  "status": 413,
  "timestamp": "2026-07-27T12:57:03.711Z"
}
```

> Rate Limit Exceeded – API rate limit exceeded

```json
{
  "timestamp": "2026-06-06T14:00:00.000Z",
  "path": "/v1.0/phone/validation/bulk",
  "status": 429,
  "error": "Too Many Requests",
  "message": "API rate limit exceeded."
}
```

#### Responses

|Status|Meaning|Description|Schema|
|---|---|---|---|
|200|[OK](https://tools.ietf.org/html/rfc7231#section-6.3.1)|Array of phone validation results, one entry per requested number, in the same order. A number that fails validation is not a separate error object — it's the same result shape with error/message added and possible/valid set to false. An item missing the required number field is silently omitted from the array rather than causing an error.|[BulkPhoneValidationResponse](#bulkphonevalidationresponse)|
|400|[Bad Request](https://tools.ietf.org/html/rfc7231#section-6.5.1)|Bad Request – Missing or malformed request body|[ErrorResponse](#errorresponse)|
|404|[Not Found](https://tools.ietf.org/html/rfc7231#section-6.5.4)|Not Found – Wrong HTTP method used on the endpoint (e.g. GET instead of POST)|[ErrorResponse](#errorresponse)|
|408|[Request Timeout](https://tools.ietf.org/html/rfc7231#section-6.5.7)|Request Timeout – Timed out while connecting to the remote server|[ErrorResponse](#errorresponse)|
|413|[Payload Too Large](https://tools.ietf.org/html/rfc7231#section-6.5.11)|Payload Too Large – Request body exceeds the size limit|[ErrorResponse](#errorresponse)|
|429|[Too Many Requests](https://tools.ietf.org/html/rfc6585#section-4)|Rate Limit Exceeded – API rate limit exceeded|[ErrorResponse](#errorresponse)|

#### Response Headers

|Status|Header|Type|Format|Description|
|---|---|---|---|---|
|200|X-AF-Credits-Cost|integer||Specifies the number of credits consumed by the current request.|
|400|X-AF-Credits-Cost|integer||Specifies the number of credits consumed by the current request.|
|404|X-AF-Credits-Cost|integer||Specifies the number of credits consumed by the current request.|
|408|X-AF-Credits-Cost|integer||Specifies the number of credits consumed by the current request.|
|413|X-AF-Credits-Cost|integer||Specifies the number of credits consumed by the current request.|
|429|X-AF-Credits-Cost|integer||Specifies the number of credits consumed by the current request.|

To perform this operation, you must be authenticated by means of one of the following methods:
ApiKeyAuthHeader, ApiKeyAuthQuery

## Schemas

### BulkPhoneValidationResponse

Array of per-number results, one entry per requested phone number that had a number field, in the same order as the request. Items missing number are silently omitted rather than erroring.

#### Properties

|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|[[PhoneValidationResponse](#phonevalidationresponse)]|false|none|Array of per-number results, one entry per requested phone number that had a number field, in the same order as the request. Items missing number are silently omitted rather than erroring.|

### PhoneValidationResponse

Phone validation result for a single number in the batch. When the number fails validation, error/message are populated instead of the full metadata fields, and possible/valid are false.

#### Properties

|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|raw_input|[PhoneRawInput](#phonerawinput)|true|none|Original request payload sent by the caller.|
|possible|boolean|true|none|Whether the number is possible (length and format checks only). A number can be possible but not valid.|
|valid|boolean|true|none|Whether the number is valid according to the numbering plan.|
|country_prefix|integer|false|none|The international dialing prefix for the number's country (e.g., 1 for US/Canada, 44 for United Kingdom).|
|national_number|integer|false|none|The national significant number (the phone number without the country code).|
|country_code|string|false|none|ISO-2 country code inferred from the number (e.g., US, GB).|
|carrier|string|false|none|Carrier name associated with the number (if available). May not reflect ported carriers.|
|location|string|false|none|Geographic description (city/region) for the number (if applicable).|
|time_zones|[string]|false|none|Array of possible time zones associated with the number.|
|line_type|string|false|none|Classification of the phone line (MOBILE, FIXED_LINE, VOIP, etc.).|
|formats|[PhoneFormats](#phoneformats)|false|none|Four standardized representations of the phone number.|
|area_code_length|integer|false|none|Length of the geographic area code. Only applies to geographically-assigned numbers.|
|ndc_length|integer|false|none|Length of the National Destination Code (NDC), the routing prefix within a country.|
|can_be_internationally_dialled|boolean|false|none|Whether the number can be dialled internationally. false for short codes, emergency numbers, and domestic-only services.|
|error|string|false|none|Short error category. Present only when this item failed validation (e.g. malformed number, conflicting region parameters).|
|message|string|false|none|Human-readable reason for failure. Present only when this item failed validation.|

##### Enumerated Values

|Property|Value|
|---|---|
|line_type|MOBILE|
|line_type|FIXED_LINE|
|line_type|FIXED_LINE_OR_MOBILE|
|line_type|VOIP|
|line_type|TOLL_FREE|
|line_type|PREMIUM_RATE|
|line_type|SHARED_COST|
|line_type|PERSONAL_NUMBER|
|line_type|PAGER|
|line_type|UAN|
|line_type|VOICEMAIL|
|line_type|UNKNOWN|

### PhoneRawInput

Original request payload sent by the caller.

#### Properties

|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|number|string|true|none|The phone number as entered by the user.|
|region|string|false|none|ISO-2 country code.|
|dialer_region|string|false|none|ISO-2 country code of the dialing origin.|

### PhoneFormats

Four standardized representations of the phone number.

#### Properties

|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|E164|string|false|none|Number in E.164 format.|
|International|string|false|none|Human-readable international format.|
|National|string|false|none|Local format as dialed within the country.|
|RFC3966|string|false|none|URI format following RFC 3966.|

### BulkPhoneValidationRequest

Request body for bulk phone validation.

#### Properties

|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|numbers|[[BulkPhoneNumberItem](#bulkphonenumberitem)]|true|none|Array of phone number objects. Maximum 100 per request.|

### BulkPhoneNumberItem

A single phone number entry in a bulk validation request.

#### Properties

|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|number|string|true|none|Phone number to validate.|
|region|string|false|none|Two-letter ISO country code. Required for local format numbers.|
|dialer_region|string|false|none|Two-letter ISO country code of the dialing origin. Required for IDD format numbers.|

### ErrorResponse

Standard error envelope returned by the API on failed requests.

#### Properties

|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|error|string|false|none|Short error category or exception type.|
|message|string|true|none|Human-readable error message describing the failure.|
|path|string|false|none|API endpoint path that produced the error.|
|status|integer|false|none|HTTP status code returned with the error.|
|timestamp|string(date-time)|false|none|Timestamp when the error occurred (ISO 8601).|