## Get a task template

`GET /v1/task-templates/:templateId`

Returns a task template by ID.

## Parameters

| Parameter | Type | Required | Description |
|----------|-----|:-----:|----------|
| `templateId` (path) | number | yes | Template ID, a positive integer. List: [`GET /v1/task-templates`](/docs/entities/tasks/templates-list) |
| `params` (query) | string | no | URL-encoded JSON object of Bitrix24 parameters, for example `{"select":["ID","TITLE"]}`. Field names are not converted |

The method accepts no other query parameters.

## Examples

### curl — personal key

```bash
curl "https://vibecode.bitrix24.com/v1/task-templates/75" \
  -H "X-Api-Key: YOUR_API_KEY"
```

### curl — OAuth application

```bash
curl "https://vibecode.bitrix24.com/v1/task-templates/75" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN"
```

### JavaScript — personal key

```javascript
const res = await fetch('https://vibecode.bitrix24.com/v1/task-templates/75', {
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
  },
})

const { success, data } = await res.json()
if (data === false) {
  console.log('Template not found')
} else {
  console.log(data.TITLE, '— responsible person', data.RESPONSIBLE_ID)
}
```

### JavaScript — OAuth application

```javascript
const res = await fetch('https://vibecode.bitrix24.com/v1/task-templates/75', {
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
  },
})

const { success, data } = await res.json()
```

## Response fields

Standard template field values are strings or `null`, including numbers and `Y`/`N` flags.

| Field | Type | Description |
|------|-----|----------|
| `success` | boolean | `true` on success |
| `data` | object \| false | The template. `false` — there is no template with this `templateId`. The response still comes with status `200`, not `404` |
| `data.ID` | string | Template ID |
| `data.TITLE` | string | Title of the template and of the future task |
| `data.DESCRIPTION` | string \| null | Task description |
| `data.DESCRIPTION_IN_BBCODE` | string | `Y` — the description contains BB code |
| `data.PRIORITY` | string | Priority: `0` — low, `1` — normal, `2` — high |
| `data.CREATED_BY` | string | Creator ID. Get: [`GET /v1/users/:id`](/docs/entities/users/get) |
| `data.RESPONSIBLE_ID` | string | Responsible person ID. Get: [`GET /v1/users/:id`](/docs/entities/users/get) |
| `data.RESPONSIBLES` | string | Responsible person IDs in PHP serialization format, for example `a:1:{i:0;s:2:"42";}`. The [template list](/docs/entities/tasks/templates-list) without `select` returns the same IDs as an array. Employee list: [`GET /v1/users`](/docs/entities/users/list) |
| `data.ACCOMPLICES` | string | Participant IDs in the same format. With no participants — `a:0:{}`. Employee list: [`GET /v1/users`](/docs/entities/users/list) |
| `data.AUDITORS` | string | Observer IDs in the same format. Employee list: [`GET /v1/users`](/docs/entities/users/list) |
| `data.GROUP_ID` | string \| null | Workgroup ID. Get: [`GET /v1/workgroups/:id`](/docs/entities/workgroups/get) |
| `data.PARENT_ID` | string \| null | Parent task ID. Get: [`GET /v1/tasks/:id`](/docs/entities/tasks/get) |
| `data.DEPENDS_ON` | string \| null | IDs of the tasks the future task depends on. Get: [`GET /v1/tasks/:id`](/docs/entities/tasks/get) |
| `data.TIME_ESTIMATE` | string | Effort estimate in seconds |
| `data.ALLOW_CHANGE_DEADLINE` | string | `Y` — the responsible person may move the deadline themselves |
| `data.ALLOW_TIME_TRACKING` | string | `Y` — time tracking is enabled |
| `data.TASK_CONTROL` | string | `Y` — once completed, the task returns to the creator for approval |
| `data.MATCH_WORK_TIME` | string | `Y` — deadline calculation skips weekends and holidays |
| `data.ADD_IN_REPORT` | string | `Y` — the task is counted in efficiency reports |
| `data.MULTITASK` | string | `Y` — the task has several responsible persons |
| `data.REPLICATE` | string | `Y` — a recurring task template |
| `data.CREATED_BY_NAME`, `data.CREATED_BY_LAST_NAME`, `data.CREATED_BY_SECOND_NAME` | string \| null | First name, last name and middle name of the creator |
| `data.CREATED_BY_LOGIN`, `data.CREATED_BY_WORK_POSITION`, `data.CREATED_BY_PHOTO` | string \| null | Login, job title and photo file ID of the creator |
| `data.RESPONSIBLE_NAME`, `data.RESPONSIBLE_LAST_NAME`, `data.RESPONSIBLE_SECOND_NAME` | string \| null | First name, last name and middle name of the responsible person |
| `data.RESPONSIBLE_LOGIN`, `data.RESPONSIBLE_WORK_POSITION`, `data.RESPONSIBLE_PHOTO` | string \| null | Login, job title and photo file ID of the responsible person |
| `data.UF_*` | — | Task user fields of the Bitrix24 account. The type depends on the field. An empty field comes as `null`, `false` or an empty string |
| `data.*` | string \| null | Other template fields as Bitrix24 stores them: `STATUS`, `STAGE_ID`, `XML_ID`, `SITE_ID`, `DEADLINE_AFTER`, `START_DATE_PLAN_AFTER`, `END_DATE_PLAN_AFTER`, `FILES`, `TAGS`, `TASK_ID`, `TPARAM_TYPE`, `TPARAM_REPLICATION_COUNT`, `REPLICATE_PARAMS`, `BASE_TEMPLATE_ID`, `TEMPLATE_CHILDREN_COUNT`, `SCENARIO` |

## Response example

The main template fields are shown; names and logins are replaced:

```json
{
  "success": true,
  "data": {
    "ID": "75",
    "TITLE": "Weekly status report",
    "DESCRIPTION": null,
    "DESCRIPTION_IN_BBCODE": "Y",
    "PRIORITY": "1",
    "RESPONSIBLE_ID": "1295",
    "CREATED_BY": "1295",
    "TIME_ESTIMATE": "0",
    "GROUP_ID": null,
    "ACCOMPLICES": "a:0:{}",
    "AUDITORS": "a:0:{}",
    "RESPONSIBLES": "a:1:{i:0;s:4:\"1295\";}",
    "DEPENDS_ON": null,
    "CREATED_BY_NAME": "Anna",
    "CREATED_BY_LAST_NAME": "Clark",
    "CREATED_BY_LOGIN": "a.clark@example.com",
    "RESPONSIBLE_NAME": "Anna",
    "RESPONSIBLE_LAST_NAME": "Clark",
    "RESPONSIBLE_LOGIN": "a.clark@example.com"
  }
}
```

## Error response example

400 — `templateId` is not a positive integer:

```json
{
  "success": false,
  "error": {
    "code": "INVALID_PARAMS",
    "message": "templateId must be a positive integer"
  }
}
```

## Errors

| HTTP | Code | Description |
|------|-----|----------|
| 400 | `INVALID_PARAMS` | `templateId` is not a positive integer. Message `templateId must be a positive integer` |
| 400 | `INVALID_PARAMS` | `params` is not a JSON object. Message `params must be a JSON object` |
| 400 | `INVALID_PARAMS` | `start` or any query parameter other than `params` was passed. Messages `start is only supported for list`, `Only params and start are supported` |
| 401 | `MISSING_API_KEY` | The `X-Api-Key` header is missing |
| 401 | `TOKEN_MISSING` | The key has no Bitrix24 tokens |
| 403 | `SCOPE_DENIED` | The key does not have the `task` scope |
| 422 | `BITRIX_ERROR` | Bitrix24 rejected the call. The text is in `error.message` |
| 429 | `RATE_LIMITED` | Request rate exceeded. The effective cap is in the `x-ratelimit-limit` header |

Full list of common API errors — [Errors](/docs/errors).

## Known specifics

**`select` does not narrow the response to the listed fields.** The `CREATED_BY_*` and `RESPONSIBLE_*` fields with creator and responsible person data, as well as the `RESPONSIBLES`, `ACCOMPLICES`, `AUDITORS` and `SCENARIO` fields, are returned even when they are not in `select`.

## See also

- [Task templates](/docs/entities/tasks/templates)
- [List task templates](/docs/entities/tasks/templates-list)
- [Create a task template](/docs/entities/tasks/templates-create)
- [Update a task template](/docs/entities/tasks/templates-update)