NAV Navbar
JSON
Agilant Solutions, Inc.
Account Management API v2.4.1
Updated 6/9/2021

Overview

Introduction

This API implements functionality for managing accounts and services within our TOGa 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
VersionIntegerMust be exactly set to the value of 2
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
Version: 2
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',
    
'Version: 2',
    (
'Timestamp: '.$timestamp),
    (
'Authorization: '.$publicApiKey.'.'.base64_encode(hash_hmac('SHA256'$timestamp$secretApiKeytrue)))
];

?>

Responses

Sample Response Headers


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

Response Headers for Every Transaction

Header FieldTypeDescription
Content-TypeStringWill always be set to application/json
VersionIntegerVersion of the API which processed the request. Will be set to the value of 2.
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 of the request headers failed.Review the returned errors and correct the issue in the Request Header.
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

Account Status

Defines the account statuses.

Values

ValueDescription
ACTIVEAccount services are active
INACTIVEAccount services are inactive

Service Status

Defines the service statuses.

Values

ValueDescription
ACTIVEService is active
INACTIVEService is inactive
CANCELLEDService has been cancelled

Order Status

Defines the order statuses.

Values

ValueDescription
QUOTE_CREATEDNew quote record which is unpaid and unconfirmed
QUOTE_INCOMPLETEQuote which is missing required information
QUOTE_AWAITING_DIAGNOSTICQuote which is awaiting results of a diagnostic
QUOTE_DIAGNOSTIC_IN_PROGRESSQuote which is currently undergoing a diagnostic
QUOTE_DIAGNOSTIC_COMPLETEQuote which has had a diagnostic completed
QUOTE_DIAGNOSTIC_COMPLETE_FULL_SCAN_RECOMMENDEDQuote which has had a diagnostic completed but is recommending a full scan
QUOTE_PAYMENT_PENDINGQuote which is ready and pending payment confirmation
QUOTE_PAYMENT_ACCEPTEDQuote which is ready and a payment has been accepted
ORDER_ISSUE_INCOMPLETEPaid order which is missing required information
ORDER_ISSUE_ACTION_NEEDEDPaid order which is pending a required action to be completed
ORDER_SERVICE_PENDINGPaid order which has services pending
ORDER_IN_PROGRESSPaid order which has services currently being executed
ORDER_COMPLETEPaid order in which all services have been executed
ORDER_CANCELLEDPaid order which was cancelled

Order Type

Defines the order type.

Values

ValueDescription
NEWThe order is for a new PC
EXISTINGThe order is for an existing PC

Item Status

Defines the status of an item.

Values

ValueDescription
CREATEDThe item is created and unpaid
PAIDThe item is paid for
ISSUE_INCOMPLETEThe item is missing required information
ISSUE_ACTION_NEEDEDThe item requires an action to be taken
SERVICE_PENDINGA service appointment is pending
IN_PROGRESSA service appointment is in progress
COMPLETEThe service on the item is completed
CANCELLEDThe service on the item has been cancelled

Webhook Types

Defines the type of a webhook request

Values

ValueDescription
ACCOUNT_STATUS_CHANGEOccurs when an order status has changed.
SERVICE_STATUS_CHANGEOccurs when an order status has changed.
ORDER_STATUS_CHANGEOccurs when an order status has changed.
ITEM_STATUS_CHANGEOccurs when the status of an item changes.

Data Objects

Address

Sample Address Object


{
    "firstName" : "John",
    "lastName" : "Smith",
    "businessName" : "XYZ Company",
    "address1" : "123 Test Street",
    "address2" : "Suite 413",
    "city" : "Testville",
    "state" : "TN",
    "zipCode" : "12345"
}

Represents an address object.

Fields

FieldTypeDescription
firstNameStringAddress first name
lastNameStringAddress last name
businessNameStringAddress business name
address1StringAddress line 1
address2StringAddress line 2
cityStringAddress city
stateStringAddress state
zipCodeStringAddress ZIP code

Account

Sample Account Object


{
    "id" : "23526813",
    "firstName" : "Jane",
    "lastName" : "Doe",
    "emailAddress" : "jdoe@abccompany.com",
    "phoneNumber" : "534-555-3467",
    "businessName" : "ABC Company",
    "createDate" : "2019-08-06",
    "status" : "ACTIVE",
    "service" : [
        {
            "lineNumber" : 1,
            "skuNumber" : "PREM-SECURITY",
            "status" : "ACTIVE",
            "purchaseDate" : "2020-01-01",
            "cancellationDate" : "2021-07-01",
            "renewalDate" : "2021-01-01",
            "expirationDate" : "2020-12-31",
            "storeNumber" : "12345",
            "associateId" : "98765",
            "transactionId" : "2345789245789187635",
            "invoiceNumber" : "873452484",
            "comment" : "Please call upon arrival"
        },
        {
            "lineNumber" : 2,
            "skuNumber" : "IHIO-SMARTTV",
            "status" : "INACTIVE",
            "purchaseDate" : "2020-01-01",
            "cancellationDate" : null,
            "renewalDate" : null,
            "expirationDate" : null,
            "storeNumber" : "12345",
            "associateId" : "98765",
            "transactionId" : "1234524456246246",
            "invoiceNumber" : "3456745472",
            "comment" : "Please call upon arrival"
        }
    ]
}

Represents an account object.

Fields

FieldTypeDescription
idStringYour reference id referring to the account record in your system.
firstNameStringFirst name of the account holder
lastNameStringLast name of the account holder
emailAddressStringEmail address of the account holder
phoneNumberStringPhone number of the account holder
businessNameStringBusiness name of the account holder
createDateDateDate the account was created
statusStringThe status of the account. See Account Status for all values.
service[]ArrayArray of Service objects
service[]{}.lineNumberIntegerLine number of the service on the account
service[]{}.skuNumberStringSKU number of the service record
service[]{}.statusStringThe status of the service. See Service Status for all values.
service[]{}.purchaseDateDateDate of purchase
service[]{}.cancellationDateDateCancellation date that the service will be cancelled on. If this is null, the service will not be cancelled.
service[]{}.renewalDateDateDate the service will be renewed. If this is null, the service will not be renewed and will be expire on the expirationDate.
service[]{}.expirationDateDateDate the service will expire.
service[]{}.storeNumberStringStore number the service was sold in
service[]{}.associateIdStringAssociate ID of the salesperson who sold the service
service[]{}.transactionIdStringTransaction ID of the receipt the service was purchased on
service[]{}.invoiceNumberStringInvoice number the service was purchased on
service[]{}.commentStringNotes/comments of the service

Service

Sample Service Object


{
    "lineNumber" : 1,
    "skuNumber" : "PREM-SECURITY",
    "status" : "ACTIVE",
    "purchaseDate" : "2020-01-01",
    "cancellationDate" : "2021-07-01",
    "renewalDate" : "2021-01-01",
    "expirationDate" : "2020-12-31",
    "storeNumber" : "12345",
    "associateId" : "98765",
    "transactionId" : "2345789245789187635",
    "invoiceNumber" : "873452484",
    "comment" : "Please call upon arrival"
}

Represents a service object.

Fields

FieldTypeDescription
lineNumberIntegerLine number of the service on the account
skuNumberStringSKU number of the service record
statusStringThe status of the service. See Service Status for all values.
purchaseDateDateDate of purchase
cancellationDateDateCancellation date that the service will be cancelled on. If this is null, the service will not be cancelled.
renewalDateDateDate the service will be renewed. If this is null, the service will not be renewed and will be expire on the expirationDate.
expirationDateDateDate the service will expire.
storeNumberStringStore number the service was sold in
associateIdStringAssociate ID of the salesperson who sold the service
transactionIdStringTransaction ID of the receipt the service was purchased on
invoiceNumberStringInvoice number the service was purchased on
commentStringNotes/comments of the service

Order

Sample Order Object


{
    "number" : "89023475",
    "type" : "NEW",
    "status" : "QUOTE_CREATED",
    "firstName" : "John",
    "lastName" : "Smith",
    "emailAddress" : "jsmith@abccompany.com",
    "phoneNumber" : "893-555-4523",
    "businessName" : "ABC Company",
    "createdOn" : "2021-09-15T14:35:00-05:00",
    "updatedOn" : "2021-09-15T14:35:00-05:00",
    "paid" : true,
    "vendorId" : "45626",
    "loyaltyId" : "457215",
    "storeNumber" : "6125",
    "associateId" : "3456",
    "billTo" : {
        "firstName" : "John",
        "lastName" : "Smith",
        "businessName" : "ABC Company",
        "address1" : "123 Test Street",
        "address2" : "Suite 413",
        "city" : "Testville",
        "state" : "TN",
        "zipCode" : "12345"
    },
    "shipTo" : {
        "firstName" : "John",
        "lastName" : "Smith",
        "businessName" : "ABC Company",
        "address1" : "123 Test Street",
        "address2" : "Suite 413",
        "city" : "Testville",
        "state" : "TN",
        "zipCode" : "12345"
    },
    "item" : [
        {
            "lineNumber" : 1,
            "skuNumber" : "890345563",
            "partNumber" : "ABC-12345",
            "upcCode" : "23457892345789",
            "status" : "PAID",
            "quantity" : 1,
            "paid" : true,
            "returned" : false,
            "returnable" : true,
            "voidable" : true,
            "discountable" : true,
            "taxable" : true,
            "isSubscription" : false,
            "createdOn" : "2021-09-15T14:35:00-05:00",
            "paidOn" : "2021-09-16T17:23:54-05:00",
            "title" : "In-Home Smart TV Installation",
            "shortDescription" : "A qualified and experienced technician will come to your house to install your smart TV.",
            "longDescription" : "Lorem ipsum dolor sit amet, consectetur adipiscing elit. Donec fermentum vehicula nisl, sed volutpat tellus sollicitudin id. Ut id risus lobortis, molestie neque eu, dictum metus.",
            "termsAndConditions" : "Morbi dignissim augue massa, eget vestibulum erat molestie nec. Donec at lorem at lacus mollis condimentum bibendum non enim. Curabitur eu odio at dolor feugiat aliquet. Donec non ante faucibus, hendrerit felis eget, vulputate arcu."
        },
        {
            "lineNumber" : 2,
            "skuNumber" : "346346",
            "partNumber" : "DEF-56756",
            "upcCode" : "38924579458",
            "status" : "COMPLETE",
            "quantity" : 1,
            "paid" : true,
            "returned" : false,
            "returnable" : true,
            "voidable" : true,
            "discountable" : true,
            "taxable" : true,
            "isSubscription" : false,
            "createdOn" : "2021-09-15T14:35:00-05:00",
            "paidOn" : "2021-09-16T17:23:54-05:00",
            "title" : "In-Home Smart Doorbell Installation",
            "shortDescription" : "A qualified and experienced technician will come to your house to install your smart doorbell.",
            "longDescription" : "Lorem ipsum dolor sit amet, consectetur adipiscing elit. Donec fermentum vehicula nisl, sed volutpat tellus sollicitudin id. Ut id risus lobortis, molestie neque eu, dictum metus.",
            "termsAndConditions" : "Morbi dignissim augue massa, eget vestibulum erat molestie nec. Donec at lorem at lacus mollis condimentum bibendum non enim. Curabitur eu odio at dolor feugiat aliquet. Donec non ante faucibus, hendrerit felis eget, vulputate arcu."
        }
    ]
}

Represents an order object.

Fields

FieldTypeDescription
numberStringUnique order number reference
typeStringThe type of order. See Order Type for all values.
statusStringThe current status of the order. See Order Status for all values.
firstNameStringFirst name of the order holder
lastNameStringLast name of the order holder
emailAddressStringEmail address of the order holder
phoneNumberStringPhone number of the order holder
businessNameStringBusiness name of the order holder
createdOnDate/TimeDate/time the order was created
updatedOnDate/TimeDate/time the order was created
paidBooleanWhether or not ALL items have been for
vendorIdStringInternal vendor identifier
loyaltyIdStringLoyalty ID reference identifier
storeNumberStringStore number where the order was created
associateIdStringAssociate ID who initiated the order
billTo{}AddressBilling address information
billTo{}.firstNameStringAddress first name
billTo{}.lastNameStringAddress last name
billTo{}.businessNameStringAddress business name
billTo{}.address1StringAddress line 1
billTo{}.address2StringAddress line 2
billTo{}.cityStringAddress city
billTo{}.stateStringAddress state
billTo{}.zipCodeStringAddress ZIP code
shipTo{}AddressShipping address information
shipTo{}.firstNameStringAddress first name
shipTo{}.lastNameStringAddress last name
shipTo{}.businessNameStringAddress business name
shipTo{}.address1StringAddress line 1
shipTo{}.address2StringAddress line 2
shipTo{}.cityStringAddress city
shipTo{}.stateStringAddress state
shipTo{}.zipCodeStringAddress ZIP code
item[]ArrayArray of Item objects on the order.
item[]{}.lineNumberIntegerLine number of the item on the order
item[]{}.skuNumberStringSKU number of the item on the order
item[]{}.partNumberStringManufacturer's part number of the item
item[]{}.upcCodeStringUPC code of the item
item[]{}.statusStringCurrent status of the item. See Item Status for all values.
item[]{}.quantityIntegerUnit quantity of the item
item[]{}.paidBooleanWhether or not the item has been paid for
item[]{}.returnedBooleanWhether or not the item has been returned
item[]{}.returnableBooleanWhether or not the item is returnable
item[]{}.voidableBooleanWhether or not the item is voidable
item[]{}.discountableBooleanWhether or not the item is discountable
item[]{}.taxableBooleanWhether or not the item is taxable
item[]{}.isSubscriptionBooleanWhether or not the item is a recurring subscription
item[]{}.createdOnDate/TimeDate/time the item was created on
item[]{}.paidOnDate/TimeDate/time the item was paid for
item[]{}.titleStringTitle of the item
item[]{}.shortDescriptionStringShort description of the item
item[]{}.longDescriptionStringLong description of the item
item[]{}.termsAndConditionsStringItem-level terms & conditions

Item

Sample Item Object


{
    "lineNumber" : 1,
    "skuNumber" : "890345563",
    "partNumber" : "ABC-12345",
    "upcCode" : "23457892345789",
    "status" : "PAID",
    "quantity" : 1,
    "paid" : true,
    "returned" : false,
    "returnable" : true,
    "voidable" : true,
    "discountable" : true,
    "taxable" : true,
    "isSubscription" : false,
    "createdOn" : "2021-09-15T14:35:00-05:00",
    "paidOn" : "2021-09-16T17:23:54-05:00",
    "title" : "In-Home Smart TV Installation",
    "shortDescription" : "A qualified and experienced technician will come to your house to install your smart TV.",
    "longDescription" : "Lorem ipsum dolor sit amet, consectetur adipiscing elit. Donec fermentum vehicula nisl, sed volutpat tellus sollicitudin id. Ut id risus lobortis, molestie neque eu, dictum metus.",
    "termsAndConditions" : "Morbi dignissim augue massa, eget vestibulum erat molestie nec. Donec at lorem at lacus mollis condimentum bibendum non enim. Curabitur eu odio at dolor feugiat aliquet. Donec non ante faucibus, hendrerit felis eget, vulputate arcu."
}

Represents an item object.

Fields

FieldTypeDescription
lineNumberIntegerLine number of the item on the order
skuNumberStringSKU number of the item on the order
partNumberStringManufacturer's part number of the item
upcCodeStringUPC code of the item
statusStringCurrent status of the item. See Item Status for all values.
quantityIntegerUnit quantity of the item
paidBooleanWhether or not the item has been paid for
returnedBooleanWhether or not the item has been returned
returnableBooleanWhether or not the item is returnable
voidableBooleanWhether or not the item is voidable
discountableBooleanWhether or not the item is discountable
taxableBooleanWhether or not the item is taxable
isSubscriptionBooleanWhether or not the item is a recurring subscription
createdOnDate/TimeDate/time the item was created on
paidOnDate/TimeDate/time the item was paid for
titleStringTitle of the item
shortDescriptionStringShort description of the item
longDescriptionStringLong description of the item
termsAndConditionsStringItem-level terms & conditions

Accounts

Retrieve an AccountGET /account/{account.id}

Use this request to retrieve an account and view its status or information

Sample Request

GET /account/23526813

Content-Type: application/json
Version: 2
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" : null,
    "account" : {
        "id" : "23526813",
        "firstName" : "Jane",
        "lastName" : "Doe",
        "emailAddress" : "jdoe@abccompany.com",
        "phoneNumber" : "534-555-3467",
        "businessName" : "ABC Company",
        "createDate" : "2019-08-06",
        "status" : "ACTIVE",
        "service" : [
            {
                "lineNumber" : 1,
                "skuNumber" : "PREM-SECURITY",
                "status" : "ACTIVE",
                "purchaseDate" : "2020-01-01",
                "cancellationDate" : "2021-07-01",
                "renewalDate" : "2021-01-01",
                "expirationDate" : "2020-12-31",
                "storeNumber" : "12345",
                "associateId" : "98765",
                "transactionId" : "2345789245789187635",
                "invoiceNumber" : "873452484",
                "comment" : "Please call upon arrival"
            },
            {
                "lineNumber" : 2,
                "skuNumber" : "IHIO-SMARTTV",
                "status" : "INACTIVE",
                "purchaseDate" : "2020-01-01",
                "cancellationDate" : null,
                "renewalDate" : null,
                "expirationDate" : null,
                "storeNumber" : "12345",
                "associateId" : "98765",
                "transactionId" : "1234524456246246",
                "invoiceNumber" : "3456745472",
                "comment" : "Please call upon arrival"
            }
        ]
    }
}

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 null if no error occurred.
account{}AccountContains the returned account object.
account{}.idStringYour reference id referring to the account record in your system.
account{}.firstNameStringFirst name of the account holder
account{}.lastNameStringLast name of the account holder
account{}.emailAddressStringEmail address of the account holder
account{}.phoneNumberStringPhone number of the account holder
account{}.businessNameStringBusiness name of the account holder
account{}.createDateDateDate the account was created
account{}.statusStringThe status of the account. See Account Status for all values.
account{}.service[]ArrayArray of Service objects
account{}.service[]{}.lineNumberIntegerLine number of the service on the account
account{}.service[]{}.skuNumberStringSKU number of the service record
account{}.service[]{}.statusStringThe status of the service. See Service Status for all values.
account{}.service[]{}.purchaseDateDateDate of purchase
account{}.service[]{}.cancellationDateDateCancellation date that the service will be cancelled on. If this is null, the service will not be cancelled.
account{}.service[]{}.renewalDateDateDate the service will be renewed. If this is null, the service will not be renewed and will be expire on the expirationDate.
account{}.service[]{}.expirationDateDateDate the service will expire.
account{}.service[]{}.storeNumberStringStore number the service was sold in
account{}.service[]{}.associateIdStringAssociate ID of the salesperson who sold the service
account{}.service[]{}.transactionIdStringTransaction ID of the receipt the service was purchased on
account{}.service[]{}.invoiceNumberStringInvoice number the service was purchased on
account{}.service[]{}.commentStringNotes/comments of the service

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.

Create an AccountPOST /account

Use this request to create one or many accounts.

Sample Request

POST /account

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

{
    "account" : [
        {
            "id" : "23526813",
            "firstName" : "Jane",
            "lastName" : "Doe",
            "emailAddress" : "jdoe@abccompany.com",
            "phoneNumber" : "534-555-3467",
            "businessName" : "ABC Company",
            "service" : [
                {
                    "lineNumber" : 1,
                    "skuNumber" : "PREM-SECURITY",
                    "purchaseDate" : "2020-01-01",
                    "cancellationDate" : "2021-07-01",
                    "renewalDate" : "2021-01-01",
                    "expirationDate" : "2020-12-31",
                    "storeNumber" : "12345",
                    "associateId" : "98765",
                    "transactionId" : "2345789245789187635",
                    "invoiceNumber" : "873452484",
                    "comment" : "Please call upon arrival"
                },
                {
                    "lineNumber" : 2,
                    "skuNumber" : "IHIO-SMARTTV",
                    "purchaseDate" : "2020-01-01",
                    "cancellationDate" : null,
                    "renewalDate" : null,
                    "expirationDate" : null,
                    "storeNumber" : "12345",
                    "associateId" : "98765",
                    "transactionId" : "1234524456246246",
                    "invoiceNumber" : "3456745472",
                    "comment" : "Please call upon arrival"
                }
            ]
        }
    ]
}

Input/Request Parameters

FieldTypeDescriptionRequired
account[]ArrayAn array of Account objects.Yes
account[]{}.idStringYour reference id referring to the account record in your system.Yes
account[]{}.firstNameStringFirst name of the account holderYes
account[]{}.lastNameStringLast name of the account holderYes
account[]{}.emailAddressStringEmail address of the account holderYes
account[]{}.phoneNumberStringPhone number of the account holderNo
account[]{}.businessNameStringBusiness name of the account holderNo
account[]{}.service[]ArrayArray of Service objectsNo
account[]{}.service[]{}.lineNumberIntegerLine number of the service on the accountNo
account[]{}.service[]{}.skuNumberStringSKU number of the service recordYes
account[]{}.service[]{}.purchaseDateDateDate of purchaseYes
account[]{}.service[]{}.cancellationDateDateCancellation date that the service will be cancelled on. If this is null, the service will not be cancelled.No
account[]{}.service[]{}.renewalDateDateDate the service will be renewed. If this is null, the service will not be renewed and will be expire on the expirationDate.No
account[]{}.service[]{}.expirationDateDateDate the service will expire.No
account[]{}.service[]{}.storeNumberStringStore number the service was sold inNo
account[]{}.service[]{}.associateIdStringAssociate ID of the salesperson who sold the serviceNo
account[]{}.service[]{}.transactionIdStringTransaction ID of the receipt the service was purchased onNo
account[]{}.service[]{}.invoiceNumberStringInvoice number the service was purchased onNo
account[]{}.service[]{}.commentStringNotes/comments of the serviceNo

Sample Response

HTTP/1.1 201 CREATED

{
    "success" : true,
    "error" : null
}

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 null if no error occurred.

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.
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.

Modify an AccountPUT /account/{account.id}

Use this request to modify an account in the system.

Sample Request

PUT /account/23526813

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

{
    "account" : {
        "id" : "23526813",
        "firstName" : "Jane",
        "lastName" : "Doe",
        "emailAddress" : "jdoe@abccompany.com",
        "phoneNumber" : "534-555-3467",
        "businessName" : "ABC Company"
    }
}

Input/Request Parameters

FieldTypeDescriptionRequired
account{}AccountThe account to modifyYes
account{}.idStringYour reference id referring to the account record in your system.No
account{}.firstNameStringFirst name of the account holderNo
account{}.lastNameStringLast name of the account holderNo
account{}.emailAddressStringEmail address of the account holderNo
account{}.phoneNumberStringPhone number of the account holderNo
account{}.businessNameStringBusiness name of the account holderNo

Sample Response

HTTP/1.1 200 OK

{
    "success" : true,
    "error" : null
}

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 null if no error occurred.

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.
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.

Delete an AccountDELETE /account/{account.id}

Use this request to delete an account and cancel any outstanding subscriptions

Sample Request

DELETE /account/23526813

Content-Type: application/json
Version: 2
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" : null
}

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 null if no error occurred.

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.

Use this request to retrieve the unique agent download link for the account.

Sample Request

GET /account/23526813/link/agent

Content-Type: application/json
Version: 2
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" : null,
    "link" : "https://test.agentlink.com/ABCDEFG12345"
}

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 null if no error occurred.
linkStringContains the returned download link string.

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.

Services

Create a ServicePOST /account/{account.id}/service

Use this request to add one or more new services to an account

Sample Request

POST /account/23526813/service

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

{
    "service" : {
        "lineNumber" : 1,
        "skuNumber" : "PREM-SECURITY",
        "purchaseDate" : "2020-01-01",
        "cancellationDate" : "2021-07-01",
        "renewalDate" : "2021-01-01",
        "expirationDate" : "2020-12-31",
        "storeNumber" : "12345",
        "associateId" : "98765",
        "transactionId" : "2345789245789187635",
        "invoiceNumber" : "873452484",
        "comment" : "Please call upon arrival"
    }
}

Input/Request Parameters

FieldTypeDescriptionRequired
service{}ServiceThe service to add to the accountYes
service{}.skuNumberStringSKU number of the service recordYes
service{}.purchaseDateDateDate of purchaseYes
service{}.cancellationDateDateCancellation date that the service will be cancelled on. If this is null, the service will not be cancelled.No
service{}.renewalDateDateDate the service will be renewed. If this is null, the service will not be renewed and will be expire on the expirationDate.No
service{}.expirationDateDateDate the service will expire.No
service{}.storeNumberStringStore number the service was sold inNo
service{}.associateIdStringAssociate ID of the salesperson who sold the serviceNo
service{}.transactionIdStringTransaction ID of the receipt the service was purchased onNo
service{}.invoiceNumberStringInvoice number the service was purchased onNo
service{}.commentStringNotes/comments of the serviceNo

No input/request parameters are accepted.

Sample Response

HTTP/1.1 201 CREATED

{
    "success" : true,
    "error" : null
}

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 null if no error occurred.

Typical Response Codes

HTTP CodeMeaningRequired Action
201 CREATEDThe record was successfully created.
(Applicable only to POST requests)
N/A
404 NOT FOUNDThe record could not be located.Ensure you have requested a record that exists.
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.

Modify a ServicePUT /account/{account.id}/service/{service.skuNumber}

Use this request to modify a service on an account.

Sample Request

PUT /account/23526813/service/PREM-SECURITY

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

{
    "service" : {
        "lineNumber" : 1,
        "purchaseDate" : "2020-01-01",
        "cancellationDate" : "2021-07-01",
        "renewalDate" : "2021-01-01",
        "expirationDate" : "2020-12-31",
        "storeNumber" : "12345",
        "associateId" : "98765",
        "transactionId" : "2345789245789187635",
        "invoiceNumber" : "873452484",
        "comment" : "Please call upon arrival"
    }
}

Input/Request Parameters

FieldTypeDescriptionRequired
service{}ServiceThe service to modifyYes
service{}.lineNumberIntegerLine number of the service on the accountYes
service{}.purchaseDateDateDate of purchaseNo
service{}.cancellationDateDateCancellation date that the service will be cancelled on. If this is null, the service will not be cancelled.No
service{}.renewalDateDateDate the service will be renewed. If this is null, the service will not be renewed and will be expire on the expirationDate.No
service{}.expirationDateDateDate the service will expire.No
service{}.storeNumberStringStore number the service was sold inNo
service{}.associateIdStringAssociate ID of the salesperson who sold the serviceNo
service{}.transactionIdStringTransaction ID of the receipt the service was purchased onNo
service{}.invoiceNumberStringInvoice number the service was purchased onNo
service{}.commentStringNotes/comments of the serviceNo

Sample Response

HTTP/1.1 200 OK

{
    "success" : true,
    "error" : null
}

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 null if no error occurred.

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.

Delete a ServiceDELETE /account/{account.id}/service/{service.skuNumber}

Use this request to remove a service from an account.

Sample Request

DELETE /account/23526813/service/PREM-SECURITY

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

{
    "lineNumber" : 1
}

Input/Request Parameters

FieldTypeDescriptionRequired
lineNumberIntegerThe line number of the service to make the change upon. *Required for multiple services of the same SKU number.Yes

Sample Response

HTTP/1.1 200 OK

{
    "success" : true,
    "error" : null
}

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 null if no error occurred.

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.

Orders

Retrieve an OrderGET /order/{order.number || order.transactionId}

Use this request to retrieve order details of an order number or transaction ID. This call should be used to check an order status or get its details.

Sample Request

GET /order/89023475

Content-Type: application/json
Version: 2
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" : null,
    "order" : {
        "number" : "89023475",
        "type" : "NEW",
        "status" : "QUOTE_CREATED",
        "firstName" : "John",
        "lastName" : "Smith",
        "emailAddress" : "jsmith@abccompany.com",
        "phoneNumber" : "893-555-4523",
        "businessName" : "ABC Company",
        "createdOn" : "2021-09-15T14:35:00-05:00",
        "updatedOn" : "2021-09-15T14:35:00-05:00",
        "paid" : true,
        "vendorId" : "45626",
        "loyaltyId" : "457215",
        "storeNumber" : "6125",
        "associateId" : "3456",
        "billTo" : {
            "firstName" : "John",
            "lastName" : "Smith",
            "businessName" : "ABC Company",
            "address1" : "123 Test Street",
            "address2" : "Suite 413",
            "city" : "Testville",
            "state" : "TN",
            "zipCode" : "12345"
        },
        "shipTo" : {
            "firstName" : "John",
            "lastName" : "Smith",
            "businessName" : "ABC Company",
            "address1" : "123 Test Street",
            "address2" : "Suite 413",
            "city" : "Testville",
            "state" : "TN",
            "zipCode" : "12345"
        },
        "item" : [
            {
                "lineNumber" : 1,
                "skuNumber" : "890345563",
                "partNumber" : "ABC-12345",
                "upcCode" : "23457892345789",
                "status" : "PAID",
                "quantity" : 1,
                "paid" : true,
                "returned" : false,
                "returnable" : true,
                "voidable" : true,
                "discountable" : true,
                "taxable" : true,
                "isSubscription" : false,
                "createdOn" : "2021-09-15T14:35:00-05:00",
                "paidOn" : "2021-09-16T17:23:54-05:00",
                "title" : "In-Home Smart TV Installation",
                "shortDescription" : "A qualified and experienced technician will come to your house to install your smart TV.",
                "longDescription" : "Lorem ipsum dolor sit amet, consectetur adipiscing elit. Donec fermentum vehicula nisl, sed volutpat tellus sollicitudin id. Ut id risus lobortis, molestie neque eu, dictum metus.",
                "termsAndConditions" : "Morbi dignissim augue massa, eget vestibulum erat molestie nec. Donec at lorem at lacus mollis condimentum bibendum non enim. Curabitur eu odio at dolor feugiat aliquet. Donec non ante faucibus, hendrerit felis eget, vulputate arcu."
            },
            {
                "lineNumber" : 2,
                "skuNumber" : "346346",
                "partNumber" : "DEF-56756",
                "upcCode" : "38924579458",
                "status" : "COMPLETE",
                "quantity" : 1,
                "paid" : true,
                "returned" : false,
                "returnable" : true,
                "voidable" : true,
                "discountable" : true,
                "taxable" : true,
                "isSubscription" : false,
                "createdOn" : "2021-09-15T14:35:00-05:00",
                "paidOn" : "2021-09-16T17:23:54-05:00",
                "title" : "In-Home Smart Doorbell Installation",
                "shortDescription" : "A qualified and experienced technician will come to your house to install your smart doorbell.",
                "longDescription" : "Lorem ipsum dolor sit amet, consectetur adipiscing elit. Donec fermentum vehicula nisl, sed volutpat tellus sollicitudin id. Ut id risus lobortis, molestie neque eu, dictum metus.",
                "termsAndConditions" : "Morbi dignissim augue massa, eget vestibulum erat molestie nec. Donec at lorem at lacus mollis condimentum bibendum non enim. Curabitur eu odio at dolor feugiat aliquet. Donec non ante faucibus, hendrerit felis eget, vulputate arcu."
            }
        ]
    }
}

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 null if no error occurred.
order{}OrderContains the returned order details.
order{}.numberStringUnique order number reference
order{}.typeStringThe type of order. See Order Type for all values.
order{}.statusStringThe current status of the order. See Order Status for all values.
order{}.firstNameStringFirst name of the order holder
order{}.lastNameStringLast name of the order holder
order{}.emailAddressStringEmail address of the order holder
order{}.phoneNumberStringPhone number of the order holder
order{}.businessNameStringBusiness name of the order holder
order{}.createdOnDate/TimeDate/time the order was created
order{}.updatedOnDate/TimeDate/time the order was created
order{}.paidBooleanWhether or not ALL items have been for
order{}.vendorIdStringInternal vendor identifier
order{}.loyaltyIdStringLoyalty ID reference identifier
order{}.storeNumberStringStore number where the order was created
order{}.associateIdStringAssociate ID who initiated the order
order{}.billTo{}AddressBilling address information
order{}.billTo{}.firstNameStringAddress first name
order{}.billTo{}.lastNameStringAddress last name
order{}.billTo{}.businessNameStringAddress business name
order{}.billTo{}.address1StringAddress line 1
order{}.billTo{}.address2StringAddress line 2
order{}.billTo{}.cityStringAddress city
order{}.billTo{}.stateStringAddress state
order{}.billTo{}.zipCodeStringAddress ZIP code
order{}.shipTo{}AddressShipping address information
order{}.shipTo{}.firstNameStringAddress first name
order{}.shipTo{}.lastNameStringAddress last name
order{}.shipTo{}.businessNameStringAddress business name
order{}.shipTo{}.address1StringAddress line 1
order{}.shipTo{}.address2StringAddress line 2
order{}.shipTo{}.cityStringAddress city
order{}.shipTo{}.stateStringAddress state
order{}.shipTo{}.zipCodeStringAddress ZIP code
order{}.item[]ArrayArray of Item objects on the order.
order{}.item[]{}.lineNumberIntegerLine number of the item on the order
order{}.item[]{}.skuNumberStringSKU number of the item on the order
order{}.item[]{}.partNumberStringManufacturer's part number of the item
order{}.item[]{}.upcCodeStringUPC code of the item
order{}.item[]{}.statusStringCurrent status of the item. See Item Status for all values.
order{}.item[]{}.quantityIntegerUnit quantity of the item
order{}.item[]{}.paidBooleanWhether or not the item has been paid for
order{}.item[]{}.returnedBooleanWhether or not the item has been returned
order{}.item[]{}.returnableBooleanWhether or not the item is returnable
order{}.item[]{}.voidableBooleanWhether or not the item is voidable
order{}.item[]{}.discountableBooleanWhether or not the item is discountable
order{}.item[]{}.taxableBooleanWhether or not the item is taxable
order{}.item[]{}.isSubscriptionBooleanWhether or not the item is a recurring subscription
order{}.item[]{}.createdOnDate/TimeDate/time the item was created on
order{}.item[]{}.paidOnDate/TimeDate/time the item was paid for
order{}.item[]{}.titleStringTitle of the item
order{}.item[]{}.shortDescriptionStringShort description of the item
order{}.item[]{}.longDescriptionStringLong description of the item
order{}.item[]{}.termsAndConditionsStringItem-level terms & conditions

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.

Modify an OrderPUT /order/{order.number || order.transactionId}

Use this request to update or change order details including payment confirmation.

Sample Request

PUT /order/89023475

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

{
    "order" : {
        "number" : "89023475",
        "firstName" : "John",
        "lastName" : "Smith",
        "emailAddress" : "jsmith@abccompany.com",
        "phoneNumber" : "893-555-4523",
        "businessName" : "ABC Company",
        "loyaltyId" : "457215",
        "storeNumber" : "6125",
        "associateId" : "3456",
        "billTo" : {
            "firstName" : "John",
            "lastName" : "Smith",
            "businessName" : "ABC Company",
            "address1" : "123 Test Street",
            "address2" : "Suite 413",
            "city" : "Testville",
            "state" : "TN",
            "zipCode" : "12345"
        },
        "shipTo" : {
            "firstName" : "John",
            "lastName" : "Smith",
            "businessName" : "ABC Company",
            "address1" : "123 Test Street",
            "address2" : "Suite 413",
            "city" : "Testville",
            "state" : "TN",
            "zipCode" : "12345"
        },
        "item" : [
            {
                "lineNumber" : 1,
                "quantity" : 1,
                "paid" : true,
                "returned" : false
            },
            {
                "lineNumber" : 2,
                "quantity" : 1,
                "paid" : true,
                "returned" : false
            }
        ]
    }
}

Input/Request Parameters

FieldTypeDescriptionRequired
order{}OrderThe order object to modify.Yes
order{}.numberStringUnique order number referenceNo
order{}.firstNameStringFirst name of the order holderNo
order{}.lastNameStringLast name of the order holderNo
order{}.emailAddressStringEmail address of the order holderNo
order{}.phoneNumberStringPhone number of the order holderNo
order{}.businessNameStringBusiness name of the order holderNo
order{}.loyaltyIdStringLoyalty ID reference identifierNo
order{}.storeNumberStringStore number where the order was createdNo
order{}.associateIdStringAssociate ID who initiated the orderNo
order{}.billTo{}AddressBilling address informationNo
order{}.billTo{}.firstNameStringAddress first nameNo
order{}.billTo{}.lastNameStringAddress last nameNo
order{}.billTo{}.businessNameStringAddress business nameNo
order{}.billTo{}.address1StringAddress line 1No
order{}.billTo{}.address2StringAddress line 2No
order{}.billTo{}.cityStringAddress cityNo
order{}.billTo{}.stateStringAddress stateNo
order{}.billTo{}.zipCodeStringAddress ZIP codeNo
order{}.shipTo{}AddressShipping address informationNo
order{}.shipTo{}.firstNameStringAddress first nameNo
order{}.shipTo{}.lastNameStringAddress last nameNo
order{}.shipTo{}.businessNameStringAddress business nameNo
order{}.shipTo{}.address1StringAddress line 1No
order{}.shipTo{}.address2StringAddress line 2No
order{}.shipTo{}.cityStringAddress cityNo
order{}.shipTo{}.stateStringAddress stateNo
order{}.shipTo{}.zipCodeStringAddress ZIP codeNo
order{}.item[]ArrayArray of Item objects on the order.No
order{}.item[]{}.lineNumberIntegerLine number of the item on the orderNo
order{}.item[]{}.quantityIntegerUnit quantity of the itemNo
order{}.item[]{}.paidBooleanWhether or not the item has been paid forNo
order{}.item[]{}.returnedBooleanWhether or not the item has been returnedNo

Sample Response

HTTP/1.1 200 OK

{
    "success" : true,
    "error" : null
}

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 null if no error occurred.

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.

Delete an Order ItemDELETE /order/{order.number || order.transactionId}/item/{item.skuNumber}

Use this request to remove an item.

Sample Request

DELETE /order/89023475

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

]

Input/Request Parameters

FieldTypeDescriptionRequired
lineNumberIntegerThe line number of the service to delete. *Required for multiple services of the same SKU number.Yes

Sample Response

HTTP/1.1 200 OK

{
    "success" : true,
    "error" : null
}

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 null if no error occurred.

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.

Account Status ChangePOST {YourEndpoint}

This webhook will trigger when the status of an account changes and will POST an up-to-date Account object containing the status and all other account details.

Sample Request to {YourEndpoint}

POST {YourEndpoint}

Content-Type: application/json

{
    "webhook" : "ACCOUNT_STATUS_CHANGE",
    "account" : {
        "id" : "23526813",
        "firstName" : "Jane",
        "lastName" : "Doe",
        "emailAddress" : "jdoe@abccompany.com",
        "phoneNumber" : "534-555-3467",
        "businessName" : "ABC Company",
        "createDate" : "2019-08-06",
        "status" : "ACTIVE",
        "service" : [
            {
                "lineNumber" : 1,
                "skuNumber" : "PREM-SECURITY",
                "status" : "ACTIVE",
                "purchaseDate" : "2020-01-01",
                "cancellationDate" : "2021-07-01",
                "renewalDate" : "2021-01-01",
                "expirationDate" : "2020-12-31",
                "storeNumber" : "12345",
                "associateId" : "98765",
                "transactionId" : "2345789245789187635",
                "invoiceNumber" : "873452484",
                "comment" : "Please call upon arrival"
            },
            {
                "lineNumber" : 2,
                "skuNumber" : "IHIO-SMARTTV",
                "status" : "INACTIVE",
                "purchaseDate" : "2020-01-01",
                "cancellationDate" : null,
                "renewalDate" : null,
                "expirationDate" : null,
                "storeNumber" : "12345",
                "associateId" : "98765",
                "transactionId" : "1234524456246246",
                "invoiceNumber" : "3456745472",
                "comment" : "Please call upon arrival"
            }
        ]
    }
}

Request Parameters to {YourEndpoint}

FieldTypeDescription
webhookStringWill be exactly ACCOUNT_STATUS_CHANGE. See Webhook Types for all possible webhook values.
account{}AccountContains the returned account details.
account{}.idStringYour reference id referring to the account record in your system.
account{}.firstNameStringFirst name of the account holder
account{}.lastNameStringLast name of the account holder
account{}.emailAddressStringEmail address of the account holder
account{}.phoneNumberStringPhone number of the account holder
account{}.businessNameStringBusiness name of the account holder
account{}.createDateDateDate the account was created
account{}.statusStringThe status of the account. See Account Status for all values.
account{}.service[]ArrayArray of Service objects
account{}.service[]{}.lineNumberIntegerLine number of the service on the account
account{}.service[]{}.skuNumberStringSKU number of the service record
account{}.service[]{}.statusStringThe status of the service. See Service Status for all values.
account{}.service[]{}.purchaseDateDateDate of purchase
account{}.service[]{}.cancellationDateDateCancellation date that the service will be cancelled on. If this is null, the service will not be cancelled.
account{}.service[]{}.renewalDateDateDate the service will be renewed. If this is null, the service will not be renewed and will be expire on the expirationDate.
account{}.service[]{}.expirationDateDateDate the service will expire.
account{}.service[]{}.storeNumberStringStore number the service was sold in
account{}.service[]{}.associateIdStringAssociate ID of the salesperson who sold the service
account{}.service[]{}.transactionIdStringTransaction ID of the receipt the service was purchased on
account{}.service[]{}.invoiceNumberStringInvoice number the service was purchased on
account{}.service[]{}.commentStringNotes/comments of the service

Service Status ChangePOST {YourEndpoint}

This webhook will trigger when the status of a service changes and will POST an up-to-date Account object containing the status and all other account details.

Sample Request to {YourEndpoint}

POST {YourEndpoint}

Content-Type: application/json

{
    "webhook" : "SERVICE_STATUS_CHANGE",
    "account" : {
        "id" : "23526813",
        "firstName" : "Jane",
        "lastName" : "Doe",
        "emailAddress" : "jdoe@abccompany.com",
        "phoneNumber" : "534-555-3467",
        "businessName" : "ABC Company",
        "createDate" : "2019-08-06",
        "status" : "ACTIVE",
        "service" : [
            {
                "lineNumber" : 1,
                "skuNumber" : "PREM-SECURITY",
                "status" : "ACTIVE",
                "purchaseDate" : "2020-01-01",
                "cancellationDate" : "2021-07-01",
                "renewalDate" : "2021-01-01",
                "expirationDate" : "2020-12-31",
                "storeNumber" : "12345",
                "associateId" : "98765",
                "transactionId" : "2345789245789187635",
                "invoiceNumber" : "873452484",
                "comment" : "Please call upon arrival"
            },
            {
                "lineNumber" : 2,
                "skuNumber" : "IHIO-SMARTTV",
                "status" : "INACTIVE",
                "purchaseDate" : "2020-01-01",
                "cancellationDate" : null,
                "renewalDate" : null,
                "expirationDate" : null,
                "storeNumber" : "12345",
                "associateId" : "98765",
                "transactionId" : "1234524456246246",
                "invoiceNumber" : "3456745472",
                "comment" : "Please call upon arrival"
            }
        ]
    }
}

Request Parameters to {YourEndpoint}

FieldTypeDescription
webhookStringWill be exactly SERVICE_STATUS_CHANGE. See Webhook Types for all possible webhook values.
account{}AccountContains the returned account details.
account{}.idStringYour reference id referring to the account record in your system.
account{}.firstNameStringFirst name of the account holder
account{}.lastNameStringLast name of the account holder
account{}.emailAddressStringEmail address of the account holder
account{}.phoneNumberStringPhone number of the account holder
account{}.businessNameStringBusiness name of the account holder
account{}.createDateDateDate the account was created
account{}.statusStringThe status of the account. See Account Status for all values.
account{}.service[]ArrayArray of Service objects
account{}.service[]{}.lineNumberIntegerLine number of the service on the account
account{}.service[]{}.skuNumberStringSKU number of the service record
account{}.service[]{}.statusStringThe status of the service. See Service Status for all values.
account{}.service[]{}.purchaseDateDateDate of purchase
account{}.service[]{}.cancellationDateDateCancellation date that the service will be cancelled on. If this is null, the service will not be cancelled.
account{}.service[]{}.renewalDateDateDate the service will be renewed. If this is null, the service will not be renewed and will be expire on the expirationDate.
account{}.service[]{}.expirationDateDateDate the service will expire.
account{}.service[]{}.storeNumberStringStore number the service was sold in
account{}.service[]{}.associateIdStringAssociate ID of the salesperson who sold the service
account{}.service[]{}.transactionIdStringTransaction ID of the receipt the service was purchased on
account{}.service[]{}.invoiceNumberStringInvoice number the service was purchased on
account{}.service[]{}.commentStringNotes/comments of the service

Order Status ChangePOST {YourEndpoint}

This webhook will trigger when an order status has changed and will POST an up-to-date Order object containing the status and order details.

Sample Request to {YourEndpoint}

POST {YourEndpoint}

Content-Type: application/json

{
    "webhook" : "ORDER_STATUS_CHANGE",
    "order" : {
        "number" : "89023475",
        "type" : "NEW",
        "status" : "QUOTE_CREATED",
        "firstName" : "John",
        "lastName" : "Smith",
        "emailAddress" : "jsmith@abccompany.com",
        "phoneNumber" : "893-555-4523",
        "businessName" : "ABC Company",
        "createdOn" : "2021-09-15T14:35:00-05:00",
        "updatedOn" : "2021-09-15T14:35:00-05:00",
        "paid" : true,
        "vendorId" : "45626",
        "loyaltyId" : "457215",
        "storeNumber" : "6125",
        "associateId" : "3456",
        "billTo" : {
            "firstName" : "John",
            "lastName" : "Smith",
            "businessName" : "ABC Company",
            "address1" : "123 Test Street",
            "address2" : "Suite 413",
            "city" : "Testville",
            "state" : "TN",
            "zipCode" : "12345"
        },
        "shipTo" : {
            "firstName" : "John",
            "lastName" : "Smith",
            "businessName" : "ABC Company",
            "address1" : "123 Test Street",
            "address2" : "Suite 413",
            "city" : "Testville",
            "state" : "TN",
            "zipCode" : "12345"
        },
        "item" : [
            {
                "lineNumber" : 1,
                "skuNumber" : "890345563",
                "partNumber" : "ABC-12345",
                "upcCode" : "23457892345789",
                "status" : "PAID",
                "quantity" : 1,
                "paid" : true,
                "returned" : false,
                "returnable" : true,
                "voidable" : true,
                "discountable" : true,
                "taxable" : true,
                "isSubscription" : false,
                "createdOn" : "2021-09-15T14:35:00-05:00",
                "paidOn" : "2021-09-16T17:23:54-05:00",
                "title" : "In-Home Smart TV Installation",
                "shortDescription" : "A qualified and experienced technician will come to your house to install your smart TV.",
                "longDescription" : "Lorem ipsum dolor sit amet, consectetur adipiscing elit. Donec fermentum vehicula nisl, sed volutpat tellus sollicitudin id. Ut id risus lobortis, molestie neque eu, dictum metus.",
                "termsAndConditions" : "Morbi dignissim augue massa, eget vestibulum erat molestie nec. Donec at lorem at lacus mollis condimentum bibendum non enim. Curabitur eu odio at dolor feugiat aliquet. Donec non ante faucibus, hendrerit felis eget, vulputate arcu."
            },
            {
                "lineNumber" : 2,
                "skuNumber" : "346346",
                "partNumber" : "DEF-56756",
                "upcCode" : "38924579458",
                "status" : "COMPLETE",
                "quantity" : 1,
                "paid" : true,
                "returned" : false,
                "returnable" : true,
                "voidable" : true,
                "discountable" : true,
                "taxable" : true,
                "isSubscription" : false,
                "createdOn" : "2021-09-15T14:35:00-05:00",
                "paidOn" : "2021-09-16T17:23:54-05:00",
                "title" : "In-Home Smart Doorbell Installation",
                "shortDescription" : "A qualified and experienced technician will come to your house to install your smart doorbell.",
                "longDescription" : "Lorem ipsum dolor sit amet, consectetur adipiscing elit. Donec fermentum vehicula nisl, sed volutpat tellus sollicitudin id. Ut id risus lobortis, molestie neque eu, dictum metus.",
                "termsAndConditions" : "Morbi dignissim augue massa, eget vestibulum erat molestie nec. Donec at lorem at lacus mollis condimentum bibendum non enim. Curabitur eu odio at dolor feugiat aliquet. Donec non ante faucibus, hendrerit felis eget, vulputate arcu."
            }
        ]
    }
}

Request Parameters to {YourEndpoint}

FieldTypeDescription
webhookStringWill be exactly ORDER_STATUS_CHANGE. See Webhook Types for all possible webhook values.
order{}OrderContains the returned order object.
order{}.numberStringUnique order number reference
order{}.typeStringThe type of order. See Order Type for all values.
order{}.statusStringThe current status of the order. See Order Status for all values.
order{}.firstNameStringFirst name of the order holder
order{}.lastNameStringLast name of the order holder
order{}.emailAddressStringEmail address of the order holder
order{}.phoneNumberStringPhone number of the order holder
order{}.businessNameStringBusiness name of the order holder
order{}.createdOnDate/TimeDate/time the order was created
order{}.updatedOnDate/TimeDate/time the order was created
order{}.paidBooleanWhether or not ALL items have been for
order{}.vendorIdStringInternal vendor identifier
order{}.loyaltyIdStringLoyalty ID reference identifier
order{}.storeNumberStringStore number where the order was created
order{}.associateIdStringAssociate ID who initiated the order
order{}.billTo{}AddressBilling address information
order{}.billTo{}.firstNameStringAddress first name
order{}.billTo{}.lastNameStringAddress last name
order{}.billTo{}.businessNameStringAddress business name
order{}.billTo{}.address1StringAddress line 1
order{}.billTo{}.address2StringAddress line 2
order{}.billTo{}.cityStringAddress city
order{}.billTo{}.stateStringAddress state
order{}.billTo{}.zipCodeStringAddress ZIP code
order{}.shipTo{}AddressShipping address information
order{}.shipTo{}.firstNameStringAddress first name
order{}.shipTo{}.lastNameStringAddress last name
order{}.shipTo{}.businessNameStringAddress business name
order{}.shipTo{}.address1StringAddress line 1
order{}.shipTo{}.address2StringAddress line 2
order{}.shipTo{}.cityStringAddress city
order{}.shipTo{}.stateStringAddress state
order{}.shipTo{}.zipCodeStringAddress ZIP code
order{}.item[]ArrayArray of Item objects on the order.
order{}.item[]{}.lineNumberIntegerLine number of the item on the order
order{}.item[]{}.skuNumberStringSKU number of the item on the order
order{}.item[]{}.partNumberStringManufacturer's part number of the item
order{}.item[]{}.upcCodeStringUPC code of the item
order{}.item[]{}.statusStringCurrent status of the item. See Item Status for all values.
order{}.item[]{}.quantityIntegerUnit quantity of the item
order{}.item[]{}.paidBooleanWhether or not the item has been paid for
order{}.item[]{}.returnedBooleanWhether or not the item has been returned
order{}.item[]{}.returnableBooleanWhether or not the item is returnable
order{}.item[]{}.voidableBooleanWhether or not the item is voidable
order{}.item[]{}.discountableBooleanWhether or not the item is discountable
order{}.item[]{}.taxableBooleanWhether or not the item is taxable
order{}.item[]{}.isSubscriptionBooleanWhether or not the item is a recurring subscription
order{}.item[]{}.createdOnDate/TimeDate/time the item was created on
order{}.item[]{}.paidOnDate/TimeDate/time the item was paid for
order{}.item[]{}.titleStringTitle of the item
order{}.item[]{}.shortDescriptionStringShort description of the item
order{}.item[]{}.longDescriptionStringLong description of the item
order{}.item[]{}.termsAndConditionsStringItem-level terms & conditions

Item Status ChangePOST {YourEndpoint}

This webhook will trigger when the status of an item changes and will POST an up-to-date Order object containing the status and all other order details.

Sample Request to {YourEndpoint}

POST {YourEndpoint}

Content-Type: application/json

{
    "webhook" : "ITEM_STATUS_CHANGE",
    "order" : {
        "number" : "89023475",
        "type" : "NEW",
        "status" : "QUOTE_CREATED",
        "firstName" : "John",
        "lastName" : "Smith",
        "emailAddress" : "jsmith@abccompany.com",
        "phoneNumber" : "893-555-4523",
        "businessName" : "ABC Company",
        "createdOn" : "2021-09-15T14:35:00-05:00",
        "updatedOn" : "2021-09-15T14:35:00-05:00",
        "paid" : true,
        "vendorId" : "45626",
        "loyaltyId" : "457215",
        "storeNumber" : "6125",
        "associateId" : "3456",
        "billTo" : {
            "firstName" : "John",
            "lastName" : "Smith",
            "businessName" : "ABC Company",
            "address1" : "123 Test Street",
            "address2" : "Suite 413",
            "city" : "Testville",
            "state" : "TN",
            "zipCode" : "12345"
        },
        "shipTo" : {
            "firstName" : "John",
            "lastName" : "Smith",
            "businessName" : "ABC Company",
            "address1" : "123 Test Street",
            "address2" : "Suite 413",
            "city" : "Testville",
            "state" : "TN",
            "zipCode" : "12345"
        },
        "item" : [
            {
                "lineNumber" : 1,
                "skuNumber" : "890345563",
                "partNumber" : "ABC-12345",
                "upcCode" : "23457892345789",
                "status" : "PAID",
                "quantity" : 1,
                "paid" : true,
                "returned" : false,
                "returnable" : true,
                "voidable" : true,
                "discountable" : true,
                "taxable" : true,
                "isSubscription" : false,
                "createdOn" : "2021-09-15T14:35:00-05:00",
                "paidOn" : "2021-09-16T17:23:54-05:00",
                "title" : "In-Home Smart TV Installation",
                "shortDescription" : "A qualified and experienced technician will come to your house to install your smart TV.",
                "longDescription" : "Lorem ipsum dolor sit amet, consectetur adipiscing elit. Donec fermentum vehicula nisl, sed volutpat tellus sollicitudin id. Ut id risus lobortis, molestie neque eu, dictum metus.",
                "termsAndConditions" : "Morbi dignissim augue massa, eget vestibulum erat molestie nec. Donec at lorem at lacus mollis condimentum bibendum non enim. Curabitur eu odio at dolor feugiat aliquet. Donec non ante faucibus, hendrerit felis eget, vulputate arcu."
            },
            {
                "lineNumber" : 2,
                "skuNumber" : "346346",
                "partNumber" : "DEF-56756",
                "upcCode" : "38924579458",
                "status" : "COMPLETE",
                "quantity" : 1,
                "paid" : true,
                "returned" : false,
                "returnable" : true,
                "voidable" : true,
                "discountable" : true,
                "taxable" : true,
                "isSubscription" : false,
                "createdOn" : "2021-09-15T14:35:00-05:00",
                "paidOn" : "2021-09-16T17:23:54-05:00",
                "title" : "In-Home Smart Doorbell Installation",
                "shortDescription" : "A qualified and experienced technician will come to your house to install your smart doorbell.",
                "longDescription" : "Lorem ipsum dolor sit amet, consectetur adipiscing elit. Donec fermentum vehicula nisl, sed volutpat tellus sollicitudin id. Ut id risus lobortis, molestie neque eu, dictum metus.",
                "termsAndConditions" : "Morbi dignissim augue massa, eget vestibulum erat molestie nec. Donec at lorem at lacus mollis condimentum bibendum non enim. Curabitur eu odio at dolor feugiat aliquet. Donec non ante faucibus, hendrerit felis eget, vulputate arcu."
            }
        ]
    }
}

Request Parameters to {YourEndpoint}

FieldTypeDescription
webhookStringWill be exactly ITEM_STATUS_CHANGE. See Webhook Types for all possible webhook values.
order{}OrderContains the returned order object.
order{}.numberStringUnique order number reference
order{}.typeStringThe type of order. See Order Type for all values.
order{}.statusStringThe current status of the order. See Order Status for all values.
order{}.firstNameStringFirst name of the order holder
order{}.lastNameStringLast name of the order holder
order{}.emailAddressStringEmail address of the order holder
order{}.phoneNumberStringPhone number of the order holder
order{}.businessNameStringBusiness name of the order holder
order{}.createdOnDate/TimeDate/time the order was created
order{}.updatedOnDate/TimeDate/time the order was created
order{}.paidBooleanWhether or not ALL items have been for
order{}.vendorIdStringInternal vendor identifier
order{}.loyaltyIdStringLoyalty ID reference identifier
order{}.storeNumberStringStore number where the order was created
order{}.associateIdStringAssociate ID who initiated the order
order{}.billTo{}AddressBilling address information
order{}.billTo{}.firstNameStringAddress first name
order{}.billTo{}.lastNameStringAddress last name
order{}.billTo{}.businessNameStringAddress business name
order{}.billTo{}.address1StringAddress line 1
order{}.billTo{}.address2StringAddress line 2
order{}.billTo{}.cityStringAddress city
order{}.billTo{}.stateStringAddress state
order{}.billTo{}.zipCodeStringAddress ZIP code
order{}.shipTo{}AddressShipping address information
order{}.shipTo{}.firstNameStringAddress first name
order{}.shipTo{}.lastNameStringAddress last name
order{}.shipTo{}.businessNameStringAddress business name
order{}.shipTo{}.address1StringAddress line 1
order{}.shipTo{}.address2StringAddress line 2
order{}.shipTo{}.cityStringAddress city
order{}.shipTo{}.stateStringAddress state
order{}.shipTo{}.zipCodeStringAddress ZIP code
order{}.item[]ArrayArray of Item objects on the order.
order{}.item[]{}.lineNumberIntegerLine number of the item on the order
order{}.item[]{}.skuNumberStringSKU number of the item on the order
order{}.item[]{}.partNumberStringManufacturer's part number of the item
order{}.item[]{}.upcCodeStringUPC code of the item
order{}.item[]{}.statusStringCurrent status of the item. See Item Status for all values.
order{}.item[]{}.quantityIntegerUnit quantity of the item
order{}.item[]{}.paidBooleanWhether or not the item has been paid for
order{}.item[]{}.returnedBooleanWhether or not the item has been returned
order{}.item[]{}.returnableBooleanWhether or not the item is returnable
order{}.item[]{}.voidableBooleanWhether or not the item is voidable
order{}.item[]{}.discountableBooleanWhether or not the item is discountable
order{}.item[]{}.taxableBooleanWhether or not the item is taxable
order{}.item[]{}.isSubscriptionBooleanWhether or not the item is a recurring subscription
order{}.item[]{}.createdOnDate/TimeDate/time the item was created on
order{}.item[]{}.paidOnDate/TimeDate/time the item was paid for
order{}.item[]{}.titleStringTitle of the item
order{}.item[]{}.shortDescriptionStringShort description of the item
order{}.item[]{}.longDescriptionStringLong description of the item
order{}.item[]{}.termsAndConditionsStringItem-level terms & conditions