Number Check API

Swagger UI

Verify whether phone numbers are registered on WhatsApp using a connected session. Numbers must include the country code.

Use a connected WhatsApp session to query WhatsApp registration status. Dashboard routes require JWT (`contacts:read`). External routes require an API key with the `numbers:check` permission.

POST/api/v1/number-check

Check single number

Check if one phone number is registered on WhatsApp.

URL: https://api.actiwapi.com/api/v1/number-check

Auth: JWT Bearer

Headers

HeaderValueRequired
AuthorizationBearer {accessToken}Yes
Content-Typeapplication/jsonYes*

Request example

{
  "sessionId": "uuid-of-connected-session",
  "phone": "+919876543210"
}

Code examples

curl -X POST "https://api.actiwapi.com/api/v1/number-check" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {accessToken}"
  -d '{  "sessionId": "uuid-of-connected-session",  "phone": "+919876543210"}'

Response example200

{
  "success": true,
  "data": {
    "sessionId": "uuid",
    "result": {
      "phone": "919876543210",
      "displayPhone": "+919876543210",
      "exists": true,
      "jid": "919876543210@s.whatsapp.net",
      "whatsappRegistered": true
    }
  }
}

Try in Swagger UI

POST/api/v1/number-check/bulk

Bulk check numbers

Check up to 500 numbers in one request. Use `phones` array or multiline `text`.

URL: https://api.actiwapi.com/api/v1/number-check/bulk

Auth: JWT Bearer

Headers

HeaderValueRequired
AuthorizationBearer {accessToken}Yes
Content-Typeapplication/jsonYes*

Request example

{
  "sessionId": "uuid-of-connected-session",
  "phones": ["+14155552671", "+919876543210"]
}

Code examples

curl -X POST "https://api.actiwapi.com/api/v1/number-check/bulk" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {accessToken}"
  -d '{  "sessionId": "uuid-of-connected-session",  "phones": ["+14155552671", "+919876543210"]}'

Response example200

{
  "success": true,
  "data": {
    "sessionId": "uuid",
    "summary": {
      "total": 2,
      "registered": 1,
      "notRegistered": 1,
      "invalid": 0,
      "truncated": 0
    },
    "results": [
      {
        "phone": "14155552671",
        "displayPhone": "+14155552671",
        "exists": true,
        "jid": "14155552671@s.whatsapp.net",
        "whatsappRegistered": true
      }
    ],
    "invalid": []
  }
}

Try in Swagger UI

POST/api/external/number-check

Check single number (API key)

Check one number via API key. Requires `numbers:check` permission.

URL: https://api.actiwapi.com/api/external/number-check

Auth: API Key

Headers

HeaderValueRequired
X-API-Key{apiKey}Yes
Content-Typeapplication/jsonYes*

Request example

{
  "sessionId": "uuid-of-connected-session",
  "phone": "+919876543210"
}

Code examples

curl -X POST "https://api.actiwapi.com/api/external/number-check" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: {apiKey}"
  -d '{  "sessionId": "uuid-of-connected-session",  "phone": "+919876543210"}'

Response example200

{
  "success": true,
  "data": {
    "sessionId": "uuid",
    "result": {
      "phone": "919876543210",
      "displayPhone": "+919876543210",
      "exists": true,
      "whatsappRegistered": true
    }
  }
}

Try in Swagger UI

POST/api/external/number-check/bulk

Bulk check numbers (API key)

Bulk number check via API key. Requires `numbers:check` permission.

URL: https://api.actiwapi.com/api/external/number-check/bulk

Auth: API Key

Headers

HeaderValueRequired
X-API-Key{apiKey}Yes
Content-Typeapplication/jsonYes*

Request example

{
  "sessionId": "uuid-of-connected-session",
  "text": "+14155552671\n+919876543210"
}

Code examples

curl -X POST "https://api.actiwapi.com/api/external/number-check/bulk" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: {apiKey}"
  -d '{  "sessionId": "uuid-of-connected-session",  "text": "+14155552671\n+919876543210"}'

Response example200

{
  "success": true,
  "data": {
    "sessionId": "uuid",
    "summary": { "total": 2, "registered": 1, "notRegistered": 1, "invalid": 0 },
    "results": [],
    "invalid": []
  }
}

Try in Swagger UI

Error codes

Failed requests return a JSON envelope with success: false and a human-readable message.

{
  "success": false,
  "message": "Validation failed",
  "errors": {
    "phone": "Valid phone number is required"
  }
}
HTTPCodeDescription
400VALIDATION_ERRORRequest body or query failed validation.
401UNAUTHORIZEDMissing or invalid JWT / API key.
403FORBIDDENAuthenticated but lacking permission or entitlement.
403SUBSCRIPTION_INACTIVETrial expired or subscription not active.
403LIMIT_EXCEEDEDPlan limit reached (sessions, messages, API requests, etc.).
404NOT_FOUNDResource does not exist or is not in your account.
409CONFLICTDuplicate resource or invalid state transition.
429RATE_LIMITEDToo many requests; retry after backoff.
500INTERNAL_ERRORUnexpected server error.
502WHATSAPP_UNAVAILABLEWhatsApp session disconnected or provider error.

← Back to Getting Started