Within Teamwork Desk, 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.

Import request format

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 format

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 format

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 format

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 Format

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"
      }
   ]
}

For more information, see: Importing tickets from Zendesk