Skip to content

Ad Management

This page describes the available Dealer Hub API endpoints and how to use them to create and manage ads on the marketplace.

Available endpoints

For a full list of available endpoints and their details, see the API documentation.

Ad lifecycle statuses

From the perspective of an integrating party, an ad within Dealer Hub may be in one of the following statuses

Status Description
DRAFT Initial status of an ad. Attributes and media can be set, but the ad is not yet visible on the marketplace.
PUBLISHED The ad has passed marketplace validation and is live and visible to buyers. It can be hidden, renewed, or marked as sold.
PENDING The ad has been submitted and is awaiting marketplace validation. It cannot be duplicated while in this status.
HIDDEN A previously published ad that has been temporarily taken down and is no longer visible on the marketplace. It can still be reached with an existing link, but will not show up in search results. It can be unhidden or marked as sold.
REJECTED The ad did not pass marketplace validation. A previously published version may still be visible. The ad can be corrected and resubmitted.
EXPIRED The ad has exceeded its active duration and is no longer visible. It can be renewed or duplicated, but not edited.
SOLD The ad has been marked as sold by the dealer. It can still be reached and will show up in search results on marketplace.
DELETED The ad has been permanently removed and can no longer be modified or reached.

WARNING: An ad could be in a status PENDING or PUBLISHED and have new attributes sent to it via the API. Such an ad would still be in PENDING or PUBLISH status and new changes would become visible after another /publish API call is made for this ad.]

--- title: Ad Status config: elk: mergeEdges: false #nodePlacementStrategy: SIMPLE #nodePlacementStrategy: NETWORK_SIMPLEX #nodePlacementStrategy: LINEAR_SEGMENTS nodePlacementStrategy: BRANDES_KOEPF cycleBreakingStrategy: MODEL_ORDER #forceNodeModelOrder: true nodePlacementAlignment: LEFTUP #keepEntryNodeOnTop: true --- stateDiagram-v2 direction LR [*] --> DRAFT: set-attributes note left of DRAFT _modify_ in this diagram means one of following operation ids:   · _set-attributes_ · _upload-file_ · _upload-image_ · _set-image_ · _set-file_   end note DRAFT --> DRAFT: modify DRAFT --> PENDING: publish note right of PENDING blank label means the transition is done without explicit an api call due to internal logic end note PENDING --> PUBLISHED PUBLISHED --> PENDING: publish PUBLISHED --> PUBLISHED: modify PENDING --> REJECTED REJECTED --> PENDING: publish REJECTED --> REJECTED: modify %% PUBLISHED --> HIDDEN: unhide / hide HIDDEN --> PUBLISHED: unhide PUBLISHED --> HIDDEN: hide PUBLISHED --> SOLD: dispose PUBLISHED --> EXPIRED EXPIRED --> DELETED EXPIRED --> PUBLISHED: power-up-bump %% Not included for clarity %% PUBLISHED --> PUBLISHED: power-up-bump %% PUBLISHED --> PUBLISHED: power-up-pole-position note right of DELETED all states can be transitioned to **DELETED** by _delete_, these transitions not included on diagram for clarity end note DELETED --> [*] classDef temp stroke: var(--md-accent-fg-color); class DELETED temp class EXPIRED temp class PENDING temp classDef hidden stroke-width: 2, stroke-dasharray: 10; class DRAFT hidden class EXPIRED hidden class DELETED hidden class HIDDEN hidden class REJECTED hidden

Ad creation journey

The diagram below shows step-by-step ad creation process:

sequenceDiagram participant dms as Integrator participant api as Dealer Hub API note over dms: 1. Get make and models dms ->> api: GET /v0/CAR/models?make=volvo api -->> dms: 200 OK [List<MakeAndModelId>] note over dms: 2. Set attributes dms ->> api: POST /v0/ads/set-attributes api -->> dms: 200 OK note over dms: 3. Upload images par imageId 1 dms ->> api: POST /v0/ads/upload-image api -->> dms: 200 OK and imageId 2 dms ->> api: POST /v0/ads/upload-image api -->> dms: 200 OK end note over dms: 4. Set images dms ->> api: POST /v0/ads/set-images api -->> dms: 200 OK alt conditionReport.type=PDF note over dms: 5. Upload file dms ->> api: POST /v0/ads/upload-file api -->> dms: 200 OK end note over dms: 6. Set condition report dms ->> api: POST /v0/ads/set-condition-report api -->> dms: 200 OK note over dms: 8. Publish dms ->> api: POST /v0/ads/publish api -->> dms: 200 OK note over dms: 9. Get ad details dms ->> api: GET /v0/ads/get-details api -->> dms: GetDetailsResponse
  1. The journey begins by fetching the ad model details and car models to establish which attribute values are allowed.
  2. Ad attributes are set using set-attributes.
  3. Images are uploaded, which can be done for multiple files in parallel.
  4. Uploaded images are associated with the ad draft using set-images, which also defines their display order.
  5. If the condition report is provided as a PDF file, it must be uploaded first using upload-file.
  6. The condition report, in any of its supported forms, must be associated with the ad draft using set-condition-report.
  7. The ad is published using publish. A successful response means the ad has been sent to the marketplace for validation - the actual publication may take a moment.
  8. The current status of the ad can be retrieved at any time using get-details.

Ad lifecycle journey

The diagram below shows step-by-step ad lifecycle process:

sequenceDiagram participant dms as Integrator participant api as Dealer Hub API note over dms: 1. Get details dms ->> api: GET /v0/ads/get-details api -->> dms: GetDetailsResponse note over dms: 2. Set attributes dms ->> api: POST /v0/ads/set-attributes api -->> dms: 200 OK note over dms: 3. Upload image dms ->> api: POST /v0/ads/upload-image api -->> dms: 200 OK note over dms: 4. Set images dms ->> api: POST /v0/ads/set-images api -->> dms: 200 OK note over dms: 5. Publish dms ->> api: POST /v0/ads/publish api -->> dms: 200 OK note over dms: 6. Hide dms ->> api: POST /v0/ads/hide api -->> dms: 200 OK note over dms: 7. Unhide dms ->> api: POST /v0/ads/unhide api -->> dms: 200 OK note over dms: 8. Dispose dms ->> api: POST /v0/ads/dispose api -->> dms: 200 OK note over dms: 9. Delete dms ->> api: POST /v0/ads/delete api -->> dms: 200 OK
  1. Ad details are retrieved using get-details to get current property values.
  2. Ad attributes are updated using set-attributes. Because this is a full replacement endpoint, previously fetched attributes must be included alongside updated values (e.g., description, mileageInKm).
  3. New images are uploaded using upload-image, which can be done for multiple files in parallel.
  4. Newly uploaded images are associated with the ad using set-images, which also defines their display order. Omitting a previously uploaded image will remove it from the displayed images.
  5. The ad is published using publish. A successful response means the ad update has been sent to the marketplace for validation - the actual publication may take a moment.
  6. The current status of the ad can be retrieved at any time using get-details.
  7. The ad is hidden from marketplace search results using hide.
  8. The ad is made searchable again using unhide.
  9. The ad is disposed using dispose, which hides it from search results and marks it as sold.
  10. The ad is deleted from the system using delete.