---
title: "List WhatsApp Templates with OAuth 2.0"
slug: "list-whatsapp-templates-with-oauth-2-0"
description: "Documents the OAuth 2.0-authenticated GET /api/wa/v2/templates endpoint for listing WhatsApp templates with pagination, filters, sorting, and error responses."
tags: ["add cta", "whatsapp api template message", "transactional whatsapp api"]
updated: 2026-11-02T11:51:20Z
published: 2026-11-02T11:51:20Z
canonical: "academy.insiderone.com/list-whatsapp-templates-with-oauth-2-0"
---

> ## Documentation Index
> Fetch the complete documentation index at: https://academy.insiderone.com/llms.txt
> Use this file to discover all available pages before exploring further.

# List WhatsApp Templates with OAuth 2.0

You can use the WhatsApp Template Management API to receive a list of your managed WhatsApp templates with OAuth 2.0. You can use this API version if you authenticate requests with OAuth 2.0.

> [!WARNING]
> **Field naming rule**
> 
> The token generation request uses snake_case fields, such as **client_id** and **client_secret**. Template CRUD request bodies use camelCase fields, such as **name**, **language,** **category**, and **components**.

## Endpoint and Headers

> **GET** https://gw.useinsider.com/api/wa/v2/templates

| Header | Sample Value | Description |
| --- | --- | --- |
| Authorization: Bearer your-oauth2-token | 1a2b3c4d5e6f | This key is required to authorize your request. Refer to [Generate OAuth 2.0 Credentials for WhatsApp Template Management](/v1/docs/generate-api-credentials-for-whatsapp-template-management#generate-oauth-20-credentials-for-whatsapp-template-management) to generate your credentials. |
| Content-Type | application/json | This header specifies the media type of the resource. |

## Body Parameters

| Column | Data Type | Required | Description |
| --- | --- | --- | --- |
| name | String | Yes | The template name to create. |
| language | String | Yes | The template locale, such as **en_US**. |
| category | String | Yes | The Meta template category. |
| components | Array[object] | Yes | At least one component is required. |
| bid_spec | Object | No | Opt-in for dynamic pricing. Only valid for MARKETING templates. |

## Sample Request

You can filter and paginate the template list with query parameters such as `page`, `per_page`, `name`, `statuses[]`, `languages[]`, `qualities[]`, and `sort`.

```bash
curl --location 'https://gw.useinsider.com/api/wa/v2/templates?page=1&per_page=10&statuses[]=APPROVED&languages[]=en_US&sort=createdAt|desc' \
--header 'Authorization: Bearer your-oauth2-token'
```

## Sample Response

A successful request returns the following JSON response with a paginated list of your WhatsApp templates.

```json
{
  "data": [
    {
      "id": 42,
      "name": "spring_campaign_template",
      "language": "en_US",
      "quality": "PENDING",
      "status": "APPROVED"
    }
  ],
  "current_page": 1,
  "last_page": 1,
  "per_page": 10,
  "total": 1,
  "from": 1,
  "to": 1
}
```

### Status Values

The `statuses[]` filter and the `status` field in the response use the following values.

| Status | Description |
| --- | --- |
| APPROVED | Meta approved the template and you can send it. |
| PENDING | The template is waiting for Meta's review to start. |
| IN-REVIEW | Meta is reviewing the template. You cannot edit it until Meta responds. |
| REJECTED | Meta rejected the template. You can edit it and resubmit. |
| PAUSED | Meta paused the template because of low quality. You cannot send messages with it, but you can edit it. |
| ARCHIVED | The template had no activity for 12 months. You can restore it within 28 days. |

To find archived templates, send `statuses[]=ARCHIVED` in your request.

> [!NOTE]
> To restore an archived template, refer to [Restore an Archived WhatsApp Template with OAuth 2.0](https://academy.insiderone.com/docs/restore-an-archived-whatsapp-template-with-oauth-2-0).

## Sample Error Responses

Most template endpoint failures return a JSON body with a `message` field. Creating validation failures can also include an `error` field. OAuth token and scope failures may be returned by the Gateway before the request reaches the template service.

### 401 Unauthorized: Invalid OAuth Client Credentials

You will receive this error if the token request contains an invalid `client_id` or `client_secret`,

```json
{
  "message": "invalid client credentials"
}
```

### 401 Unauthorized: Missing or Invalid Bearer Token

You will receive this error if the token is missing, expired, or malformed.

```json
{
  "message": "unauthorized"
}
```

### 403 Forbidden: Missing Required Scope

You will receive this error if the token does not include the required scope for the operation.

```json
{
  "message": "forbidden"
}
```

### 400 Bad Request: Invalid JSON Body

You will receive this error if the request body cannot be decoded.

```json
{
  "message": "failed to decode request"
}
```

### 400 Bad Request: Missing Required Fields

You will receive this error if a required field, such as `name`, `language`, or `components` is missing.

```json
{
  "message": "failed to validate request",
  "error": "Key: 'CreateRequest.Name' Error:Field validation for 'Name' failed on the 'required' tag"
}
```

### 400 Bad Request: Empty Components Array

You will receive this error if `components` is provided but empty.

```json
{
  "message": "failed to validate request",
  "error": "Key: 'CreateRequest.Components' Error:Field validation for 'Components' failed on the 'min' tag"
}
```

### Invalid List Query Parameters

You will receive this error if the “List” endpoint validation runs before querying templates.

```json
{ "message": "page must be a positive integer" }
{ "message": "per_page must be between 1 and 100" }
{ "message": "sort must be in column|direction format" }
{ "message": "sort column is invalid" }
{ "message": "sort direction is invalid" }
```

### 400 Buttons Total Exceeded, Buttons URL Exceeded, Buttons Phone Exceeded, Buttons Copy Code Exceeded, Buttons Request Contact Info Exceeded, Buttons Interleaved

For combined-button validation errors, the detail arrives only via error.key. error.code and error.subcode are reserved for Meta-sourced errors and are not returned for these validation errors.

The message format is "<description> (<scope>)", where scope refers to the failing button group (e.g., components[1].buttons).

Below is the payload for accepted create.

```json
{
  "name": "order_update_combined",
  "language": "en",
  "category": "UTILITY",
  "components": [
    {
      "type": "BODY",
      "text": "Hi {{1}}, your order {{2}} is on its way."
    },
    {
      "type": "BUTTONS",
      "buttons": [
        {
          "type": "URL",
          "text": "Track order",
          "url": "https://shop.example.com/track/{{1}}",
          "example": [
            "https://shop.example.com/track/12345"
          ]
        },
        {
          "type": "PHONE_NUMBER",
          "text": "Call us",
          "phone_number": "+905000000000"
        },
        {
          "type": "QUICK_REPLY",
          "text": "Delivered"
        },
        {
          "type": "QUICK_REPLY",
          "text": "Not received"
        }
      ]
    }
  ]
}
```

Below is the rejected payload.

```plaintext
"buttons": [
  {
    "type": "URL",
    "text": "Track order",
    "url": "https://shop.example.com/track/{{1}}"
  },
  {
    "type": "QUICK_REPLY",
    "text": "Delivered"
  },
  {
    "type": "PHONE_NUMBER",
    "text": "Call us",
    "phone_number": "+905000000000"
  }
]
```

This returns 400 with buttons.interleaved, because the phone button falls behind the Quick Reply.

Below is the 400 response body.

```json
{
  "message": "call-to-action and quick reply buttons must each be contiguous; interleaved ordering is not supported (components[1].buttons)",
  "error": {
    "key": "buttons.interleaved"
  }
}
```

### 400 Bad Request: Invalid Template ID in Path

You will receive this error if the `:id` path parameter is not numeric.

```json
{
  "message": "template id is invalid"
}
```

### 404 Not Found: Template Not Found

You will receive this error if the template does not exist for the authenticated partner, the detail and delete endpoints return.

```json
{
  "message": "template not found"
}
```

### 422 Unprocessable Entity: Router Domain Missing for URL Buttons

You will receive this error if you create a template with URL buttons, but you have no active WhatsApp router domain.

```json
{
  "message": "active whatsapp router domain not found"
}
```

### Meta Rejects the Template Payload

You will receive this error if Meta validation errors are exposed as readable messages. Unsupported button combinations are a common example.

```json
{
  "message": "Invalid parameter - buttons: quick reply and url combination is not supported"
}
```

### 400 Bad Request: Upload Request Without a File

You will receive this error if the multipart upload request does not contain a `file` field.

```json
{
  "message": "file is required"
}
```

### 429 Too Many Requests: Upload Rate Limit Exceeded

You will receive this error if you exceed the upload quota.

```json
{
  "message": "upload rate limit exceeded"
}
```

### Media Upload Fails Upstream

If Meta rejects the uploaded file type or upload session, the API returns the upstream message.

```json
{
  "message": "Unsupported post request. Object with ID 'upload-session-id' does not exist"
}
```

### Unexpected Upstream or Local Failure

In less common cases, the API can return internal decoding or persistence errors.

```json
{ "message": "failed to decode template creation response" }
{ "message": "template created in Meta but could not be persisted locally" }
```