Phone Ownership
curl --request POST \
--url https://api.deepidv.com/v1/screening/phone-ownershipimport requests
url = "https://api.deepidv.com/v1/screening/phone-ownership"
response = requests.post(url)
print(response.text)const options = {method: 'POST'};
fetch('https://api.deepidv.com/v1/screening/phone-ownership', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.deepidv.com/v1/screening/phone-ownership",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://api.deepidv.com/v1/screening/phone-ownership"
req, _ := http.NewRequest("POST", url, nil)
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.deepidv.com/v1/screening/phone-ownership")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.deepidv.com/v1/screening/phone-ownership")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
response = http.request(request)
puts response.read_body{
"outcome": "MATCH",
"nameScore": 100,
"firstNameScore": 100,
"lastNameScore": 100,
"dobScore": 100,
"addressScore": 80,
"strictness": "medium",
"threshold": 70,
"statusMessage": "Response from one supplier",
"checkedAt": "2026-09-16T16:21:08.955Z",
"correlationId": "89c0104f-dc14-4286-ae88-831ad995b835"
}
{
"outcome": "NO_MATCH",
"nameScore": 0,
"firstNameScore": 0,
"lastNameScore": 0,
"addressScore": -1,
"strictness": "medium",
"threshold": 70,
"statusMessage": "Response from one supplier",
"checkedAt": "2026-09-16T16:21:24.834Z",
"correlationId": "2cdf7aaf-9a67-4814-8486-0cdaa5508a88"
}
Carrier Intelligence
Phone Ownership
Ask the mobile carrier how well a name matches the subscriber on record for a phone number
POST
/
v1
/
screening
/
phone-ownership
Phone Ownership
curl --request POST \
--url https://api.deepidv.com/v1/screening/phone-ownershipimport requests
url = "https://api.deepidv.com/v1/screening/phone-ownership"
response = requests.post(url)
print(response.text)const options = {method: 'POST'};
fetch('https://api.deepidv.com/v1/screening/phone-ownership', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.deepidv.com/v1/screening/phone-ownership",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://api.deepidv.com/v1/screening/phone-ownership"
req, _ := http.NewRequest("POST", url, nil)
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.deepidv.com/v1/screening/phone-ownership")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.deepidv.com/v1/screening/phone-ownership")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
response = http.request(request)
puts response.read_body{
"outcome": "MATCH",
"nameScore": 100,
"firstNameScore": 100,
"lastNameScore": 100,
"dobScore": 100,
"addressScore": 80,
"strictness": "medium",
"threshold": 70,
"statusMessage": "Response from one supplier",
"checkedAt": "2026-09-16T16:21:08.955Z",
"correlationId": "89c0104f-dc14-4286-ae88-831ad995b835"
}
{
"outcome": "NO_MATCH",
"nameScore": 0,
"firstNameScore": 0,
"lastNameScore": 0,
"addressScore": -1,
"strictness": "medium",
"threshold": 70,
"statusMessage": "Response from one supplier",
"checkedAt": "2026-09-16T16:21:24.834Z",
"correlationId": "2cdf7aaf-9a67-4814-8486-0cdaa5508a88"
}
POST /v1/screening/phone-ownership
Carrier coverage varies by country. Where the carrier route is not live the outcome is
NO_DATA. UK numbers return live data today; US and Canadian numbers return NO_DATA.Request
Headers
| Header | Required | Description |
|---|---|---|
x-api-key | Yes | Your API key |
Content-Type | Yes | application/json |
Body parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
phone | string | Yes* | Mobile number in E.164 format (+ and country code). Bare 10-digit North American numbers are treated as +1. |
firstName | string | Yes** | Name to match against the carrier record (1–255 chars). |
lastName | string | Yes** | Name to match against the carrier record (1–255 chars). |
sessionId | string | No | Attach the result to an existing verification session instead of creating a standalone screening record. See Attaching to a session. |
address | string | No | Free-text address (1–500 chars). When given, addressScore is meaningful. Never changes the outcome. |
dateOfBirth | string | No | Date of birth in YYYY-MM-DD format. Reported as dobScore. Never changes the outcome. |
strictness | string | No | relaxed, medium (default) or strict. See Strictness. |
email | string | No | Applicant email for the screening record. A placeholder is synthesized when omitted. |
sessionId is given, in which case it defaults to the session applicant’s phone.
** At least one of firstName or lastName is required unless sessionId is given, in which case the session applicant’s name is used.
Strictness
| Strictness | Minimum name score for MATCH |
|---|---|
relaxed | 50 |
medium | 70 |
strict | 90 |
Example request
curl -X POST https://api.deepidv.com/v1/screening/phone-ownership \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-d '{
"phone": "+447425604497",
"firstName": "John",
"lastName": "Smith",
"address": "23 Omnia Street, London, EC1A 1BB, GB",
"dateOfBirth": "1990-01-15",
"strictness": "medium"
}'
const response = await fetch("https://api.deepidv.com/v1/screening/phone-ownership", {
method: "POST",
headers: {
"Content-Type": "application/json",
"x-api-key": "YOUR_API_KEY",
},
body: JSON.stringify({
phone: "+447425604497",
firstName: "John",
lastName: "Smith",
address: "23 Omnia Street, London, EC1A 1BB, GB",
dateOfBirth: "1990-01-15",
strictness: "medium",
}),
});
const data = await response.json();
import requests
response = requests.post(
"https://api.deepidv.com/v1/screening/phone-ownership",
headers={
"Content-Type": "application/json",
"x-api-key": "YOUR_API_KEY",
},
json={
"phone": "+447425604497",
"firstName": "John",
"lastName": "Smith",
"address": "23 Omnia Street, London, EC1A 1BB, GB",
"dateOfBirth": "1990-01-15",
"strictness": "medium",
},
)
Response
200 — Success
| Field | Type | Description |
|---|---|---|
outcome | string | MATCH (name score at or above the threshold), NO_MATCH (below it) or NO_DATA (carrier holds no servable subscriber data) |
nameScore | integer | Overall name match, 0–100. -1 when the carrier holds no data |
firstNameScore | integer | First-name match, 0–100, when reported |
lastNameScore | integer | Last-name match, 0–100, when reported |
dobScore | integer | Date-of-birth match, 0–100, when dateOfBirth was sent and the carrier scored it |
addressScore | integer | Address match, 0–100, when address was sent and the carrier scored it. -1 when no address data |
strictness | string | The strictness that was applied |
threshold | integer | The minimum name score that counted as a match |
statusMessage | string | Carrier status text |
checkedAt | string | ISO 8601 timestamp of the check |
correlationId | string | Provider correlation id. Quote it in support requests |
sessionId | string | Present when the result was attached to a verification session |
-1 the carrier holds no data, 0 held but no match, 1–99 partial match, 100 exact match.
Error responses
| Status | Description |
|---|---|
400 Bad Request | Request body failed schema validation, no usable name was supplied, or sessionId was given without phone and the session applicant has no phone on file |
401 Unauthorized | API key is invalid |
402 Payment Required | Insufficient balance for this check |
403 Forbidden | API key is missing, or the session belongs to another organization |
404 Not Found | sessionId does not exist |
503 Service Unavailable | The carrier data provider is temporarily unavailable. Nothing was billed; retry later |
500 Server Error | Unexpected server error |
{
"outcome": "MATCH",
"nameScore": 100,
"firstNameScore": 100,
"lastNameScore": 100,
"dobScore": 100,
"addressScore": 80,
"strictness": "medium",
"threshold": 70,
"statusMessage": "Response from one supplier",
"checkedAt": "2026-09-16T16:21:08.955Z",
"correlationId": "89c0104f-dc14-4286-ae88-831ad995b835"
}
{
"outcome": "NO_MATCH",
"nameScore": 0,
"firstNameScore": 0,
"lastNameScore": 0,
"addressScore": -1,
"strictness": "medium",
"threshold": 70,
"statusMessage": "Response from one supplier",
"checkedAt": "2026-09-16T16:21:24.834Z",
"correlationId": "2cdf7aaf-9a67-4814-8486-0cdaa5508a88"
}
Attaching to a session
By default each call is filed as a completed silent-screening session for audit and billed on success. PasssessionId to attach the result to one of your existing verification sessions instead:
- The result is written to that session’s
analysis_data.phone_checks.ownership, visible on Retrieve Session and in the console’s Carrier Intelligence tab. phone,firstNameandlastNamemay be omitted; they default to the session applicant.- A repeat call overwrites the previous result.
- If the session’s workflow already contains the Phone Ownership Match step, no second charge is taken because the passive step billed at session creation.