Teamwork Import API Beta.md

The Ticket Import API is used by the Teamwork Desk importer and can be used by others to perform their own import from their own systems.

Endpoint: POST /v1/import/tickets.json

How it works

Inboxes

Tickets will be imported to the Inbox with the matching emailSource if one exists, otherwise they will be put in the Inbox with the id given as fallbackInboxId.

Users

Customers and agents will be matched by email address, if they do not exists they will be created. Agents created will be marked as "Invited" and will not count against to your agent limit on your Teamwork Desk plan unless activated.

Threads

Threads with a type of "message" will be created as a reply from an agent or customer. Those with a type of "note" will be created as a private note and must have a createdBy as a user of type "agent".

Tags

Tags will be created if they do not exist, otherwise matched.

Status

Imported tickets will have a status of Closed.

Source

Imported tickets will have the Source given in the import request, it will be created if it doesn't exist.

Importing multiple times

Tickets will not be imported multiple times if they have the same source, so you can perform an import at a later time to import new tickets.

Format

Import Request

Field	Type	Description	Required
source	string	used as ticket Source in Teamwork Desk and used to prevent duplicate imports	x
fallbackInboxId	integer	id of Teamwork Desk inbox to use if ticket emailSource isn't matched	x
tickets	array of tickets	tickets to import	x

Ticket

Field	Type	Description	Required
id	integer	unique identifier of the ticket	x
assignedTo	user with type "user"	agent assigned to the ticket
customer	user with type "customer"	customer who created the ticket	x
priority	string	priority, e.g Low
type	string	type, e.g Question
subject	string	subject of the ticket	x
tags	array of strings	tags for the ticket
threads	array of threads	threads for the ticket	x
emailSource	string	email address the ticket was sent to (used to match inbox)
createdAt	string	time (Zulu) e.g 2016-01-11T17:31:10Z	x
updatedAt	string	time (Zulu) e.g 2016-01-11T17:31:10Z	x

Thread

Field	Type	Description	Required
body	string	body of the thread	x
type	string	message or note	x
bcc	array of strings	BCC'd email addressess
cc	array of strings	CC'd email addresses
attachments	array of attachments	attachments for the thread
createdBy	user	user who created the thread	x
createdAt	string	time (Zulu) e.g 2016-01-11T17:31:10Z	x
updatedAt	string	time (Zulu) e.g 2016-01-11T17:31:10Z	x

User

Field	Type	Description	Required
email	string	users email address	x
firstName	string	users first name	x
lastName	string	users last name
type	string	user or customer	x

Attachment

Field	Type	Description	Required
filename	string	filename of attachment	x
downloadurl	string	URL of attachment	x

Example

{
   "source":"Example Import",
   "fallbackInboxId":9995,
   "tickets":[
      {
         "id":9000199794,
         "assignedTo":{
            "email":"agent.smith@example.com",
            "firstName":"Agent",
            "lastName":"Smith",
            "type":"user"
         },
         "customer":{
            "email":"john@example.com",
            "firstName":"John",
            "lastName":"Doe",
            "type":"customer"
         },
         "emailSource":"support@example.com",
         "type":"Question",
         "priority":"Low",
         "subject":"This is an example ticket",
         "tags":["tag1", "tag2"],
         "threads":[
            {
               "body":"Hi, I am having issues with foo....",
               "type":"message",
               "bcc":null,
               "cc":null,
               "attachments":[
                  {
                     "filename":"299363.zip",
                     "downloadurl":"http://example.com/299363.zip"
                  }
               ],
               "createdBy":{
                  "email":"john@example.com",
                  "firstName":"John",
                  "lastName":"Doe",
                  "type":"customer"
               },
               "createdAt":"2015-11-20T14:03:18Z",
               "updatedAt":"2015-11-25T14:16:03Z"
            },
            {
               "body":"this is a note added by an agent",
               "type":"note",
               "bcc":null,
               "cc":null,
               "createdBy":{
                  "email":"agent.smith@example.com",
                  "firstName":"Agent",
                  "lastName":"Smith",
                  "type":"user"
               },
               "createdAt":"2015-11-20T14:03:18Z",
               "updatedAt":"2015-11-20T14:03:18Z"
            }
         ],
         "createdAt":"2015-11-20T14:03:18Z",
         "updatedAt":"2015-11-25T14:16:03Z"
      }
   ]
}