{"openapi":"3.1.0","info":{"title":"trustmydealer API","version":"1.0.0","description":"Admin and dealer API for trustmydealer.co.uk. Every dealership is addressed by its MSAI Dealer ID — the same identifier used for its Google review source.","contact":{"name":"trustmydealer","url":"https://trustmydealer.co.uk/docs/api"}},"servers":[{"url":"https://trustmydealer.co.uk","description":"Production"}],"tags":[{"name":"Dealers","description":"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."},{"name":"Review sources","description":"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."},{"name":"Sync","description":"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."},{"name":"Scores","description":"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."},{"name":"Reviews","description":"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."},{"name":"Replies","description":"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."},{"name":"Resolution cases","description":"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."},{"name":"Review collection","description":"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."},{"name":"Purchase verification","description":"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."},{"name":"Dealer accounts","description":"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."},{"name":"Widgets","description":"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."},{"name":"Reporting","description":"The same figures the dealer portal reports page shows, available as JSON or CSV."},{"name":"Webhooks","description":"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."}],"components":{"securitySchemes":{"partnerKey":{"type":"http","scheme":"bearer","description":"Partner key (prefix tmd_partner_). Scopes: dealers:read, dealers:write, reviews:read, reviews:write, replies:write, cases:read, cases:write, cases:admin, invitations:write, verification:write, members:write, widgets:read, widgets:write, sync:write, webhooks:write."},"dealerKey":{"type":"http","scheme":"bearer","description":"Dealer key (prefix tmd_dealer_). Scoped to a single dealership."}}},"paths":{"/api/v1/dealers":{"get":{"tags":["Dealers"],"summary":"List dealerships","description":"Every dealership the key can see. A dealer key returns only its own dealership. Results are ordered by name.","operationId":"get_dealers","parameters":[{"name":"search","in":"query","required":false,"description":"Match on name, town or postcode.","schema":{"type":"string"},"example":"barnsley"},{"name":"claimed","in":"query","required":false,"description":"Filter to claimed or unclaimed dealerships.","schema":{"type":"boolean"}},{"name":"cursor","in":"query","required":false,"description":"Opaque cursor from the previous page's `next_cursor`.","schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"description":"Page size, 1–100. Defaults to 25.","schema":{"type":"integer"},"example":"50"}],"security":[{"partnerKey":["dealers:read"]},{"dealerKey":["dealers:read"]}],"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"data":[{"msai_dealer_id":"10031287","id":"b3f1c0e2-4f1a-4f1a-9c3d-2f1a4f1a9c3d","slug":"anycolourcar","name":"Any Colour Car","location":"Barnsley, South Yorkshire","website":"https://www.anycolourcar.com","phone":"+441226000000","logo_url":"https://cdn.trustmydealer.co.uk/logos/anycolourcar.png","description":"Independent used car specialist in South Yorkshire.","opening_hours":"Mon–Sat 9:00–18:00","claimed":true,"require_approval":false,"profile_url":"https://trustmydealer.co.uk/dealers/anycolourcar","created_at":"2026-02-11T09:14:22Z"}],"next_cursor":"cD0yMDI2LTA4LTE5","has_more":true}}}}}},"post":{"tags":["Dealers"],"summary":"Create a dealership","description":"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.","operationId":"post_dealers","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["msai_dealer_id","name"],"properties":{"msai_dealer_id":{"type":"string","description":"Canonical external identifier. Must be unique."},"name":{"type":"string","description":"Trading name as buyers would recognise it."},"slug":{"type":"string","description":"Profile URL segment. Generated from the name if omitted."},"location":{"type":"string","description":"Town and county."},"website":{"type":"string","description":"Public website URL."},"phone":{"type":"string","description":"Contact number in E.164 or national format."},"description":{"type":"string","description":"Short profile blurb."},"opening_hours":{"type":"string","description":"Free-text opening hours."},"logo_url":{"type":"string","description":"Absolute URL to a square logo."}},"additionalProperties":false}}}},"security":[{"partnerKey":["dealers:write"]}],"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"msai_dealer_id":"10031287","id":"b3f1c0e2-4f1a-4f1a-9c3d-2f1a4f1a9c3d","slug":"anycolourcar","name":"Any Colour Car","location":"Barnsley, South Yorkshire","website":"https://www.anycolourcar.com","phone":"+441226000000","logo_url":"https://cdn.trustmydealer.co.uk/logos/anycolourcar.png","description":"Independent used car specialist in South Yorkshire.","opening_hours":"Mon–Sat 9:00–18:00","claimed":true,"require_approval":false,"profile_url":"https://trustmydealer.co.uk/dealers/anycolourcar","created_at":"2026-02-11T09:14:22Z"}}}},"409":{"description":"That MSAI Dealer ID is already assigned to another dealership.","content":{"application/json":{"example":{"error":{"code":"msai_id_conflict","message":"That MSAI Dealer ID is already assigned to another dealership."}}}}},"422":{"description":"One or more fields failed validation. See the `fields` array.","content":{"application/json":{"example":{"error":{"code":"validation_failed","message":"One or more fields failed validation. See the `fields` array."}}}}}}}},"/api/v1/dealers/{msaiDealerId}":{"get":{"tags":["Dealers"],"summary":"Get a dealership","description":"The full profile record for one dealership.","operationId":"get_dealers_msaiDealerId_","parameters":[{"name":"msaiDealerId","in":"path","required":true,"description":"The dealership's MSAI Dealer ID — the same identifier used for their Google review source.","schema":{"type":"string"},"example":"10031287"}],"security":[{"partnerKey":["dealers:read"]},{"dealerKey":["dealers:read"]}],"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"msai_dealer_id":"10031287","id":"b3f1c0e2-4f1a-4f1a-9c3d-2f1a4f1a9c3d","slug":"anycolourcar","name":"Any Colour Car","location":"Barnsley, South Yorkshire","website":"https://www.anycolourcar.com","phone":"+441226000000","logo_url":"https://cdn.trustmydealer.co.uk/logos/anycolourcar.png","description":"Independent used car specialist in South Yorkshire.","opening_hours":"Mon–Sat 9:00–18:00","claimed":true,"require_approval":false,"profile_url":"https://trustmydealer.co.uk/dealers/anycolourcar","created_at":"2026-02-11T09:14:22Z"}}}},"404":{"description":"No dealership matches that MSAI Dealer ID.","content":{"application/json":{"example":{"error":{"code":"dealer_not_found","message":"No dealership matches that MSAI Dealer ID."}}}}}}},"patch":{"tags":["Dealers"],"summary":"Update a dealership","description":"Partial update. A dealer key may change profile presentation fields only — name, description, phone, website, opening hours and logo.","operationId":"patch_dealers_msaiDealerId_","parameters":[{"name":"msaiDealerId","in":"path","required":true,"description":"The dealership's MSAI Dealer ID — the same identifier used for their Google review source.","schema":{"type":"string"},"example":"10031287"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","required":[],"properties":{"name":{"type":"string","description":"Trading name."},"location":{"type":"string","description":"Town and county."},"website":{"type":"string","description":"Public website URL."},"phone":{"type":"string","description":"Contact number."},"description":{"type":"string","description":"Profile blurb."},"opening_hours":{"type":"string","description":"Opening hours."},"logo_url":{"type":"string","description":"Logo URL."},"require_approval":{"type":"boolean","description":"Hold new aggregated reviews for moderation. Partner key only."}},"additionalProperties":false}}}},"security":[{"partnerKey":["dealers:write"]},{"dealerKey":["dealers:write"]}],"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"msai_dealer_id":"10031287","id":"b3f1c0e2-4f1a-4f1a-9c3d-2f1a4f1a9c3d","slug":"anycolourcar","name":"Any Colour Car","location":"Barnsley, South Yorkshire","website":"https://www.anycolourcar.com","phone":"+441226000000","logo_url":"https://cdn.trustmydealer.co.uk/logos/anycolourcar.png","description":"Independent used car specialist in South Yorkshire.","opening_hours":"Mon–Sat 9:00–18:00","claimed":true,"require_approval":false,"profile_url":"https://trustmydealer.co.uk/dealers/anycolourcar","created_at":"2026-02-11T09:14:22Z"}}}},"404":{"description":"No dealership matches that MSAI Dealer ID.","content":{"application/json":{"example":{"error":{"code":"dealer_not_found","message":"No dealership matches that MSAI Dealer ID."}}}}},"422":{"description":"One or more fields failed validation. See the `fields` array.","content":{"application/json":{"example":{"error":{"code":"validation_failed","message":"One or more fields failed validation. See the `fields` array."}}}}}}},"delete":{"tags":["Dealers"],"summary":"Delete a dealership","description":"Removes the dealership, its sources, reviews and widgets. Irreversible, and refused while open resolution cases exist.","operationId":"delete_dealers_msaiDealerId_","parameters":[{"name":"msaiDealerId","in":"path","required":true,"description":"The dealership's MSAI Dealer ID — the same identifier used for their Google review source.","schema":{"type":"string"},"example":"10031287"}],"security":[{"partnerKey":["dealers:write"]}],"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"deleted":true,"msai_dealer_id":"10031287"}}}},"404":{"description":"No dealership matches that MSAI Dealer ID.","content":{"application/json":{"example":{"error":{"code":"dealer_not_found","message":"No dealership matches that MSAI Dealer ID."}}}}},"409":{"description":"The resolution case has ended and no longer accepts messages or actions.","content":{"application/json":{"example":{"error":{"code":"case_closed","message":"The resolution case has ended and no longer accepts messages or actions."}}}}}}}},"/api/v1/dealers/{msaiDealerId}/sources":{"get":{"tags":["Review sources"],"summary":"List sources","description":"Every connected source with its last sync outcome and platform-reported aggregate.","operationId":"get_dealers_msaiDealerId_sources","parameters":[{"name":"msaiDealerId","in":"path","required":true,"description":"The dealership's MSAI Dealer ID — the same identifier used for their Google review source.","schema":{"type":"string"},"example":"10031287"}],"security":[{"partnerKey":["dealers:read"]},{"dealerKey":["dealers:read"]}],"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"data":[{"id":"5a1b2c3d-0000-1111-2222-333344445555","source":"trustpilot","url":"https://www.trustpilot.com/review/anycolourcar.com","write_url":"https://www.trustpilot.com/evaluate/anycolourcar.com","enabled":true,"aggregate_rating":4.6,"aggregate_count":88,"last_synced_at":"2026-08-25T06:00:11Z","last_status":"ok","last_error":null,"last_review_count":88}]}}}}}},"post":{"tags":["Review sources"],"summary":"Add a source","description":"Connects a platform. For `google`, pass the MSAI Dealer ID as `url`. For every other platform, pass the dealer's public review page URL.","operationId":"post_dealers_msaiDealerId_sources","parameters":[{"name":"msaiDealerId","in":"path","required":true,"description":"The dealership's MSAI Dealer ID — the same identifier used for their Google review source.","schema":{"type":"string"},"example":"10031287"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["source","url"],"properties":{"source":{"type":"string","description":"One of the supported source keys."},"url":{"type":"string","description":"Review page URL, or the MSAI Dealer ID for `google`."},"write_url":{"type":"string","description":"Where customers should be sent to leave a review on that platform."},"enabled":{"type":"boolean","description":"Include in syncs and the combined score. Defaults to true."}},"additionalProperties":false}}}},"security":[{"partnerKey":["dealers:write"]}],"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"id":"5a1b2c3d-0000-1111-2222-333344445555","source":"trustpilot","enabled":true}}}},"404":{"description":"No dealership matches that MSAI Dealer ID.","content":{"application/json":{"example":{"error":{"code":"dealer_not_found","message":"No dealership matches that MSAI Dealer ID."}}}}},"422":{"description":"One or more fields failed validation. See the `fields` array.","content":{"application/json":{"example":{"error":{"code":"validation_failed","message":"One or more fields failed validation. See the `fields` array."}}}}}}}},"/api/v1/dealers/{msaiDealerId}/sources/{sourceId}":{"patch":{"tags":["Review sources"],"summary":"Update a source","description":"Change the URL, the write URL, or enable and disable the source.","operationId":"patch_dealers_msaiDealerId_sources_sourceId_","parameters":[{"name":"msaiDealerId","in":"path","required":true,"description":"The dealership's MSAI Dealer ID — the same identifier used for their Google review source.","schema":{"type":"string"},"example":"10031287"},{"name":"sourceId","in":"path","required":true,"description":"Source identifier from the list endpoint.","schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","required":[],"properties":{"url":{"type":"string","description":"Review page URL."},"write_url":{"type":"string","description":"Leave-a-review URL."},"enabled":{"type":"boolean","description":"Include in syncs and scoring."}},"additionalProperties":false}}}},"security":[{"partnerKey":["dealers:write"]},{"dealerKey":["dealers:write"]}],"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"id":"5a1b2c3d-0000-1111-2222-333344445555","enabled":false}}}},"404":{"description":"The review, case, invitation or member does not exist.","content":{"application/json":{"example":{"error":{"code":"resource_not_found","message":"The review, case, invitation or member does not exist."}}}}}}},"delete":{"tags":["Review sources"],"summary":"Remove a source","description":"Disconnects the platform and drops the reviews it contributed from the combined score.","operationId":"delete_dealers_msaiDealerId_sources_sourceId_","parameters":[{"name":"msaiDealerId","in":"path","required":true,"description":"The dealership's MSAI Dealer ID — the same identifier used for their Google review source.","schema":{"type":"string"},"example":"10031287"},{"name":"sourceId","in":"path","required":true,"description":"Source identifier.","schema":{"type":"string","format":"uuid"}}],"security":[{"partnerKey":["dealers:write"]}],"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"deleted":true}}}},"404":{"description":"The review, case, invitation or member does not exist.","content":{"application/json":{"example":{"error":{"code":"resource_not_found","message":"The review, case, invitation or member does not exist."}}}}}}}},"/api/v1/dealers/{msaiDealerId}/sync":{"post":{"tags":["Sync"],"summary":"Sync one dealership","description":"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.","operationId":"post_dealers_msaiDealerId_sync","parameters":[{"name":"msaiDealerId","in":"path","required":true,"description":"The dealership's MSAI Dealer ID — the same identifier used for their Google review source.","schema":{"type":"string"},"example":"10031287"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","required":[],"properties":{"sources":{"type":"array","items":{"type":"string"},"description":"Restrict the run to these source keys. Defaults to all enabled."}},"additionalProperties":false}}}},"security":[{"partnerKey":["sync:write"]},{"dealerKey":["sync:write"]}],"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"run_id":"9f8e7d6c-1234-5678-9abc-def012345678","status":"queued","queued_sources":["trustpilot","google"]}}}},"404":{"description":"No dealership matches that MSAI Dealer ID.","content":{"application/json":{"example":{"error":{"code":"dealer_not_found","message":"No dealership matches that MSAI Dealer ID."}}}}},"429":{"description":"Too many requests. Retry after the `Retry-After` header.","content":{"application/json":{"example":{"error":{"code":"rate_limited","message":"Too many requests. Retry after the `Retry-After` header."}}}}}}}},"/api/v1/sync":{"post":{"tags":["Sync"],"summary":"Sync every dealership","description":"Fleet-wide run, the same job the daily schedule triggers. Partner key only.","operationId":"post_sync","security":[{"partnerKey":["sync:write"]}],"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"run_id":"1111aaaa-2222-bbbb-3333-cccc4444dddd","status":"queued","dealers":148}}}}}}},"/api/v1/dealers/{msaiDealerId}/sync-runs":{"get":{"tags":["Sync"],"summary":"Sync history","description":"Recent runs for the dealership, newest first, with counts and any error text.","operationId":"get_dealers_msaiDealerId_sync_runs","parameters":[{"name":"msaiDealerId","in":"path","required":true,"description":"The dealership's MSAI Dealer ID — the same identifier used for their Google review source.","schema":{"type":"string"},"example":"10031287"},{"name":"cursor","in":"query","required":false,"description":"Opaque cursor from the previous page's `next_cursor`.","schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"description":"Page size, 1–100. Defaults to 25.","schema":{"type":"integer"},"example":"50"}],"security":[{"partnerKey":["sync:write"]},{"dealerKey":["sync:write"]}],"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"data":[{"id":"9f8e7d6c-1234-5678-9abc-def012345678","source":"trustpilot","status":"ok","found":88,"inserted":3,"updated":1,"error":null,"trigger":"api","started_at":"2026-08-25T06:00:02Z","finished_at":"2026-08-25T06:00:11Z"}],"next_cursor":"cD0yMDI2LTA4LTE5","has_more":true}}}}}}},"/api/v1/dealers/{msaiDealerId}/score":{"get":{"tags":["Scores"],"summary":"Get the combined score","description":"Headline score, total review count and the per-source breakdown that sits underneath it.","operationId":"get_dealers_msaiDealerId_score","parameters":[{"name":"msaiDealerId","in":"path","required":true,"description":"The dealership's MSAI Dealer ID — the same identifier used for their Google review source.","schema":{"type":"string"},"example":"10031287"}],"security":[{"partnerKey":["dealers:read"]},{"dealerKey":["dealers:read"]}],"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"msai_dealer_id":"10031287","score":4.7,"total":486,"updated_at":"2026-08-25T06:00:11Z","breakdown":[{"source":"trustmydealer","score":4.9,"count":41},{"source":"google","score":4.8,"count":302},{"source":"trustpilot","score":4.6,"count":88},{"source":"reviewsio","score":4.5,"count":55}]}}}},"404":{"description":"No dealership matches that MSAI Dealer ID.","content":{"application/json":{"example":{"error":{"code":"dealer_not_found","message":"No dealership matches that MSAI Dealer ID."}}}}}}}},"/api/v1/dealers/{msaiDealerId}/score/history":{"get":{"tags":["Scores"],"summary":"Score trend","description":"Daily score and cumulative review count over the requested window.","operationId":"get_dealers_msaiDealerId_score_history","parameters":[{"name":"msaiDealerId","in":"path","required":true,"description":"The dealership's MSAI Dealer ID — the same identifier used for their Google review source.","schema":{"type":"string"},"example":"10031287"},{"name":"days","in":"query","required":false,"description":"30, 90 or 365. Defaults to 90.","schema":{"type":"integer"},"example":"90"}],"security":[{"partnerKey":["dealers:read"]},{"dealerKey":["dealers:read"]}],"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"days":90,"series":[{"date":"2026-08-24","score":4.69,"total":484},{"date":"2026-08-25","score":4.7,"total":486}]}}}}}}},"/api/v1/dealers/{msaiDealerId}/reviews":{"get":{"tags":["Reviews"],"summary":"List reviews","description":"Newest first by review date, with cursor pagination.","operationId":"get_dealers_msaiDealerId_reviews","parameters":[{"name":"msaiDealerId","in":"path","required":true,"description":"The dealership's MSAI Dealer ID — the same identifier used for their Google review source.","schema":{"type":"string"},"example":"10031287"},{"name":"type","in":"query","required":false,"description":"`direct`, `aggregated` or `all`. Defaults to all.","schema":{"type":"string"}},{"name":"source","in":"query","required":false,"description":"Filter to one source key.","schema":{"type":"string"}},{"name":"status","in":"query","required":false,"description":"`published`, `pending`, `hidden`, `in_resolution`. Partner key may query non-public states.","schema":{"type":"string"}},{"name":"min_rating","in":"query","required":false,"description":"Lowest rating to include.","schema":{"type":"number"},"example":"4"},{"name":"max_rating","in":"query","required":false,"description":"Highest rating to include.","schema":{"type":"number"}},{"name":"since","in":"query","required":false,"description":"ISO date. Only reviews on or after this date.","schema":{"type":"string","format":"date"},"example":"2026-01-01"},{"name":"has_reply","in":"query","required":false,"description":"Filter to reviews with or without a dealer reply.","schema":{"type":"boolean"}},{"name":"cursor","in":"query","required":false,"description":"Opaque cursor from the previous page's `next_cursor`.","schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"description":"Page size, 1–100. Defaults to 25.","schema":{"type":"integer"},"example":"50"}],"security":[{"partnerKey":["reviews:read"]},{"dealerKey":["reviews:read"]}],"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"data":[{"id":"7c1e0f22-9a4b-4f10-8d2e-1a2b3c4d5e6f","type":"direct","source":"trustmydealer","rating":5,"title":"Straightforward from start to finish","body":"Car was exactly as described and the paperwork took ten minutes.","author":"Rachel M.","review_date":"2026-08-19","status":"published","verified_purchase":true,"vehicle":"2019 Ford Focus ST-Line","source_url":null,"reply":{"id":"1d2e3f40-1111-2222-3333-444455556666","body":"Thanks Rachel — enjoy the Focus.","created_at":"2026-08-20T10:02:00Z"}}],"next_cursor":"cD0yMDI2LTA4LTE5","has_more":true}}}}}}},"/api/v1/dealers/{msaiDealerId}/reviews/{reviewId}":{"get":{"tags":["Reviews"],"summary":"Get a review","description":"One review with its reply and, for direct reviews, its verification and case state.","operationId":"get_dealers_msaiDealerId_reviews_reviewId_","parameters":[{"name":"msaiDealerId","in":"path","required":true,"description":"The dealership's MSAI Dealer ID — the same identifier used for their Google review source.","schema":{"type":"string"},"example":"10031287"},{"name":"reviewId","in":"path","required":true,"description":"Review identifier.","schema":{"type":"string","format":"uuid"}}],"security":[{"partnerKey":["reviews:read"]},{"dealerKey":["reviews:read"]}],"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"id":"7c1e0f22-9a4b-4f10-8d2e-1a2b3c4d5e6f","type":"direct","source":"trustmydealer","rating":5,"title":"Straightforward from start to finish","body":"Car was exactly as described and the paperwork took ten minutes.","author":"Rachel M.","review_date":"2026-08-19","status":"published","verified_purchase":true,"vehicle":"2019 Ford Focus ST-Line","source_url":null,"reply":{"id":"1d2e3f40-1111-2222-3333-444455556666","body":"Thanks Rachel — enjoy the Focus.","created_at":"2026-08-20T10:02:00Z"}}}}},"404":{"description":"The review, case, invitation or member does not exist.","content":{"application/json":{"example":{"error":{"code":"resource_not_found","message":"The review, case, invitation or member does not exist."}}}}}}}},"/api/v1/dealers/{msaiDealerId}/reviews/{reviewId}/moderate":{"post":{"tags":["Reviews"],"summary":"Moderate a review","description":"Arbitration action. Dealers can never hide or remove a review — this endpoint rejects dealer keys outright, and the UI says so plainly.","operationId":"post_dealers_msaiDealerId_reviews_reviewId_moderate","parameters":[{"name":"msaiDealerId","in":"path","required":true,"description":"The dealership's MSAI Dealer ID — the same identifier used for their Google review source.","schema":{"type":"string"},"example":"10031287"},{"name":"reviewId","in":"path","required":true,"description":"Review identifier.","schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["action","reason"],"properties":{"action":{"type":"string","description":"`hide`, `restore`, `flag` or `remove`."},"reason":{"type":"string","description":"Recorded on the audit trail and shown to admins."}},"additionalProperties":false}}}},"security":[{"partnerKey":["reviews:write"]}],"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"id":"7c1e0f22-9a4b-4f10-8d2e-1a2b3c4d5e6f","status":"hidden","moderated_at":"2026-08-25T09:10:00Z"}}}},"403":{"description":"The key is valid but lacks the scope this endpoint needs.","content":{"application/json":{"example":{"error":{"code":"forbidden_scope","message":"The key is valid but lacks the scope this endpoint needs."}}}}},"404":{"description":"The review, case, invitation or member does not exist.","content":{"application/json":{"example":{"error":{"code":"resource_not_found","message":"The review, case, invitation or member does not exist."}}}}},"422":{"description":"One or more fields failed validation. See the `fields` array.","content":{"application/json":{"example":{"error":{"code":"validation_failed","message":"One or more fields failed validation. See the `fields` array."}}}}}}}},"/api/v1/dealers/{msaiDealerId}/reviews/{reviewId}/reply":{"post":{"tags":["Replies"],"summary":"Publish a reply","description":"Creates the dealer's public response. Returns 409 if a reply already exists.","operationId":"post_dealers_msaiDealerId_reviews_reviewId_reply","parameters":[{"name":"msaiDealerId","in":"path","required":true,"description":"The dealership's MSAI Dealer ID — the same identifier used for their Google review source.","schema":{"type":"string"},"example":"10031287"},{"name":"reviewId","in":"path","required":true,"description":"Review identifier.","schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["body"],"properties":{"body":{"type":"string","description":"Reply text, 10–2000 characters."}},"additionalProperties":false}}}},"security":[{"partnerKey":["replies:write"]},{"dealerKey":["replies:write"]}],"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"id":"1d2e3f40-1111-2222-3333-444455556666","body":"Thanks Rachel — enjoy the Focus.","created_at":"2026-08-20T10:02:00Z"}}}},"404":{"description":"The review, case, invitation or member does not exist.","content":{"application/json":{"example":{"error":{"code":"resource_not_found","message":"The review, case, invitation or member does not exist."}}}}},"409":{"description":"A review may carry only one dealer reply. Use PATCH to change it.","content":{"application/json":{"example":{"error":{"code":"already_replied","message":"A review may carry only one dealer reply. Use PATCH to change it."}}}}},"422":{"description":"One or more fields failed validation. See the `fields` array.","content":{"application/json":{"example":{"error":{"code":"validation_failed","message":"One or more fields failed validation. See the `fields` array."}}}}}}},"patch":{"tags":["Replies"],"summary":"Edit a reply","description":"Replaces the reply text. Edits are timestamped and kept in the audit trail.","operationId":"patch_dealers_msaiDealerId_reviews_reviewId_reply","parameters":[{"name":"msaiDealerId","in":"path","required":true,"description":"The dealership's MSAI Dealer ID — the same identifier used for their Google review source.","schema":{"type":"string"},"example":"10031287"},{"name":"reviewId","in":"path","required":true,"description":"Review identifier.","schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["body"],"properties":{"body":{"type":"string","description":"New reply text."}},"additionalProperties":false}}}},"security":[{"partnerKey":["replies:write"]},{"dealerKey":["replies:write"]}],"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"id":"1d2e3f40-1111-2222-3333-444455556666","updated_at":"2026-08-21T08:00:00Z"}}}},"404":{"description":"The review, case, invitation or member does not exist.","content":{"application/json":{"example":{"error":{"code":"resource_not_found","message":"The review, case, invitation or member does not exist."}}}}}}},"delete":{"tags":["Replies"],"summary":"Delete a reply","description":"Removes the public response. The review itself is untouched.","operationId":"delete_dealers_msaiDealerId_reviews_reviewId_reply","parameters":[{"name":"msaiDealerId","in":"path","required":true,"description":"The dealership's MSAI Dealer ID — the same identifier used for their Google review source.","schema":{"type":"string"},"example":"10031287"},{"name":"reviewId","in":"path","required":true,"description":"Review identifier.","schema":{"type":"string","format":"uuid"}}],"security":[{"partnerKey":["replies:write"]},{"dealerKey":["replies:write"]}],"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"deleted":true}}}},"404":{"description":"The review, case, invitation or member does not exist.","content":{"application/json":{"example":{"error":{"code":"resource_not_found","message":"The review, case, invitation or member does not exist."}}}}}}}},"/api/v1/dealers/{msaiDealerId}/cases":{"get":{"tags":["Resolution cases"],"summary":"List cases","description":"Open cases first, sorted by time remaining.","operationId":"get_dealers_msaiDealerId_cases","parameters":[{"name":"msaiDealerId","in":"path","required":true,"description":"The dealership's MSAI Dealer ID — the same identifier used for their Google review source.","schema":{"type":"string"},"example":"10031287"},{"name":"state","in":"query","required":false,"description":"`open`, `escalated`, `resolved` or `closed`.","schema":{"type":"string"}},{"name":"cursor","in":"query","required":false,"description":"Opaque cursor from the previous page's `next_cursor`.","schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"description":"Page size, 1–100. Defaults to 25.","schema":{"type":"integer"},"example":"50"}],"security":[{"partnerKey":["cases:read"]},{"dealerKey":["cases:read"]}],"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"data":[{"id":"cc11dd22-3344-5566-7788-99aabbccddee","state":"open","deadline":"2026-08-30T12:00:00Z","hours_remaining":74,"escalated":false,"extended":false,"review":{"id":"7c1e0f22-9a4b-4f10-8d2e-1a2b3c4d5e6f","rating":2,"title":"Delay on the V5","status":"in_resolution"},"unread_messages":1}],"next_cursor":"cD0yMDI2LTA4LTE5","has_more":true}}}}}}},"/api/v1/dealers/{msaiDealerId}/cases/{caseId}":{"get":{"tags":["Resolution cases"],"summary":"Get a case","description":"The case, the held review, the full private message thread and the immutable event timeline.","operationId":"get_dealers_msaiDealerId_cases_caseId_","parameters":[{"name":"msaiDealerId","in":"path","required":true,"description":"The dealership's MSAI Dealer ID — the same identifier used for their Google review source.","schema":{"type":"string"},"example":"10031287"},{"name":"caseId","in":"path","required":true,"description":"Case identifier.","schema":{"type":"string","format":"uuid"}}],"security":[{"partnerKey":["cases:read"]},{"dealerKey":["cases:read"]}],"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"id":"cc11dd22-3344-5566-7788-99aabbccddee","state":"open","deadline":"2026-08-30T12:00:00Z","review":{"id":"7c1e0f22-9a4b-4f10-8d2e-1a2b3c4d5e6f","rating":2,"body":"Waited three weeks for the V5."},"messages":[{"id":"m1","author_side":"dealer","body":"Apologies — DVLA delay. Chasing today.","created_at":"2026-08-24T11:00:00Z"}],"timeline":[{"event_type":"case_opened","actor_side":"system","created_at":"2026-08-23T12:00:00Z"},{"event_type":"message_sent","actor_side":"dealer","created_at":"2026-08-24T11:00:00Z"}]}}}},"404":{"description":"The review, case, invitation or member does not exist.","content":{"application/json":{"example":{"error":{"code":"resource_not_found","message":"The review, case, invitation or member does not exist."}}}}}}}},"/api/v1/dealers/{msaiDealerId}/cases/{caseId}/messages":{"post":{"tags":["Resolution cases"],"summary":"Post a message","description":"Adds to the private thread and notifies the other side by email. Reviewer email addresses are never exposed to a dealer key.","operationId":"post_dealers_msaiDealerId_cases_caseId_messages","parameters":[{"name":"msaiDealerId","in":"path","required":true,"description":"The dealership's MSAI Dealer ID — the same identifier used for their Google review source.","schema":{"type":"string"},"example":"10031287"},{"name":"caseId","in":"path","required":true,"description":"Case identifier.","schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["body"],"properties":{"body":{"type":"string","description":"Message text, 5–4000 characters."}},"additionalProperties":false}}}},"security":[{"partnerKey":["cases:write"]},{"dealerKey":["cases:write"]}],"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"id":"m2","created_at":"2026-08-25T09:20:00Z"}}}},"404":{"description":"The review, case, invitation or member does not exist.","content":{"application/json":{"example":{"error":{"code":"resource_not_found","message":"The review, case, invitation or member does not exist."}}}}},"409":{"description":"The resolution case has ended and no longer accepts messages or actions.","content":{"application/json":{"example":{"error":{"code":"case_closed","message":"The resolution case has ended and no longer accepts messages or actions."}}}}}}}},"/api/v1/dealers/{msaiDealerId}/cases/{caseId}/offer":{"post":{"tags":["Resolution cases"],"summary":"Send a resolution offer","description":"Records a concrete offer on the timeline. The reviewer is always free to decline — an offer can never require withdrawal.","operationId":"post_dealers_msaiDealerId_cases_caseId_offer","parameters":[{"name":"msaiDealerId","in":"path","required":true,"description":"The dealership's MSAI Dealer ID — the same identifier used for their Google review source.","schema":{"type":"string"},"example":"10031287"},{"name":"caseId","in":"path","required":true,"description":"Case identifier.","schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["summary"],"properties":{"summary":{"type":"string","description":"What is being offered, in plain English."},"message":{"type":"string","description":"Optional accompanying note."}},"additionalProperties":false}}}},"security":[{"partnerKey":["cases:write"]},{"dealerKey":["cases:write"]}],"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"id":"cc11dd22-3344-5566-7788-99aabbccddee","state":"open","offer_sent_at":"2026-08-25T09:22:00Z"}}}},"409":{"description":"The resolution case has ended and no longer accepts messages or actions.","content":{"application/json":{"example":{"error":{"code":"case_closed","message":"The resolution case has ended and no longer accepts messages or actions."}}}}}}}},"/api/v1/dealers/{msaiDealerId}/cases/{caseId}/escalate":{"post":{"tags":["Resolution cases"],"summary":"Escalate to arbitration","description":"Flags the case for a trustmydealer administrator. Either side may escalate once.","operationId":"post_dealers_msaiDealerId_cases_caseId_escalate","parameters":[{"name":"msaiDealerId","in":"path","required":true,"description":"The dealership's MSAI Dealer ID — the same identifier used for their Google review source.","schema":{"type":"string"},"example":"10031287"},{"name":"caseId","in":"path","required":true,"description":"Case identifier.","schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["reason"],"properties":{"reason":{"type":"string","description":"Why arbitration is needed."}},"additionalProperties":false}}}},"security":[{"partnerKey":["cases:write"]},{"dealerKey":["cases:write"]}],"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"id":"cc11dd22-3344-5566-7788-99aabbccddee","state":"escalated","escalated":true}}}},"409":{"description":"The resolution case has ended and no longer accepts messages or actions.","content":{"application/json":{"example":{"error":{"code":"case_closed","message":"The resolution case has ended and no longer accepts messages or actions."}}}}}}}},"/api/v1/dealers/{msaiDealerId}/cases/{caseId}/resolve":{"post":{"tags":["Resolution cases"],"summary":"Arbitrate a case","description":"Administrator decision: publish the held review immediately, remove it for a policy breach, or grant the single permitted seven-day extension.","operationId":"post_dealers_msaiDealerId_cases_caseId_resolve","parameters":[{"name":"msaiDealerId","in":"path","required":true,"description":"The dealership's MSAI Dealer ID — the same identifier used for their Google review source.","schema":{"type":"string"},"example":"10031287"},{"name":"caseId","in":"path","required":true,"description":"Case identifier.","schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["action","note"],"properties":{"action":{"type":"string","description":"`publish`, `remove` or `extend`."},"note":{"type":"string","description":"Reasoning, written to the timeline."}},"additionalProperties":false}}}},"security":[{"partnerKey":["cases:admin"]}],"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"id":"cc11dd22-3344-5566-7788-99aabbccddee","state":"resolved","outcome":"published"}}}},"403":{"description":"The key is valid but lacks the scope this endpoint needs.","content":{"application/json":{"example":{"error":{"code":"forbidden_scope","message":"The key is valid but lacks the scope this endpoint needs."}}}}},"409":{"description":"The resolution case has ended and no longer accepts messages or actions.","content":{"application/json":{"example":{"error":{"code":"case_closed","message":"The resolution case has ended and no longer accepts messages or actions."}}}}}}}},"/api/v1/dealers/{msaiDealerId}/invitations":{"post":{"tags":["Review collection"],"summary":"Send a review request","description":"Sends one request immediately, or schedules it for `delay_days` after the handover date. Send `Idempotency-Key` to make retries safe.","operationId":"post_dealers_msaiDealerId_invitations","parameters":[{"name":"msaiDealerId","in":"path","required":true,"description":"The dealership's MSAI Dealer ID — the same identifier used for their Google review source.","schema":{"type":"string"},"example":"10031287"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["channel"],"properties":{"channel":{"type":"string","description":"`email` or `sms`."},"customer_email":{"type":"string","description":"Required when channel is `email`."},"customer_phone":{"type":"string","description":"Required when channel is `sms`."},"customer_name":{"type":"string","description":"Used to personalise the message."},"vehicle":{"type":"string","description":"Vehicle description shown in the request."},"destination":{"type":"string","description":"`trustmydealer` or an external source key such as `google`."},"delay_days":{"type":"integer","description":"Delay before sending. Defaults to the dealership's invite settings."}},"additionalProperties":false}}}},"security":[{"partnerKey":["invitations:write"]},{"dealerKey":["invitations:write"]}],"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"id":"aa11bb22-cc33-dd44-ee55-ff6677889900","code":"K7QX2M","status":"queued","channel":"email","review_url":"https://trustmydealer.co.uk/r/K7QX2M"}}}},"422":{"description":"One or more fields failed validation. See the `fields` array.","content":{"application/json":{"example":{"error":{"code":"validation_failed","message":"One or more fields failed validation. See the `fields` array."}}}}}}},"get":{"tags":["Review collection"],"summary":"List requests","description":"Delivery and response state for every request sent.","operationId":"get_dealers_msaiDealerId_invitations","parameters":[{"name":"msaiDealerId","in":"path","required":true,"description":"The dealership's MSAI Dealer ID — the same identifier used for their Google review source.","schema":{"type":"string"},"example":"10031287"},{"name":"status","in":"query","required":false,"description":"`queued`, `sent`, `opened`, `completed`, `bounced`, `unsubscribed`.","schema":{"type":"string"}},{"name":"cursor","in":"query","required":false,"description":"Opaque cursor from the previous page's `next_cursor`.","schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"description":"Page size, 1–100. Defaults to 25.","schema":{"type":"integer"},"example":"50"}],"security":[{"partnerKey":["invitations:write"]},{"dealerKey":["invitations:write"]}],"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"data":[{"id":"aa11bb22-cc33-dd44-ee55-ff6677889900","code":"K7QX2M","channel":"email","status":"completed","sent_at":"2026-08-18T09:00:00Z","opened_at":"2026-08-18T12:41:00Z","completed_review_id":"7c1e0f22-9a4b-4f10-8d2e-1a2b3c4d5e6f","reminder_count":1}],"next_cursor":"cD0yMDI2LTA4LTE5","has_more":true}}}}}}},"/api/v1/dealers/{msaiDealerId}/invitations/bulk":{"post":{"tags":["Review collection"],"summary":"Bulk send","description":"Up to 500 requests in one call. Each row is validated independently; valid rows send even if others fail.","operationId":"post_dealers_msaiDealerId_invitations_bulk","parameters":[{"name":"msaiDealerId","in":"path","required":true,"description":"The dealership's MSAI Dealer ID — the same identifier used for their Google review source.","schema":{"type":"string"},"example":"10031287"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["invitations"],"properties":{"invitations":{"type":"array","items":{"type":"object","additionalProperties":true},"description":"Array of request objects in the shape above."}},"additionalProperties":false}}}},"security":[{"partnerKey":["invitations:write"]},{"dealerKey":["invitations:write"]}],"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"accepted":498,"rejected":2,"errors":[{"index":12,"code":"validation_failed","field":"customer_email"}]}}}}}}},"/api/v1/dealers/{msaiDealerId}/campaigns":{"get":{"tags":["Review collection"],"summary":"List campaigns","description":"Standing campaigns with their schedule, reminder rules and response rate.","operationId":"get_dealers_msaiDealerId_campaigns","parameters":[{"name":"msaiDealerId","in":"path","required":true,"description":"The dealership's MSAI Dealer ID — the same identifier used for their Google review source.","schema":{"type":"string"},"example":"10031287"}],"security":[{"partnerKey":["invitations:write"]},{"dealerKey":["invitations:write"]}],"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"data":[{"id":"camp-1","name":"Post-handover email","channel":"email","destination":"trustmydealer","schedule_delay_days":3,"reminder_interval_days":5,"max_reminders":1,"status":"active","stats":{"sent":412,"opened":268,"completed":96,"response_rate":0.233}}]}}}}}},"post":{"tags":["Review collection"],"summary":"Create a campaign","description":"Defines the message, timing and reminder policy applied to future requests.","operationId":"post_dealers_msaiDealerId_campaigns","parameters":[{"name":"msaiDealerId","in":"path","required":true,"description":"The dealership's MSAI Dealer ID — the same identifier used for their Google review source.","schema":{"type":"string"},"example":"10031287"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name","channel","destination"],"properties":{"name":{"type":"string","description":"Internal label."},"channel":{"type":"string","description":"`email` or `sms`."},"destination":{"type":"string","description":"Where the customer is sent to review."},"schedule_delay_days":{"type":"integer","description":"Days after the handover before the first send."},"reminder_interval_days":{"type":"integer","description":"Gap between reminders."},"max_reminders":{"type":"integer","description":"Reminder cap, 0–3."},"message_subject":{"type":"string","description":"Email subject line."},"message_body":{"type":"string","description":"Message body."}},"additionalProperties":false}}}},"security":[{"partnerKey":["invitations:write"]},{"dealerKey":["invitations:write"]}],"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"id":"camp-2","status":"active"}}}}}}},"/api/v1/dealers/{msaiDealerId}/invite-settings":{"get":{"tags":["Review collection"],"summary":"Get collection settings","description":"Default channel, destination, timing, sender name and message templates.","operationId":"get_dealers_msaiDealerId_invite_settings","parameters":[{"name":"msaiDealerId","in":"path","required":true,"description":"The dealership's MSAI Dealer ID — the same identifier used for their Google review source.","schema":{"type":"string"},"example":"10031287"}],"security":[{"partnerKey":["invitations:write"]},{"dealerKey":["invitations:write"]}],"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"default_channel":"email","default_destination":"trustmydealer","request_delay_days":3,"max_reminders":1,"reminder_interval_days":5,"send_from_name":"Any Colour Car","email_subject_line":"How did we do?","sms_body":"Thanks for buying with us — leave a review: {link}"}}}}}},"patch":{"tags":["Review collection"],"summary":"Update collection settings","description":"Partial update of the same fields.","operationId":"patch_dealers_msaiDealerId_invite_settings","parameters":[{"name":"msaiDealerId","in":"path","required":true,"description":"The dealership's MSAI Dealer ID — the same identifier used for their Google review source.","schema":{"type":"string"},"example":"10031287"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","required":[],"properties":{"default_channel":{"type":"string","description":"`email` or `sms`."},"default_destination":{"type":"string","description":"Default review destination."},"request_delay_days":{"type":"integer","description":"Default send delay."},"max_reminders":{"type":"integer","description":"Reminder cap."},"reminder_interval_days":{"type":"integer","description":"Reminder gap."},"send_from_name":{"type":"string","description":"Sender name shown to customers."},"email_subject_line":{"type":"string","description":"Default subject."},"sms_body":{"type":"string","description":"Default SMS text, must contain {link}."}},"additionalProperties":false}}}},"security":[{"partnerKey":["invitations:write"]},{"dealerKey":["invitations:write"]}],"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"updated":true}}}}}}},"/api/v1/dealers/{msaiDealerId}/kiosk-codes":{"post":{"tags":["Review collection"],"summary":"Mint a kiosk code","description":"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.","operationId":"post_dealers_msaiDealerId_kiosk_codes","parameters":[{"name":"msaiDealerId","in":"path","required":true,"description":"The dealership's MSAI Dealer ID — the same identifier used for their Google review source.","schema":{"type":"string"},"example":"10031287"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","required":[],"properties":{"label":{"type":"string","description":"Where the code lives, e.g. “Handover desk”."}},"additionalProperties":false}}}},"security":[{"partnerKey":["invitations:write"]},{"dealerKey":["invitations:write"]}],"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"code":"TMD4KQ","kiosk_url":"https://trustmydealer.co.uk/kiosk/TMD4KQ","qr_png_url":"https://trustmydealer.co.uk/api/public/qr/TMD4KQ","short_url":"https://trustmydealer.co.uk/r/TMD4KQ"}}}}}}},"/api/v1/verification/queue":{"get":{"tags":["Purchase verification"],"summary":"List proofs awaiting review","description":"Uncertain proofs across every dealership, oldest first.","operationId":"get_verification_queue","parameters":[{"name":"msai_dealer_id","in":"query","required":false,"description":"Restrict to one dealership.","schema":{"type":"string"}},{"name":"cursor","in":"query","required":false,"description":"Opaque cursor from the previous page's `next_cursor`.","schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"description":"Page size, 1–100. Defaults to 25.","schema":{"type":"integer"},"example":"50"}],"security":[{"partnerKey":["verification:write"]}],"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"data":[{"id":"pf-1","msai_dealer_id":"10031287","review_id":"7c1e0f22-9a4b-4f10-8d2e-1a2b3c4d5e6f","verdict":"uncertain","confidence":0.61,"reason":"Dealer name legible, purchase date unreadable.","created_at":"2026-08-24T15:00:00Z"}],"next_cursor":"cD0yMDI2LTA4LTE5","has_more":true}}}}}}},"/api/v1/verification/{proofId}":{"post":{"tags":["Purchase verification"],"summary":"Decide a proof","description":"Applies or refuses the verified-purchase mark and records the override against the administrator.","operationId":"post_verification_proofId_","parameters":[{"name":"proofId","in":"path","required":true,"description":"Proof identifier.","schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["verdict"],"properties":{"verdict":{"type":"string","description":"`verified` or `rejected`."},"reason":{"type":"string","description":"Note kept on the record."}},"additionalProperties":false}}}},"security":[{"partnerKey":["verification:write"]}],"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"id":"pf-1","verdict":"verified","admin_override":true}}}},"404":{"description":"The review, case, invitation or member does not exist.","content":{"application/json":{"example":{"error":{"code":"resource_not_found","message":"The review, case, invitation or member does not exist."}}}}}}}},"/api/v1/dealers/{msaiDealerId}/members":{"get":{"tags":["Dealer accounts"],"summary":"List members","description":"Everyone with access to that dealership's portal, plus outstanding invites.","operationId":"get_dealers_msaiDealerId_members","parameters":[{"name":"msaiDealerId","in":"path","required":true,"description":"The dealership's MSAI Dealer ID — the same identifier used for their Google review source.","schema":{"type":"string"},"example":"10031287"}],"security":[{"partnerKey":["members:write"]}],"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"data":[{"id":"mem-1","email":"jonathan@anycolourcar.com","role":"owner","status":"active","created_at":"2026-06-01T10:00:00Z"}],"pending_invites":[{"email":"sales@anycolourcar.com","expires_at":"2026-08-28T10:00:00Z"}]}}}}}},"post":{"tags":["Dealer accounts"],"summary":"Invite a member","description":"Creates the login if needed and sends the branded set-password email.","operationId":"post_dealers_msaiDealerId_members","parameters":[{"name":"msaiDealerId","in":"path","required":true,"description":"The dealership's MSAI Dealer ID — the same identifier used for their Google review source.","schema":{"type":"string"},"example":"10031287"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["email"],"properties":{"email":{"type":"string","description":"Where the invite is sent."},"role":{"type":"string","description":"`owner` or `staff`. Defaults to staff."}},"additionalProperties":false}}}},"security":[{"partnerKey":["members:write"]}],"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"email":"sales@anycolourcar.com","status":"invited","expires_at":"2026-08-28T10:00:00Z"}}}},"422":{"description":"One or more fields failed validation. See the `fields` array.","content":{"application/json":{"example":{"error":{"code":"validation_failed","message":"One or more fields failed validation. See the `fields` array."}}}}}}}},"/api/v1/dealers/{msaiDealerId}/members/{memberId}/resend":{"post":{"tags":["Dealer accounts"],"summary":"Resend an invite","description":"Issues a fresh token and invalidates the previous one.","operationId":"post_dealers_msaiDealerId_members_memberId_resend","parameters":[{"name":"msaiDealerId","in":"path","required":true,"description":"The dealership's MSAI Dealer ID — the same identifier used for their Google review source.","schema":{"type":"string"},"example":"10031287"},{"name":"memberId","in":"path","required":true,"description":"Member identifier.","schema":{"type":"string","format":"uuid"}}],"security":[{"partnerKey":["members:write"]}],"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"resent":true,"expires_at":"2026-08-31T10:00:00Z"}}}}}}},"/api/v1/dealers/{msaiDealerId}/members/{memberId}":{"patch":{"tags":["Dealer accounts"],"summary":"Change a role","description":"Promotes or demotes a member between owner and staff.","operationId":"patch_dealers_msaiDealerId_members_memberId_","parameters":[{"name":"msaiDealerId","in":"path","required":true,"description":"The dealership's MSAI Dealer ID — the same identifier used for their Google review source.","schema":{"type":"string"},"example":"10031287"},{"name":"memberId","in":"path","required":true,"description":"Member identifier.","schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["role"],"properties":{"role":{"type":"string","description":"`owner` or `staff`."}},"additionalProperties":false}}}},"security":[{"partnerKey":["members:write"]}],"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"id":"mem-1","role":"staff"}}}}}},"delete":{"tags":["Dealer accounts"],"summary":"Remove a member","description":"Revokes portal access immediately. The user account itself is untouched.","operationId":"delete_dealers_msaiDealerId_members_memberId_","parameters":[{"name":"msaiDealerId","in":"path","required":true,"description":"The dealership's MSAI Dealer ID — the same identifier used for their Google review source.","schema":{"type":"string"},"example":"10031287"},{"name":"memberId","in":"path","required":true,"description":"Member identifier.","schema":{"type":"string","format":"uuid"}}],"security":[{"partnerKey":["members:write"]}],"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"deleted":true}}}}}}},"/api/v1/dealers/{msaiDealerId}/widgets":{"get":{"tags":["Widgets"],"summary":"List every available widget","description":"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.","operationId":"get_dealers_msaiDealerId_widgets","parameters":[{"name":"msaiDealerId","in":"path","required":true,"description":"The dealership's MSAI Dealer ID — the same identifier used for their Google review source.","schema":{"type":"string"},"example":"10031287"},{"name":"theme","in":"query","required":false,"description":"`light` or `dark`. Defaults to the dealership's saved theme.","schema":{"type":"string"}}],"security":[{"partnerKey":["widgets:read"]},{"dealerKey":["widgets:read"]}],"responses":{"200":{"description":"Badge variants: standard, compact, seal. Review widget variants: summary, strip, wall, quote.","content":{"application/json":{"example":{"msai_dealer_id":"10031287","slug":"anycolourcar","theme":"light","widgets":[{"kind":"badge","variant":"standard","name":"Standard badge","description":"Header, footer or contact page.","embed_html":"<div class=\"tmd-badge\" data-dealer=\"anycolourcar\" data-variant=\"standard\" data-theme=\"light\"></div>\n<script src=\"https://trustmydealer.co.uk/api/public/badge.js\" async></script>","script_url":"https://trustmydealer.co.uk/api/public/badge.js","iframe_html":"<iframe src=\"https://trustmydealer.co.uk/widget/anycolourcar\" title=\"Customer reviews\" style=\"width:100%;border:0;height:360px\" loading=\"lazy\"></iframe>","preview_url":"https://trustmydealer.co.uk/widget/anycolourcar?variant=standard&theme=light","recommended_height":96},{"kind":"reviews","variant":"wall","name":"Review wall","description":"Grid of reviews for a dedicated page.","embed_html":"<div class=\"tmd-reviews\" data-dealer=\"anycolourcar\" data-widget=\"wall\" data-theme=\"light\"></div>\n<script src=\"https://trustmydealer.co.uk/api/public/reviews.js\" async></script>","script_url":"https://trustmydealer.co.uk/api/public/reviews.js","iframe_html":"<iframe src=\"https://trustmydealer.co.uk/widget/anycolourcar\" title=\"Customer reviews\" style=\"width:100%;border:0;height:640px\" loading=\"lazy\"></iframe>","preview_url":"https://trustmydealer.co.uk/widget/anycolourcar?variant=wall&theme=light","recommended_height":640}]}}}},"404":{"description":"No dealership matches that MSAI Dealer ID.","content":{"application/json":{"example":{"error":{"code":"dealer_not_found","message":"No dealership matches that MSAI Dealer ID."}}}}}}}},"/api/v1/dealers/{msaiDealerId}/widgets/badge":{"get":{"tags":["Widgets"],"summary":"Get one badge embed","description":"The embed payload for a single badge variant and theme.","operationId":"get_dealers_msaiDealerId_widgets_badge","parameters":[{"name":"msaiDealerId","in":"path","required":true,"description":"The dealership's MSAI Dealer ID — the same identifier used for their Google review source.","schema":{"type":"string"},"example":"10031287"},{"name":"variant","in":"query","required":false,"description":"`standard`, `compact` or `seal`.","schema":{"type":"string"},"example":"seal"},{"name":"theme","in":"query","required":false,"description":"`light` or `dark`.","schema":{"type":"string"}}],"security":[{"partnerKey":["widgets:read"]},{"dealerKey":["widgets:read"]}],"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"kind":"badge","variant":"seal","embed_html":"<div class=\"tmd-badge\" data-dealer=\"anycolourcar\" data-variant=\"seal\" data-theme=\"dark\"></div>\n<script src=\"https://trustmydealer.co.uk/api/public/badge.js\" async></script>","script_url":"https://trustmydealer.co.uk/api/public/badge.js","preview_url":"https://trustmydealer.co.uk/widget/anycolourcar?variant=seal&theme=dark"}}}}}}},"/api/v1/dealers/{msaiDealerId}/widgets/reviews":{"get":{"tags":["Widgets"],"summary":"Get one review widget embed","description":"The embed payload for a single review widget variant and theme.","operationId":"get_dealers_msaiDealerId_widgets_reviews","parameters":[{"name":"msaiDealerId","in":"path","required":true,"description":"The dealership's MSAI Dealer ID — the same identifier used for their Google review source.","schema":{"type":"string"},"example":"10031287"},{"name":"variant","in":"query","required":false,"description":"`summary`, `strip`, `wall` or `quote`.","schema":{"type":"string"},"example":"strip"},{"name":"theme","in":"query","required":false,"description":"`light` or `dark`.","schema":{"type":"string"}}],"security":[{"partnerKey":["widgets:read"]},{"dealerKey":["widgets:read"]}],"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"kind":"reviews","variant":"strip","embed_html":"<div class=\"tmd-reviews\" data-dealer=\"anycolourcar\" data-widget=\"strip\" data-theme=\"light\"></div>\n<script src=\"https://trustmydealer.co.uk/api/public/reviews.js\" async></script>","script_url":"https://trustmydealer.co.uk/api/public/reviews.js","preview_url":"https://trustmydealer.co.uk/widget/anycolourcar?variant=strip&theme=light"}}}}}}},"/api/v1/dealers/{msaiDealerId}/badge":{"get":{"tags":["Widgets"],"summary":"Badge data","description":"The raw figures a badge renders from, for teams building their own component. Cached for five minutes and safe to call from a browser.","operationId":"get_dealers_msaiDealerId_badge","parameters":[{"name":"msaiDealerId","in":"path","required":true,"description":"The dealership's MSAI Dealer ID — the same identifier used for their Google review source.","schema":{"type":"string"},"example":"10031287"}],"security":[{"partnerKey":["widgets:read"]},{"dealerKey":["widgets:read"]}],"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"msai_dealer_id":"10031287","slug":"anycolourcar","name":"Any Colour Car","score":4.7,"count":486,"verified":true,"profile_url":"https://trustmydealer.co.uk/dealers/anycolourcar","sources":[{"source":"google","score":4.8,"count":302}]}}}}}}},"/api/v1/dealers/{msaiDealerId}/widget-settings":{"get":{"tags":["Widgets"],"summary":"Get widget settings","description":"The dealership's saved appearance settings.","operationId":"get_dealers_msaiDealerId_widget_settings","parameters":[{"name":"msaiDealerId","in":"path","required":true,"description":"The dealership's MSAI Dealer ID — the same identifier used for their Google review source.","schema":{"type":"string"},"example":"10031287"}],"security":[{"partnerKey":["widgets:read"]},{"dealerKey":["widgets:read"]}],"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"theme":"light","badge_variant":"standard","accent":"#0F5C57","autoplay_ms":6000,"min_rating":4,"max_reviews":12,"sources":["trustpilot","google","reviewsio"],"show_header":true}}}}}},"patch":{"tags":["Widgets"],"summary":"Update widget settings","description":"Appearance only. A dealership can choose how its widget looks, never what it says — score and count are always live.","operationId":"patch_dealers_msaiDealerId_widget_settings","parameters":[{"name":"msaiDealerId","in":"path","required":true,"description":"The dealership's MSAI Dealer ID — the same identifier used for their Google review source.","schema":{"type":"string"},"example":"10031287"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","required":[],"properties":{"theme":{"type":"string","description":"`light` or `dark`."},"badge_variant":{"type":"string","description":"`standard`, `compact` or `seal`."},"accent":{"type":"string","description":"Hex accent colour."},"autoplay_ms":{"type":"integer","description":"Carousel interval in milliseconds, 0 to disable."},"min_rating":{"type":"number","description":"Lowest rating shown in review widgets."},"max_reviews":{"type":"integer","description":"Maximum reviews rendered, 3–50."},"sources":{"type":"array","items":{"type":"string"},"description":"Source keys to include in review widgets."},"show_header":{"type":"boolean","description":"Show the score header above the reviews."}},"additionalProperties":false}}}},"security":[{"partnerKey":["widgets:write"]},{"dealerKey":["widgets:write"]}],"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"updated":true}}}},"422":{"description":"One or more fields failed validation. See the `fields` array.","content":{"application/json":{"example":{"error":{"code":"validation_failed","message":"One or more fields failed validation. See the `fields` array."}}}}}}}},"/api/v1/dealers/{msaiDealerId}/report":{"get":{"tags":["Reporting"],"summary":"Dealer report","description":"Review volume, rating distribution, source mix, response rate and resolution outcomes over the window.","operationId":"get_dealers_msaiDealerId_report","parameters":[{"name":"msaiDealerId","in":"path","required":true,"description":"The dealership's MSAI Dealer ID — the same identifier used for their Google review source.","schema":{"type":"string"},"example":"10031287"},{"name":"days","in":"query","required":false,"description":"30, 90 or 365. Defaults to 30.","schema":{"type":"integer"}},{"name":"format","in":"query","required":false,"description":"`json` or `csv`. Defaults to json.","schema":{"type":"string"}}],"security":[{"partnerKey":["dealers:read"]},{"dealerKey":["dealers:read"]}],"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"days":30,"volume":{"total":42,"direct":18,"aggregated":24},"distribution":{"1":1,"2":2,"3":2,"4":7,"5":30},"source_mix":[{"source":"google","count":24}],"response_rate":0.86,"resolution":{"opened":3,"resolved":2,"withdrawn":1,"published":1,"average_hours_to_first_reply":6.4}}}}}}}},"/api/v1/webhooks":{"get":{"tags":["Webhooks"],"summary":"List endpoints","description":"Registered endpoints with their subscribed events and recent delivery health.","operationId":"get_webhooks","security":[{"partnerKey":["webhooks:write"]}],"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"data":[{"id":"wh-1","url":"https://partner.example.com/hooks/tmd","events":["review.published","case.opened"],"active":true,"last_delivery":{"status":200,"at":"2026-08-25T08:59:00Z"}}]}}}}}},"post":{"tags":["Webhooks"],"summary":"Register an endpoint","description":"Returns the signing secret once, at creation. Store it — it is never shown again.","operationId":"post_webhooks","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["url","events"],"properties":{"url":{"type":"string","description":"HTTPS endpoint that will receive deliveries."},"events":{"type":"array","items":{"type":"string"},"description":"Events to subscribe to."},"msai_dealer_id":{"type":"string","description":"Restrict deliveries to one dealership."}},"additionalProperties":false}}}},"security":[{"partnerKey":["webhooks:write"]}],"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"id":"wh-1","secret":"whsec_9f2a…","active":true}}}}}}},"/api/v1/webhooks/{webhookId}":{"delete":{"tags":["Webhooks"],"summary":"Delete an endpoint","description":"Stops all deliveries to that endpoint.","operationId":"delete_webhooks_webhookId_","parameters":[{"name":"webhookId","in":"path","required":true,"description":"Endpoint identifier.","schema":{"type":"string"}}],"security":[{"partnerKey":["webhooks:write"]}],"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"deleted":true}}}}}}}}}