---
title: "get chat ID from phone number"
method: POST
path: "/instances/{id}/client/action/get-number-id"
tags: ["number"]
---

# get chat ID from phone number

`POST /instances/{id}/client/action/get-number-id`

## Request

- Base URL: `https://waapi.app/api/v1`
- URL: `https://waapi.app/api/v1/instances/{id}/client/action/get-number-id`
- Auth: HTTP bearer

Converts a phone number into the proper chat ID format. This is especially useful for countries that don't follow the standard chat ID format (like Brazil, Mexico and Argentina). The endpoint ensures you get the correct chat ID for any phone number.

## Path parameters

- `id` integer, required

## Request body

- object
  - `number` string, required: Phone number in international format without leading + or 00

## Response `200`

Request reached the instance. `data.status` reports whether the action was carried out; on error `data` carries `message` and `explanation`. Payload: Successfully retrieved chat ID.

- object
  - `data` union: The action's outcome. `status: success` carries the payload; `status: error` is an `actionError`.
    - object
      - `status` 'success', required: Whether the instance carried the action out — the authoritative field. In this branch it is always `success`; when the instance refused the action the whole `data` object is an `actionError` with `status: error`, `message` and `explanation`.
      - `instanceId` union
        - integer
        - string
      - `data` object
        - `numberId` object
          - `server` string: server suffix
          - `user` string: Phone number in international format
          - `_serialized` string: Complete chat ID
    - ActionError: Shape of `data` when the instance refused the action. HTTP status is still 200 and the outer `status` is still `success`.
      - `status` 'error', required
      - `message` string
      - `explanation` string
      - `instanceId` union
        - integer
        - string
  - `links` object
    - `self` string
  - `status` 'success' | 'error': Whether the request reached the instance. `success` here does **not** mean the action was carried out — that is reported by `data.status`, which is the authoritative one. A malformed input arrives as `status: success` with `data.status: error`.

## Other responses

- `401`: Unauthorized — invalid or missing bearer token
- `403`: Forbidden — insufficient permissions or account blocked
- `404`: Not found — instance does not exist or does not belong to you
- `409`: Conflict — instance is not ready
- `422`: Validation error — invalid or missing request parameters
- `429`: Too many requests — rate limit exceeded

---

[API](https://skmtc.dev/waapi/apis/waapi-api-2.md) · [All operations](https://skmtc.dev/waapi/apis/waapi-api-2/llms.txt) · [OpenAPI document](https://skmtc.dev/waapi/apis/waapi-api-2/revisions/490302f75576?raw)