Ctrlk
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Phone

Phone numbers remain one of the most direct and effective communication channels—when they're accurate and properly formatted. Delpha's Phone Validator helps you standardize, verify, and clean your phone data to ensure consistency across systems and better outreach performance.

Each phone entry is evaluated on three key aspects:

  • Completeness: Detects whether a phone number is present and properly structured.

  • Validity: Checks if the number follows the correct national or international format and isn't blacklisted or clearly invalid.

  • Consistency: Compares the original input to its normalized international form.

By using optional context such as a country or country code, the system applies the right validation rules and returns a standardized E.164-compliant number. When no country is provided, Delpha applies smart defaults based on global dialing patterns.

Focused purely on validation and normalization, Phone Validator ensures your phone data stays clean, reliable, and ready for business use.

Validate and normalize a phone number

get

Synchronous phone validation: normalize a phone number and receive its type, carrier, timezone, zone, area and validity in a single request (no job_id polling). Provide the number with an international (+) prefix, or pass country (a name or ISO code) for national-format numbers.

Required scopes
This endpoint requires the following scopes:
  • : Access to the public API
Authorizations
OAuth2clientCredentialsRequired

OAuth2 client credentials flow for API access

Token URL:
Query parameters
phonestringRequired

The phone number. Include the international code (e.g. '+33672557378') for automatic country detection, otherwise provide 'country'.

Example: {"value":"+33672557378"}
countrystringOptional

The country of the phone number — a country name ('France') OR a 2-letter ISO code ('FR'). Required when the phone has no international (+) prefix.

Example: {"value":"FR"}
Responses
200

Phone assessment succeeded

application/json

Public response for the synchronous phone validation.

messagestringRequired

The message to return

Example: Phone assessment succeeded
statusstring · enumRequired

The status of the process

Example: SUCCESSPossible values:
status_codeintegerRequired

The status code to return

Example: 200
process_timenumber · nullableOptional

The processing time of the request, in seconds.

Example: 0.42
get/v1/phone
GET /v1/phone?phone=text HTTP/1.1
Host: api.delpha.io
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: */*

{
  "message": "Phone assessment succeeded",
  "status": "SUCCESS",
  "status_code": 200,
  "result": {
    "normalized_value": "+33672557378",
    "phone_type": "MOBILE",
    "carrier": "Orange France",
    "timezone": "Europe/Paris",
    "zone": "FR",
    "area": "France",
    "valid": true
  },
  "process_time": 0.42
}

Submit phone for finding and validation

post

Submit an phone for finding and validation. Returns a job ID for tracking the process.

Required scopes
This endpoint requires the following scopes:
  • : Access to the public API
Authorizations
OAuth2clientCredentialsRequired

OAuth2 client credentials flow for API access

Token URL:
Query parameters
phonestringRequired

The phone number. Include the international code (e.g. '+33672557378') for automatic country detection, otherwise provide 'country'.

Example: {"value":"+33672557378"}
countrystringOptional

The country of the phone number — a country name ('France') OR a 2-letter ISO code ('FR'). Required when the phone has no international (+) prefix.

Example: {"value":"FR"}
Body

Payload to submit a new phone quality job.

Important: For proper normalization and country detection, either:

  • Provide a phone number with international code (e.g., "+33672557378"), OR
  • Provide the phone number along with country or country_code

If none of these conditions are met, the system may not be able to properly detect the country and apply the related normalization.

phonestringRequired

The phone number. Should include international code (e.g., '+33672557378') for automatic country detection. If not provided, 'country' or 'country_code' must be specified.

Example: +33672557378
countrystring · nullableOptional

The country name of the phone number (e.g., 'France'). Required if phone number does not include international code (+XX).

Example: France
country_codestring · nullableOptional

The 2-letter ISO country code of the phone number.Required if phone number does not include international code (+XX).

Example: FR
Responses
202

Job submitted to assess_phone_v16

application/json

Response after submitting a new phone quality job.

job_idstring · nullableOptional

The job ID. Required if status <= 300.

Example: 21014abc65004d2781d2e0ef4c9fbb46
messagestringRequired

The message to return

Example: Job submitted to assess_phone_v16
statusstring · enumRequired

The status of the process

Example: SUCCESSPossible values:
status_codeintegerRequired

The status code to return

Example: 202
post/v1/phone
POST /v1/phone?phone=text HTTP/1.1
Host: api.delpha.io
Authorization: Bearer YOUR_OAUTH2_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 63

{
  "phone": "+33672557378",
  "country": "France",
  "country_code": "FR"
}
{
  "job_id": "21014abc65004d2781d2e0ef4c9fbb46",
  "message": "Job submitted to assess_phone_v16",
  "status": "SUCCESS",
  "status_code": 202
}

Get phone finder and validator job status

get

Retrieve the result and status of a previously submitted phone finder and validator job.

Required scopes
This endpoint requires the following scopes:
  • : Access to the public API
Authorizations
OAuth2clientCredentialsRequired

OAuth2 client credentials flow for API access

Token URL:
Path parameters
job_idstringRequired

The unique identifier of the phone job

Example: {"summary":"Sample job ID","value":"21014abc65004d2781d2e0ef4c9fbb46"}
Responses
200

Job succeeded.

application/json

Response after retrieving the status and result of an phone quality job.

messagestringRequired

A human-readable message describing the current state or outcome of the job.

Example: Job succeeded.
statusstring · enumRequired

The status of the process

Example: SUCCESSPossible values:
status_codeintegerRequired

The HTTP status code representing the job's current state.

Example: 200
process_timenumber · nullableOptional

The total time taken to process the job, in seconds.

Example: 0.123
get/v1/phone/{job_id}
GET /v1/phone/{job_id} HTTP/1.1
Host: api.delpha.io
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: */*

{
  "message": "Job succeeded.",
  "status": "SUCCESS",
  "status_code": 200,
  "result": {
    "data_type": "phone",
    "normalized_value": "+33672557378",
    "phone_type": "MOBILE",
    "carrier": "Orange France",
    "timezone": "Europe/Paris",
    "zone": "FR",
    "area": "France",
    "scores": {
      "validity": 1,
      "completeness": 1,
      "consistency": 1,
      "accuracy": -1
    }
  },
  "process_time": 0.123
}

Submit a batch of phone items

post

Submit 1..100 phone items for asynchronous batch processing as ONE job (never a per-item fan-out). Returns a job_id immediately (202); poll GET /v1/phone/batch/{job_id} for status and results. Each item is validated identically to the single-route POST /v1/phone payload; a payload with 0 items or more than 100 is rejected with 422.

Required scopes
This endpoint requires the following scopes:
  • : Access to the public API
Authorizations
OAuth2clientCredentialsRequired

OAuth2 client credentials flow for API access

Token URL:
Body

Batch envelope for POST /v1/phone/batch: {"items": [...]} (1..100 items, 422 beyond); each item is shaped exactly like the single-route POST /v1/phone payload (reused here by $ref as PhoneSubmitInput).

Responses
202

Batch submitted

application/json

Response after submitting a batch quality job.

job_idstring · nullableOptional

The job ID. Required if status <= 300.

Example: 21014abc65004d2781d2e0ef4c9fbb46
item_countinteger · nullableOptional

Number of items accepted in the batch (present on success).

Example: 100
messagestringRequired

The message to return

Example: Batch submitted
statusstring · enumRequired

The status of the process

Example: SUCCESSPossible values:
status_codeintegerRequired

The status code to return

Example: 202
post/v1/phone/batch
POST /v1/phone/batch HTTP/1.1
Host: api.delpha.io
Authorization: Bearer YOUR_OAUTH2_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 75

{
  "items": [
    {
      "phone": "+33672557378",
      "country": "France",
      "country_code": "FR"
    }
  ]
}
{
  "job_id": "21014abc65004d2781d2e0ef4c9fbb46",
  "item_count": 100,
  "message": "Batch submitted",
  "status": "SUCCESS",
  "status_code": 202
}

Get phone batch job status

get

Poll a batch of phone items submitted via POST /v1/phone/batch. 202 while running (with item_count/processed_count progress); 200 once SUCCEEDED (with counts, a presigned result_url, and result_data inlined when <=1MB); 409 if the credit reservation expired before delivery (resubmit); 500 if the job failed; 504 past the 24h ceiling (batch jobs run on Batch/Vertex timescales, hours not minutes).

Required scopes
This endpoint requires the following scopes:
  • : Access to the public API
Authorizations
OAuth2clientCredentialsRequired

OAuth2 client credentials flow for API access

Token URL:
Path parameters
job_idstringRequired

The unique identifier of the phone batch job.

Example: {"summary":"Sample job ID","value":"21014abc65004d2781d2e0ef4c9fbb46"}
Responses
200

97/100 items succeeded

application/json

Response for GET /v1/phone/batch/{job_id}. Each result_data.items[] entry is keyed to its request item by dispatch_key ({"record_id": "<job_id>#<index>"}). On success its result is the SAME object GET /v1/phone/{job_id} returns for a single item. On failure it carries an error string instead of result.

messagestringRequired

A human-readable message describing the current state or outcome of the job.

Example: 97/100 items succeeded
statusstring · enumRequired

The status of the process

Example: SUCCESSPossible values:
status_codeintegerRequired

The HTTP status code representing the job's current state.

Example: 200
result_urlstring · nullableOptional

Presigned URL (1h expiry) to download the full batch result JSON from S3.

Example: https://delpha-api-batch-dev.s3.amazonaws.com/batch-results/<job_id>.json?...
item_countinteger · nullableOptional

Total number of items in the batch (present while the job is running).

processed_countinteger · nullableOptional

Number of items processed so far (present while the job is running; may be absent early in the job's lifecycle).

process_timenumber · nullableOptional

The total time taken to process the job, in seconds.

Example: 12.3
get/v1/phone/batch/{job_id}
GET /v1/phone/batch/{job_id} HTTP/1.1
Host: api.delpha.io
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: */*

{
  "message": "97/100 items succeeded",
  "status": "SUCCESS",
  "status_code": 200,
  "counts": {
    "total": 100,
    "succeeded": 97,
    "failed": 3
  },
  "result_url": "https://delpha-api-batch-dev.s3.amazonaws.com/batch-results/<job_id>.json?...",
  "result_data": {
    "job_id": "21014abc65004d2781d2e0ef4c9fbb46",
    "usecase": "phone",
    "counts": {
      "total": 2,
      "succeeded": 1,
      "failed": 1
    },
    "items": [
      {
        "dispatch_key": {
          "record_id": "21014abc65004d2781d2e0ef4c9fbb46#0"
        },
        "result": {
          "data_type": "phone",
          "normalized_value": "+33672557378",
          "phone_type": "MOBILE",
          "carrier": "Orange France",
          "timezone": "Europe/Paris",
          "zone": "FR",
          "area": "France",
          "scores": {
            "validity": 1,
            "completeness": 1,
            "consistency": 1,
            "accuracy": -1
          }
        }
      },
      {
        "dispatch_key": {
          "record_id": "21014abc65004d2781d2e0ef4c9fbb46#1"
        },
        "error": "Processing failed for this item."
      }
    ]
  },
  "item_count": null,
  "processed_count": null,
  "process_time": 12.3
}
PreviousWebsite
NextName

Last updated

Was this helpful?