---
title: "Submit template"
method: POST
path: "/api/v1/templates"
tags: ["templates"]
---

# Submit template

`POST /api/v1/templates`

## Request

- Base URL: `https://app.blueticked.com`
- URL: `https://app.blueticked.com/api/v1/templates`
- Auth: HTTP bearer

Submit a WhatsApp template for Meta approval through a connected WABA.

Only approved templates can be used for outbound WhatsApp sends.

`name` must match `^[a-z0-9_]+$` (lowercase letters, numbers and underscores only); `category` is one of `marketing`, `utility`, `authentication`; `language` defaults to `en_US`.

Optional `footer` (≤60 chars) and up to 3 `buttons`, each `{ type: "url", text, url }`, `{ type: "phone", text, phone }` or `{ type: "quick_reply", text }`.

`channel_id` chooses which connected WhatsApp number submits the template; omit it to use the workspace's connected number.

The template is returned flat (fields at the top level), matching GET /api/v1/templates/{id}.

Category is what the message does: `utility` only for updates about something the customer already has, with no promotional wording (Meta rejects it or moves it to marketing), `marketing` for anything promotional, `authentication` for codes. Number variables {{1}}, {{2}} and on, in order with none skipped.

The API creates templates without a header (a body, with an optional footer and buttons). A template with a DOCUMENT header (a statement or an invoice) is made in the dashboard, then sent with `document` on POST /api/v1/messages or `document_source` on a campaign. A body carrying a header field (any field whose name starts with `header`, in any case: `header`, `header_format`, `headerFormat`) answers 422 `template_kind_unsupported` with details.field naming it, and nothing is created.

## Headers

- `Idempotency-Key` string

## Request body

- object
  - `name` string, required
  - `category` 'marketing' | 'utility' | 'authentication', required
  - `language` string
  - `body` string, required
  - `footer` string, nullable
  - `buttons` union[]
    - union
      - object
        - `type` 'url', required
        - `text` string, required
        - `url` string, uri, required
      - object
        - `type` 'phone', required
        - `text` string, required
        - `phone` string, required
      - object
        - `type` 'quick_reply', required
        - `text` string, required
  - `channel_id` string, uuid, nullable

## Response `201`

Success

- object
  - `id` string, uuid, required
  - `name` string, required
  - `category` 'marketing' | 'utility' | 'authentication', required
  - `language` string, required
  - `status` 'draft' | 'pending' | 'approved' | 'rejected' | 'paused' | 'disabled', required
  - `request_id` string, required

## Other responses

- `400`: Validation failed
- `401`: Unauthorized: missing or invalid API key
- `402`: Insufficient wallet balance
- `403`: Forbidden: scope, plan limit, or suspension
- `404`: Not found
- `409`: Conflict (idempotency-key reuse or resource in use)
- `413`: Request body above the endpoint's size limit
- `422`: Understood but refused: the request is well-formed, the action is not permitted for this resource
- `429`: Rate limited
- `500`: Internal error
- `502`: An upstream provider refused or failed the request
- `503`: Channel or send queue unavailable

---

[API](https://skmtc.dev/blueticked/apis/blueticked-api.md) · [All operations](https://skmtc.dev/blueticked/apis/blueticked-api/llms.txt) · [OpenAPI document](https://skmtc.dev/blueticked/apis/blueticked-api/revisions/07132284f4ff?raw)