Create a template

POST /v1/templates

Creates a template and submits it to WhatsApp for review. WhatsApp approves or rejects it later.

Needs templates:write. Counts against the heavy request limit (10 a minute).

If WhatsApp refuses the template, Soosh keeps it as a DRAFT in the app, and error.details.id is the draft.

A utility template with a link

curl -X POST https://app.soosh.io/v1/templates \
  -H "Authorization: Bearer $SOOSH_API_KEY" \
  -H "Idempotency-Key: create-template-a-utility-template-1" \
  -H "Content-Type: application/json" \
  -d '{
    "number_id": "0f6d3c1e-5b7a-4c52-9a55-3f6a2d5c8b10",
    "name": "order_update",
    "language": "en",
    "category": "UTILITY",
    "header": {
      "format": "TEXT",
      "text": "Order {{1}}",
      "example": "A-1001"
    },
    "body": "Hi {{1}}, your order {{2}} is on its way.",
    "body_examples": [
      "Priya",
      "A-1001"
    ],
    "footer": "Thanks for shopping with us",
    "buttons": [
      {
        "type": "URL",
        "text": "Track",
        "url": "https://example.com/track/{{1}}",
        "example": "A-1001"
      }
    ]
  }'

const res = await fetch('https://app.soosh.io/v1/templates', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.SOOSH_API_KEY}`,
    'Idempotency-Key': 'create-template-a-utility-template-1',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "number_id": "0f6d3c1e-5b7a-4c52-9a55-3f6a2d5c8b10",
    "name": "order_update",
    "language": "en",
    "category": "UTILITY",
    "header": {
      "format": "TEXT",
      "text": "Order {{1}}",
      "example": "A-1001"
    },
    "body": "Hi {{1}}, your order {{2}} is on its way.",
    "body_examples": [
      "Priya",
      "A-1001"
    ],
    "footer": "Thanks for shopping with us",
    "buttons": [
      {
        "type": "URL",
        "text": "Track",
        "url": "https://example.com/track/{{1}}",
        "example": "A-1001"
      }
    ]
  }),
});
console.log(await res.json());

import os
import requests

res = requests.post(
    "https://app.soosh.io/v1/templates",
    headers={"Authorization": f"Bearer {os.environ['SOOSH_API_KEY']}", "Idempotency-Key": "create-template-a-utility-template-1"},
    json={
        "number_id": "0f6d3c1e-5b7a-4c52-9a55-3f6a2d5c8b10",
        "name": "order_update",
        "language": "en",
        "category": "UTILITY",
        "header": {
            "format": "TEXT",
            "text": "Order {{1}}",
            "example": "A-1001",
        },
        "body": "Hi {{1}}, your order {{2}} is on its way.",
        "body_examples": [
            "Priya",
            "A-1001",
        ],
        "footer": "Thanks for shopping with us",
        "buttons": [
            {
                "type": "URL",
                "text": "Track",
                "url": "https://example.com/track/{{1}}",
                "example": "A-1001",
            },
        ],
    },
)
print(res.json())

Response201

{
  "id": "2f9a6c1d-5e3b-4a78-8c04-b1d7e5f3a920",
  "name": "order_update",
  "language": "en",
  "category": "UTILITY",
  "status": "PENDING",
  "rejection_reason": null,
  "quality": "UNKNOWN",
  "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:15:03.774Z"
}

Every field of the template object

Body

number_id string · uuid Required

The number to make the template on (see GET /v1/numbers).

name string Required

Lowercase letters, numbers and underscores, up to 255 characters. Unique per number and language.

language string Required

A WhatsApp language code, such as en or pt_BR.

category string Required

Authentication templates are made in the app.

One of MARKETING UTILITY.

body string Required

Up to 1024 characters. Variables are {{1}}, {{2}} in order, or {{name}}; not both.

header object

A text header. Image, video and document headers are made in the app.

Show 3 child parametersHide child parameters

header.format string Required

Always TEXT.

header.text string Required

Up to 60 characters, with at most one variable.

header.example string

An example for the header’s variable. Required when it has one.

body_examples array of strings

One example for each variable of the body, in the order they first appear. Required when the body has variables.

footer string

Up to 60 characters.

buttons array of objects

Up to 10 buttons. Keep quick replies together, before or after the others.

Show 5 child parametersHide child parameters

Each item:

buttons[].type string Required

One of QUICK_REPLY URL PHONE_NUMBER COPY_CODE.

buttons[].text string

Up to 25 characters. Not used by COPY_CODE.

buttons[].url string

For URL. May end in {{1}}.

buttons[].phone_number string

For PHONE_NUMBER, for example +14155550123.

buttons[].example string

For URL with a {{1}}: an example for the variable. For COPY_CODE: the sample code (up to 20 characters).

Headers

Idempotency-Key string

Send one so a retry doesn’t create the template twice. See Retrying safely.

1 to 255 characters.

Names and languages

A template is the same one only in the same language. The same name in another language is a new template.

Copy-code buttons

A COPY_CODE button needs an example code. Its value is required again when you send the template: variables.buttons of the template lists it, and POST /v1/messages must supply it.

Returns

201 The template object. The template, PENDING until WhatsApp decides. Follow it with GET /v1/templates/{id} or the template.status webhook.

Errors

Besides the ones every request can get:

422invalid_fieldA field breaks a rule, such as a header that isn’t TEXT, or WhatsApp refuses the template.

409conflictThe name and language already exist on this number. error.details.id is the existing template.

409idempotency_in_progressA request with the same Idempotency-Key is still running.

422idempotency_mismatchThe Idempotency-Key was used before for a different request, or by another of your API keys.