# Create tickets from other systems with the Todomator API

> Authenticate with the token of Todomator and create a ticket with one JSON call, from a script, an email or a website form, with folders, people, tags, attachments and a callback.

Framework: todomator
Product: Todomator (todomator@1.7)
Language: en
Content-SHA256: 1ef7cc7f899dabeb5c0827e652b42f39755b3320dc1891cbd1a0b0579c7ba6cc
Snapshot: c0700e321579725c5cf4f5ace1ad7d2866d1b4f93c24a63c0b41b6b7998e976c
Sources: 
Review: not-recorded

Todomator exposes its actions through one API endpoint: `POST /api/` with a JSON body `{ "schema": "<name>", "data": { ... } }` (the Total.js API routes; see the recipe [API routes](/en/total5/api-routes/)). The address `/api/` comes from the line `$api` of the `config` file.

## Authenticate with the token

Besides the session of a signed-in person, the API accepts a **token**: send it in the header `x-token` or in the query parameter `token`. If it equals the setting `token` (see [settings](/en/todomator/settings-and-database/)), the request runs as a built-in user called *Bot*, an administrator with the permission `bot`; any other token is refused. Use a long random token, keep it on your server and send it only over HTTPS.

## Create a ticket

The name of the call is `tickets_create`. Only `name` is required; the rest is optional:

| Field | Notes |
|---|---|
| `name` | the title |
| `folder` or `folderid` | the folder, by **name** (Todomator looks it up) or by id; the ticket takes the billable flag of the folder |
| `users` | the people to assign, by **name or email**; an unknown person is an error (`User "..." not found`) |
| `watcherid` | the people who follow it, by **id** (unlike `users`, the schema of this version does not take them by name) |
| `statusid` | `pending` (default), `open`, `review`, `postponed`, `note` or `closed` |
| `markdown`, `html` | the content |
| `tags`, `ispriority`, `isbillable`, `ispublic` | tags and flags |
| `date`, `deadline`, `worked` | the day, a deadline and minutes already worked |
| `attachments` | a list of `{ name, data }` where `data` is the file in Base64 |
| `reference`, `source`, `attrs` | free fields to link the ticket with your system |
| `callback` | an address that receives the ticket |

```json
{
	"schema": "tickets_create",
	"data": {
		"name": "The invoice page fails with a 500",
		"folder": "Customer support",
		"users": ["jane@example.com"],
		"markdown": "Reported by the contact form.\n\nSteps: open the invoice and click *Print*.",
		"tags": ["bug"],
		"source": "website",
		"reference": "form-2041"
	}
}
```

The answer is the id of the new ticket. The people assigned are notified and the open sessions of the people who may see it are refreshed.

## The callback

When `callback` is set, Todomator sends a `POST` to that address with the ticket data when the ticket is created, updated or cloned, and when a comment is added (on creation and update it also sends the list of the fields that were given, `keys`). Your system can use it to mirror the status of a ticket.

## Other calls

The same endpoint serves the rest of the actions, with the names of `controllers/api.js`: `tickets` (list), `tickets_detail/{id}`, `tickets_update/{id}`, `tickets_clone/{id}`, `tickets_remove/{id}`, `logwork_create`, `folders`, `tags` and more. The official API documentation is at [docs.totaljs.com/todomator](https://docs.totaljs.com/todomator/).