Mobile Lookup

Detect which mobile operator serves a given phone number, returning the topup products to charge against

`POST /api/v1/topups/lookup`

Identifies which operators serve a given mobile number. Octopus Cards resolves the number, intersects the result with your active MOBILE catalogue, and returns the matching products. Use the returned product_id directly with /topups/charges or /topups/orders.

This endpoint is only useful for mobile recharges. For gaming top-ups, ask the customer for their player/account ID and go straight to charges.

Request

curl -X POST "https://api.octopuscards.io/api/v1/topups/lookup" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "mobile_number": "+918879685100"
  }'

Request Parameters

Key	Type	Required	Description
`mobile_number`	string	Yes	Mobile number in E.164 format (leading `+`, country code, digits). Example: `+918879685100`.

Response

The endpoint returns a bare JSON array of operators — no envelope object. The array is ordered with Octopus Cards's primary/best guess first.

[
  {
    "product_id": 4219,
    "name": "Airtel India",
    "country_code": "IND",
    "identified": true
  },
  {
    "product_id": 4231,
    "name": "Vi (Vodafone Idea) India",
    "country_code": "IND",
    "identified": false
  }
]

The array may be empty if the number could not be identified, or if no matching MOBILE product exists in your catalogue.

Response Fields

Each array entry:

Key	Type	Description
`product_id`	integer	Use this directly with `/topups/charges` and `/topups/orders`.
`name`	string	Operator display name (e.g. "Airtel India").
`country_code`	string	ISO 3166-1 alpha-3 country code (e.g. `IND`).
`identified`	boolean	`true` for Octopus Cards's primary/best guess; `false` for alternatives the customer can disambiguate.

Errors

400 Bad Request — mobile_number missing or empty.

{
  "error": {
    "name": "ValidationException",
    "code": "VALIDATION_FAILURE",
    "message": "mobile_number is required"
  }
}