---
title: "Number lookup"
method: GET
path: "/lookup/{number}"
tags: ["Number Intelligence & HLR"]
---

# Number lookup

`GET /lookup/{number}`

## Request

- Base URL: `https://api.envoisms.ma/v1`
- URL: `https://api.envoisms.ma/v1/lookup/{number}`
- Auth: HTTP bearer

Validate a phone number and resolve its destination and, for Moroccan mobiles, the serving operator — including ported numbers the platform has learned about, which prefix tables alone cannot see. Billed per successful lookup (`lookup` channel of your rate card, 0.05 MAD list price); an invalid number is a 400 and is never billed. Requires the `send` permission scope.

## Path parameters

- `number` string, required

## Response `200`

Lookup result

- object
  - `id` string
  - `number` string
  - `valid` boolean
  - `country_iso` string: ISO 3166-1 alpha-2 of the destination, or XX when unknown.
  - `type` 'mobile' | 'unknown'
  - `operator` string, nullable: Serving operator when known (Moroccan mobiles and major foreign prefixes), else null.
  - `ported` boolean: true when the platform has evidence the number moved to a different operator than its allocated block.
  - `cost` object
    - `eur` number
    - `mad` number

## Other responses

- `400`: Invalid number (not billed)
- `402`: Insufficient balance

---

[API](https://skmtc.dev/envoisms/apis/envoisms-ma-api.md) · [All operations](https://skmtc.dev/envoisms/apis/envoisms-ma-api/llms.txt) · [OpenAPI document](https://skmtc.dev/envoisms/apis/envoisms-ma-api/revisions/662db074bd86?raw)