NAV Navbar
JSON
Agilant Solutions, Inc.
TOGaDesk Ticketing API v2.1.2
Updated 8/18/2020

Overview

Introduction

This API implements functionality for utilizing the ticketing features of Agilant’s TOGaDesk system through a RESTful HTTP transaction containing a JSON payload.

Endpoints

Beta/Test/Sandbox Environment
https://api.beta.agilantsolutions.com


Production Environment
https://api.agilantsolutions.com

Structure & Schema

Authentication & Authorization

Required Request Headers for Every Transaction

Header FieldTypeDescription
Content-TypeStringMust be set to application/json
TimestampStringThe current timestamp of your transaction in ISO 8601 notation.
Example: 2019-01-02T17:34:52-05:00
AuthorizationStringConcatenated string of your public API key, followed by a literal period (.), followed by your signature. Your signature is your timestamp value, signed using your secret API key through the HMAC-SHA-256 cryptographic hash algorithm in a raw binary format and then Base64 encoded.
Format: {publicKey}.{signatureOfTimestampUsingSecretKey}

Sample Authentication Request Headers


Content-Type: application/json
Timestamp: 2019-01-02T17:34:52-05:00
Authorization: 1111AAAA-22BB-33CC-44DD-555555EEEEEE.Omjruf/UNd+rKEbjobxJzky84h6XOE9o9jz6/IKqc7Q=

Sample Authentication Request Headers

See the sample request using the sample information below.

Sample PHP Code for Assembling Request Headers

<?php

$publicApiKey 
'1111AAAA-22BB-33CC-44DD-555555EEEEEE';     // Replace with your Public API Key
$secretApiKey 'EEEE5555-DD44-CC33-BB22-AAAAAA111111';     // Replace with your Secret API Key

$timestamp date('c'time());
$headers = [
    
'Content-Type: application/json',
    (
'Timestamp: '.$timestamp),
    (
'Authorization: '.$publicApiKey.'.'.base64_encode(hash_hmac('SHA256'$timestamp$secretApiKeytrue)))
];

?>

Responses

Sample Response Headers


Content-Type: application/json
Content-Length: 354

Response Headers for Every Transaction

Header FieldTypeDescription
Content-TypeStringWill always be set to application/json
Content-LengthIntegerLength of the response payload in bytes.

Response Codes

HTTP CodeMeaningRequired Action
200 OKThe transaction was successful.
(Applicable to GET, PUT, and DELETE requests)
N/A
201 CREATEDThe record was successfully created.
(Applicable only to POST requests)
N/A
400 BAD REQUESTA logic error was encountered or the request was missing a required parameter.Review the returned errors and correct the issue.
401 UNAUTHORIZEDAuthentication or authorization failed.Review the returned errors and correct the issue. If the problem persists, you may not be permitted to perform this API call.
403 FORBIDDENAccess was denied when trying to retrieve data for a record.Ensure you have proper authorization to access the record.
404 NOT FOUNDThe record could not be located.Ensure you have requested a record that exists.
405 METHOD NOT ALLOWEDThe requested action is not supported.Ensure that you are calling a valid API method and using the correct method and route.
408 REQUEST TIMEOUTA connection error was encountered and the request may or may not have completed successfully.Retry the transaction and/or perform other GET requests to check if the previous request succeeded.
422 UNPROCESSABLE ENTITYThe request structure is correct and the server understands the request but is unable to process the transaction. This typically can occur in a POST request if the record being created or changed already exists.Ensure you are not trying to create the same record that was already processed in a previous transaction.
500 INTERNAL SERVER ERRRORAn unexpected internal server error was encountered.Contact the administrator. Further analysis and debugging may need to be performed.
502 BAD GATEWAYA temporary network issue occurred when receiving the request. This is rare and typically caused by a very temporary network issue which should resolve within a few seconds.Retry the transaction or try again later. If the problem persists, please contact the administrator.
504 GATEWAY TIMEOUTA network issue occurred when receiving the request.Retry the transaction or try again later. If the problem persists, please contact the administrator.

PHP Example

<?php

$endpoint 
'https://api.beta.agilantsolutions.com';        // SANDBOX ENDPOINT
//$endpoint = 'https://api.agilantsolutions.com';           // PRODUCTION ENDPOINT

$publicApiKey '1111AAAA-22BB-33CC-44DD-555555EEEEEE';     // Replace with your Public API Key
$secretApiKey 'EEEE5555-DD44-CC33-BB22-AAAAAA111111';     // Replace with your Secret API Key

$method 'GET';
$route '/provider';
$payload '{"providers":["C638C170-3EC1-4DF2-942C-1D1C3AD74FBC","16527A9E-4048-452CA8DF-605E1038A313"]}';

//////////////////////////////////////////////////

$url = ($endpoint $route);
$timestamp date('c'time());
$headers = [
    
'Content-Type: application/json',
    (
'Timestamp: '.$timestamp),
    (
'Authorization: '.$publicApiKey.'.'.base64_encode(hash_hmac('SHA256'$timestamp$secretApiKeytrue)))
];
$ch curl_init($url);
curl_setopt($chCURLOPT_CUSTOMREQUEST$method);
curl_setopt($chCURLOPT_POSTFIELDS$payload);
curl_setopt($chCURLOPT_RETURNTRANSFERtrue);
curl_setopt($chCURLOPT_SSL_VERIFYPEERfalse);
curl_setopt($chCURLOPT_HTTPHEADER$headers);
$responseBody curl_exec($ch);
$responseCode curl_getinfo($chCURLINFO_HTTP_CODE);
curl_close($ch);

echo 
'responseCode=' $responseCode '<br>';
echo 
'responseBody=' $responseBody;

///////////////////////////////////////////////

/*

EXAMPLE OUTPUT:

responseCode=200
responseBody=
{
    "success": true,
    "error": "",
    "providers": [
        {
            "providerId": "C638C170-3EC1-4DF2-942C-1D1C3AD74FBC",
            "providerName": "Porch",
            "avgRating": 4.3,
            "reviews": [
                {
                    "name": "Jane Doe",
                    "rating": 4.7,
                    "review": "I like this service very much!"
                },
                {
                    "name": "John Smith",
                    "rating": 3.5,
                    "review": "I was quite happy!"
                }
            ]
        },
        {
            "providerId": "16527A9E-4048-452C-A8DF-605E1038A313",
            "providerName": "Hello Tech",
            "avgRating": 3.1,
            "reviews": [
                {
                    "name": "Mary Doe",
                    "rating": 2.7,
                    "review": "I was not happy with this service.
                },
                {
                    "name": "Jim Dean",
                    "rating": 4.1,
                    "review": "This looks really nice!"
                }
            ]
        }
    ]
}
*/

Enumerated Lists

Webhook Types

Defines the type of a webhook request

Values

ValueDescription
TICKET_STATUS_CHANGEWhen a ticket status has changed.
TICKET_REPLYWhen a ticket reply has been added.

Ticket Statuses

Defines the status of a ticket

Values

ValueDescription
NEW_TICKETThe ticket is newly submitted and has not been handled yet.
OPENThe ticket is open and is waiting for review.
IN_PROGRESSThe ticket is in progress and is being handled.
AWAITING_USERThe ticket is open and is awaiting the user to provide more information.
CLOSEDThe ticket has been closed.
REVIEWThe ticket was closed and is now under review after being requested to re-open.

Ticket Priorities

Defines the priority of a ticket

Values

ValueDescription
LOWA low-priority ticket.
NORMALA normal-priority ticket.
HIGHA high-priority ticket.

Data Objects

Ticket

Sample Ticket Object


{
    "ticketNumber" : 12345678,
    "priority" : "NORMAL",
    "status" : "IN_PROGRESS",
    "firstName" : "John",
    "lastName" : "Smith",
    "emailAddress" : "johnsmith@testco.com",
    "phoneNumber" : "(123) 456-7890",
    "subject" : "My computer won't boot up",
    "message" : "I cannot get the computer to boot into Windows",
    "replies" : [
        {
            "repliedOn" : "2020-02-03T07:34:16-06:00",
            "firstName" : "Jane",
            "lastName" : "Doe",
            "emailAddress" : "janedoe@testco.com",
            "message" : "Have you tried powering the system off then on?"
        },
        {
            "repliedOn" : "2020-02-03T08:19:27-06:00",
            "firstName" : "John",
            "lastName" : "Smith",
            "emailAddress" : "johnsmith@testco.com",
            "message" : "Yes, I have."
        }
    ]
}

Represents a ticket data object.

Fields

FieldTypeDescription
ticketNumberIntegerThe reference number of the ticket.
priorityStringThe priority of the ticket. See Ticket Priorities for all possible values.
statusStringThe status of the ticket. See Ticket Statuses for all possible values
firstNameStringThe first name of the person creating the ticket
lastNameStringThe last name of the person creating the ticket
emailAddressStringThe email address of the contact
phoneNumberStringThe phone number of the person creating the ticket
subjectStringThe subject of the ticket
messageStringThe message body of the ticket
replies[]ArrayAn array of Ticket Reply objects.
replies[]{}.repliedOnDate/TimeThe date/time when the ticket reply was made. (Defaults to "now" when creating.)
replies[]{}.firstNameStringThe first name of the person replying to the ticket
replies[]{}.lastNameStringThe last name of the person replying to the ticket
replies[]{}.emailAddressStringThe email address of the person replying to the ticket
replies[]{}.messageStringThe message body of the ticket reply

Ticket Reply

Sample Ticket Reply Object


{
    "repliedOn" : "2020-02-03T07:34:16-06:00",
    "firstName" : "Jane",
    "lastName" : "Doe",
    "emailAddress" : "janedoe@testco.com",
    "message" : "Have you tried powering the system off then on?"
}

Represents a ticket reply data object.

Fields

FieldTypeDescription
repliedOnDate/TimeThe date/time when the ticket reply was made. (Defaults to "now" when creating.)
firstNameStringThe first name of the person replying to the ticket
lastNameStringThe last name of the person replying to the ticket
emailAddressStringThe email address of the person replying to the ticket
messageStringThe message body of the ticket reply

Tickets

Create a TicketPOST /ticket

Use this request to create a ticket.

Sample Request

POST /ticket

Content-Type: application/json
Timestamp: (See Authentication & Authorization)
Authorization: (See Authentication & Authorization)

{
    "priority" : "NORMAL",
    "firstName" : "John",
    "lastName" : "Smith",
    "emailAddress" : "johnsmith@testco.com",
    "phoneNumber" : "(123) 456-7890",
    "subject" : "My computer won't boot up",
    "message" : "I cannot get the computer to boot into Windows"
}

Input/Request Parameters

FieldTypeDescriptionRequired
priorityStringThe priority of the ticket. See Ticket Priorities for all possible values.No
firstNameStringThe first name of the person creating the ticketNo
lastNameStringThe last name of the person creating the ticketNo
emailAddressStringThe email address of the contactYes
phoneNumberStringThe phone number of the person creating the ticketNo
subjectStringThe subject of the ticketYes
messageStringThe message body of the ticketYes

Sample Response

HTTP/1.1 201 CREATED

{
    "success" : true,
    "error" : "",
    "ticketNumber" : 12345678
}

Output/Response Parameters

FieldTypeDescription
successBooleanWill return true or false for whether or not the transaction was successful.
errorStringIntelligible string of the error that occurred. Will be empty if no error occurred.
ticketNumberIntegerThe ticket number which was created for referencing later

Typical Response Codes

HTTP CodeMeaningRequired Action
201 CREATEDThe record was successfully created.
(Applicable only to POST requests)
N/A
400 BAD REQUESTA logic error was encountered or the request was missing a required parameter.Review the returned errors and correct the issue.

Add a Ticket ReplyPOST /ticket/{ticketNumber}/reply

Use this request to add a reply messages to a ticket.

Sample Request

POST /ticket/12345678/reply

Content-Type: application/json
Timestamp: (See Authentication & Authorization)
Authorization: (See Authentication & Authorization)

{
    "repliedOn" : "2020-02-03T07:34:16-06:00",
    "emailAddress" : "janedoe@testco.com",
    "firstName" : "Jane",
    "lastName" : "Doe",
    "message" : "Have you tried powering the system off then on?"
}

Input/Request Parameters

FieldTypeDescriptionRequired
repliedOnDate/TimeThe date/time when the ticket reply was made. (Defaults to "now" when creating.)No
firstNameStringThe first name of the person replying to the ticketNo
lastNameStringThe last name of the person replying to the ticketNo
emailAddressStringThe email address of the person replying to the ticketYes
messageStringThe message body of the ticket replyYes

Sample Response

HTTP/1.1 201 CREATED

{
    "success" : true,
    "error" : "",
    "ticketNumber" : 12345678
}

Output/Response Parameters

FieldTypeDescription
successBooleanWill return true or false for whether or not the transaction was successful.
errorStringIntelligible string of the error that occurred. Will be empty if no error occurred.
ticketNumberIntegerThe ticket number of the record which the reply was posted to

Typical Response Codes

HTTP CodeMeaningRequired Action
201 CREATEDThe record was successfully created.
(Applicable only to POST requests)
N/A
400 BAD REQUESTA logic error was encountered or the request was missing a required parameter.Review the returned errors and correct the issue.
404 NOT FOUNDThe record could not be located.Ensure you have requested a record that exists.

Update a TicketPUT /ticket/{ticketNumber}

Use this request to modify a ticket or update its status.

Sample Request

PUT /ticket/12345678

Content-Type: application/json
Timestamp: (See Authentication & Authorization)
Authorization: (See Authentication & Authorization)

{
    "priority" : "NORMAL",
    "status" : "IN_PROGRESS",
    "firstName" : "Jane",
    "lastName" : "Doe",
    "emailAddress" : "janedoe@testco.com",
    "phoneNumber" : "(123) 456-7890",
    "subject" : "My computer won't boot up",
    "message" : "I cannot get the computer to boot into Windows"
}

Input/Request Parameters

FieldTypeDescriptionRequired
priorityStringThe priority of the ticket. See Ticket Priorities for all possible values.No
statusStringThe status of the ticket. See Ticket Statuses for all possible valuesNo
firstNameStringThe first name of the person creating the ticketNo
lastNameStringThe last name of the person creating the ticketNo
emailAddressStringThe email address of the contactNo
phoneNumberStringThe phone number of the person creating the ticketNo
subjectStringThe subject of the ticketNo
messageStringThe message body of the ticketNo

Sample Response

HTTP/1.1 200 OK

{
    "success" : true,
    "error" : "",
    "ticketNumber" : 12345678
}

Output/Response Parameters

FieldTypeDescription
successBooleanWill return true or false for whether or not the transaction was successful.
errorStringIntelligible string of the error that occurred. Will be empty if no error occurred.
ticketNumberIntegerThe ticket number which was updated

Typical Response Codes

HTTP CodeMeaningRequired Action
200 OKThe transaction was successful.
(Applicable to GET, PUT, and DELETE requests)
N/A
400 BAD REQUESTA logic error was encountered or the request was missing a required parameter.Review the returned errors and correct the issue.
404 NOT FOUNDThe record could not be located.Ensure you have requested a record that exists.

Retrieve a TicketGET /ticket/{ticketNumber}

Use this request to retrieve a ticket and view its status or information

Sample Request

GET /ticket/12345678

Content-Type: application/json
Timestamp: (See Authentication & Authorization)
Authorization: (See Authentication & Authorization)

Input/Request Parameters

No input/request parameters are accepted.

Sample Response

HTTP/1.1 200 OK

{
    "success" : true,
    "error" : "",
    "ticket" : {
        "ticketNumber" : 12345678,
        "priority" : "NORMAL",
        "status" : "IN_PROGRESS",
        "firstName" : "John",
        "lastName" : "Smith",
        "emailAddress" : "johnsmith@testco.com",
        "phoneNumber" : "(123) 456-7890",
        "subject" : "My computer won't boot up",
        "message" : "I cannot get the computer to boot into Windows",
        "replies" : [
            {
                "repliedOn" : "2020-02-03T07:34:16-06:00",
                "firstName" : "Jane",
                "lastName" : "Doe",
                "emailAddress" : "janedoe@testco.com",
                "message" : "Have you tried powering the system off then on?"
            },
            {
                "repliedOn" : "2020-02-03T08:19:27-06:00",
                "firstName" : "John",
                "lastName" : "Smith",
                "emailAddress" : "johnsmith@testco.com",
                "message" : "Yes, I have."
            }
        ]
    }
}

Output/Response Parameters

FieldTypeDescription
successBooleanWill return true or false for whether or not the transaction was successful.
errorStringIntelligible string of the error that occurred. Will be empty if no error occurred.
ticketTicketContains the returned ticket details.
ticket{}.ticketNumberIntegerThe reference number of the ticket.
ticket{}.priorityStringThe priority of the ticket. See Ticket Priorities for all possible values.
ticket{}.statusStringThe status of the ticket. See Ticket Statuses for all possible values
ticket{}.firstNameStringThe first name of the person creating the ticket
ticket{}.lastNameStringThe last name of the person creating the ticket
ticket{}.emailAddressStringThe email address of the contact
ticket{}.phoneNumberStringThe phone number of the person creating the ticket
ticket{}.subjectStringThe subject of the ticket
ticket{}.messageStringThe message body of the ticket
ticket{}.replies[]ArrayAn array of Ticket Reply objects.
ticket{}.replies[]{}.repliedOnDate/TimeThe date/time when the ticket reply was made. (Defaults to "now" when creating.)
ticket{}.replies[]{}.firstNameStringThe first name of the person replying to the ticket
ticket{}.replies[]{}.lastNameStringThe last name of the person replying to the ticket
ticket{}.replies[]{}.emailAddressStringThe email address of the person replying to the ticket
ticket{}.replies[]{}.messageStringThe message body of the ticket reply

Typical Response Codes

HTTP CodeMeaningRequired Action
200 OKThe transaction was successful.
(Applicable to GET, PUT, and DELETE requests)
N/A
404 NOT FOUNDThe record could not be located.Ensure you have requested a record that exists.

Webhooks

If a webhook has been configured with your account, Agilant Solutions will automatically POST a JSON request to your provided endpoint when an event occurs.

Ticket Status ChangePOST {YourEndpoint}

This webhook will trigger when the status of a ticket has changed.

Sample Request to {YourEndpoint}

POST {YourEndpoint}

Content-Type: application/json

{
    "webhook" : "TICKET_STATUS_CHANGE",
    "ticketNumber" : 12345678,
    "status" : "CLOSED"
}

Request Parameters to {YourEndpoint}

FieldTypeDescription
webhookStringWill be exactly TICKET_STATUS_CHANGE. See Webhook Types for all possible webhook values.
ticketNumberIntegerThe ticket number of the ticket that changed
statusStringThe new status of the ticket. See Ticket Statuses for all possible values

Ticket ReplyPOST {YourEndpoint}

This webhook will trigger when a reply has been added to the ticket.

Sample Request to {YourEndpoint}

POST {YourEndpoint}

Content-Type: application/json

{
    "webhook" : "TICKET_REPLY",
    "ticketNumber" : 12345678,
    "reply" : {
        "repliedOn" : "2020-02-03T07:34:16-06:00",
        "firstName" : "Jane",
        "lastName" : "Doe",
        "emailAddress" : "janedoe@testco.com",
        "message" : "Have you tried restarting your machine?"
    }
}

Request Parameters to {YourEndpoint}

FieldTypeDescription
webhookStringWill be exactly TICKET_REPLY. See Webhook Types for all possible webhook values.
ticketNumberIntegerThe ticket number of the ticket that changed
replyTicket ReplyThe reply object that was added to the ticket.
reply{}.repliedOnDate/TimeThe date/time when the ticket reply was made. (Defaults to "now" when creating.)
reply{}.firstNameStringThe first name of the person replying to the ticket
reply{}.lastNameStringThe last name of the person replying to the ticket
reply{}.emailAddressStringThe email address of the person replying to the ticket
reply{}.messageStringThe message body of the ticket reply