API Service Documentation

Command Basics

For all intents and purposes, this website containing the API service will be referred to as the server and all parties communicating to the server will be referred to as the client.

The following will be provided: An API ID and an API password. On every request to the server, the client must provide this information as "ai_login_id" and "ai_login_password" respectively.

Authentication and Requests

All API requests to the server are made as a POST request to the secure URL:https://www.dunndealautosales.com/service

All parameters are included in the POST body as typical name-value pairs. The following is required from all clients for all requests.

Name

Type

Required

Example

ai_login_id

String

Y

apiuser

ai_login_password

String

Y

APIuser123

ai_sitecom_token

String

Y

A20ZPutYormM9S8AXjMGqTvmLEbx8FS_2lQCvBwinbA - use in place of ai_login_id & ai_login_password. Must be generated in the authtoken class using this site's comm_key.

ai_command

String

Y

create_lead - this is the command you want to execute

Responses

All API responses back to the client are in a similar format to the request, that is, they are URL-encoded name-value pairs. The following should be present in all responses. If they are not present, the client can assume it an error.

Name

Type

Example

status

Integer

0

All non-zero values can be assumed to be an error. There is no definitive error-code-table at this moment.

status_message

String

Success

If there is more than one message, this field may return as a tuple, i.e., status_message[n], where n is a 0-based index.

Notification Basics

Notifications are requests initiated by the server to the client, and the client must then respond back to the server with an appropriate response. Unlike commands, all requests and responses will be in the JSON format sent over in the body of an HTTP POST request/response.

Authentication and Requests

There are only two types of requests: authenticate and delivery.

Authenticate requests are used to authenticate communication between server and client. The client must respond with ai_login_id and ai_login_password. By default, the request contains a key parameter. This parameter is used to create an MD5 hash of (ai_login_id + ai_login_password + key). The hash is returned as ai_login_password in place of the plain-text value. If key-authentication is turned off, this parameter is not provided and ai_login_password is returned as the plain-text password (not recommended). Alternatively, the client can respond with a status:OK in case it does not want to trust any incoming request for login/password. The client is then expected to use the Command authenticate_notifications asynchronously to validate and open up notification communications.

Delivery requests are used for all notification and message delivery. The messages parameter that is present with all delivery requests contains an array of objects. Each object has a type, which indicates what type of notification it is, and the object also has data, which could either be a simple string message, or another set of objects that can vary with complexity depending on the message type. Please refer to the List of Notifications for a list of types and details about what to expect in the data field for each type.

Name

Type

Present

Example

request

String

Y

delivery

One of "authenticate" or "delivery"

key

String

N

12345678abcdefgh

Present only in "authenticate" requests and only when enabled in the settings (enabled by default)

Present only in "delivery" requests and only when enabled in the settings (enabled by default)

Responses

The client is expected to respond back with a JSON string. In general, all responses should contain a status parameter with an OK value. If this is missing, the server will assume communication resulted in an error. If this was a delivery request, the messages will be enqueued again for another delivery attempt (unless Ignore Confirmation is enabled). The exception to this is during authentication with immediate response. The expected parameters in this type of authentication are ai_login_id and ai_login_password. If asynchronous authentication is desired, the default status OK response is accepted.

Name

Type

Example

status

String

OK

ai_login_id

String

apiuser

Only for the "authenticate" request when responding immediately.

ai_login_password

String

0123456789abcdef0123456789abcdef

Only for the "authenticate" request when responding immediately.
This could be either an MD5 hash (default) or the plain-text password depending on the setup.