Lookup Agent

GET/agents/lookupOpen in the API playground →

Info

Find an agent by their registered phone number. Useful for verifying agents before transactions.

Request

Authorizationstringheaderrequired

Bearer olive_live_xxx or Bearer eyJ... (JWT)

Query Parameters

phone_numberstringqueryrequired

Phone number to search. Accepts local (0771234567) or E.164 (+23277123456)

---

Response

foundboolean

Whether agent was found

agentobject

Agent object if found

---

Examples

Request

cURL

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

Response

200 Found

{
  "found": true,
  "agent": {
    "id": "agent_abc123",
    "type": "super_agent",
    "business_name": "ABC Money Services",
    "first_name": "John",
    "last_name": "Doe",
    "phone_number": "+23277123456",
    "status": "active",
    "location": "Freetown CBD"
  }
}

404 Not Found

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

---

Use Cases

Agent Verification

Verify agent identity before funding

Float Transfer

Find sub-agent before transferring float

---

Errors

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