> For the complete documentation index, see [llms.txt](https://docs.taqnyat.sa/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.taqnyat.sa/api-reference/templates/create-template/document-template.md).

# Document Template

## Create Document Template

Use this endpoint to create a WhatsApp template with a **document header**.

The template is submitted for approval and can be used for sending only after it is approved.

### Endpoint

```http
POST /templates/
```

Full URL:

```
https://api.taqnyat.sa/wa/v2/templates/
```

### Authentication

Include your API token in the request header:

```http
Authorization: <YOUR_TOKEN>
Content-Type: application/json
```

### Request Parameters

| Parameter               | Type   | Required   | Description                                                        |
| ----------------------- | ------ | ---------- | ------------------------------------------------------------------ |
| `name`                  | String | Yes        | Unique name of the template.                                       |
| `language`              | String | Yes        | Language code of the template.                                     |
| `category`              | String | Yes        | Template category, such as `UTILITY` or `MARKETING`.               |
| `components`            | Array  | Yes        | Contains the template body and document header.                    |
| `components[].type`     | String | Yes        | Component type, such as `BODY` or `HEADER`.                        |
| `components[].text`     | String | For body   | Text content of the template body.                                 |
| `format`                | String | For header | Must be `DOCUMENT`.                                                |
| `example.header_handle` | Array  | Yes        | Contains the document reference used when submitting the template. |

### Example Payload

```json
{
  "name": "document_update",
  "language": "en",
  "category": "UTILITY",
  "components": [
    {
      "type": "BODY",
      "text": "This is a test message"
    },
    {
      "type": "HEADER",
      "format": "DOCUMENT",
      "example": {
        "header_handle": [
          "<DOCUMENT_LINK>"
        ]
      }
    }
  ]
}
```

### Example Request

```bash
curl --location 'https://api.taqnyat.sa/wa/v2/templates/' \
--header 'Content-Type: application/json' \
--header 'Authorization: <YOUR_TOKEN>' \
--data '{
  "name": "document_update",
  "language": "en",
  "category": "UTILITY",
  "components": [
    {
      "type": "BODY",
      "text": "This is a test message"
    },
    {
      "type": "HEADER",
      "format": "DOCUMENT",
      "example": {
        "header_handle": [
          "<DOCUMENT_LINK>"
        ]
      }
    }
  ]
}'
```

### Body Component

The `BODY` component contains the main template text:

```json
{
  "type": "BODY",
  "text": "This is a test message"
}
```

### Document Header

To create a document template, add a `HEADER` component with:

```json
{
  "type": "HEADER",
  "format": "DOCUMENT",
  "example": {
    "header_handle": [
      "<DOCUMENT_LINK>"
    ]
  }
}
```

The `header_handle` array contains the document reference used as the example media when submitting the template.

### Template Category

Set `category` according to the purpose of the template.

Common values include:

```
UTILITY
MARKETING
```

Meta reviews the submitted template and determines its final classification and approval status.

### Response

{% code overflow="wrap" expandable="true" %}

```json
{
   "type":"template",
   "statuses":{
      "message_id":"wamid.HBgMOTYyNzk3MDI3Nzg3FQIAERgSRjAyRDE0RDc5RDA0NkVBQjBCAA==",
      "recipient":"+966********"
   }
}
```

{% endcode %}

### Notes

* The header `format` must be `DOCUMENT`.
* The document reference is provided through `example.header_handle`.
* The template body is defined separately using the `BODY` component.
* The template must be approved before it can be used to send document template messages.