Authentication & requirements ​

This page explains what you need before calling the API and how to authenticate. Endpoint detail is organized by topic: start at HTTP API v2 Overview, then use the sidebar or Developer API capability map.

Get your API token ​

  1. Sign in to the AvenPing app.
  2. Open Settings → API Settings.
  3. Generate or copy your API access token.

Treat it like a password: store it in secrets management, never commit it to source control, and never expose it in browser-side code.

Base URL and version ​

EnvironmentBase URL
Productionhttps://api.avenping.com

All documented REST routes use the /v2 prefix (for example GET https://api.avenping.com/v2/health).

Send the token on every protected request ​

You can use either form (same token value):

http
Authorization: Bearer YOUR_TOKEN_HERE
http
X-API-Token: YOUR_TOKEN_HERE

Missing or invalid tokens receive 401 with error code UNAUTHORIZED.

Token revocation

Regenerating the token in the dashboard invalidates the previous token immediately.

Subscription and plan rules ​

After the token is validated, the API enforces:

  1. Active plan — your primary subscription must not be expired (403 PLAN_EXPIRED if it is).
  2. Premium or Enterprise — API access is limited to these plans (403 DEVELOPER_PLAN_REQUIRED otherwise).
  3. Linked WhatsApp Business account — your user must have a WhatsApp account with a valid Meta access token in AvenPing (404 NOT_FOUND if the account is missing).

The only v2 routes that work without a token are GET /v2/health and GET /v2/version.

Phone number ID (phoneNumberId) ​

For messages and for template send endpoints, the JSON body must include phoneNumberId: the Meta Phone number ID for the WhatsApp number you use with AvenPing. That ID must belong to your workspace (403 FORBIDDEN if it does not).

You can obtain this ID from the Meta Business / WhatsApp configuration or from tooling your team uses to register numbers.

Success and error format ​

Successful JSON responses typically look like:

json
{
  "success": true,
  "data": {}
}

Errors:

json
{
  "success": false,
  "error": "ERROR_CODE",
  "message": "Human-readable explanation"
}

See the reference overview — Error response shape for all application error codes.

First request (health check) ​

No authentication:

bash
curl -s https://api.avenping.com/v2/health

Example response:

json
{ "success": true, "data": { "ok": true } }

Discover phone number IDs (GET /v2/me) ​

Replace YOUR_TOKEN:

bash
curl -s https://api.avenping.com/v2/me \
  -H "Authorization: Bearer YOUR_TOKEN"

Use each object’s phoneNumberId (Meta) in message and template send bodies. If defaultPhoneNumberId is set, your account has exactly one line and that value is the usual sender id.

First authenticated request (example) ​

List templates (requires Premium/Enterprise and linked WhatsApp account):

bash
curl -s https://api.avenping.com/v2/templates \
  -H "Authorization: Bearer YOUR_TOKEN"

Next steps ​