Age verification API

Identity and age assurance. Provero uses age-verification information available from the subscriber's mobile network to determine whether a chosen age threshold can be confirmed. This is an age check, not an identity or KYC check, and it does not return an exact age or date of birth. The upstream service currently supports Pay Monthly subscribers on the UK's four main mobile networks: EE, O2, Vodafone and Three.

Send a mobile number with either minimum_age or dob (YYYY-MM-DD). At least one is required. A DOB is converted to a whole-year age for the check and takes precedence if both fields are supplied. Use meets_age_requirement as the age-check outcome: status: success means the request completed, not that the requirement was met. Live requests require a Provero API key and Age verification access.

Endpoint

POST

https://api.provero.io/api/validate/age

Headers

Authorization:
Content-Type: application/json
Accept: application/json

Request Body

Field	Type	Required	Description
`mobile_number`	`string`	Yes	Mobile number in international format, for example `+447700900123` or `447700900123`. Send the number with its country code; the leading `+` is optional.
`minimum_age`	`integer`	No	Minimum age to verify, from 0 to 120. For example, use 18 for an 18+ check or 25 for a 25+ check. Provide either `minimum_age` or `dob` — at least one is required.
`dob`	`string`	No	Date of birth in `YYYY-MM-DD` format. Provero converts it to a whole-year age and verifies that threshold. If both `minimum_age` and `dob` are supplied, `dob` takes precedence.

Request Payload Example (JSON)

{
    "mobile_number": "+447700900123",
    "minimum_age": 18
}

Request Examples

Choose language Bash (cURL) 5 examples

curl -X POST https://api.provero.io/api/validate/age \
  -H "Authorization: Bearer REPLACE_WITH_API_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{"mobile_number":"+447700900123","minimum_age":18}'

<?php
$payload = [
    "mobile_number" => "+447700900123",
    "minimum_age" => 18,
];

$curl = curl_init();
curl_setopt_array($curl, [
    CURLOPT_URL => "https://api.provero.io/api/validate/age",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POSTFIELDS => json_encode($payload),
    CURLOPT_HTTPHEADER => [
        "Authorization: Bearer REPLACE_WITH_API_TOKEN",
        "Content-Type: application/json",
        "Accept: application/json"
    ],
]);

$response = curl_exec($curl);
if (curl_errno($curl)) {
    echo 'Error:' . curl_error($curl);
}
curl_close($curl);
echo $response;

$response = Http::withToken('REPLACE_WITH_API_TOKEN')
    ->acceptJson()
    ->post('https://api.provero.io/api/validate/age', [
        'mobile_number' => '+447700900123',
        'minimum_age' => 18,
    ]);

return $response->json();

const response = await fetch('https://api.provero.io/api/validate/age', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer REPLACE_WITH_API_TOKEN',
    'Content-Type': 'application/json',
    Accept: 'application/json'
  },
  body: JSON.stringify({
    mobile_number: '+447700900123',
    minimum_age: 18
  })
});

response = requests.post(
    'https://api.provero.io/api/validate/age',
    headers={'Authorization': 'Bearer REPLACE_WITH_API_TOKEN'},
    json={'mobile_number': '+447700900123', 'minimum_age': 18},
)

Response Examples

Choose response example Success - Requirement Met 18 examples

{
    "status": "success",
    "verification_id": "age_123456",
    "mobile_number": "+447746266201",
    "minimum_age": 18,
    "meets_age_requirement": true,
    "identity_verified": true,
    "adult_content_restriction_active": false,
    "parental_controls_active": false,
    "mobile_network_code": "23410"
}

{
    "status": "success",
    "verification_id": "age_123457",
    "mobile_number": "+447746266202",
    "minimum_age": 25,
    "meets_age_requirement": false,
    "identity_verified": false,
    "adult_content_restriction_active": false,
    "parental_controls_active": false,
    "mobile_network_code": "23410"
}

{
    "status": "success",
    "verification_id": "age_123458",
    "mobile_number": "+447746266201",
    "minimum_age": 50,
    "meets_age_requirement": true,
    "identity_verified": true,
    "adult_content_restriction_active": false,
    "parental_controls_active": false,
    "mobile_network_code": "23410"
}

{
    "status": "success",
    "verification_id": "age_123459",
    "mobile_number": "+447746266205",
    "minimum_age": 18,
    "meets_age_requirement": true,
    "identity_verified": null,
    "adult_content_restriction_active": null,
    "parental_controls_active": null,
    "mobile_network_code": null
}

{
    "status": "success",
    "verification_id": "age_123460",
    "mobile_number": "+447746266203",
    "minimum_age": 18,
    "meets_age_requirement": true,
    "identity_verified": true,
    "adult_content_restriction_active": true,
    "parental_controls_active": false,
    "mobile_network_code": "23410"
}

{
    "status": "success",
    "verification_id": "age_123461",
    "mobile_number": "+447746266204",
    "minimum_age": 18,
    "meets_age_requirement": true,
    "identity_verified": true,
    "adult_content_restriction_active": false,
    "parental_controls_active": true,
    "mobile_network_code": "23410"
}

{
    "status": "error",
    "error": {
        "code": "invalid_mobile_number",
        "message": "Enter a valid mobile number in international format."
    }
}

{
    "status": "error",
    "error": {
        "code": "invalid_age",
        "message": "Enter a valid minimum age."
    }
}

{
    "status": "error",
    "error": {
        "code": "invalid_dob",
        "message": "Enter a valid date of birth in YYYY-MM-DD format."
    }
}

{
    "status": "error",
    "error": {
        "code": "subscriber_not_found",
        "message": "We couldn't find information for this mobile number."
    }
}

{
    "status": "error",
    "error": {
        "code": "network_not_supported",
        "message": "Age verification isn't available for this mobile network."
    }
}

{
    "status": "error",
    "error": {
        "code": "subscriber_opted_out",
        "message": "Age verification isn't available for this mobile number."
    }
}

{
    "status": "error",
    "error": {
        "code": "age_verification_not_available",
        "message": "Age verification isn't available for this mobile number."
    }
}

{
    "status": "error",
    "error": {
        "code": "invalid_api_key",
        "message": "The API key is missing or invalid."
    }
}

{
    "status": "error",
    "error": {
        "code": "age_verification_access_not_enabled",
        "message": "Age verification isn't currently enabled for this account. Sign in to the Provero UI and request access from the Playground."
    }
}

{
    "status": "error",
    "error": {
        "code": "rate_limit_exceeded",
        "message": "Too many requests have been made. Please try again later."
    }
}

{
    "status": "error",
    "error": {
        "code": "request_timed_out",
        "message": "The verification request timed out. Please try again."
    }
}

{
    "status": "error",
    "error": {
        "code": "service_temporarily_unavailable",
        "message": "Age verification is temporarily unavailable. Please try again later."
    }
}

Response Body

Success structure

Field Name	Type	Always Returned	Description
`status`	`string`	Yes	Indicates that the verification request completed. This is not the age-check result.
`verification_id`	`string`	Yes	Unique Provero reference for this request.
`mobile_number`	`string`	Yes	The mobile number checked, normalized to E.164 international format.
`minimum_age`	`integer`	Yes	The age checked: the supplied `minimum_age`, or the whole-year age calculated from `dob`.
`meets_age_requirement`	`boolean`	Yes	The primary age-check outcome. Whether the available subscriber information confirms the requested minimum age.
`identity_verified`	`boolean\|null`	Yes	Whether the information used for the age check was verified against official identification. This supporting signal is not an identity or KYC result; `null` means it is unavailable.
`adult_content_restriction_active`	`boolean\|null`	Yes	Whether the network reports an adult-content restriction as active. This does not replace the age result; `null` means the signal is unavailable or unsupported.
`parental_controls_active`	`boolean\|null`	Yes	Whether the network reports parental controls as active. This does not replace the age result; `null` means the signal is unavailable or unsupported.
`mobile_network_code`	`string\|null`	Yes	Combined mobile country and network code associated with the result, or `null` when unavailable.

Error structure

Field Name	Type	Always Returned	Example	Description
`status`	`string`	Yes		Indicates that the request could not be completed.
`error`	`object`	Yes		Contains a stable `error.code` for integration logic and a human-readable `error.message`. Some errors intentionally share customer-safe messages.

Understanding the response

Use meets_age_requirement as the primary outcome. A value of false means the requested threshold was not confirmed; it must not be interpreted as the subscriber's exact age or as confirmation that they are below the threshold.

identity_verified, adult_content_restriction_active and parental_controls_active are supporting signals and do not override the age result. Do not treat a null supporting signal as false.

Request examples

Choose a fixed minimum_age for an 18+, 21+, 25+, or 50+ check, or provide dob to check the person's current whole-year age. If you send both, dob takes precedence. Mobile numbers may be sent with or without the leading +, for example 447746266141; the response returns the number in canonical E.164 form with +.

18+ check

{
    "mobile_number": "+447746266141",
    "minimum_age": 18
}

21+ check

{
    "mobile_number": "+447746266141",
    "minimum_age": 21
}

25+ check

{
    "mobile_number": "+447746266141",
    "minimum_age": 25
}

50+ check

{
    "mobile_number": "+447746266141",
    "minimum_age": 50
}

Date of birth check

{
    "mobile_number": "+447746266141",
    "dob": "1990-06-01"
}

Errors and recommended actions

Error responses use the same envelope across Age verification failures. The HTTP status identifies the failure class and error.code is the stable value to branch on in your integration; do not branch on the human-readable message. Automatically retry only request_timed_out (408), rate_limit_exceeded (429) and service_temporarily_unavailable (503), using bounded backoff. Do not retry other responses unchanged.

HTTP status	Code	Recommended action
`422`	`invalid_mobile_number`	Correct the number, for example +447700900123 or 447700900123. The leading + is optional.
`422`	`invalid_age`	Supply an integer minimum_age from 0 to 120.
`422`	`invalid_dob`	Supply a past date of birth in YYYY-MM-DD format that yields an age between 0 and 120.
`422`	`age_verification_not_available`	Do not infer an age outcome; use another permitted age-assurance route.
`404`	`subscriber_not_found`	Check the number. If it is correct, use another permitted age-assurance route.
`422`	`network_not_supported`	Use another permitted age-assurance route.
`422`	`subscriber_opted_out`	Do not retry unless the subscriber's status changes.
`403`	`age_verification_access_not_enabled`	Sign in to Provero and request Age verification access from the Playground.
`401`	`invalid_api_key`	Supply a valid API token.
`402`	`insufficient_balance`	Add credit before sending another request.
`429`	`rate_limit_exceeded`	Wait and retry using backoff.
`408`	`request_timed_out`	Retry with backoff.
`503`	`service_temporarily_unavailable`	Retry later using exponential backoff.

Ready to go live?

The Playground offers a free demo and, when Age verification is enabled on your account, a live check. Live API checks require a Provero API key.