# List templates

`GET /v1/templates`

Returns a page of your workspace's templates, newest first. Every filter is optional, and the ones you give all have to match.

Needs `templates:read`.

## Query parameters

- `limit` (integer): How many items to return. From 1 to 100. Default `25`.
- `cursor` (string): The `next_cursor` of the previous page, unchanged. A cursor that was changed, or made for a different `sort`, is `400 invalid_request`.
- `sort` (string): `created_at` lists newest first. `updated_at` lists oldest change first. Default `created_at`.
- `number_id` (string, uuid): Only templates on this number (see `GET /v1/numbers`). A number that isn't in your workspace matches nothing.
- `status` (string): Only templates with this status, for example `APPROVED`. Case doesn't matter.
- `name` (string): Only templates with exactly this name (every language of it).
- `language` (string): Only templates in this language, for example `en` or `pt_BR`.
- `category` (string): Only templates in this category, for example `MARKETING`. Case doesn't matter.

## Following WhatsApp's review

Use `sort=updated_at` to follow the review. A template moves to the end of the list each time its status changes. See [Pagination](/reference/api/#pagination).

## Example

```sh
curl "https://app.soosh.io/v1/templates?status=APPROVED" \
  -H "Authorization: Bearer $SOOSH_API_KEY"
```

Response 200:

```json
{
  "data": [
    {
      "id": "2f9a6c1d-5e3b-4a78-8c04-b1d7e5f3a920",
      "name": "order_update",
      "language": "en",
      "category": "UTILITY",
      "status": "APPROVED",
      "rejection_reason": null,
      "quality": "GREEN",
      "number_id": "0f6d3c1e-5b7a-4c52-9a55-3f6a2d5c8b10",
      "parameter_format": "positional",
      "header": {
        "format": "TEXT",
        "text": "Order {{1}}"
      },
      "body": "Hi {{1}}, your order {{2}} is on its way.",
      "footer": "Thanks for shopping with us",
      "buttons": [
        {
          "type": "URL",
          "text": "Track",
          "url": "https://example.com/track/{{1}}"
        }
      ],
      "variables": {
        "header": [
          "1"
        ],
        "body": [
          "1",
          "2"
        ],
        "buttons": {
          "0": [
            "1"
          ]
        }
      },
      "created_at": "2026-10-01T06:15:03.774Z",
      "updated_at": "2026-10-01T06:42:19.008Z"
    }
  ],
  "next_cursor": null
}
```

## Returns

200. A page of templates.