List WhatsApp Flows with AvenPing API ​

/v2/forms maps to Meta flows. List and detail come from Graph; search uses the AvenPing database. Auth, Premium/Enterprise, and an active plan are required.

Base: /v2/forms

Auth + Premium/Enterprise + active plan required. See HTTP API v2 Overview.

Prerequisites ​

  • An API token and Premium/Enterprise plan (Authentication)
  • A linked WhatsApp Business account (GET /v2/me)
  • Optional: phoneNumberId or accountId when you need a non-default WABA

Step-by-step ​

  1. Authenticate
    Send Authorization: Bearer YOUR_TOKEN or X-API-Token: YOUR_TOKEN.

  2. Select the WABA (optional)
    Pass query phoneNumberId or accountId on list, search, and get-by-id — same selector as Templates. Without them, list/get use the default WABA; search queries all linked WABAs.

  3. List or search
    GET /v2/forms lists Meta flows from Graph. GET /v2/forms/search queries AvenPing DB rows (q, limit 1–50). Call /search as a path so it is not treated as a flow id.

  4. Fetch one flow
    GET /v2/forms/:flowId returns the Graph object for that flow. Missing flowId returns 400 VALIDATION_ERROR. Graph 4xx map to the same error envelope as other proxied routes.

GET /v2/forms ​

Query (optional): limit (default "25"), after (cursor), phoneNumberId, accountId (same WABA selection as Templates).

Example request:

bash
curl -sS "https://api.avenping.com/v2/forms?limit=25" \
  -H "Authorization: Bearer YOUR_TOKEN"

Response 200:

json
{
  "success": true,
  "data": {
    "items": [
      {
        "id": "flow-id-from-meta",
        "name": "Lead capture",
        "status": "PUBLISHED",
        "categories": ["OTHER"]
      }
    ],
    "paging": {
      "cursors": {
        "after": "QVFIUz..."
      }
    }
  }
}

items are Meta flow objects from GET /{waba-id}/flows (fields vary).

Query

NameTypeDefaultNotes
qstring—Optional filter on name (contains) or status (exact uppercased match)
limitinteger201–50
phoneNumberId / accountIdstring—When set, search only that WABA’s rows; otherwise all linked WABAs

Example request:

bash
curl -sS "https://api.avenping.com/v2/forms/search?q=lead&limit=10" \
  -H "Authorization: Bearer YOUR_TOKEN"

Response 200 — each item is a WhatsAppForm row (Prisma); shape is illustrative:

json
{
  "success": true,
  "data": {
    "items": [
      {
        "id": "flow-id-from-meta",
        "name": "Lead capture",
        "status": "PUBLISHED",
        "validation": [],
        "accountId": "clu01exampleaccountid01",
        "createdAt": "2025-02-10T12:00:00.000Z",
        "updatedAt": "2025-02-11T09:15:00.000Z",
        "_count": {
          "responses": 0
        }
      }
    ]
  }
}

Note: The server registers /search before /:flowId. Call GET /v2/forms/search?q=... so the path is not confused with GET /v2/forms/:flowId.

GET /v2/forms/:flowId ​

Same optional phoneNumberId / accountId query as list (Graph is called with that WABA’s token).

Example request:

bash
curl -sS "https://api.avenping.com/v2/forms/flow-id-from-meta" \
  -H "Authorization: Bearer YOUR_TOKEN"

Response 200 — data is the raw Graph object for GET /{flow-id} (Meta node). Shape varies; often includes id, name, status, and flow definition fields.

json
{
  "success": true,
  "data": {
    "id": "flow-id-from-meta",
    "name": "Lead capture",
    "status": "PUBLISHED"
  }
}

FAQ ​

Why is search a different path from list?

GET /v2/forms lists Meta flows from Graph. GET /v2/forms/search queries AvenPing DB rows. Call /search before /:flowId so search is not treated as a flow id.

Can I list flows for a specific WABA?

Yes. Pass phoneNumberId or accountId as query parameters on list, search, and get-by-id. Search without a selector includes rows from all linked WABAs.

What happens if the flow id is missing?

GET /v2/forms/:flowId returns 400 VALIDATION_ERROR when flowId is empty. Graph errors follow the same envelope as other proxied routes (VALIDATION_ERROR for most 4xx, with details when Meta returns a payload).