Phone number lookup

Two checks cover phone numbers — one Kenyan, one global.

`check`	Country	Required fields	Returns
`phone`	Kenya	`number`	Registered name, carrier and line status
`phone_ng`	Nigeria	`number`	Registered name and carrier
`phone_advance_ng`	Nigeria	`number`	Full record: names, date of birth, address
`phone_status_global`	Global	`number`	Carrier, line type and active status

The Kenyan check is the one to reach for when you need a name. The global check answers whether a line is live and who carries it, but does not name the subscriber.

Kenya

Kenyan numbers are normalised for you, so all of 0712345678, 712345678, 254712345678 and +254 712 345 678 resolve to the same line — and to the same cache entry.

curl -X POST "$PH_CONNECT_URL/api/v1/kyc/verify/phone" \
  -u "$PH_API_USERNAME:$PH_API_PASSWORD" \
  -H "Content-Type: application/json" \
  -d '{ "number": "254712345678" }'

const res = await fetch(`${process.env.PH_CONNECT_URL}/api/v1/kyc/verify/phone`, {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    Authorization: 'Basic ' + Buffer.from(
      `${process.env.PH_API_USERNAME}:${process.env.PH_API_PASSWORD}`,
    ).toString('base64'),
  },
  body: JSON.stringify({ number: '0712345678' }),
})

const check = await res.json()
const phoneToken = check.status === 'verified' ? check.lookup_id : null

import os, requests

res = requests.post(
    f"{os.environ['PH_CONNECT_URL']}/api/v1/kyc/verify/phone",
    auth=(os.environ["PH_API_USERNAME"], os.environ["PH_API_PASSWORD"]),
    json={"number": "0712345678"},
)
check = res.json()
phone_token = check["lookup_id"] if check["status"] == "verified" else None

{
  "lookup_id": "c41e77d9b0a24f6e89305ab2",
  "check": "phone",
  "category": "phone",
  "country": "KE",
  "actor_type": "I",
  "subject_name": "JANE WANJIRU DOE",
  "status": "verified",
  "verification_status": "VERIFIED",
  "source": "prembly",
  "cached": false,
  "charged_amount": 65,
  "charge_currency": "KES",
  "charge_status": "charged"
}

A phone check always reports actor_type: "I" — a line is registered to a person.

Outside Kenya

Pass the number in full international form, including the +:

curl -X POST "$PH_CONNECT_URL/api/v1/kyc/verify/phone_status_global" \
  -u "$PH_API_USERNAME:$PH_API_PASSWORD" \
  -H "Content-Type: application/json" \
  -d '{ "number": "+265991234567" }'

{
  "lookup_id": "7d5a1e3fc6b84920ae7f0c15",
  "check": "phone_status_global",
  "category": "phone",
  "country": "GLOBAL",
  "actor_type": "I",
  "status": "verified",
  "verification_status": "VERIFIED",
  "data": {
    "carrier": "Airtel Malawi",
    "line_type": "mobile",
    "active": true
  },
  "source": "prembly",
  "charged_amount": 70,
  "charge_currency": "KES",
  "charge_status": "charged"
}

Nigeria

Nigerian numbers take the local 0-prefixed form:

curl -X POST "$PH_CONNECT_URL/api/v1/kyc/verify/phone_ng" \
  -u "$PH_API_USERNAME:$PH_API_PASSWORD" \
  -H "Content-Type: application/json" \
  -d '{ "number": "08012345678" }'

phone_advance_ng takes the same input and returns the fuller record — registered names, date of birth and address — at a higher price.

Using a phone check for KYC

A verified phone token is enough on its own to carry a Team to KYC tier 2. Attach it as kyc_tokens.phone_number on a KYC submission:

{
  "account_id": 63,
  "kyc_tokens": {
    "phone_number": "c41e77d9b0a24f6e89305ab2"
  }
}