curl -X GET "https://demo.api.vultlocal.com/api/v1/subscribers/lookup?phone_number=0771234567" \
-H "Authorization: Bearer olive_live_xxx"
{
"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"
}
}
{
"found": false,
"message": "No subscriber found with this phone number"
}
Subscribers
Lookup Subscriber
Find subscriber by phone number
GET
/
subscribers
/
lookup
curl -X GET "https://demo.api.vultlocal.com/api/v1/subscribers/lookup?phone_number=0771234567" \
-H "Authorization: Bearer olive_live_xxx"
{
"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"
}
}
{
"found": false,
"message": "No subscriber found with this phone number"
}
Use this endpoint to find a subscriber by phone number instead of ID.
Request
string
required
Bearer olive_live_xxx or Bearer eyJ... (JWT)Query Parameters
string
required
Phone number to search. Accepts:
- Local format:
0771234567 - E.164 format:
+23279123456
Response
boolean
Whether subscriber was found
object
Subscriber object if found
Examples
curl -X GET "https://demo.api.vultlocal.com/api/v1/subscribers/lookup?phone_number=0771234567" \
-H "Authorization: Bearer olive_live_xxx"
{
"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"
}
}
{
"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 |
⌘I