Spec - Tickets

Table Of Contents

• Get Tickets
• Add Ticket
• Edit Ticket
• Get Ticket Updates
• Add Ticket Update
• Get Ticket Categories
• Get Ticket Forms

Get Tickets

This function allows the caller to retrieve a company’s list of tickets from the database.

Search parameters should be specified inside the tag.

Shared access users must have contacts permission to the account in order to perform this action.

Input

• account_id (required for shared access users)
• group_id
• company_id
• ticket_id (optional, to fetch a single ticket)
• page (1, 2, 3, etc.)
• include_ticket_updates (true/false)

Output

Success or failure. List of tickets.

Example Request

<GetTicketsRequest></GetTicketsRequest>

Example Request

<GetTicketsRequest group_id="4" company_id="1"></GetTicketsRequest>

Example Request

<GetTicketsRequest group_id="4" company_id="1" page="1"></GetTicketsRequest>

Example Request

<GetTicketsRequest ticket_id="1" page="1"></GetTicketsRequest>

Example Request (include ticket updates in response)

<GetTicketsRequest include_ticket_updates="true" page="1"></GetTicketsRequest>

Successful Response

<GetTicketsResponse>
    <Result>Success</Result>
    <Tickets>
        <Ticket>
            <TicketID>2</TicketID>
            <Firstname>Todd</Firstname>
            <Lastname>Smith</Lastname>
            <Email>todd@smith.com</Email>
            <TicketSummary>Test</TicketSummary>
            <Status>Open (Escalated)</Status>
            <CreatedDatetime>20141027103646</CreatedDatetime>
            <ClosedDatetime></ClosedDatetime>
        </Ticket>
        <Ticket>
            <TicketID>18</TicketID>
            <Firstname>Test</Firstname>
            <Lastname>Wade</Lastname>
            <Email>contact.test@gmail.com</Email>
            <TicketSummary>Test</TicketSummary>
            <Status>Closed</Status>
            <CreatedDatetime>20141113052054</CreatedDatetime>
            <ClosedDatetime>20141120193949</ClosedDatetime>
        </Ticket>
        <Ticket>
            <TicketID>19</TicketID>
            <Firstname>Test</Firstname>
            <Lastname>Wade</Lastname>
            <Email>contact.test2@gmail.com</Email>
            <TicketSummary>Test</TicketSummary>
            <Status>Open</Status>
            <CreatedDatetime>20141113061011</CreatedDatetime>
            <ClosedDatetime></ClosedDatetime>
        </Ticket>
        <Ticket>
            <TicketID>20</TicketID>
            <Firstname>Test</Firstname>
            <Lastname>Wade</Lastname>
            <Email>contact.test@gmail.com</Email>
            <TicketSummary>Test</TicketSummary>
            <Status>Open</Status>
            <CreatedDatetime>20141119055612</CreatedDatetime>
            <ClosedDatetime></ClosedDatetime>
        </Ticket>
    </Tickets>
</GetTicketsResponse>

Successful Response (include_ticket_updates=”true”)

<GetTicketsResponse>
    <Result>Success</Result>
    <Tickets>
        <Ticket>
            <TicketID>2</TicketID>
            <Firstname>Todd</Firstname>
            <Lastname>Smith</Lastname>
            <Email>todd@smithco.com</Email>
            <TicketSummary>Test</TicketSummary>
            <Status>Open</Status>
            <CreatedDatetime>20141027103646</CreatedDatetime>
            <ClosedDatetime></ClosedDatetime>
            <TicketUpdates>
                <TicketUpdate>
                    <TicketUpdateID>1</TicketUpdateID>
                    <UpdateDatetime>20140724104145</UpdateDatetime>
                    <ContactID>627</ContactID>
                    <Firstname>Todd</Firstname>
                    <Lastname>Smith</Lastname>
                    <Email>toddsmith.test@gmail.com</Email>
                    <Content><![CDATA[Test ticket details<br>]]></Content>
                    <ImageURL></ImageURL>
                    <ImageSizeKB>0</ImageSizeKB>
                    <UpdateIP></UpdateIP>
                </TicketUpdate>
            </TicketUpdates>
        </Ticket>
    </Tickets>
</GetTicketsResponse>

Add Ticket

Call this API to add a new ticket.

Lookup ContactID or ContactEmail with GetContactsRequest.

Lookup CategoryID with GetTicketCategoriesRequest.

Lookup FormID with GetTicketFormsRequest.

Input

• account_id (required for shared access users)
• group_id (required for shared access users)
• ContactID or ContactEmail (required, contact must exists)
• CategoryID (required)
• FormID (required)
• Summary (required)
• Detail (required, text or escaped-XML entity sets allowed, eg. £ will not work, use £ instead. Basic entities like <, >, &, ', and " will work just fine.)

Output

Success or failure for ticket.

Example Request (ContactID)

<AddTicketRequest>
    <Ticket>
        <ContactID>1</ContactID>
        <CategoryID>2</CategoryID>
        <FormID>2</FormID>
        <Summary>One line ticket title or description</Summary>
        <Detail>&lt;p&gt;Long explanation of ticket&lt;/p&gt;&lt;p&gt;New line&lt;/p&gt;</Detail>
    </Ticket>
</AddTicketRequest>

Example Request (ContactEmail)

<AddTicketRequest>
    <Ticket>
        <ContactEmail>john.smith@gmail.com</ContactEmail>
        <CategoryID>2</CategoryID>
        <FormID>2</FormID>
        <Summary>One line ticket title or description</Summary>
        <Detail>Long explanation of ticket</Detail>
    </Ticket>
</AddTicketRequest>

Example Request (shared access users)

<AddTicketRequest account_id="12345" group_id="1">
    <Ticket>
        <ContactID>1</ContactID>
        <CategoryID>2</CategoryID>
        <FormID>2</FormID>
        <Summary>One line ticket title or description</Summary>
        <Detail>Long explanation of ticket</Detail>
    </Ticket>
</AddTicketRequest>

Example Response

<AddTicketResponse>
    <Result>Success</Result>
    <Ticket>
        <TicketID>41</TicketID>
        <ContactID>1</ContactID>
        <CategoryID>2</CategoryID>
        <FormID>2</FormID>
        <Summary>One line ticket title or description</Summary>
        <Detail>Long explanation of ticket</Detail>
    </Ticket>
</AddTicketResponse>

Edit Ticket

Call this API to update the ticket status, change the ticket category and/or assign the ticket to a new contact.

Input

• ticket_id (required)
• account_id (required for shared access users)
• group_id (required for shared access users)
• Status (‘Open’/’Open (Escalated)’/’Closed’/’Closed (Locked)’)
• CategoryID
• AssignedToContactID

Output

Success or failure for ticket.

Example Request

<EditTicketRequest ticket_id="32">
    <Ticket>
        <Status>Open</Status>
        <CategoryID>3</CategoryID>
        <AssignedToContactID>623</AssignedToContactID>
    </Ticket>
</EditTicketRequest>

Example Request (shared access users)

<EditTicketRequest ticket_id="32" account_id="12345" group_id="1">
    <Ticket>
        <Status>Closed</Status>
        <CategoryID>3</CategoryID>
        <AssignedToContactID>623</AssignedToContactID>
    </Ticket>
</EditTicketRequest>

Example Response

<EditTicketResponse>
    <Result>Success</Result>
    <Ticket>
        <TicketID>41</TicketID>
        <Status>Open</Status>
        <CategoryID>3</CategoryID>
        <AssignedToContactID>623</AssignedToContactID>
    </Ticket>
</EditTicketResponse>

Get Ticket Updates

This function allows the caller to retrieve the ticket update for a ticket.

Shared access users must have contacts permission to the account in order to perform this action.

Input

• ticket_id (required)
• account_id (required for shared access users)
• group_id (required for shared access users)

Output

Success or failure. List of ticket updates.

Example Request

<GetTicketUpdatesRequest ticket_id="1"></GetTicketUpdatesRequest>

Example Request (for shared access users)

<GetTicketUpdatesRequest ticket_id="1" account_id="12345" group_id="1"></GetTicketUpdatesRequest>

Successful Response

<GetTicketUpdatesResponse>
    <Result>Success</Result>
    <TicketUpdates>
        <TicketUpdate>
            <TicketUpdateID>3</TicketUpdateID>
            <UpdateDatetime>20190916105001</UpdateDatetime>
            <ContactID>1</ContactID>
            <Firstname>John</Firstname>
            <Lastname>Smith</Lastname>
            <Email>john.smith@somedomain.com</Email>
            <Content><![CDATA[<p>The quick brown fox jumps over the lazy dog.</p>]]></Content>
            <ImageURL></ImageURL>
            <ImageSizeKB>0</ImageSizeKB>
            <UpdateIP>75.179.1.49</UpdateIP>
        </TicketUpdate>
        <TicketUpdate>
            <TicketUpdateID>2</TicketUpdateID>
            <UpdateDatetime>20180916105001</UpdateDatetime>
            <ContactID>1</ContactID>
            <Firstname>John</Firstname>
            <Lastname>Smith</Lastname>
            <Email>john.smith@somedomain.com</Email>
            <Content><![CDATA[<p>The quick brown fox jumps over the lazy dog.</p>]]></Content>
            <ImageURL></ImageURL>
            <ImageSizeKB>0</ImageSizeKB>
            <UpdateIP>75.179.1.49</UpdateIP>
        </TicketUpdate>
        <TicketUpdate>
            <TicketUpdateID>1</TicketUpdateID>
            <UpdateDatetime>20170916105001</UpdateDatetime>
            <ContactID>1</ContactID>
            <Firstname>John</Firstname>
            <Lastname>Smith</Lastname>
            <Email>john.smith@somedomain.com</Email>
            <Content><![CDATA[<p>The quick brown fox jumps over the lazy dog.</p>]]></Content>
            <ImageURL></ImageURL>
            <ImageSizeKB>0</ImageSizeKB>
            <UpdateIP>75.179.1.49</UpdateIP>
        </TicketUpdate>
    </TicketUpdates>
</GetTicketUpdatesResponse>

Add Ticket Update

Call this API to add a ticket update/reply.

Lookup ContactID or ContactEmail with GetContactsRequest.

Input

• ticket_id (required)
• account_id (required for shared access users)
• group_id (required for shared access users)
• ContactID or ContactEmail (required, contact must exists)
• Detail (required, text or escaped-XML entity sets allowed, eg. £ will not work, use £ instead. Basic entities like <, >, &, ', and " will work just fine.)
• Status (required, ‘Open’/’Open (Escalated)’/’Closed’/’Closed (Locked)’)
• EmailClient (required, Y/N)
• EmailSupportTeam (required, Y/N)

Output

Success or failure for ticket update.

Example Request (ContactID)

<AddTicketUpdateRequest ticket_id="32">
    <TicketUpdate>
        <ContactID>1</ContactID>
        <Detail>&lt;p&gt;Long ticket reply&lt;/p&gt;&lt;p&gt;New line&lt;/p&gt;</Detail>
        <Status>Open</Status>
        <EmailClient>Y</EmailClient>
        <EmailSupportTeam>Y</EmailSupportTeam>
    </TicketUpdate>
</AddTicketUpdateRequest>

Example Request (ContactEmail)

<AddTicketUpdateRequest ticket_id="32">
    <TicketUpdate>
        <ContactEmail>john.smith@gmail.com</ContactEmail>
        <Detail>Long ticket reply</Detail>
        <Status>Open</Status>
        <EmailClient>Y</EmailClient>
        <EmailSupportTeam>Y</EmailSupportTeam>
    </TicketUpdate>
</AddTicketUpdateRequest>

Example Request (shared access users)

<AddTicketUpdateRequest ticket_id="32" account_id="12345" group_id="1">
    <TicketUpdate>
        <ContactID>1</ContactID>
        <Detail>Long ticket reply</Detail>
        <Status>Open</Status>
        <EmailClient>Y</EmailClient>
        <EmailSupportTeam>Y</EmailSupportTeam>
    </TicketUpdate>
</AddTicketUpdateRequest>

Example Response

<AddTicketUpdateResponse>
    <Result>Success</Result>
    <TicketUpdate>
        <TicketUpdateID>106</TicketUpdateID>
        <TicketID>41</TicketID>
        <ContactID>1</ContactID>
        <Detail>Long ticket reply</Detail>
        <Status>Open</Status>
        <EmailSupportTeam>Y</EmailSupportTeam>
        <EmailClient>Y</EmailClient>
    </TicketUpdate>
</AddTicketUpdateResponse>

Get Ticket Categories

Call this API to retrieve the list of available ticket categories.

Input

• account_id (required for shared access users)
• group_id (required for shared access users)
• category_id

Output

Success or failure. List of ticket categories.

Example Request

<GetTicketCategoriesRequest/>

Example Request (filter by group_id)

<GetTicketCategoriesRequest group_id="1"/>

Example Request (filter by category_id)

<GetTicketCategoriesRequest category_id="2"/>

Example Request (shared access users)

<GetTicketCategoriesRequest account_id="12345" group_id="1"/>

Example Response

<GetTicketCategoriesResponse>
    <Result>Success</Result>
    <TicketCategories>
        <TicketCategory>
            <CategoryID>1</CategoryID>
            <CategoryName>First Category</CategoryName>
            <GroupID>1</GroupID>
            <AutomaticallyAssignToContactID>623</AutomaticallyAssignToContactID>
            <CloseTicketWorkflowID>2</CloseTicketWorkflowID>
            <AlertIfResponseLaterThanHours>0</AlertIfResponseLaterThanHours>
        </TicketCategory>
        <TicketCategory>
            <CategoryID>2</CategoryID>
            <CategoryName>Second Category</CategoryName>
            <GroupID>1</GroupID>
            <AutomaticallyAssignToContactID>-1</AutomaticallyAssignToContactID>
            <CloseTicketWorkflowID>0</CloseTicketWorkflowID>
            <AlertIfResponseLaterThanHours>0</AlertIfResponseLaterThanHours>
        </TicketCategory>
    </TicketCategories>
</GetTicketCategoriesResponse>

Get Ticket Forms

Call this API to retrieve the list of available ticket forms.

Input

• account_id (required for shared access users)
• group_id (required for shared access users)
• form_id

Output

Success or failure. List of ticket forms.

Example Request

<GetTicketFormsRequest/>

Example Request (filter by group_id)

<GetTicketFormsRequest group_id="1"/>

Example Request (filter by form_id)

<GetTicketFormsRequest form_id="2"/>

Example Request (shared access users)

<GetTicketFormsRequest account_id="12345" group_id="1"/>

Example Response

<GetTicketFormsResponse>
    <Result>Success</Result>
    <TicketForms>
        <TicketForm>
            <FormID>1</FormID>
            <FormName>Bug Report</FormName>
            <AddNewContactsToGroupIDs>
                <AddNewContactsToGroupID>2</AddNewContactsToGroupID>
            </AddNewContactsToGroupIDs>
            <ManagedByGroupID>1</ManagedByGroupID>
            <QuickSummaryText>Report bug here</QuickSummaryText>
            <SendNewTicketToOpener>Y</SendNewTicketToOpener>
            <AllowImageUpload>Optional</AllowImageUpload>
            <AssignWorkflowID>2</AssignWorkflowID>
            <StartJourneyID>1</StartJourneyID>
            <ReopenLimit></ReopenLimit>
        </TicketForm>
        <TicketForm>
            <FormID>2</FormID>
            <FormName>Feature Request</FormName>
            <AddNewContactsToGroupIDs>
                <AddNewContactsToGroupID>4</AddNewContactsToGroupID>
                <AddNewContactsToGroupID>2</AddNewContactsToGroupID>
            </AddNewContactsToGroupIDs>
            <ManagedByGroupID>1</ManagedByGroupID>
            <QuickSummaryText>Submit request here</QuickSummaryText>
            <SendNewTicketToOpener>Y</SendNewTicketToOpener>
            <AllowImageUpload>Optional</AllowImageUpload>
            <AssignWorkflowID>2</AssignWorkflowID>
            <StartJourneyID>1</StartJourneyID>
            <ReopenLimit></ReopenLimit>
        </TicketForm>
    </TicketForms>
</GetTicketFormsResponse>