API reference · v1.0.0

trustmydealer API

A single REST API covering everything an administrator or a dealership can do: profiles, review sources, syncing, reviews and replies, the resolution engine, review collection, reporting and website widgets. Every dealership is addressed by its MSAI Dealer ID.

Base URL: https://trustmydealer.co.uk/api/v1
Format: JSON over HTTPS
Schema: openapi.json

Getting started

1. Request a key. Partner keys are issued by trustmydealer. Dealership keys are generated in the dealer portal under Widgets & integrations.
2. Find the MSAI Dealer ID. It is the identifier already used for the dealership’s Google review source and appears on their record in the admin panel.
3. Make your first call. The score endpoint is the quickest way to confirm the key and the identifier are right.
4. Embed the badge. Call /widgets and paste the returned snippet straight into the dealership’s website.

curl "https://trustmydealer.co.uk/api/v1/dealers/10031287/score" \
  -H "Authorization: Bearer tmd_partner_live_xxx"

The MSAI Dealer ID

Every dealer-scoped path takes the form /api/v1/dealers/{msaiDealerId}/…. It is the same identifier stored today against a dealership’s Google review source, so partner systems and trustmydealer always mean the same dealership.

Internal UUIDs and profile slugs are returned in responses for linking, but are never required in a request path.
A dealership without an MSAI Dealer ID is not addressable here. Reads return dealer_not_found; attempts to attach data return msai_id_missing.
The identifier is unique across the platform and cannot be reassigned.

Authentication

Send the key as a bearer token on every request. There are two kinds, and the difference is reach, not capability.

Authorization: Bearer tmd_partner_live_xxx

Key	Prefix	Reach
Partner key	tmd_partner_	Any dealership, including administrative and arbitration actions.
Dealer key	tmd_dealer_	One dealership, portal-level actions only. Cannot moderate reviews or manage accounts.

Scopes

Scope	Grants	Available to
dealers:read	Read dealer profiles, sources and scores.	Partner, Dealer
dealers:write	Create and update dealerships and their review sources.	Partner
reviews:read	Read aggregated and direct reviews.	Partner, Dealer
reviews:write	Moderate reviews — hide, restore, flag, remove.	Partner
replies:write	Publish, edit and delete the dealer's public reply.	Partner, Dealer
cases:read	Read resolution cases, message threads and timelines.	Partner, Dealer
cases:write	Post messages, make offers, escalate a case.	Partner, Dealer
cases:admin	Force-publish, remove or extend a case. Arbitration only.	Partner
invitations:write	Send review requests, run campaigns, mint kiosk codes.	Partner, Dealer
verification:write	Approve or reject verified-purchase proofs.	Partner
members:write	Invite, change and remove dealer portal users.	Partner
widgets:read	Read widget settings and embed payloads.	Partner, Dealer
widgets:write	Change widget appearance settings.	Partner, Dealer
sync:write	Trigger a review sync and read sync history.	Partner, Dealer
webhooks:write	Register and manage webhook endpoints.	Partner

Keys can be rotated at any time. A rotated key keeps working for one hour so you can deploy the replacement without downtime.

Conventions

Pagination

List endpoints are cursor-paginated. Pass limit (1–100, default 25) and follow next_cursor until has_more is false.

Idempotency

Send an Idempotency-Key header on any POST. Repeating a request with the same key within 24 hours returns the original result instead of creating a duplicate.

Rate limits

600 requests per minute on a partner key, 120 on a dealer key. Every response carries X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset. A 429 includes Retry-After.

Errors

Failures return a consistent envelope with a stable machine code. Validation failures list the offending fields.

{
  "error": {
    "code": "validation_failed",
    "message": "One or more fields are invalid.",
    "fields": [
      {
        "field": "customer_email",
        "message": "Not a valid email address."
      }
    ],
    "request_id": "req_8f2c1a"
  }
}

Dealers

Dealerships are addressed by their MSAI Dealer ID everywhere in this API. The internal UUID and profile slug are returned for linking but are never required in a request path.

GET/api/v1/dealers

List dealerships

Every dealership the key can see. A dealer key returns only its own dealership. Results are ordered by name.

Partner or dealer keydealers:read

Parameters

searchstring · query
Match on name, town or postcode.
claimedboolean · query
Filter to claimed or unclaimed dealerships.
cursorstring · query
Opaque cursor from the previous page's `next_cursor`.
limitinteger · query
Page size, 1–100. Defaults to 25.

curl -X GET "https://trustmydealer.co.uk/api/v1/dealers" \
  -H "Authorization: Bearer tmd_partner_live_xxx"

GET/api/v1/dealers/{msaiDealerId}

Get a dealership

The full profile record for one dealership.

Partner or dealer keydealers:read

Parameters

msaiDealerIdstring · path · required
The dealership's MSAI Dealer ID — the same identifier used for their Google review source.

curl -X GET "https://trustmydealer.co.uk/api/v1/dealers/10031287" \
  -H "Authorization: Bearer tmd_partner_live_xxx"

Errorsdealer_not_found

POST/api/v1/dealers

Create a dealership

Creates the dealership and, when `msai_dealer_id` is supplied, provisions its Google review source in the same call. The slug is derived from the name unless you provide one.

Partner keydealers:write

Body

msai_dealer_idstring · required
Canonical external identifier. Must be unique.
namestring · required
Trading name as buyers would recognise it.
slugstring
Profile URL segment. Generated from the name if omitted.
locationstring
Town and county.
websitestring
Public website URL.
phonestring
Contact number in E.164 or national format.
descriptionstring
Short profile blurb.
opening_hoursstring
Free-text opening hours.
logo_urlstring
Absolute URL to a square logo.

curl -X POST "https://trustmydealer.co.uk/api/v1/dealers" \
  -H "Authorization: Bearer tmd_partner_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{"msai_dealer_id":"string","name":"string"}'

Errorsvalidation_failedmsai_id_conflict

PATCH/api/v1/dealers/{msaiDealerId}

Update a dealership

Partial update. A dealer key may change profile presentation fields only — name, description, phone, website, opening hours and logo.

Partner or dealer keydealers:write

Parameters

msaiDealerIdstring · path · required
The dealership's MSAI Dealer ID — the same identifier used for their Google review source.

Body

namestring
Trading name.
locationstring
Town and county.
websitestring
Public website URL.
phonestring
Contact number.
descriptionstring
Profile blurb.
opening_hoursstring
Opening hours.
logo_urlstring
Logo URL.
require_approvalboolean
Hold new aggregated reviews for moderation. Partner key only.

curl -X PATCH "https://trustmydealer.co.uk/api/v1/dealers/10031287" \
  -H "Authorization: Bearer tmd_partner_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{"key":"value"}'

Errorsdealer_not_foundvalidation_failed

DELETE/api/v1/dealers/{msaiDealerId}

Delete a dealership

Removes the dealership, its sources, reviews and widgets. Irreversible, and refused while open resolution cases exist.

Partner keydealers:write

Parameters

msaiDealerIdstring · path · required
The dealership's MSAI Dealer ID — the same identifier used for their Google review source.

curl -X DELETE "https://trustmydealer.co.uk/api/v1/dealers/10031287" \
  -H "Authorization: Bearer tmd_partner_live_xxx"

Errorsdealer_not_foundcase_closed

Review sources

A source is one external review platform connected to a dealership. Supported source keys: `trustpilot`, `reviewsio`, `cardealerreviews`, `judgeservice`, `feefo`, `google`. The `google` source stores the MSAI Dealer ID itself.

GET/api/v1/dealers/{msaiDealerId}/sources

List sources

Every connected source with its last sync outcome and platform-reported aggregate.

Partner or dealer keydealers:read

Parameters

msaiDealerIdstring · path · required
The dealership's MSAI Dealer ID — the same identifier used for their Google review source.

curl -X GET "https://trustmydealer.co.uk/api/v1/dealers/10031287/sources" \
  -H "Authorization: Bearer tmd_partner_live_xxx"

POST/api/v1/dealers/{msaiDealerId}/sources

Add a source

Connects a platform. For `google`, pass the MSAI Dealer ID as `url`. For every other platform, pass the dealer's public review page URL.

Partner keydealers:write

Parameters

msaiDealerIdstring · path · required
The dealership's MSAI Dealer ID — the same identifier used for their Google review source.

Body

sourcestring · required
One of the supported source keys.
urlstring · required
Review page URL, or the MSAI Dealer ID for `google`.
write_urlstring
Where customers should be sent to leave a review on that platform.
enabledboolean
Include in syncs and the combined score. Defaults to true.

curl -X POST "https://trustmydealer.co.uk/api/v1/dealers/10031287/sources" \
  -H "Authorization: Bearer tmd_partner_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{"source":"string","url":"string"}'

Errorsdealer_not_foundvalidation_failed

PATCH/api/v1/dealers/{msaiDealerId}/sources/{sourceId}

Update a source

Change the URL, the write URL, or enable and disable the source.

Partner or dealer keydealers:write

Parameters

msaiDealerIdstring · path · required
The dealership's MSAI Dealer ID — the same identifier used for their Google review source.
sourceIduuid · path · required
Source identifier from the list endpoint.

Body

urlstring
Review page URL.
write_urlstring
Leave-a-review URL.
enabledboolean
Include in syncs and scoring.

curl -X PATCH "https://trustmydealer.co.uk/api/v1/dealers/10031287/sources/{sourceId}" \
  -H "Authorization: Bearer tmd_partner_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{"key":"value"}'

Errorsresource_not_found

DELETE/api/v1/dealers/{msaiDealerId}/sources/{sourceId}

Remove a source

Disconnects the platform and drops the reviews it contributed from the combined score.

Partner keydealers:write

Parameters

msaiDealerIdstring · path · required
The dealership's MSAI Dealer ID — the same identifier used for their Google review source.
sourceIduuid · path · required
Source identifier.

curl -X DELETE "https://trustmydealer.co.uk/api/v1/dealers/10031287/sources/{sourceId}" \
  -H "Authorization: Bearer tmd_partner_live_xxx"

Errorsresource_not_found

Sync

Syncs pull fresh reviews from every enabled source and recalculate the combined score. Scheduled syncs run daily; these endpoints trigger and inspect them on demand.

POST/api/v1/dealers/{msaiDealerId}/sync

Sync one dealership

Queues a sync across the dealership's enabled sources and returns immediately with a run identifier. Rate limited to one manual sync per dealership per five minutes.

Partner or dealer keysync:write

Parameters

msaiDealerIdstring · path · required
The dealership's MSAI Dealer ID — the same identifier used for their Google review source.

Body

sourcesstring[]
Restrict the run to these source keys. Defaults to all enabled.

curl -X POST "https://trustmydealer.co.uk/api/v1/dealers/10031287/sync" \
  -H "Authorization: Bearer tmd_partner_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{"key":"value"}'

Errorsdealer_not_foundrate_limited

POST/api/v1/sync

Sync every dealership

Fleet-wide run, the same job the daily schedule triggers. Partner key only.

Partner keysync:write

curl -X POST "https://trustmydealer.co.uk/api/v1/sync" \
  -H "Authorization: Bearer tmd_partner_live_xxx"

GET/api/v1/dealers/{msaiDealerId}/sync-runs

Sync history

Recent runs for the dealership, newest first, with counts and any error text.

Partner or dealer keysync:write

Parameters

msaiDealerIdstring · path · required
The dealership's MSAI Dealer ID — the same identifier used for their Google review source.
cursorstring · query
Opaque cursor from the previous page's `next_cursor`.
limitinteger · query
Page size, 1–100. Defaults to 25.

curl -X GET "https://trustmydealer.co.uk/api/v1/dealers/10031287/sync-runs" \
  -H "Authorization: Bearer tmd_partner_live_xxx"

Scores

The combined score is a count-weighted mean across every enabled source plus published direct reviews. It is recalculated whenever a review changes state and after each sync.

GET/api/v1/dealers/{msaiDealerId}/score

Get the combined score

Headline score, total review count and the per-source breakdown that sits underneath it.

Partner or dealer keydealers:read

Parameters

msaiDealerIdstring · path · required
The dealership's MSAI Dealer ID — the same identifier used for their Google review source.

curl -X GET "https://trustmydealer.co.uk/api/v1/dealers/10031287/score" \
  -H "Authorization: Bearer tmd_partner_live_xxx"

Errorsdealer_not_found

GET/api/v1/dealers/{msaiDealerId}/score/history

Score trend

Daily score and cumulative review count over the requested window.

Partner or dealer keydealers:read

Parameters

msaiDealerIdstring · path · required
The dealership's MSAI Dealer ID — the same identifier used for their Google review source.
daysinteger · query
30, 90 or 365. Defaults to 90.

curl -X GET "https://trustmydealer.co.uk/api/v1/dealers/10031287/score/history" \
  -H "Authorization: Bearer tmd_partner_live_xxx"

Reviews

One endpoint returns both aggregated reviews (scraped or API-sourced from other platforms) and direct reviews left on trustmydealer. The `type` field distinguishes them. Reviews inside the resolution window are never returned to a dealer key as public content — they appear under Cases.

GET/api/v1/dealers/{msaiDealerId}/reviews

List reviews

Newest first by review date, with cursor pagination.

Partner or dealer keyreviews:read

Parameters

msaiDealerIdstring · path · required
The dealership's MSAI Dealer ID — the same identifier used for their Google review source.
typestring · query
`direct`, `aggregated` or `all`. Defaults to all.
sourcestring · query
Filter to one source key.
statusstring · query
`published`, `pending`, `hidden`, `in_resolution`. Partner key may query non-public states.
min_ratingnumber · query
Lowest rating to include.
max_ratingnumber · query
Highest rating to include.
sincedate · query
ISO date. Only reviews on or after this date.
has_replyboolean · query
Filter to reviews with or without a dealer reply.
cursorstring · query
Opaque cursor from the previous page's `next_cursor`.
limitinteger · query
Page size, 1–100. Defaults to 25.

curl -X GET "https://trustmydealer.co.uk/api/v1/dealers/10031287/reviews" \
  -H "Authorization: Bearer tmd_partner_live_xxx"

GET/api/v1/dealers/{msaiDealerId}/reviews/{reviewId}

Get a review

One review with its reply and, for direct reviews, its verification and case state.

Partner or dealer keyreviews:read

Parameters

msaiDealerIdstring · path · required
The dealership's MSAI Dealer ID — the same identifier used for their Google review source.
reviewIduuid · path · required
Review identifier.

curl -X GET "https://trustmydealer.co.uk/api/v1/dealers/10031287/reviews/{reviewId}" \
  -H "Authorization: Bearer tmd_partner_live_xxx"

Errorsresource_not_found

POST/api/v1/dealers/{msaiDealerId}/reviews/{reviewId}/moderate

Moderate a review

Arbitration action. Dealers can never hide or remove a review — this endpoint rejects dealer keys outright, and the UI says so plainly.

Partner keyreviews:write

Parameters

msaiDealerIdstring · path · required
The dealership's MSAI Dealer ID — the same identifier used for their Google review source.
reviewIduuid · path · required
Review identifier.

Body

actionstring · required
`hide`, `restore`, `flag` or `remove`.
reasonstring · required
Recorded on the audit trail and shown to admins.

curl -X POST "https://trustmydealer.co.uk/api/v1/dealers/10031287/reviews/{reviewId}/moderate" \
  -H "Authorization: Bearer tmd_partner_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{"action":"string","reason":"string"}'

Errorsforbidden_scoperesource_not_foundvalidation_failed

Replies

A review carries at most one public dealer reply. Replies work identically for direct and aggregated reviews and are shown as “Response from the dealer” on the profile.

POST/api/v1/dealers/{msaiDealerId}/reviews/{reviewId}/reply

Publish a reply

Creates the dealer's public response. Returns 409 if a reply already exists.

Partner or dealer keyreplies:write

Parameters

msaiDealerIdstring · path · required
The dealership's MSAI Dealer ID — the same identifier used for their Google review source.
reviewIduuid · path · required
Review identifier.

Body

bodystring · required
Reply text, 10–2000 characters.

curl -X POST "https://trustmydealer.co.uk/api/v1/dealers/10031287/reviews/{reviewId}/reply" \
  -H "Authorization: Bearer tmd_partner_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{"body":"string"}'

Errorsalready_repliedresource_not_foundvalidation_failed

PATCH/api/v1/dealers/{msaiDealerId}/reviews/{reviewId}/reply

Edit a reply

Replaces the reply text. Edits are timestamped and kept in the audit trail.

Partner or dealer keyreplies:write

Parameters

msaiDealerIdstring · path · required
The dealership's MSAI Dealer ID — the same identifier used for their Google review source.
reviewIduuid · path · required
Review identifier.

Body

bodystring · required
New reply text.

curl -X PATCH "https://trustmydealer.co.uk/api/v1/dealers/10031287/reviews/{reviewId}/reply" \
  -H "Authorization: Bearer tmd_partner_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{"body":"string"}'

Errorsresource_not_found

DELETE/api/v1/dealers/{msaiDealerId}/reviews/{reviewId}/reply

Delete a reply

Removes the public response. The review itself is untouched.

Partner or dealer keyreplies:write

Parameters

msaiDealerIdstring · path · required
The dealership's MSAI Dealer ID — the same identifier used for their Google review source.
reviewIduuid · path · required
Review identifier.

curl -X DELETE "https://trustmydealer.co.uk/api/v1/dealers/10031287/reviews/{reviewId}/reply" \
  -H "Authorization: Bearer tmd_partner_live_xxx"

Errorsresource_not_found

Resolution cases

A review of two stars or fewer is held privately for seven days and a case is opened. During the hold the review is invisible to the public and excluded from the score. Every action is written to an append-only timeline that neither side can alter.

GET/api/v1/dealers/{msaiDealerId}/cases

List cases

Open cases first, sorted by time remaining.

Partner or dealer keycases:read

Parameters

msaiDealerIdstring · path · required
The dealership's MSAI Dealer ID — the same identifier used for their Google review source.
statestring · query
`open`, `escalated`, `resolved` or `closed`.
cursorstring · query
Opaque cursor from the previous page's `next_cursor`.
limitinteger · query
Page size, 1–100. Defaults to 25.

curl -X GET "https://trustmydealer.co.uk/api/v1/dealers/10031287/cases" \
  -H "Authorization: Bearer tmd_partner_live_xxx"

GET/api/v1/dealers/{msaiDealerId}/cases/{caseId}

Get a case

The case, the held review, the full private message thread and the immutable event timeline.

Partner or dealer keycases:read

Parameters

msaiDealerIdstring · path · required
The dealership's MSAI Dealer ID — the same identifier used for their Google review source.
caseIduuid · path · required
Case identifier.

curl -X GET "https://trustmydealer.co.uk/api/v1/dealers/10031287/cases/{caseId}" \
  -H "Authorization: Bearer tmd_partner_live_xxx"

Errorsresource_not_found

POST/api/v1/dealers/{msaiDealerId}/cases/{caseId}/messages

Post a message

Adds to the private thread and notifies the other side by email. Reviewer email addresses are never exposed to a dealer key.

Partner or dealer keycases:write

Parameters

msaiDealerIdstring · path · required
The dealership's MSAI Dealer ID — the same identifier used for their Google review source.
caseIduuid · path · required
Case identifier.

Body

bodystring · required
Message text, 5–4000 characters.

curl -X POST "https://trustmydealer.co.uk/api/v1/dealers/10031287/cases/{caseId}/messages" \
  -H "Authorization: Bearer tmd_partner_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{"body":"string"}'

Errorscase_closedresource_not_found

POST/api/v1/dealers/{msaiDealerId}/cases/{caseId}/offer

Send a resolution offer

Records a concrete offer on the timeline. The reviewer is always free to decline — an offer can never require withdrawal.

Partner or dealer keycases:write

Parameters

msaiDealerIdstring · path · required
The dealership's MSAI Dealer ID — the same identifier used for their Google review source.
caseIduuid · path · required
Case identifier.

Body

summarystring · required
What is being offered, in plain English.
messagestring
Optional accompanying note.

curl -X POST "https://trustmydealer.co.uk/api/v1/dealers/10031287/cases/{caseId}/offer" \
  -H "Authorization: Bearer tmd_partner_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{"summary":"string"}'

Errorscase_closed

POST/api/v1/dealers/{msaiDealerId}/cases/{caseId}/escalate

Escalate to arbitration

Flags the case for a trustmydealer administrator. Either side may escalate once.

Partner or dealer keycases:write

Parameters

msaiDealerIdstring · path · required
The dealership's MSAI Dealer ID — the same identifier used for their Google review source.
caseIduuid · path · required
Case identifier.

Body

reasonstring · required
Why arbitration is needed.

curl -X POST "https://trustmydealer.co.uk/api/v1/dealers/10031287/cases/{caseId}/escalate" \
  -H "Authorization: Bearer tmd_partner_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{"reason":"string"}'

Errorscase_closed

POST/api/v1/dealers/{msaiDealerId}/cases/{caseId}/resolve

Arbitrate a case

Administrator decision: publish the held review immediately, remove it for a policy breach, or grant the single permitted seven-day extension.

Partner keycases:admin

Parameters

msaiDealerIdstring · path · required
The dealership's MSAI Dealer ID — the same identifier used for their Google review source.
caseIduuid · path · required
Case identifier.

Body

actionstring · required
`publish`, `remove` or `extend`.
notestring · required
Reasoning, written to the timeline.

curl -X POST "https://trustmydealer.co.uk/api/v1/dealers/10031287/cases/{caseId}/resolve" \
  -H "Authorization: Bearer tmd_partner_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{"action":"string","note":"string"}'

Errorsforbidden_scopecase_closed

Review collection

Review requests go out by email or SMS, or are collected in person through a kiosk or QR code. Every request carries a single-use code that ties the resulting review back to a real transaction.

POST/api/v1/dealers/{msaiDealerId}/invitations

Send a review request

Sends one request immediately, or schedules it for `delay_days` after the handover date. Send `Idempotency-Key` to make retries safe.

Partner or dealer keyinvitations:write

Parameters

msaiDealerIdstring · path · required
The dealership's MSAI Dealer ID — the same identifier used for their Google review source.

Body

channelstring · required
`email` or `sms`.
customer_emailstring
Required when channel is `email`.
customer_phonestring
Required when channel is `sms`.
customer_namestring
Used to personalise the message.
vehiclestring
Vehicle description shown in the request.
destinationstring
`trustmydealer` or an external source key such as `google`.
delay_daysinteger
Delay before sending. Defaults to the dealership's invite settings.

curl -X POST "https://trustmydealer.co.uk/api/v1/dealers/10031287/invitations" \
  -H "Authorization: Bearer tmd_partner_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{"channel":"string"}'

Errorsvalidation_failed

POST/api/v1/dealers/{msaiDealerId}/invitations/bulk

Bulk send

Up to 500 requests in one call. Each row is validated independently; valid rows send even if others fail.

Partner or dealer keyinvitations:write

Parameters

msaiDealerIdstring · path · required
The dealership's MSAI Dealer ID — the same identifier used for their Google review source.

Body

invitationsobject[] · required
Array of request objects in the shape above.

curl -X POST "https://trustmydealer.co.uk/api/v1/dealers/10031287/invitations/bulk" \
  -H "Authorization: Bearer tmd_partner_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{"invitations":[]}'

GET/api/v1/dealers/{msaiDealerId}/invitations

List requests

Delivery and response state for every request sent.

Partner or dealer keyinvitations:write

Parameters

msaiDealerIdstring · path · required
The dealership's MSAI Dealer ID — the same identifier used for their Google review source.
statusstring · query
`queued`, `sent`, `opened`, `completed`, `bounced`, `unsubscribed`.
cursorstring · query
Opaque cursor from the previous page's `next_cursor`.
limitinteger · query
Page size, 1–100. Defaults to 25.

curl -X GET "https://trustmydealer.co.uk/api/v1/dealers/10031287/invitations" \
  -H "Authorization: Bearer tmd_partner_live_xxx"

GET/api/v1/dealers/{msaiDealerId}/campaigns

List campaigns

Standing campaigns with their schedule, reminder rules and response rate.

Partner or dealer keyinvitations:write

Parameters

msaiDealerIdstring · path · required
The dealership's MSAI Dealer ID — the same identifier used for their Google review source.

curl -X GET "https://trustmydealer.co.uk/api/v1/dealers/10031287/campaigns" \
  -H "Authorization: Bearer tmd_partner_live_xxx"

POST/api/v1/dealers/{msaiDealerId}/campaigns

Create a campaign

Defines the message, timing and reminder policy applied to future requests.

Partner or dealer keyinvitations:write

Parameters

msaiDealerIdstring · path · required
The dealership's MSAI Dealer ID — the same identifier used for their Google review source.

Body

namestring · required
Internal label.
channelstring · required
`email` or `sms`.
destinationstring · required
Where the customer is sent to review.
schedule_delay_daysinteger
Days after the handover before the first send.
reminder_interval_daysinteger
Gap between reminders.
max_remindersinteger
Reminder cap, 0–3.
message_subjectstring
Email subject line.
message_bodystring
Message body.

curl -X POST "https://trustmydealer.co.uk/api/v1/dealers/10031287/campaigns" \
  -H "Authorization: Bearer tmd_partner_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{"name":"string","channel":"string","destination":"string"}'

GET/api/v1/dealers/{msaiDealerId}/invite-settings

Get collection settings

Default channel, destination, timing, sender name and message templates.

Partner or dealer keyinvitations:write

Parameters

msaiDealerIdstring · path · required
The dealership's MSAI Dealer ID — the same identifier used for their Google review source.

curl -X GET "https://trustmydealer.co.uk/api/v1/dealers/10031287/invite-settings" \
  -H "Authorization: Bearer tmd_partner_live_xxx"

PATCH/api/v1/dealers/{msaiDealerId}/invite-settings

Update collection settings

Partial update of the same fields.

Partner or dealer keyinvitations:write

Parameters

msaiDealerIdstring · path · required
The dealership's MSAI Dealer ID — the same identifier used for their Google review source.

Body

default_channelstring
`email` or `sms`.
default_destinationstring
Default review destination.
request_delay_daysinteger
Default send delay.
max_remindersinteger
Reminder cap.
reminder_interval_daysinteger
Reminder gap.
send_from_namestring
Sender name shown to customers.
email_subject_linestring
Default subject.
sms_bodystring
Default SMS text, must contain {link}.

curl -X PATCH "https://trustmydealer.co.uk/api/v1/dealers/10031287/invite-settings" \
  -H "Authorization: Bearer tmd_partner_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{"key":"value"}'

POST/api/v1/dealers/{msaiDealerId}/kiosk-codes

Mint a kiosk code

Returns a code for the in-showroom kiosk plus a QR short link for print. Kiosk sessions are chrome-free and reset after each submission.

Partner or dealer keyinvitations:write

Parameters

msaiDealerIdstring · path · required
The dealership's MSAI Dealer ID — the same identifier used for their Google review source.

Body

labelstring
Where the code lives, e.g. “Handover desk”.

curl -X POST "https://trustmydealer.co.uk/api/v1/dealers/10031287/kiosk-codes" \
  -H "Authorization: Bearer tmd_partner_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{"key":"value"}'

Purchase verification

A reviewer may upload an invoice to earn a verified-purchase mark. An AI check reads it and returns a verdict; anything short of high confidence lands in the administrator queue. The document itself is never public and is never returned by this API.

GET/api/v1/verification/queue

List proofs awaiting review

Uncertain proofs across every dealership, oldest first.

Partner keyverification:write

Parameters

msai_dealer_idstring · query
Restrict to one dealership.
cursorstring · query
Opaque cursor from the previous page's `next_cursor`.
limitinteger · query
Page size, 1–100. Defaults to 25.

curl -X GET "https://trustmydealer.co.uk/api/v1/verification/queue" \
  -H "Authorization: Bearer tmd_partner_live_xxx"

POST/api/v1/verification/{proofId}

Decide a proof

Applies or refuses the verified-purchase mark and records the override against the administrator.

Partner keyverification:write

Parameters

proofIduuid · path · required
Proof identifier.

Body

verdictstring · required
`verified` or `rejected`.
reasonstring
Note kept on the record.

curl -X POST "https://trustmydealer.co.uk/api/v1/verification/{proofId}" \
  -H "Authorization: Bearer tmd_partner_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{"verdict":"string"}'

Errorsresource_not_found

Dealer accounts

Portal logins are created by administrators. An invite emails a single-use, hashed token that expires; it never exposes a password and never signs anyone in automatically.

GET/api/v1/dealers/{msaiDealerId}/members

List members

Everyone with access to that dealership's portal, plus outstanding invites.

Partner keymembers:write

Parameters

msaiDealerIdstring · path · required
The dealership's MSAI Dealer ID — the same identifier used for their Google review source.

curl -X GET "https://trustmydealer.co.uk/api/v1/dealers/10031287/members" \
  -H "Authorization: Bearer tmd_partner_live_xxx"

POST/api/v1/dealers/{msaiDealerId}/members

Invite a member

Creates the login if needed and sends the branded set-password email.

Partner keymembers:write

Parameters

msaiDealerIdstring · path · required
The dealership's MSAI Dealer ID — the same identifier used for their Google review source.

Body

emailstring · required
Where the invite is sent.
rolestring
`owner` or `staff`. Defaults to staff.

curl -X POST "https://trustmydealer.co.uk/api/v1/dealers/10031287/members" \
  -H "Authorization: Bearer tmd_partner_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{"email":"string"}'

Errorsvalidation_failed

POST/api/v1/dealers/{msaiDealerId}/members/{memberId}/resend

Resend an invite

Issues a fresh token and invalidates the previous one.

Partner keymembers:write

Parameters

msaiDealerIdstring · path · required
The dealership's MSAI Dealer ID — the same identifier used for their Google review source.
memberIduuid · path · required
Member identifier.

curl -X POST "https://trustmydealer.co.uk/api/v1/dealers/10031287/members/{memberId}/resend" \
  -H "Authorization: Bearer tmd_partner_live_xxx"

PATCH/api/v1/dealers/{msaiDealerId}/members/{memberId}

Change a role

Promotes or demotes a member between owner and staff.

Partner keymembers:write

Parameters

msaiDealerIdstring · path · required
The dealership's MSAI Dealer ID — the same identifier used for their Google review source.
memberIduuid · path · required
Member identifier.

Body

rolestring · required
`owner` or `staff`.

curl -X PATCH "https://trustmydealer.co.uk/api/v1/dealers/10031287/members/{memberId}" \
  -H "Authorization: Bearer tmd_partner_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{"role":"string"}'

DELETE/api/v1/dealers/{msaiDealerId}/members/{memberId}

Remove a member

Revokes portal access immediately. The user account itself is untouched.

Partner keymembers:write

Parameters

msaiDealerIdstring · path · required
The dealership's MSAI Dealer ID — the same identifier used for their Google review source.
memberIduuid · path · required
Member identifier.

curl -X DELETE "https://trustmydealer.co.uk/api/v1/dealers/10031287/members/{memberId}" \
  -H "Authorization: Bearer tmd_partner_live_xxx"

Widgets

Everything needed to put a dealership's reviews on their own website. The widget endpoints return ready-to-paste snippets — you never have to build the markup yourself — and the badge endpoint returns the raw figures if you would rather render your own.

GET/api/v1/dealers/{msaiDealerId}/widgets

List every available widget

One call returns every widget for the dealership: each badge variant and each review widget, with its embed snippet, script URL, iframe fallback and a live preview URL.

Partner or dealer keywidgets:read

Parameters

msaiDealerIdstring · path · required
The dealership's MSAI Dealer ID — the same identifier used for their Google review source.
themestring · query
`light` or `dark`. Defaults to the dealership's saved theme.

curl -X GET "https://trustmydealer.co.uk/api/v1/dealers/10031287/widgets" \
  -H "Authorization: Bearer tmd_partner_live_xxx"

Badge variants: standard, compact, seal. Review widget variants: summary, strip, wall, quote.

Errorsdealer_not_found

GET/api/v1/dealers/{msaiDealerId}/widgets/badge

Get one badge embed

The embed payload for a single badge variant and theme.

Partner or dealer keywidgets:read

Parameters

msaiDealerIdstring · path · required
The dealership's MSAI Dealer ID — the same identifier used for their Google review source.
variantstring · query
`standard`, `compact` or `seal`.
themestring · query
`light` or `dark`.

curl -X GET "https://trustmydealer.co.uk/api/v1/dealers/10031287/widgets/badge" \
  -H "Authorization: Bearer tmd_partner_live_xxx"

GET/api/v1/dealers/{msaiDealerId}/widgets/reviews

Get one review widget embed

The embed payload for a single review widget variant and theme.

Partner or dealer keywidgets:read

Parameters

msaiDealerIdstring · path · required
The dealership's MSAI Dealer ID — the same identifier used for their Google review source.
variantstring · query
`summary`, `strip`, `wall` or `quote`.
themestring · query
`light` or `dark`.

curl -X GET "https://trustmydealer.co.uk/api/v1/dealers/10031287/widgets/reviews" \
  -H "Authorization: Bearer tmd_partner_live_xxx"

GET/api/v1/dealers/{msaiDealerId}/badge

Badge data

The raw figures a badge renders from, for teams building their own component. Cached for five minutes and safe to call from a browser.

Partner or dealer keywidgets:read

Parameters

msaiDealerIdstring · path · required
The dealership's MSAI Dealer ID — the same identifier used for their Google review source.

curl -X GET "https://trustmydealer.co.uk/api/v1/dealers/10031287/badge" \
  -H "Authorization: Bearer tmd_partner_live_xxx"

GET/api/v1/dealers/{msaiDealerId}/widget-settings

Get widget settings

The dealership's saved appearance settings.

Partner or dealer keywidgets:read

Parameters

msaiDealerIdstring · path · required
The dealership's MSAI Dealer ID — the same identifier used for their Google review source.

curl -X GET "https://trustmydealer.co.uk/api/v1/dealers/10031287/widget-settings" \
  -H "Authorization: Bearer tmd_partner_live_xxx"

PATCH/api/v1/dealers/{msaiDealerId}/widget-settings

Update widget settings

Appearance only. A dealership can choose how its widget looks, never what it says — score and count are always live.

Partner or dealer keywidgets:write

Parameters

msaiDealerIdstring · path · required
The dealership's MSAI Dealer ID — the same identifier used for their Google review source.

Body

themestring
`light` or `dark`.
badge_variantstring
`standard`, `compact` or `seal`.
accentstring
Hex accent colour.
autoplay_msinteger
Carousel interval in milliseconds, 0 to disable.
min_ratingnumber
Lowest rating shown in review widgets.
max_reviewsinteger
Maximum reviews rendered, 3–50.
sourcesstring[]
Source keys to include in review widgets.
show_headerboolean
Show the score header above the reviews.

curl -X PATCH "https://trustmydealer.co.uk/api/v1/dealers/10031287/widget-settings" \
  -H "Authorization: Bearer tmd_partner_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{"key":"value"}'

Errorsvalidation_failed

Reporting

The same figures the dealer portal reports page shows, available as JSON or CSV.

GET/api/v1/dealers/{msaiDealerId}/report

Dealer report

Review volume, rating distribution, source mix, response rate and resolution outcomes over the window.

Partner or dealer keydealers:read

Parameters

msaiDealerIdstring · path · required
The dealership's MSAI Dealer ID — the same identifier used for their Google review source.
daysinteger · query
30, 90 or 365. Defaults to 30.
formatstring · query
`json` or `csv`. Defaults to json.

curl -X GET "https://trustmydealer.co.uk/api/v1/dealers/10031287/report" \
  -H "Authorization: Bearer tmd_partner_live_xxx"

Webhooks

Register an HTTPS endpoint and we post a signed JSON body when something happens. Every delivery carries `X-TMD-Signature`, an HMAC-SHA256 of the raw body using your endpoint secret, and `X-TMD-Timestamp`. Compare in constant time and reject anything older than five minutes.

Event	Fires when
review.created	A direct review was submitted, before any resolution hold.
review.published	A review became publicly visible on the profile.
review.moderated	A review was hidden, restored or removed by an administrator.
reply.published	A dealer reply went live on a review.
case.opened	A low rating entered the resolution window.
case.message	A new message was posted in a case thread.
case.resolved	A case ended — withdrawn, updated, published or arbitrated.
sync.completed	A source sync finished, successfully or not.
invitation.responded	A review request produced a review.
score.changed	The dealer's combined score or review count changed.

GET/api/v1/webhooks

List endpoints

Registered endpoints with their subscribed events and recent delivery health.

Partner keywebhooks:write

curl -X GET "https://trustmydealer.co.uk/api/v1/webhooks" \
  -H "Authorization: Bearer tmd_partner_live_xxx"

POST/api/v1/webhooks

Register an endpoint

Returns the signing secret once, at creation. Store it — it is never shown again.

Partner keywebhooks:write

Body

urlstring · required
HTTPS endpoint that will receive deliveries.
eventsstring[] · required
Events to subscribe to.
msai_dealer_idstring
Restrict deliveries to one dealership.

curl -X POST "https://trustmydealer.co.uk/api/v1/webhooks" \
  -H "Authorization: Bearer tmd_partner_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{"url":"string","events":[]}'

DELETE/api/v1/webhooks/{webhookId}

Delete an endpoint

Stops all deliveries to that endpoint.

Partner keywebhooks:write

Parameters

webhookIdstring · path · required
Endpoint identifier.

curl -X DELETE "https://trustmydealer.co.uk/api/v1/webhooks/{webhookId}" \
  -H "Authorization: Bearer tmd_partner_live_xxx"

Error codes

Code	HTTP	Meaning
unauthorized	401	Missing, malformed or revoked API key.
forbidden_scope	403	The key is valid but lacks the scope this endpoint needs.
forbidden_dealer	403	A dealer key was used against a dealership it is not linked to.
dealer_not_found	404	No dealership matches that MSAI Dealer ID.
resource_not_found	404	The review, case, invitation or member does not exist.
msai_id_missing	409	The dealership exists but has no MSAI Dealer ID, so it is not addressable by this API.
msai_id_conflict	409	That MSAI Dealer ID is already assigned to another dealership.
already_replied	409	A review may carry only one dealer reply. Use PATCH to change it.
case_closed	409	The resolution case has ended and no longer accepts messages or actions.
validation_failed	422	One or more fields failed validation. See the `fields` array.
rate_limited	429	Too many requests. Retry after the `Retry-After` header.
internal_error	500	Unexpected failure on our side. Safe to retry with the same Idempotency-Key.

Changelog

v1.0.0First published contract: dealers, sources, sync, scores, reviews, replies, resolution cases, review collection, verification, dealer accounts, widgets, reporting and webhooks — all keyed by MSAI Dealer ID.

The slug-based endpoints /api/public/badge/{slug} and /api/public/reviews/{slug} remain supported for existing embeds. New integrations should use the MSAI-keyed /api/v1 equivalents.

Not integrating yet? See what the dealer portal does.