The TeamSupport API is a RESTful style API over HTTP using XML or JSON. Each object (Tickets, Customers, Products, Jira, etc…) in TeamSupport is treated as a resource. You can use four verbs (GET, POST, PUT, DELETE) to manipulate the data.

API Topics

Authentication

To gain access to your data, you must get authenticated. TeamSupport uses HTTP Basic Authentication over SSL to secure your data. You will use your OrganizationID for your username, and your authentication token as your password. Your authentication token allows access to your data, so be sure to keep it very secure.

Locate your OrgID: Go to Admin, My Company tab.
Locate your API Token: Go to Admin, Integration tab and expand the top selection labeled TeamSupport API.

Verbs

GET (Retrieve)

The GET verb allows you to retrieve the data. For example:

Use the following url with the GET verb to retrieve all of your customers:
https://app.[ServerName].teamsupport.com/api/xml/customers OR https://app.[ServerName].teamsupport.com/api/json/customers

Use the following url with the GET verb to retrieve a single customer with the CustomerID of 123:
https://app.[ServerName].teamsupport.com/api/xml/customers/123 OR https://app.[ServerName].teamsupport.com/api/json/customers/123

Use the following url with the GET verb to retrieve the Ticket Status IDs:
https://app.[ServerName].teamsupport.com/api/xml/properties/ticketstatuses OR
https://app.[ServerName].teamsupport.com/api/json/properties/ticketstatuses

POST (Insert or Create)

The POST verb will allow you create resources. For example, use the following URL with the POST verb to create a new customer:

https://app.[ServerName].teamsupport.com/api/xml/customers OR https://app.[ServerName].teamsupport.com/api/json/customers

  • The Body of the request (for POST and PUT verbs) needs to be formatted in either XML or JSON. The request must include the parent tag and all the required tags. Here is an example in XML:
    <Customer>
        <Name>John Doe Company</Name>
    </Customer>


    Here is an example in JSON:

    {
      "Ticket": {
                      "Name": "Testing add ticket with JSON",
                      "TicketStatusID": "28746",
                      "TicketTypeID": "6080",
                      "TicketSeverityID": "6109"
                   }
    }
  • If there are no required tags, an empty ID tag will be required to parse the request file successfully. Here is an example in XML:
    <Table>
        <TableID></TableID>
    </Table>
  • The request also may include any other relevant tags for the new record, including custom fields. If an invalid tag or a read-only tag are included they will be ignored without preventing the request to take effect. To update a read-only field the related field needs to be updated instead. Here is an example in XML:
    <Customer>
        <Name>John Doe Company</Name>
        <Website>www.3TestCustomer.com</Website>
        <FirstCustomField>This is the value for the custom field with the API field name "FirstCustomField"</FirstCustomField>
    </Customer>
  • To update the value of the <PrimaryContact> the corresponding value needs to be specified in the <PrimaryUserID> tag.
  • DateTime fields values need to be provided in UTC time, nevertheless they will be returned in the local time specified for the organization.
  • The only required field to create a ticket is the <TicketStatusID>. For Example:
    <ticket>
    <TicketStatusID>28732</TicketStatusID>
    <TicketTypeID>6077</TicketTypeID>
    <Name>A Ticket added from API</Name>
    </ticket>
  • We define the ticket description as a ticket action. When you create a ticket an empty description is created. You can get the ID of the new empty description created using the following URL.


    "Tickets/{TicketID}/Actions" or "Tickets/{TicketName}/Actions"

    A description is a ticket action with a SystemActionTypeID equal to 1. To give a value to the new empty description, call the following URL using the PUT verb:


    "Tickets/{TicketID}/Actions/{ActionID}" or "Tickets/{TicketNumber}/Actions/{ActionID}"


    The content of the description must be placed in the “Description” tag. For example:

    <Action>
    <Description>
    This is the content of the new ticket description.
    </Description>
    </Action>

PUT (Update)

The PUT verb is much like the POST, except that it updates an existing resource instead of creating a new one. You will need to put the XML in the body of the request. An easy way to see the format, is to use the GET verb to request a resource.

https://app.[ServerName].teamsupport.com/api/xml/customers/123

DELETE

The DELETE verb is pretty much straight forward. You issue an HTTP request upon a resource, and that resource will be deleted. In the following example Customer 456’s association with ticket 123 will be deleted.

Tickets/123/Customers/456

Pagination

Paginating allows your results to be separated by into a discrete number of pages. This is helpful to avoid delays if large amounts of data is being accessed.

Pagination works in the following areas:

  • Tickets
  • Contacts
  • Organizations

The default is no pagination. To use the pagination at least one of the following two parameters must be sent in the URL. If only one is used, the other field will be set with the default value.

  • pageSize: Default value is 50. Specifies the maximum number of results returned per page. If there are not enough results to reach the maximum, then the exact number of results will be returned.
  • pageNumber: Default value is 1. Specifies a specific page to return. For example, if you would like to view the 5th page of results, you would enter the the value “5” for this field.

The results returned will include a TotalRecords element. With this you can figure out how many pages there are based on the pagesize.

Examples:

.../api/xml/tickets?name[contains]=Test&pageNumber=2&pageSize=40

This will return the second page of results. Each page will contain 40 records.
Lets say the TotalRecords is 164. In this case, there will be 5 total pages. Pages 1-4 will have 40 records and page 5 with a remaining 4 records.

.../api/xml/tickets?name[contains]=Test&pageNumber=3

This will return the third page of results. Each page will contain 50 records (default).
Lets say the TotalRecords is 355. In this case, there will be 8 total pages. Pages 1-7 will have 50 records and page 8 with a remaining 5 records.

.../api/xml/tickets?name[contains]=Test&pageSize=10

This will return the first page of results (default). Each page will contain 10 records.
Lets say the TotalRecords is 31. In this case, there will be 4 total pages. Pages 1-3 will have 10 records and page 4 with a remaining 1 record.

Additional Notes

  • You also have an option of appending “.xml” to the resource. This might be useful for some clients to display the proper XML format. When you receive a response back from your request, the Status Code is very meaningful. The Status Code determines the success of the request
    For example: https://app..[ServerName]teamsupport.com/api/xml/customers.xml

    Some common codes are as follows:

    200 Successful
    201 Created
    202 Accepted
    300 Redirection
    304 Not Modified
    401 Unauthorized
    404 Not Found
    405 Method Not Allowed
    500 Server Error
    501 Not Implemented
  • The XML also may include any other relevant tags for the new record, including custom fields. For example:
    <Customer>
        <Name>John Doe Company</Name>
        <Website>www.3TestCustomer.com</Website>
        <FirstCustomField>This is the value for the custom field with the API field name "FirstCustomField"</FirstCustomField>
    </Customer>
  • The custom fields that you create will be available like any other property of a resource in TeamSupport. You can modify the property name when you create or edit your custom fields (Admin->Custom Fields). When modifying your custom fields, you will notice a value “API Field Name”. This value will determine the element name in your XML.

Attachments

You may upload attachments to Ticket Actions and Inventory Assets. We have supplied sample code here.

Need more help with this?
Customer Support

Was this helpful?

Yes No
You indicated this topic was not helpful to you ...
Could you please leave a comment telling us why? Thank you!
Thanks for your feedback.