Create tickets from other systems with the Todomator API

Todomator · todomator@1.7 todomatorapitokenticketsintegration

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). 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), 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

{
	"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.