HTTP API v2 Overview

This is the main API reference hub. Endpoint details are split into focused pages so the table of contents stays usable.

Topic	Page
Root URL, health, version (no token)	Public & meta
Current user, WABA id, phone number IDs	Account
Message templates	Templates
Flows (Meta) + DB search	Forms (flows)
Download media by Meta media id	Media
Send messages (text, media, interactive, smart /send)	Messages
Outbound webhook URL (dashboard parity)	Webhooks

For setup and your first calls, see Authentication & requirements. For Postman, see Postman collection.

---

Conventions

• Replace https://api.avenping.com with your environment’s base URL if different.
• Replace YOUR_TOKEN with your API token (Settings → API Settings).
• data from WhatsApp Graph (messages, templates list, flows from Meta, etc.) is largely a pass-through of Meta’s Cloud API. Exact fields vary by API version and resource; examples on each page are illustrative.

Base path: all v2 routes are under /v2.
Content-Type: use application/json for request bodies (when applicable).
Body size limit: 2 MB per JSON body.

---

Authentication

Send the same secret you see in the AvenPing app under Settings → API Settings (API access token).

Method	How
Bearer	Header Authorization: Bearer <token>
Header	X-API-Token: <token>

If the token is missing or invalid, the API responds with 401 and code UNAUTHORIZED.

Example (Bearer):

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

More detail: Authentication & requirements.

---

Access rules (after auth)

Middleware order matters:

1. requireAuthToken — valid user, linked WhatsApp account with Meta accessToken. If the user has no WhatsApp account configured, you may see 404 NOT_FOUND with message WhatsApp account not found.
2. requireActivePlan — primary (non–add-on) plan must not be past its end date. Otherwise 403 PLAN_EXPIRED.
3. requirePremiumOrEnterprise — primary plan name must be Premium or Enterprise. Otherwise 403 DEVELOPER_PLAN_REQUIRED.

These apply to every /v2/* route except the routes on Public & meta (GET /v2/health, GET /v2/version).

---

Phone number ownership

These routes require a JSON body field phoneNumberId (Meta Phone number ID). The server checks that this ID belongs to your AvenPing WhatsApp account:

• All routes under /v2/messages/*
• POST /v2/templates/send
• POST /v2/templates/:name/test-send

Use GET /v2/me to list valid phoneNumberId values for your token.

If phoneNumberId is missing: 400 VALIDATION_ERROR.
If it is not linked to your account: 403 FORBIDDEN (phoneNumberId does not belong to this account).

---

Success response shape

Most JSON endpoints return:

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

The data object (or array) is endpoint-specific. Message send and template send endpoints usually return Meta’s send-message response inside data (e.g. messaging_product, contacts, messages with id / WAMID). See Messages for a typical send payload.

---

Error response shape

Structured errors use:

{
  "success": false,
  "error": "ERROR_CODE",
  "message": "Human-readable message",
  "details": null
}

details is omitted when empty; some errors may attach structured details.

Example (401):

{
  "success": false,
  "error": "UNAUTHORIZED",
  "message": "Missing API token"
}

Error codes (application)

HTTP	error	Typical cause
401	UNAUTHORIZED	Missing/invalid token, deleted user
403	FORBIDDEN	phoneNumberId not owned by account
403	PLAN_EXPIRED	Subscription ended
403	DEVELOPER_PLAN_REQUIRED	Plan is not Premium/Enterprise
400	VALIDATION_ERROR	Bad input, missing required fields
404	NOT_FOUND	Resource missing (template, media URL, unknown route)
500	INTERNAL_ERROR	Unexpected failure, upstream/Graph failure surfaced as generic error
502	INTERNAL_ERROR	Media download proxy failed (message: Failed to download media)

Note: Invalid JSON bodies or Zod validation failures may still be handled by the generic error handler and appear as 500 with INTERNAL_ERROR depending on how the error propagates. Prefer matching the documented request shapes on each group page.