> ## Documentation Index
> Fetch the complete documentation index at: https://docs.leen.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# ITSM Write Endpoints

> Create and update tickets in your ITSM tools via Leen's Write API.

## Overview

The ITSM Write Endpoints feature allows you to programmatically create and update tickets in your connected IT Service Management (ITSM) systems directly through the Leen API. This enables powerful automation and workflow integration, allowing you to manage your ITSM resources without leaving your development environment.

By using the ticket write endpoints, you can build integrations that:

* Automatically create bug reports from CI/CD pipeline failures.
* Generate tasks based on security alerts from other tools.
* Keep ticket statuses synchronized with your internal systems.
* Bulk-create tickets synchronously and get per-ticket results immediately.

A sample application demonstrating the create use case is available at the [itsm-demo-app GitHub repository](https://github.com/leeninc/itsm-demo-app).

## Supported Integrations and Operations

The availability of write operations depends on the specific ITSM connector.

| Operation                   | Endpoint                          | JIRA |
| :-------------------------- | :-------------------------------- | :--- |
| Create Ticket               | `POST /itsm/tickets`              | ✅    |
| Update Ticket               | `PATCH /itsm/tickets/{ticket_id}` | ✅    |
| Bulk Create Tickets (Async) | `POST /itsm/tickets/bulk`         | ✅    |
| Bulk Create Tickets (Sync)  | `POST /itsm/tickets/bulk/sync`    | ✅    |
| Bulk Update Tickets         | `POST /itsm/tickets/bulk/update`  | ✅    |

## Creating Tickets

When creating a ticket via `POST /itsm/tickets`, you can identify the target project, issue type, assignee, and parent ticket using either **Leen UUIDs** (from a prior sync) or **vendor IDs** (directly from the vendor system). The two forms are mutually exclusive per field.

| Field         | Leen UUID                         | Vendor ID                                                 |
| :------------ | :-------------------------------- | :-------------------------------------------------------- |
| Project       | `project_id`                      | `project_vendor_id` (e.g. Jira project key `PROJ`)        |
| Issue type    | `type` / `type_id` *(deprecated)* | `type_vendor_id` (e.g. Jira issue type ID `10034`)        |
| Assignee      | `assigned_user_id`                | `assigned_user_vendor_id` (e.g. Jira `accountId`)         |
| Parent ticket | `parent_ticket_id`                | `parent_ticket_vendor_id` (e.g. Jira issue key `PROJ-42`) |

Using vendor IDs skips extra database lookups, which is useful when you have vendor data on hand and want to avoid a round-trip sync.

## Bulk Create Tickets (Sync)

`POST /itsm/tickets/bulk/sync` creates tickets synchronously using the vendor's bulk create API and returns per-ticket results immediately — no job polling required.

The response includes a summary and a `results` array in request order:

```json theme={null}
{
  "total": 3,
  "succeeded": 2,
  "failed": 1,
  "results": [
    { "success": true, "request_index": 0, "vendor_ticket_id": "PROJ-101", "ticket_id": "uuid..." },
    { "success": true, "request_index": 1, "vendor_ticket_id": "PROJ-102", "ticket_id": "uuid..." },
    { "success": false, "request_index": 2, "error": "Invalid issue type" }
  ]
}
```

When vendor ID fields are used (`project_vendor_id`, `assigned_user_vendor_id`, etc.), local DB persistence is skipped and `ticket_id` will be `null` in the response. The created tickets will appear after the next connector sync.

Batch size is capped at the same limit as async bulk create.

***

## Passthrough Endpoints

Passthrough endpoints proxy requests directly to the vendor API, bypassing Leen's normalized data store. They are useful for populating dropdowns and search UIs when configuring ticket creation — for example, to let users pick a project, issue type, or assignee without waiting for a full sync.

All passthrough endpoints require a `connection_id` scoped to a supported vendor (currently Jira). Vendor IDs returned by passthrough endpoints can be used directly in the `_vendor_id` fields of ticket create requests.

### List Projects

```
GET /itsm/passthrough/projects
```

Returns projects accessible via the connected vendor account. Supports offset pagination (`limit`, `offset`).

Each project includes a `vendor_id` (e.g. Jira project key `PROJ`), `name`, `project_type`, and optionally an embedded list of `issue_types`.

### List Issue Types

```
GET /itsm/passthrough/projects/{project_key}/issue-types
```

Returns issue types available for the given project. `project_key` is the vendor project identifier — use `vendor_id` from the List Projects response.

Each result includes a `vendor_id` that can be passed as `type_vendor_id` when creating a ticket.

### List Assignable Users

```
GET /itsm/passthrough/projects/{project_key}/assignable-users
```

Returns users who can be assigned to issues in the given project. Accepts an optional `query` parameter to filter by name or email (behavior is vendor-specific).

Each result includes a `vendor_id` (e.g. Jira `accountId`) that can be passed as `assigned_user_vendor_id` when creating a ticket. Note: total count may be `null` depending on the vendor.

### Search Tickets

```
GET /itsm/passthrough/tickets/search
```

Search tickets using vendor-native query syntax. For Jira connections, use the `jql` query parameter with standard JQL syntax. Supports cursor-based pagination via `cursor` and `limit` (1–100, default 50).

```
GET /itsm/passthrough/tickets/search?jql=project%20%3D%20PROJ%20AND%20resolution%20%3D%20Unresolved%20ORDER%20BY%20updated%20DESC&limit=50
```

The `next_cursor` field in the response can be passed as `cursor` in the next request to page through results. Omit `cursor` for the first page.

### Passthrough vs. Synced Data

|                 | Passthrough                            | Synced (standard endpoints)        |
| :-------------- | :------------------------------------- | :--------------------------------- |
| Data freshness  | Real-time from vendor                  | As of last connector sync          |
| Pagination      | Vendor-native (offset or cursor)       | Leen-normalized (offset or keyset) |
| Fields returned | Vendor-specific shape                  | Normalized Leen schema             |
| Use case        | Populating UI dropdowns, ad-hoc search | Reporting, querying across vendors |