API reference / KYC / Identity

Mobile ownership: verify OTP

Submits the OTP with the reference_id from the send call and returns the subscriber details.

POST/v1/verify/mobile/otp/verify
Authentication
Bearer token
Scope
kyc:verify

Before you integrate

  • This is step 2 of 2. Call /v1/verify/mobile/otp first to get the reference_id; the check fails if the OTP is wrong or has expired, and you can send a new OTP.

Request body

FieldTypeRequiredDescription
mobilestringYes10-digit Indian mobile number starting 6 to 9; a leading +91, 91 or 0 and spaces are ignored. Must be the number the OTP was sent to.
reference_idstringYesThe reference_id returned by /v1/verify/mobile/otp, 6 to 80 letters, digits, hyphens or underscores.
otpstringYesThe OTP the person received, 4 to 8 digits.

Sample code

Set your key in the GRAPPI_API_KEY environment variable. Sample values are placeholders.

curl -sS -X POST 'https://grappi.ai/v1/verify/mobile/otp/verify' \
  -H "Authorization: Bearer $GRAPPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "mobile": "9876543210",
  "reference_id": "telecom_abc123",
  "otp": "123456"
}'

Sample response

{
  "request_id": "req_01HZY3K8M2",
  "result": {
    "name": "ASHA RAO",
    "address": "12 Example Lane, Pune, Maharashtra, 411001",
    "split_address": {
      "district": [
        "Pune"
      ],
      "state": [
        "Maharashtra"
      ],
      "city": [
        "Pune"
      ],
      "pincode": "411001",
      "country": [
        "India"
      ],
      "address_line": "12 Example Lane"
    },
    "mobile_number": "9876543210",
    "country_code": "91",
    "mobile_network_operator": "Example Telecom",
    "billing_type": "Prepaid"
  }
}

Response fields

FieldTypeDescription
namestringSubscriber name on the telecom record.
addressstringSubscriber address on the telecom record.
split_addressobjectThe subscriber's address broken into parts.
split_address.districtarrayDistrict name, as a list.
split_address.statearrayState name, as a list.
split_address.cityarrayCity name, as a list.
split_address.pincodestringSix-digit pincode.
split_address.countryarrayCountry name, as a list.
split_address.address_linestringStreet-level part of the address.
dobstringSubscriber's date of birth, when recorded.
mobile_numberstringThe mobile number that was verified.
country_codestringCountry calling code.
emailstringEmail address on the telecom record, when recorded.
mobile_network_operatorstringCurrent mobile network operator.
billing_typestringWhether the connection is prepaid or postpaid.
alternate_phonestringAlternate phone number on the record, when recorded.
extra_fieldsobjectExtra connection details, when the operator shares them.
extra_fields.device_namestringDevice name.
extra_fields.current_packobjectCurrent plan, with its name, expiry and price.
extra_fields.loyalty_categorystringLoyalty category of the subscriber.
extra_fields.billing_historyarrayRecent billing entries.

Errors

Every failure has the same shape. A call that fails on our side or at the data source is refunded to your wallet; a "no record found" answer is charged. See the error reference.