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

NameTypeRequiredExample
ai_login_idStringYapiuser
ai_login_passwordStringYAPIuser123
ai_commandStringYcreate_lead

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.

NameTypeExample
statusInteger0

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

status_messageStringSuccess

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.

Top

List of Commands

Command Name
authenticate_notifications
batch
command_center_sync
create_customer
create_hosted_checkout
create_lead
create_order
event_set
events_get
issue_invites
lead_set
leads_get
ping
query_users
send_system_email
update_lead
update_order
update_user
user_get
user_login_link
user_login_token
validate_user

Top


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.

NameTypePresentExample
requestStringYdelivery

One of "authenticate" or "delivery"

keyStringN12345678abcdefgh

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

messagesComplexN[{"type":"simple","data":"Hello},{"type":"complex","data":{"a":1,"b":2,"c":3}}]

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.

NameTypeExample
statusStringOK
ai_login_idStringapiuser

Only for the "authenticate" request when responding immediately.

ai_login_passwordString0123456789abcdef0123456789abcdef

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.

Examples

Authentication Request

{"request":"authenticate","key":"0123456789abcdefg"}

Authentication Response

With Key Authentication:

{"ai_login_id":"apiuser","ai_login_password":"0123456789abcdef0123456789abcdef"}

Without Key Authentication:

{"ai_login_id":"apiuser","ai_login_password":"plaintextpassword"}

Passive (will call authenticate_notifications):

{"status":"OK"}

Delivery Request

{"request":"delivery","messages":[{"type":"generic","data":"Hello World"},{"type":"new_user","data":{"first_name":"John","last_name":"Doe"}}]}

Delivery Response

{"status":"OK"}

Top

List of Notifications

Notification Type
generic
membership
new_user

Top