1 Trade-in entity
- 1.1 Entity fields
- 1.2 Vehicle model
- 1.3 Condition
- 1.4 Status
- 1.5 Pictures
  - 1.5.1 Retrieve a list of uploaded pictures
  - 1.5.2 Upload pictures - adding only
  - 1.5.3 Upload pictures - add, remove and replace
- 1.6 Comments
  - 1.6.1 Retrieve a list of comments
  - 1.6.2 Add a comment(s) for the trade-in
  - 1.6.3 Edit or replace trade-in comments
2 Examples
- 2.1 List of trade-ins
- 2.2 New trade-in
  - 2.2.1 Super minimalistic example
  - 2.2.2 A bit more complete example
- 2.3 Customers and leads
- 2.4 Updating a trade-in

Trade-in entity

Entity representing a Trade-in vehicle in Salesfront is collection of core fields and number of nested entities.

{
  "id": 1233,
  "iri": "/api/v3/trade-ins/1233",
  "status": "not_done",
  "customer": {
    // customer entity (optional)
  },
  "condition": {
    // condition flags
  },
  "vehicleModel": {
    // vehicle model describes the car
  },
  "lastServiceDate": "2022-02-02",
  "note": "Vehicle is in good condition.",
  "purchasePrice": 32000,
  "priceExVat": false,
  "isVatExempt": false,
  "margin": 8,
  "daysToSale": 60,
  "dailyDepreciationRate": 0.05,
  "dealership": {
    // location dealership
  },
  "createdAt": "2022-02-22T11:55:22+02:00",
  "createdBy": {
    // user
  },
  "updatedBy": {
    // user
  }
}

Same entity is exposed in GET and PATCH endpoints. However, not all properties are changeable - please refer to API doc examples for further details.

Entity fields

Field	Description	Read / write

Field	Description	Read / write
id	Unique numeric increment key for trade-in	RO
status	Trade-in status (note_done, read_for_appraisal, done, purchase_agreement, no_deal)	RW
specificationTitle	Vehicle specification description	RW
note	Free text notes about vehicle condition	RW
customer	Link to attached customer	RW
customerAskingPrice	Price asked by customer	RW
purchasePrice	Price offered to customer	RW
marketPrice	Trade-in car general price on market	RW
marketValueOnSalesDay	Trade-in car value on selling day	RW
margin	Trade-in car sales margin	RW
refurbishCostEstimate	Trade-in car refurbishing price	RW
lastServiceDate	Trade-in car last service date	RW
daysToSale	Amount of days to sale the trade-in car	RW
dailyDepreciationRate	Trade-in car daily deperication rate	RW
rejectReason	Trade-in rejection reason type	RW
rejectReasonMetaText	Trade-in rejection additional metadata	RW
createdAt	Trade-in creation timestamp	RO
createdBy	Link to user who created trade-in	RO
updatedAt	Trade-in last update timestamp	RO
updatedBy	Link to user who last modified trade-in	RO
reportSignedAt	Trade-in report signing timestamp	RO
reportSignedBy	Link to user who signed trade-in report	RO
doneBy	Link to user who marked trade-in done	RO

Vehicle model

Vehicle model is used to expose vehicle details, specification and equipment.

Please note that not all fields in Vehicle Model is stored as part of Trade-in. Not supported fields are ignored when trade-in is created or modified.

Vehicle Model fields supported by Trade-in:

make
model
vinCode
color
mileage
gearbox
regNr
vehicleType
bodyType
cylinderCapacityCm3
maxPowerKw
firstRegistrationDate
fuel
drivetrainType
transmissionType
transmissionCode
equipment
accidents

Condition

Boolean flags to describe vehicle condition.

fullService	TRUE if vehicle has full service history documented
tiresMoreThan6mm	TRUE if vehicle tires are in good condition
acWorks	TRUE if vehicle air conditioning exists and is working
animalsInCar	TRUE if car has been used to haul pets
majorAccident	TRUE if trade-in car has participated in a major accident
mechanicalTested	TRUE if car condition has been reviewed by a mechanic
originalPaint	TRUE if car has original paint applied
smokedInCar	TRUE if previous users has been smoking inside the car

Status

There are number of built-in statuses for trade-in:

not_done - Starting status for any trade-in. The vehicle information is still incomplete.
ready_for_appraisal - Trade-in information is complete. Can be submitted to a sales manager or other person assigned vehicle appraisals.
done - Trade-in appraisal is finalized. Can be offered to the customer at a confirmed price.
sent_to_customer - Purchase offer is shared with customer, pending further decisions.
purchase_agreement - Offer is accepted by the customer. A purchase agreement can be signed.
no_deal - Trade-in has been rejected. This status usually implies the existence of the rejectReason & rejectReasonMetaText in the entity explaining the reason for no deal.

In order to change status of Trade-in, dedicated PATCH request is anticipated:

curl -X PATCH 'https://salesfront.url/api/v3/trade-ins/{ID}/status/draft' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'X-API-Key: XXX'

NB! Status codes in entity do not match 1:1 to the URLs to activate the statuses.

Pictures

API allows to access and upload pictures to the trade-in. Dedicated endpoints are available for this.

Retrieve a list of uploaded pictures

curl -X GET 'https://salesfront.url/api/v3/trade-ins/{ID}/pictures' \
  -H 'Accept: application/json' \
  -H 'X-API-Key: XXX'

Upload pictures - adding only

curl -X POST 'https://salesfront.url/api/v3/trade-ins/{ID}/pictures' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'X-API-Key: XXX' \
  -d '[
  {
    "url": "https://placehold.co/2000x1500",
    "pictureType": "/api/v3/picture-types/exterior_front"
  },
  {
    "url": "https://placehold.co/1600x1200"
  }
]'

Success response contains all uploaded pictures, not just the added ones.

Use dedicated API endpoint to retrieve all supported picture types:

curl -X GET 'https://salesfront.url/api/v3/picture-types'
  -H 'Accept: application/json' \
  -H 'X-API-Key: XXX'

Note that pictureType is not mandatory although strongly advised. When pictures are uploaded without type, they will always be added at the end of the gallery.

Upload pictures - add, remove and replace

When uploading pictures with attached type, only single picture of a type is allowed. New upload via POST request will not replace already uploaded image, it will simply be ignored.

To overwrite already uploaded pictures PATCH request needs to be used:

curl -X PATCH 'https://salesfront.url/api/v3/trade-ins/{ID}/pictures' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'X-API-Key: XXX' \
  -d '[
  {
    "url": "https://placehold.co/1600x1200",
    "pictureType": "/api/v3/picture-types/exterior_front"
  }
]'

Success response returns all uploaded pictures. Empty collection can be sent too, it will remove all uploaded pictures.

Use POST request to strictly add, PATCH to add + remove + replace.

Comments

Eeach trade-in entity hosts optionally list of comments.

Retrieve a list of comments

curl -X GET 'https://salesfront.url/api/v3/trade-ins/{ID}/comments'
  -H 'Accept: application/json' \
  -H 'X-API-Key: XXX'

Add a comment(s) for the trade-in

curl -X POST 'https://salesfront.url/api/v3/trade-ins/{ID}/comments' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'X-API-Key: XXX' \
  -d '[{"comment": "Jason said YES"}, {"comment": "Dave said NO"}]'

Please note the API accepts a collection of comments as input.

Successful response contains all the comments, not just the added ones.

Edit or replace trade-in comments

curl -X PATCH 'https://salesfront.url/api/v3/trade-ins/{ID}/comments' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'X-API-Key: XXX' \
  -d '[{"comment": "Jason said NO"}, {"comment": "Dave said YES"}]'

This request replaces all existing comments with new ones.

Examples

List of trade-ins

curl -X GET 'https://salesfront.url/api/v3/trade-ins' \
  -H 'Accept: application/json'
  -H 'X-API-Key: XXX'

Returns collection of trade-ins in Salesfront, each with full details, sorted by id (most recently added first).

Refer to API doc for available filtering and sorting options. There are several options available to change sort order. To specify fields returned in response, use property filter.

Request with applied sorting and filtering options:

curl -gX GET 'https://salesfront.url/api/v3/trade-ins' \
  -H 'Accept: application/json'
  -H 'X-API-Key: XXX' \
  -d order[updatedAt]=DESC \
  -d status[]=done \
  -d status[]=sent_to_customer \
  -d properties[]=id \
  -d properties[]=status \
  -d properties[]=purchasePrice \
  -d properties[vehicleModel][]=regNr \
  -d properties[vehicleModel][]=make \
  -d properties[vehicleModel][]=model

Result contains entities:

only in “done” or “sent_to_customer” status
sorted by last update time (recent first)
and each item represented only by "id", "status", "regNr", "make", "model", "purchasePrice" fields

[
  ...
  {
    "id": 10783,
    "status": "done",
    "purchasePrice": 15000,
    "vehicleModel": {
      "regNr": "123ABC",
      "make": "BMW",
      "model": "530D XDRIVE"
    }
  }
  ...
]

New trade-in

API does not require a lot of data to create a new trade in. Yet here are few important considerations:

if trade-in is associated with a customer, then customer should be created first.
avoid setting specific status on a trade-in during creation. It makes the data validation very strict. Resulting solution will be prone to validation errors. Better approach is to add trade-in as draft, then change it’s status using dedicated requests.
pictures and comments are always created via dedicated operations.

Super minimalistic example

curl -X POST 'https://salesfront.url/api/v3/trade-ins' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json'
  -H 'X-API-Key: XXX' \
  -d {
  "vehicleModel": {
    "make": "Volkswagen",
    "model": "Golf",
    "firstRegistrationDate": "2020-02-20"
  },
  "customerAskingPrice": 9500
}

Request will be successful. But some of critical details were omitted which makes further processing of this trade-in inconvenient due to additional required manual work in Salesfront:

customer - while not strictly required, it’s most cases good idea to attach customer to the trade-in. Exception is cases where vehicles are bought in bulk from non-customer source.
dealership - okay to skip only if there’s single outlet in Salesfront. In all other cases missing dealership definition will complicate the further workflow.
vehicleModel . regNr - not mandatory, but is used to identify the vehicle in Salesfront. So if possible, always add it.
vehicleModel . mileage - not mandatory, but required to further process the Trade-in in Salesfront. Good practice is always add it.
vehicleModel . vehicleType - defaults to PC (Passenger Cars). Unless you always add PC vehicles, make sure to specify it explicitly.

Other common fields, that are not mandatory but should be specified regardless (unless there are good reasons not to):

vehicleModel . color
vehicleModel . fuel
vehicleModel . drivetrainType
vehicleModel . transmissionType

A bit more complete example

curl -X POST 'https://salesfront.url/api/v3/trade-ins' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json'
  -H 'X-API-Key: XXX' \
  -d {
  "customer": "/api/v3/customers/214154",
  "dealership": "/api/v3/locations/4",
  "vehicleModel": {
    "make": "Volkswagen",
    "model": "Golf",
    "regNr": "890ZXC",
    "mileage": 35000,
    "firstRegistrationDate": "2020-02-20",
    "vehicleType": "PC",
    "bodyType": "Hatchback",
    "color": "Black",
    "fuel": "Petrol",
    "engineType": "Hybrid",
    "cylinderCapacityCm3": 1600,
    "drivetrainType": "AWD",
    "transmissionType": "Automatic",
    "maxPowerKw": 120
  },
  "debtInfo": {
    "amount": 2500,
    "bank": "Popular Leasing"
  },
  "customerAskingPrice": 9500
}

Result is fully qualified vehicle in Salesfront Trade-in module, ready to be further processed for valuation.

Customers and leads

When adding a new trade-in to a customer, a new lead might be automatically created (depends on Salesfront setup). However, it is advisable to create lead explicitly to gain more control over the data. Alternatively, the lead can be modified with the required parameters after it was automatically created. For details, follow separate guide to work with customers and leads.

Updating a trade-in

Common tasks regarding trade-in update involves:

uploading pictures
adding comments
changing status

Notes and examples are provided above.

In case there’s need to update main trade-in entity, use top-level PATCH operation.

Trade-in information can’t be updated after the status is set to done (except VIN)
Trade-in agreement can’t be signed if the price is not indicated

Salesfront Developers

Trade-ins