> For the complete documentation index, see [llms.txt](https://docs.capedatahub.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.capedatahub.com/cape-stock-api-documentation.md).
# CAPE Stock API Documentation
### Introduction
This document serves as a comprehensive guide to utilising the CAPE Stock API. It outlines the required payloads for successful API calls and provides examples of payloads returned in the case of unsuccessful requests.
Additionally, it details the API's authorisation process to ensure secure and authenticated calls.
### Security
#### **1. Client Authentication (First Request)**
**What's Happening?**
* A **POST request** is made to the authentication API (/api/ClientAuthentication).
* The **client's username and password** are sent as x-www-form-urlencoded data.
* If credentials are valid, the server responds with a **token (JWT - JSON Web Token)**.
**Security Considerations**
* **Authentication process:** The client must prove their identity by providing credentials.
* **Token Issuance:** The server generates a signed JWT token upon successful authentication.
* **Token Content:** The JWT might contain user details and permissions, encoded and signed (but not encrypted).
**URL:**
QA
```
https://dev-icon.cloud:9525/api/ClientAuthentication
```
PROD
```
https://prosol.cloud:9525/api/ClientAuthentication
```
**Method:**
* ClientAuthentication: Retrieve bearer token.
* Action: POST
#### **2. Making API Requests with the Bearer Token**
**What's Happening?**
* The **Bearer Token** received from authentication is used in the **Authorisation** header of the API request.
* A **POST request** is made to another API (/api/CAPEStockAPI) with JSON body parameters.
* The server verifies the **validity of the token** before allowing access.
* If valid, the server returns a **200 OK** response with the requested data.
**Security Considerations**
* **Authorisation:** Only authenticated users with a valid token can access protected endpoints.
* **Token Expiry:** JWTs typically have an expiration time, after which they must be refreshed.
* **Token Storage:** Storing tokens securely (e.g., in an encrypted store) is crucial to prevent leaks.
* **Replay Attacks:** If an attacker gets the token, they can make requests unless mitigations like token expiration or refresh tokens are in place.\
#### **3. API Response Validation**
**What's Happening?**
* The response from the CAPEStockAPI confirms that the request was authorised.
* The API returns structured **JSON data** about vehicle stock details.
* The token ensures that only authorised users retrieve this information.
**Security Best Practices**
* **Use HTTPS:** Always send tokens over an encrypted connection.
* **Implement Token Expiry & Refresh Mechanism:** Prevent long-lived access.
* **Restrict Token Scope:** Assign permissions based on user roles.
* **Monitor and Revoke Tokens if Compromised.**
### Endpoints
#### Get Dealer Vehicle Stock information
**Description:**
This endpoint will be used for all Stock vehicle information retrieval operations, and in this case, in order to retrieve vehicle information for each dealer using a unique identifier, dealer code and vehicle status.
**URL:**
QA
```
https://dev-icon.cloud:9528/api/CAPEStockAPI
```
PROD
```
https://prosol.cloud:9528/api/CAPEStockAPI
```
**Method:**
* CAPEStockAPI: Get vehicle stock Information regarding a specific dealer from CAPE.
* Action: POST
**Request:**
The request body requires 3 fields to be sent in JSON format.
Fields:
1. uniqueIdentifier
2. vehicleStatus
3. capeDealerId (optional)\
\
\
**Request Parameters:**
| **Name** | **Description** | **DataType** | **Constraints** |
| ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------- | --------------- |
| uniqueIdentifier | This will be provided to the Dealer confidentially. | string | Mandatory |
| capeDealerId | Uniquely identifies and selects a specific dealer for the client (e.g., "Ford Centurion"). If the capeDealerId and uniqueIdentifier do not match, the request will be rejected. Should this not be provided, all Dealers that are authorised for the user will be displayed | List\ | Optional |
| vehicleStatus | Filters vehicles based on their condition (e.g., New, Used, Demo, or All). | List\ | Mandatory |
\
**Request Body:**
```
{
"CAPEStockAPIRq": {
"userContext": {
"uniqueIdentifier": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX"
},
"capeDealerId": ["10XXX"],
"vehicleStatus": ["all"]
}
}
```
**Response:**
The response will return the following fields, together with additional response codes and descriptions:
**Response Codes:**
Custom:
| **Status** | **Description** |
| ------------- | ------------------------------------------------------------------------------- |
| R00 (Success) | Successful request |
| R01 (Failed) | Logical failure based on invalid parameters or constraints not being adhered to |
| R05 (Error) | Authentication or access failure |
| R09 (Error) | Downstream error/failure occurred |
HTTP:
| **Status** | **Description** |
| --------------------------- | ------------------ |
| 200 (OK) | Successful request |
| 500 (Internal Server Error) | Downstream failure |
\
Response Body:
```
{
"CAPEStockAPIRs": {
"status": "",
"message": "",
"vehicles": [
{
"dealerName": "",
"groupName": "",
"capeDealerId": "",
"newUsed": "",
"vehicleStatus": "",
"vin": "",
"capeStockId": "",
"sourceStockId": "",
"trackingNumber": "",
"registrationNumber": "",
"registrationYear": "",
"registrationDate": "",
"odometerReading": "",
"odometerUnit": "",
"ownerCount": "",
"fullServiceHistory": "",
"serviceHistroyDetail": "",
"priceCurrencyCode": "",
"priceCurrent": "",
"priceIncVat": "",
"pricePoa": "",
"pricePrevious": "",
"managersDescription": "",
"attentionGrabber": "",
"franchiseApproved": "",
"coloursExteriorGeneric": "",
"coloursExteriorManufacturer": "",
"interiorType": "",
"coloursInterior": "",
"vehicleType": "",
"mmCode": "",
"displayName": "",
"make": "",
"model": "",
"variant": "",
"bodyStyle": "",
"doorCount": "",
"driveType": "",
"transmission": "",
"gearCount": "",
"bhp": "",
"engineSizeCc": "",
"fuelConsumption": "",
"co2": "",
"fuelType": "",
"equipmentList": [],
"vehicleImages": [],
"url": "",
"Warranty": {
"Active": "",
"DateInception": "",
"DateExpiry": "",
"PeriodMonths": "",
"Description": ""
},
"ServicePlans": {
"Active": "",
"DateInception": "",
"DateExpiry": "",
"PeriodMonths": "",
"Description": ""
}
}
]
}
}
```
**API Fields Table:**\
\
| Field Name | Description | Data Type output |
| --------------------------- | ---------------------------------------------------------------------------------------------------------------------- | ---------------- |
| dealerName | Name of dealer | String |
| groupName | The name of the group dealer is associated with | String |
| capeDealerId | A unique identity number given to a dealer. | String |
| newUsed | Identifies whether the vehicle is new, used, or demo. | String |
| vehicleStatus | Online, offline, reserved, etc. | String |
| vin | The exact VIN of the vehicle. | String |
| capeStockId | Unique identifier assigned to a vehicle by CAPE | String |
| sourceStockId | Internal vehicle stock ID: This is required as a unique identifier. | String |
| trackingNumber | Contact Number for lead | String |
| registrationNumber | The exact registration of the vehicle. Must not include spaces. | String |
| registrationYear | The exact registration year of the vehicle. Must not include spaces. | String |
| registrationDate | Must be in the correct format YYYY-MM-DD. | String |
| odometerReading | Numbers only. Do not include commas or decimals. | String |
| odometerUnit | The unit the odometer reading is read. | String |
| ownerCount | Total number of previous owners. | String |
| fullServiceHistory | True/False on whether the vehicle has an up-to-date/full history record. | String |
| serviceHistroyDetail | Additional information or remarks related to the vehicle’s service and maintenance history. | String (List) |
| priceCurrencyCode | Currency code for this vehicle. | String |
| priceCurrent | The localised price of the vehicle. | String |
| priceIncVat | Define if the price is inclusive/exclusive of VAT. | String |
| pricePoa | If 1, the vehicle's price should not be displayed; instead, "POA" (Price on Application) should be displayed. | String |
| pricePrevious | The previous price of the vehicle. | String |
| managersDescription | Extended Description of the Vehicle. | String |
| attentionGrabber | Highlights or Attention Grabbers for this vehicle. | String |
| franchiseApproved | Determines if the vehicle is marked as franchise-approved. | String |
| coloursExteriorGeneric | The exact generic colour of the vehicle. | String |
| coloursExteriorManufacturer | The exact manufacturer’s standard colour, e.g., Active Red. | String |
| interiorType | The interior type and trim of the vehicle. | String |
| coloursInterior | The interior colour of the vehicle. | String |
| vehicleType | Must be one of CAR, BIKE, LCV. | String |
| mmCode | Unique vehicle model code. | String |
| displayName | Display the name of the vehicle. A combination of Make model and variant. | String |
| make | Exact Make. Do not include Model or Variant info. | String |
| model | Exact Model. Do not include Variant info. | String |
| variant | Variant including a description of the vehicle. This is expected to display on the website. | String |
| bodyStyle | The type of vehicle, e.g., 4x4, Convertible, Pickup, etc. | String |
| doorCount | The exact number of doors for this vehicle. | String |
| driveType | 4-wheel, 2-wheel drive or All Wheel Drive. | String |
| transmission | Transmission of the vehicle. E.g. Manual, Automatic | String |
| gearCount | Number of gears. | String |
| bhp | Power. (Break Horse Power) | String |
| engineSizeCc | Engine Size in CC. | String |
| fuelConsumption | Fuel consumption. | String |
| co2 | CO2 emission. | String |
| fuelType | Fuel type, e.g., Petrol, Hybrid, Electric. | String |
| equipmentList | Comma-separated list of fitted options for this vehicle, including standard and fitted specifications where available. | String |
| vehicleImages | Image URL for each image, provided in a separate node under the parent node "Image." | String |
| url | Stock URL | String |
| Warranty | | |
| Warranty.Active | Warranty active flag | String |
| Warranty.DateInception | Warranty start date | String |
| Warranty.DateExpiry | Warranty expiry | String |
| Warranty.PeriodMonths | Warranty period | String |
| Warranty.Description | Warranty description | String |
| ServicePlans | | |
| ServicePlans.Active | Service plan active flag | String |
| ServicePlans.DateInception | Service plan start date | String |
| ServicePlans.DateExpiry | Service plan expiry | String |
| ServicePlans.PeriodMonths | Service plan period | String |
| ServicePlans.Description | Service plan descriptio | String |
### Postman
Sample\
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
GET https://docs.capedatahub.com/cape-stock-api-documentation.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.