---
title: "Submits a batch of phone numbers to be validated."
method: POST
path: "/phone/bulk/v1/batches"
tags: ["Bulk Phone"]
---

# Submits a batch of phone numbers to be validated.

`POST /phone/bulk/v1/batches`

## Request

- Base URL: `https://api.experianaperture.io`
- URL: `https://api.experianaperture.io/phone/bulk/v1/batches`
- Auth: one of:
  - HTTP bearer
  - API key in header `Auth-Token`
- TypeScript: <https://skmtc.dev/experianaperture/apis/aperture-rest-api/docs/phone/bulk/v1/batches/post.ts> (a function with typed inputs; its response is checked against the schema)

## Headers

- `Reference-Id` string

## Request body

- BulkPhoneV1CreateBatchRequest: Bulk Phone V1 Create Batch request.
  - `defaults` BulkPhoneV1CreateBatchRequestOptions: The default options that applied to all the phone numbers.
    - `output_format` string, nullable: The desired format of the phone number: E164, PLUS_E164, NATIONAL, any 3-letter ISO country code. If not specified, the default format, E164, will be used.
    - `country_iso` string, nullable: You can indicate the 3-letter ISO country code if the phone number that is subject to validation doesn't contain a phone country code.
    - `get_ported_date` boolean, nullable: The date the phone number was last ported, returned only if the number has been moved to a different network. This is an optional field and is included only when get_ported_date is set to true, which incurs an additional click.
    - `supplementary_live_status` CreateBatchSupplementaryLiveStatus: The supplementary live status request model. Please note that this feature has additional charge if requested.
      - `mobile` string[], nullable: An indicator to attempt to get supplementary live status for Mobile Phone Number.
      - `landline` string[], nullable: An indicator to attempt to get supplementary live status for Landline Phone Number.
    - `batch_reference_id` string, nullable: Optional identifier that will be returned in the response to help you track the batch.
    - `max_processing_time` string, nullable: Optional maximum processing time of the batch. If the batch is still processing after this time, it will be stopped. The value should be in ISO 8601 duration format (e.g., "PT30M" for 30 minutes). Maximum allowed value is "PT24H" (24 hours). Minimum allowed value is "PT1M" (1 minute).
  - `phones` BulkPhoneV1CreateBatchRequestPhone[], required: List of input components.
    - `number` string, nullable: The phone number that is the subject of the validation.
    - `country_iso` string, nullable: You can indicate the 3-letter ISO country code if the phone number that is subject to validation doesn't contain a phone country code. This will overwrite the country_iso in the default options.

## Response `200`

OK

- BulkPhoneV1CreateBatchResponse: Bulk Phone V1 Create Batch response.
  - `error` ResponseError: Error model containing the error details.
    - `type` string, nullable: A link to documentation that provides more details about the error you’ve encountered.
    - `title` string, nullable: The title of the error.
    - `detail` string, nullable: A description of the error.
    - `instance` string, nullable: The endpoint that returned the error.
  - `result` BulkPhoneV1CreateBatchResult: Bulk Phone V1 Create Batch result.
    - `batch_id` string, nullable: Batch ID.
    - `batch_reference_id` string, nullable: Optional reference identifier to track this batch.
    - `status` string, nullable: The current Batch status.

## Other responses

- `400`: Bad Request
- `401`: Unauthorized
- `403`: Forbidden
- `406`: Not Acceptable
- `408`: Request Timeout
- `415`: Unsupported Media Type
- `429`: Too Many Requests
- `500`: Internal Server Error
- `503`: Service Unavailable

---

[API](https://skmtc.dev/experianaperture/apis/aperture-rest-api.md) - [All operations](https://skmtc.dev/experianaperture/apis/aperture-rest-api/llms.txt) - [OpenAPI document](https://skmtc.dev/experianaperture/apis/aperture-rest-api/revisions/e762934f3de5?raw)