Mobile Type & Tenure API

Contract type and network tenure. Provero checks the mobile number's contract type (Pay As You Go, Pay Monthly or Business) and whether the subscriber was connected to their current network on the date you specify. This is a network-subscription check, not an identity or KYC check.

Initial release. Mobile Type & Tenure is currently a restricted, test-only release: live responses are available for subscribers on O2/Telefonica and Vodafone networks, and are not yet covered for EE or Three. Explore the simulated Playground first.

Send a mobile number to return the contract type and whether the subscriber was connected to the current network today (UTC). Supply tenure_date to check a different date. status: success means the request completed, not that tenure was confirmed. Live requests require a Provero API key and Mobile Type & Tenure access; the Playground always returns simulated responses and never uses credits.

Endpoint

POST

https://api.provero.io/api/validate/mobile-type-tenure

Headers

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

Request Body

Field	Type	Required	Description
`mobile_number`	`string`	Yes	Mobile number in E.164 international format, including the leading `+`, for example `+447700900123`.
`tenure_date`	`string`	No	Optional date to check network tenure against, in `YYYY-MM-DD` format. Omit it to use today (UTC).

Request Payload Example (JSON)

{
    "mobile_number": "+447700900123"
}

Request Examples

Choose language Bash (cURL) 5 examples

curl -X POST https://api.provero.io/api/validate/mobile-type-tenure \
  -H "Authorization: Bearer REPLACE_WITH_API_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{"mobile_number":"+447700900123","tenure_date":"2026-03-01"}'

<?php
$payload = [
    "mobile_number" => "+447700900123",
    "tenure_date" => "2026-03-01",
];

$curl = curl_init();
curl_setopt_array($curl, [
    CURLOPT_URL => "https://api.provero.io/api/validate/mobile-type-tenure",
    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/mobile-type-tenure', [
        'mobile_number' => '+447700900123',
        'tenure_date' => '2026-03-01',
    ]);

return $response->json();

const response = await fetch('https://api.provero.io/api/validate/mobile-type-tenure', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer REPLACE_WITH_API_TOKEN',
    'Content-Type': 'application/json',
    Accept: 'application/json'
  },
  body: JSON.stringify({
    mobile_number: '+447700900123',
    tenure_date: '2026-03-01'
  })
});

response = requests.post(
    'https://api.provero.io/api/validate/mobile-type-tenure',
    headers={'Authorization': 'Bearer REPLACE_WITH_API_TOKEN'},
    json={'mobile_number': '+447700900123', 'tenure_date': '2026-03-01'},
)

Response Examples

Choose response example Success - Pay Monthly Subscriber, Tenure Confirmed 16 examples

{
    "status": "success",
    "verification_id": "mtn_123456",
    "mobile_number": "+447700900123",
    "tenure_date": "2026-03-01",
    "tenure_result": true,
    "contract_type": "PAYM",
    "mcc_mnc": "23415"
}

{
    "status": "success",
    "verification_id": "mtn_123457",
    "mobile_number": "+447700900124",
    "tenure_date": "2026-03-01",
    "tenure_result": true,
    "contract_type": "PAYG",
    "mcc_mnc": "23415"
}

{
    "status": "success",
    "verification_id": "mtn_123458",
    "mobile_number": "+447700900125",
    "tenure_date": "2026-03-01",
    "tenure_result": true,
    "contract_type": "Business",
    "mcc_mnc": "23415"
}

{
    "status": "success",
    "verification_id": "mtn_123459",
    "mobile_number": "+447700900126",
    "tenure_date": "2026-08-01",
    "tenure_result": false,
    "contract_type": "PAYM",
    "mcc_mnc": "23415"
}

{
    "message": "The given data was invalid.",
    "errors": {
        "mobile_number": [
            "Enter a valid mobile number in international format."
        ]
    }
}

{
    "message": "The given data was invalid.",
    "errors": {
        "tenure_date": [
            "Enter a valid date in YYYY-MM-DD format."
        ]
    }
}

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

{
    "status": "error",
    "error": {
        "code": "mobile_type_tenure_access_not_enabled",
        "message": "Mobile Type & Tenure isn't currently enabled for this account. Sign in to the Provero UI and request access from the Playground."
    }
}

{
    "status": "error",
    "error": {
        "code": "insufficient_balance",
        "message": "Your balance is insufficient to complete this request. Add credit and try again."
    }
}

{
    "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": "provider_configuration_error",
        "message": "Mobile Type & Tenure provider credentials or client configuration are not valid for this request."
    }
}

{
    "status": "error",
    "error": {
        "code": "network_not_supported",
        "message": "The subscriber network is not currently supported for Mobile Type & Tenure."
    }
}

{
    "status": "error",
    "error": {
        "code": "tenure_data_unavailable",
        "message": "Mobile Type & Tenure data is unavailable for this subscriber."
    }
}

{
    "status": "error",
    "error": {
        "code": "provider_malformed_response",
        "message": "Mobile Type & Tenure returned an unexpected provider response."
    }
}

{
    "status": "error",
    "error": {
        "code": "service_temporarily_unavailable",
        "message": "Mobile Type & Tenure is temporarily unavailable. Please try again later."
    }
}

Response Body

Success structure

Field Name	Type	Example	Always Present	Description
`status`	`string`	`success`	Yes	Indicates that the request completed. This is not the tenure result.
`verification_id`	`string`	`mtn_123456`	Yes	Unique Provero reference for this request.
`mobile_number`	`string`	`+447700900123`	Yes	The mobile number checked, normalized to E.164 international format.
`tenure_date`	`string`	`2026-03-01`	Yes	The date used for the check, in `YYYY-MM-DD` format. This is today (UTC) if you omitted the field.
`tenure_result`	`boolean`	`1`	Yes	Whether the subscriber was connected to the current network on `tenure_date`. `false` means the subscriber was not connected to the current network on that date.
`contract_type`	`string`	`PAYM`	Yes	The mobile number contract type: `PAYG` (Pay As You Go), `PAYM` (Pay Monthly) or `Business`.
`mcc_mnc`	`string`	`23415`	Yes	Combined current-network Mobile Country Code and Mobile Network Code (MCC/MNC) associated with the result.

Error structure

Field Name	Type	Example	Always Present	Description
`status`	`string`	`error`	Yes	Indicates that the request could not be completed.
`error`	`object`	`{"code":"insufficient_balance","message":"Your balance is insufficient to complete this request."}`	Yes	Contains a stable `error.code` for integration logic and a human-readable `error.message`. Request validation failures (HTTP 422) instead use the standard Laravel validation envelope with `message` and `errors` fields.

Understanding the response

tenure_result is the primary outcome. A value of false means the subscriber was not connected to the current network on tenure_date; it must not be interpreted as a network failure, an invalid number, or a negative credit decision on its own.

contract_type returns PAYG, PAYM or Business.

Unsupported networks and data unavailability are reported as error responses (for example network_not_supported or tenure_data_unavailable), never as tenure_result: false. If you receive an error, do not interpret it as a negative tenure result.

Request examples

Change only tenure_date to check the subscriber's connection on a different date through the same endpoint.

Tenure confirmed

{
    "mobile_number": "+447700900123",
    "tenure_date": "2026-03-01"
}

Tenure not confirmed

{
    "mobile_number": "+447700900126",
    "tenure_date": "2026-08-01"
}

Errors and recommended actions

Error responses use the same envelope across Mobile Type & Tenure failures, except request validation failures (HTTP 422), which use the standard Laravel validation envelope with message and errors fields. 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, and never treat an error as tenure_result: false.

HTTP status	Code	Recommended action
`422`	`validation error (standard envelope)`	Correct the flagged field and resend. Do not treat a 422 as a tenure result.
`401`	`invalid_api_key`	Supply a valid API token.
`402`	`insufficient_balance`	Add credit before sending another request.
`403`	`mobile_type_tenure_access_not_enabled`	Sign in to Provero and request Mobile Type & Tenure access from the Playground.
`403`	`provider_configuration_error`	Contact Provero support with the verification ID. Do not retry until the configuration issue has been resolved.
`429`	`rate_limit_exceeded`	Wait and retry using backoff.
`408`	`request_timed_out`	Retry with backoff.
`422`	`network_not_supported`	The current network is not enabled for this early release. Do not interpret this as a negative tenure result.
`422`	`tenure_data_unavailable`	The network could not provide tenure data. Do not interpret this as a negative tenure result.
`502`	`provider_malformed_response`	Contact Provero support with the verification ID. Do not interpret this as a tenure result.
`503`	`service_temporarily_unavailable`	Retry later using exponential backoff. Do not interpret this as a negative tenure result.

Ready to go live?

Mobile Type & Tenure is an initial release and is restricted to testing: live responses are currently available for O2/Telefonica and Vodafone subscribers, and EE and Three are not yet covered. Live checks require a Provero API key and Mobile Type & Tenure enabled on your account. Explore the simulated Playground first.