Lookup Subscriber

GET/subscribers/lookupOpen in the API playground →

Info

Use this endpoint to find a subscriber by phone number instead of ID.

Request

Authorizationstringheaderrequired

Bearer olive_live_xxx or Bearer eyJ... (JWT)

Query Parameters

phone_numberstringqueryrequired

Phone number to search. Accepts:

• Local format: 0771234567
• E.164 format: +23279123456

---

Response

foundboolean

Whether subscriber was found

subscriberobject

Subscriber object if found

---

Examples

Request

cURL

curl -X GET "https://demo.api.vultlocal.com/api/v1/subscribers/lookup?phone_number=0771234567" \
  -H "Authorization: Bearer olive_live_xxx"

Response

200 Found

{
  "found": true,
  "subscriber": {
    "id": "sub_abc123",
    "phone_number": "+23279123456",
    "first_name": "John",
    "last_name": "Doe",
    "kyc_level": 2,
    "status": "ACTIVE",
    "balance": "125,000.00 SLE"
  }
}

404 Not Found

{
  "found": false,
  "message": "No subscriber found with this phone number"
}

---

Use Cases

Pre-Transfer Check

Verify recipient exists before P2P transfer

Agent Cash-In

Find subscriber before processing cash deposit

---

Errors

Status	Code	Description
400	MISSING_PHONE	phone_number query param required
401	UNAUTHORIZED	Invalid or missing API key
404	NOT_FOUND	No subscriber with this phone
500	INTERNAL_ERROR	Server error