> This page is for API Reference & Tools.

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.moveworks.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.moveworks.com/_mcp/server.

# Ticket Integration Mappers (Ticket Types)

> Create, read and update Ticket Integration Mappers (Ticket Types) through the Moveworks Configuration API: endpoints, fields and examples.

`tool.ticket.integration.mappers`

Binds ticket types to destinations, with state/transition mappings.

* **Endpoint:** `/tool/ticket/integration/mappers`  |  **Methods:** GET, PATCH, POST
* **Request shape:** fields go at the top level of the JSON body, with no `resource` wrapper. The item's `id` goes in the URL for reads and updates, not in the body.
* **Updates:** a JSON merge-patch. Send only the fields you change, plus `version: {num, change_description}` with the `num` from your last read. Lists and maps you send replace the stored ones whole.

### Endpoints

All paths are relative to `https://api.moveworks.ai/configurations/v1alpha1`. Each endpoint page lists the request and response schema, an example, and the errors it can return.

| Method  | Path                                          | Endpoint reference                                                                                                                        |
| ------- | --------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| `GET`   | `/tool/ticket/integration/field-mappers`      | [List ticket type mappers](/api-reference/configuration-api/ticketing/ticket-integration-mappers-ticket-types/list-ticket-type-mappers)   |
| `POST`  | `/tool/ticket/integration/field-mappers`      | [Create ticket type mapper](/api-reference/configuration-api/ticketing/ticket-integration-mappers-ticket-types/create-ticket-type-mapper) |
| `GET`   | `/tool/ticket/integration/field-mappers/{id}` | [Get ticket type mapper](/api-reference/configuration-api/ticketing/ticket-integration-mappers-ticket-types/get-ticket-type-mapper)       |
| `PATCH` | `/tool/ticket/integration/field-mappers/{id}` | [Update ticket type mapper](/api-reference/configuration-api/ticketing/ticket-integration-mappers-ticket-types/update-ticket-type-mapper) |

### Fields

| Field          | Type                       | Required  | Notes                                                                                                                                                                                            |
| -------------- | -------------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `id`           | string                     | read-only | Unique ID of this configuration, assigned by the server.                                                                                                                                         |
| `connector_id` | string                     | ✅         | Connector for the ticketing system whose ticket types these settings describe. Cannot be changed after creation. ID of an existing connector (GET /configurations/v1alpha1/platform/connectors). |
| `ticket_types` | array\<TicketTypeSettings> |           | Settings for each ticket type in the ticketing system. A ticket type may appear more than once.                                                                                                  |
| `updated_time` | string                     | read-only | When the configuration was last updated.                                                                                                                                                         |
| `updated_by`   | string                     | read-only | Who last updated the configuration.                                                                                                                                                              |
| `version`      | Version                    | ✅         | Document version. On update, send back the num from your last read.                                                                                                                              |

### Example create body

```json
{
  "connector_id": "<connector-uuid>",
  "ticket_types": [
    {
      "type": "INCIDENT",
      "prefix": "<string>",
      "table_name": "incident",
      "domain": "IT_DOMAIN",
      "requestor_column_name": "example-name",
      "ticket_external_url_template": "https://example.com/path",
      "ticket_agent_url_template": "https://example.com/path",
      "states": {
        "internal_states": {}
      },
      "ticket_destination_id": "<destination-uuid>",
      "ticket_fields_mapper": {
        "create_ticket": {},
        "query_ticket": {},
        "update_ticket": {},
        "resolve_ticket": {},
        "reopen_ticket": {}
      },
      "jira_service_desk_id": "<id>",
      "jira_transitions": {
        "jira_transitions": {}
      },
      "retain_state_on_user_comment_enabled": true,
      "additional_query_parameter_filter": "<string>"
    }
  ],
  "version": {
    "change_description": "Create ticket type mapper"
  }
}
```