Driver Lookup

Resolve a Presto driver from an identifier and read the two balances that drive the Cash In and Cash Out operations.

Overview

This endpoint is the entry point for both flows. It:

• Validates that the identifier belongs to an active Presto driver
• Returns a partially masked driver name for verification at the counter
• Returns outstanding_debt (settleable via Cash In) and available_earnings (withdrawable via Cash Out)
• Returns the currency all subsequent amounts must be expressed in

It is a read-only call. It reserves nothing and has no expiry.

Endpoint details

Method: POST URL: /api/institutions/v1/drivers/lookup Purpose: Resolve a driver and read settleable balances

Authentication required

All API calls require a valid bearer token. See Authentication.

Request specification

Request parameters

Parameter	Type	Required	Description
driver	object	Yes	Container for driver identification information
driver.identifier_type	string	Yes	Type of identifier being provided. Valid values: "phone", "uid"
driver.identifier	string	Yes	The identifier value: • For "phone": E.164 format (country code + number, no leading +) • For "uid": Presto driver ID

Example request

// Headers:
// Authorization: Bearer {token}
// Content-Type: application/json

{
  "driver": {
    "identifier_type": "phone",
    "identifier": "218920000000"
  }
}

Response specification

Success response

200 OK

{
  "data": {
    "driver": {
      "uid": "10432",
      "name": "MOH... OK...",
      "phone": "218920000000",
      "country_code": "LY",
      "status": "active"
    },
    "balances": {
      "outstanding_debt": 340.500,
      "available_earnings": 128.750,
      "currency": "LYD"
    },
    "capabilities": {
      "cash_in_allowed": true,
      "cash_out_allowed": true,
      "cash_out_daily_remaining": 500.000
    }
  }
}

Response fields

Field	Type	Description
driver.uid	string	Presto driver identifier, stable across the driver's lifetime
driver.name	string	Partially masked driver name, for verification at the counter
driver.phone	string	Registered phone number in E.164 format without the leading +
driver.country_code	string	ISO 3166-1 alpha-2 country code of the driver's operating country
driver.status	string	"active", "suspended" (blocked by Presto operations) or "inactive"
balances.outstanding_debt	number	Amount the driver currently owes Presto, less amounts already reserved by pending Cash In transactions. Upper bound for a Cash In amount
balances.available_earnings	number	Amount Presto currently owes the driver, less amounts already held by pending Cash Out transactions. Upper bound for a Cash Out amount
balances.currency	string	Currency code that all amounts in subsequent calls must use
capabilities.cash_in_allowed	boolean	false when debt settlement is currently blocked for this driver. A suspended driver can still settle debt
capabilities.cash_out_allowed	boolean	false when payout is currently blocked for this driver. Only active drivers can be paid out
capabilities.cash_out_daily_remaining	number	Remaining Cash Out allowance for the driver today

Balances are a snapshot

Balances change while the driver works. Treat the response as valid for the duration of the counter interaction only, and let init be the authority — it re-validates the amount against the live balance.

Error responses

401 Unauthorized

{
  "message": "Unauthenticated."
}

404 Not Found

{
  "message": "Driver not found"
}

422 Unprocessable Content — phone number not in E.164 format

{
  "message": "Invalid phone number format. Number must be in E.164 format without the + prefix (e.g., \"218920000000\")"
}

422 Unprocessable Content — validation error

{
  "message": "The driver.identifier_type field is required.",
  "errors": {
    "driver.identifier_type": [
      "The driver.identifier_type field is required."
    ]
  }
}

Error handling

Common errors

HTTP Status	Error Type	Example Message	When it Occurs / Resolution
401	Unauthorized	{"message": "Unauthenticated."}	Missing or invalid token. Issue a new one.
404	Driver not found	{"message": "Driver not found"}	The identifier matches no driver. Check the type and format.
422	Invalid phone format	{"message": "Invalid phone number format. ..."}	Send the phone as country code + number with no leading +, e.g. 218920000000.
422	Validation error	{"message": "The driver.identifier_type field is required.", "errors": { ... }}	Required fields missing or malformed. Inspect errors.
500	Internal server error	{"message": "Failed to process request"}	Unexpected server error. Retry with backoff or contact support.

Next steps

• To settle debt, continue with Cash In — Initialization.
• To pay out earnings, continue with Cash Out — Initialization.