Skip to content

Vehicles ​

Create, update, withdraw or unpublish inventory vehicles.

Adding a new vehicle ​

POST /v1/vehicles

Create or update a vehicle with the given identifier.

curl --location --request POST '{baseUrl}/v1/vehicles' \
--header 'Authorization: Bearer {token}' \
--header 'Content-Type: application/json' \
--header 'x-seller-identifier: {sellerIdentifier}' \
--data-raw '{vehicle}'

Parameters ​

NameTypeDescription
tokenAuthorizationYou can obtain this token by following the Authentication guide.
sellerIdentifierGUIDIdentifies the dealer the ad will be posted to within carsales. carsales provides this for each dealer.
vehicleCSN-DTOCSN-DTO vehicle object.

Permissions ​

You must have the Inventory permission in order to use this endpoint.

Returns ​

Returns 202 Accepted if the request succeeds. The payload contains the UUID of the vehicle created. All updates/widthdraw of vehicle calls must use this unique identifier to ensure the correct inventory is modified.

This call will return an error if something goes wrong. Error reasons can include the vehicle payload failing validation. If this occurs, the property that caused the validation to fail will be provided in the response.

Sample 202 Accepted Response ​

json
{
  "Identifier": "c5e8b618-7ee1-43d0-9d45-cd9768576596"
}

Updating an existing vehicle ​

PATCH /v1/vehicles/{identifier}

Modify an existing vehicle with the provided identifier. It cannot create a new vehicle, only update an existing one. We adhere to the RFC 7396 Json Merge Patch Standard.

curl --location --request PATCH '{baseUrl}/v1/vehicles/{identifier}' \
--header 'Authorization: Bearer {token}' \
--header 'Content-Type: application/json' \
--header 'x-seller-identifier: {sellerIdentifier}' \
--data-raw '{vehicle}'

Parameters ​

NameTypeDescription
identifierGUIDUniquely identifies the vehicle. An example GUID identifier we expect is: 01eee3dc-6100-49f7-8c6e-c8d96669e091.
tokenAuthorizationYou can obtain this token by following the Authentication guide.
sellerIdentifierGUIDIdentifies the dealer the ad will be posted to within carsales. carsales provides this for each dealer.
vehicleCSN-DTOUpdates to the CSN-DTO vehicle object.

Permissions ​

You must have the Inventory permission in order to use this endpoint.

Returns ​

Returns 202 Accepted if the request succeeds. This call will return an error if something goes wrong. Error reasons can include the vehicle payload failing validation. If this occurs, the property that caused the validation to fail will be provided in the response.

Withdrawing a vehicle ​

DELETE /v1/vehicles/{identifier}

Withdraw a vehicle with the provided identifier.

curl --location --request DELETE '{baseUrl}/v1/vehicles/{identifier}' \
--header 'Authorization: Bearer {token}' \
--header 'x-seller-identifier: {sellerIdentifier}' \
curl --location --request DELETE '{baseUrl}/v1/vehicles/{identifier}?status={status}' \
--header 'Authorization: Bearer {token}' \
--header 'x-seller-identifier: {sellerIdentifier}' \

Parameters ​

NameTypeDescription
identifierGUIDUniquely identifies the vehicle. An example GUID identifier we expect is: 01eee3dc-6100-49f7-8c6e-c8d96669e091.
tokenAuthorizationYou can obtain this token by following the Authentication guide.
sellerIdentifierGUIDIdentifies the dealer the ad will be posted to within carsales. carsales provides this for each dealer.
statusstringOptional parameter to provide what status the vehicle should be withdrawn under. Acceptable Values: Withdrawn, Sold

Permissions ​

You must have the Inventory permission in order to use this endpoint.

Returns ​

Returns 202 Accepted if the request succeeds. This call will return an error if something goes wrong. Error reasons can include an invalid SaleStatus (vehicle must be in the Sold or Withdrawn states), as well as a SellerIdentifier mismatch between the vehicle owner and credentials provided in the request.

Returns ​

To bring a vehicle back online (from a Sold/Withdrawn state back to InStock), send a POST request using the Adding a new vehicle to resubmit the vehicle.

Get active vehicles ​

GET v1/vehicles/active_items

Get your actives vehicles sent via Global Inventory, ordered by last modified ascending. This will not return vehicles added to carsales through other services, such as Control Panel.

curl --location --request GET '{baseUrl}/v1/vehicles/active_items?page={page}&limit={limit}' \
--header 'Authorization: Bearer {token}' \
--header 'Content-Type: application/json' \
--header 'x-seller-identifier: {sellerIdentifier}'

Parameters ​

NameTypeDescription
tokenAuthorizationYou can obtain this token by following the Authentication guide.
sellerIdentifierGUIDThe seller identifier used to manage vehicles with Global Inventory. carsales provides this for each dealer.
pageintegerPage number of paginated results. (Defaults to 1 if omitted)
limitintegerMaximum number of results per page. (Defaults to 20 if omitted)

Permissions ​

You must have the Inventory permission in order to use this endpoint.

Returns ​

Returns 200 Ok if the request succeeds, along with a paginated array containing each active vehicles identifier, registrationNumber, title and lastModified in Coordinated Universal Time (UTC) if vehicles are found. If the seller has no active vehicles, or an invalid seller identifier was entered, an empty array will be returned. This call will return an error if something goes wrong.

Example Response ​

[
  {
    "identifier": "054410cd-d476-451c-89c1-190f7dd1a0d4",
    "registrationNumber": "ABC123",
    "title": "Subaru Liberty",
    "lastModified": "2022-12-11T06:24:59.8803872+00:00"
  },
  {
    "identifier": "9a6aefe9-b7a0-48ef-b5e1-0fd4f7bd3fb1",
    "registrationNumber": "XYZ123",
    "title": "Hyundai i30",
    "lastModified": "2022-12-11T06:24:59.8803892+00:00"
  }
]

Unpublish vehicles from destinations ​

POST v1/vehicles/{identifier}/unpublish

Unpublish a vehicle from the specified destinations. This will remove the vehicle from the publishing destinations.

curl --location --request POST '{baseUrl}/v1/vehicles/{identifier}/unpublish' \
--header 'Authorization: Bearer {token}' \
--header 'Content-Type: application/json' \
--header 'x-seller-identifier: {sellerIdentifier}'
--data-raw '{publishingRequest}'

Parameters ​

NameTypeDescription
identifierGUIDUniquely identifies the vehicle. An example GUID identifier we expect is: 01eee3dc-6100-49f7-8c6e-c8d96669e091.
tokenAuthorizationYou can obtain this token by following the Authentication guide.
sellerIdentifierGUIDThe seller identifier used to manage vehicles with Global Inventory. carsales provides this for each dealer.
publishingRequestPublishingRequestPublishingRequest object.

Permissions ​

You must have the Inventory permission in order to use this endpoint.

Returns ​

  • Returns 200 Ok if the request succeeds.
  • Returns 400 Bad Request if the required fields (IdempotencyKey and Destinations) are not provided in the request.
  • Returns 404 Not Found if the vehicle identifier is not found in the Global Inventory system.
  • Returns 204 No Content if the IdempotencyKey provided in the request already exists.
  • Returns 429 Too Many Requests if the request exceeds the rate limit for unpublishing vehicles. Limits: 2 unpublish requests per vehicle per hour and 10 unpublish requests per seller per hour.

Example 200 Ok Response ​

Vehicle 24facb55-d27b-45be-9ef0-a1c66b6130ba request to unpublish to [CARSALES] completed.

Publishing Request ​

A standardised format to unpublish a vehicle from its destinations.

{
  "IdempotencyKey": "72264130-9f1e-4a2c-b0e8-73dfb4d7a556",
  "Destinations": [
    "CARSALES"
  ]
}

Required parameters ​

These are the required parameters and requests cannot be completed without these parameters.

NameTypeDescription
IdempotencyKeyGUIDA GUID to uniquely identify the request. It ensures that if the same request is submitted multiple times, the operation will only be performed once.
Destinationsstring[]The list of publishing destinations from which you want to remove the vehicle listing.

Publish vehicles to destinations ​

POST v1/vehicles/{identifier}/publish

Publish a vehicle to the specified destinations.

curl --location --request POST '{baseUrl}/v1/vehicles/{identifier}/publish' \
--header 'Authorization: Bearer {token}' \
--header 'Content-Type: application/json' \
--header 'x-seller-identifier: {sellerIdentifier}'
--data-raw '{publishingRequest}'

Parameters ​

NameTypeDescription
identifierGUIDUniquely identifies the vehicle. An example GUID identifier we expect is: 01eee3dc-6100-49f7-8c6e-c8d96669e091.
tokenAuthorizationYou can obtain this token by following the Authentication guide.
sellerIdentifierGUIDThe seller identifier used to manage vehicles with Global Inventory. carsales provides this for each dealer.
publishingRequestPublishingRequestPublishingRequest object.

Permissions ​

You must have the Inventory permission in order to use this endpoint.

Returns ​

  • Returns 200 Ok if the request succeeds.
  • Returns 400 Bad Request if the required fields (IdempotencyKey and Destinations) are not provided in the request.
  • Returns 404 Not Found if the vehicle identifier is not found in the Global Inventory system.
  • Returns 204 No Content if the IdempotencyKey provided in the request already exists.
  • Returns 429 Too Many Requests if the request exceeds the rate limit for unpublishing vehicles. Limits: 2 unpublish requests per vehicle per hour and 10 unpublish requests per seller per hour.

Example 200 Ok Response ​

Vehicle 24facb55-d27b-45be-9ef0-a1c66b6130ba request to publish to [CARSALES] completed.

Publishing Request ​

A standardised format to provide a list of publishing destinations.

{
  "IdempotencyKey": "72264130-9f1e-4a2c-b0e8-73dfb4d7a551",
  "Destinations": [
    "CARSALES"
  ]
}

Required parameters ​

These are the required parameters and requests cannot be completed without these parameters.

NameTypeDescription
IdempotencyKeyGUIDA GUID to uniquely identify the request. It ensures that if the same request is submitted multiple times, the operation will only be performed once.
Destinationsstring[]The list of publishing destinations from which you want to publish the vehicle listing.