> ## Documentation Index
> Fetch the complete documentation index at: https://docs.deepidv.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Phone Ownership
> Ask the mobile carrier how well a name matches the subscriber on record for a phone number
```
POST /v1/screening/phone-ownership
```
Asks the subscriber's mobile carrier how well a name, and optionally an address and date of birth, matches the account holder on record for a phone number. Returns synchronously with the carrier's match scores and an outcome against a strictness threshold. The subscriber record itself is never disclosed.
Only the **name score** decides the outcome. Address and date-of-birth scores are returned for information.
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](#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](#strictness). |
| `email` | string | No | Applicant email for the screening record. A placeholder is synthesized when omitted. |
\* Required unless `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
```bash cURL theme={null}
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"
}'
```
```javascript Node.js theme={null}
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();
```
```python Python theme={null}
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 |
Score meanings: `-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 |
```json 200 theme={null}
{
"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"
}
```
```json 200 (no match) theme={null}
{
"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. Pass `sessionId` 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](/api-reference/sessions/retrieve-session) and in the console's Carrier Intelligence tab.
* `phone`, `firstName` and `lastName` may 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.
## Related
* [Phone Trust](/api-reference/carrier-intelligence/phone-trust)
* [Carrier Age Gate](/api-reference/carrier-intelligence/carrier-age-gate)