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.
All API requests to the server are made as a POST request to the secure URL:
https://www.carcitycentral.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. For a more advanced form of authentication which does not require your password be sent in its original form, please visit our Advanced Authentication topic.
| 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 |
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 | 0All non-zero values can be assumed to be an error. There is no definitive error-code-table at this moment. |
status_message | String | SuccessIf 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. |
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.
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 | deliveryOne of "authenticate" or "delivery" |
key | String | N | 12345678abcdefghPresent only in "authenticate" requests and only when enabled in the settings (enabled by default) |
messages | Complex | N | [{"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) |
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 | apiuserOnly for the "authenticate" request when responding immediately. |
ai_login_password | String | 0123456789abcdef0123456789abcdefOnly for the "authenticate" request when responding immediately. |
{"request":"authenticate","key":"0123456789abcdefg"}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"}{"request":"delivery","messages":[{"type":"generic","data":"Hello World"},{"type":"new_user","data":{"first_name":"John","last_name":"Doe"}}]}{"status":"OK"}