Developers / API documentation
Read and update a dealer's stock, customers and workshop jobs, send enquiries and bookings, run vehicle checks and finance quotes, and be told the moment something happens. Always with the dealer's permission.
The Torque API is a JSON API over HTTPS. Every request goes to https://torquegms.com/api/v1 and needs an API key. Requests and responses are JSON, dates are YYYY-MM-DD, timestamps are ISO 8601 in UTC, and prices are plain numbers in the dealer's currency (for example 14995 for £14,995).
The API is for your server, not a web browser or mobile app. Never put a key in a web page or app, where anyone could copy it.
There are two kinds of key.
For software companies whose product works with many dealers. Sign up as a developer; once we approve you, we issue your partner key. It starts with tdms_partner_.
Your key reaches no dealer data on its own. Each dealer connects your app in Torque (Settings > API & Partners) and chooses what you may do. They can change or remove that at any time.
For a dealer's own website or tools, or a developer working for them. The garage owner creates it in Settings > API & Partners (two-step sign-in must be on). It starts with tdms_live_ and works for that one location only.
Keys are shown once, when they are made. We only store a one-way hash, so we can't show a key again. If one is lost or leaked, the dealer revokes it (or we issue you a new partner key) and the old one stops working at once.
Send the key in the Authorization header on every request.
curl https://torquegms.com/api/v1/dealer \
-H "Authorization: Bearer tdms_live_xxxxxxxxxxxxxxxx"With a partner key, also say which dealer you are acting for, using a dealer id from GET /connections:
curl https://torquegms.com/api/v1/stock \
-H "Authorization: Bearer tdms_partner_xxxxxxxxxxxxxxxx" \
-H "Torque-Dealer-Id: 3f6c2a1e-8d4b-4c7a-9e21-5b0d7f9a1c42"A key stops working if it is revoked, if the dealer disconnects your app, or if the dealer's Torque account is suspended.
Each dealer key, and each dealer's connection to a partner, carries one or more of these permissions.
| Field | Type | Notes |
|---|---|---|
| dealer:read | Read | The location’s trading name, address, phone and email. |
| stock:read | Read | Cars that are in stock, available and advertised, and the vehicle.sold webhook. Never cost, margin or internal notes. |
| stock:write | Write | Add cars to stock and change price, mileage, description, photos, advertising and sale status. |
| leads:read | Read | The lead.created webhook, which includes the customer’s contact details. |
| leads:write | Write | General enquiries, test drive requests and sell-your-car leads. |
| bookings:read | Read | The booking.created webhook, which includes the customer’s contact details. |
| bookings:write | Write | Service booking requests, which staff then confirm. |
| customers:read | Read | Customers’ names, contact details and addresses. Never notes or payment details. |
| customers:write | Write | Add customers and change their contact details and address. |
| jobs:read | Read | Workshop jobs: status, work notes and mileage, and the job.completed webhook. Never prices. |
| jobs:write | Write | Open workshop jobs and move them through the workshop. |
| vehicle-check:read | Read | DVLA details and MOT history by registration, with the dealer’s own service and MOT prices. |
| finance:read | Read | HP and PCP quotes on advertised cars from the dealer’s own lender panel. |
| leasing:read | Read | The dealer’s live leasing deals. |
| leasing:write | Write | Leasing enquiries. |
Stock, leads, finance and leasing need the dealer to use Torque's Sales module; bookings and workshop jobs need the Service module. If not, you'll get a module_not_enabled error.
| Field | Type | Notes |
|---|---|---|
| Dealer key | All requests | 120 per minute |
| Partner key | All requests, across all your dealers | 600 per minute |
| Either | Requests that save something: POST and PATCH on leads, bookings, leasing enquiries, stock, customers, jobs and webhooks | 500 per day, for each dealer |
| Either | POST /vehicle-check and POST /finance-quote | 1,000 per day, for each dealer |
Going over returns 429 with a Retry-After header (in seconds). If you need more, tell us what you're building.
Errors use normal HTTP status codes and always have the same shape:
{
"error": {
"code": "insufficient_scope",
"message": "You don't have the stock:read permission for this dealer. The dealer can grant it in Torque."
}
}| Field | Type | Notes |
|---|---|---|
| 400 | invalid_request | Something in the request is missing or wrong. The message says what. |
| 400 | missing_dealer | A partner key was used without a valid Torque-Dealer-Id header. |
| 401 | unauthorised | No key, or the key isn’t valid (wrong, revoked, or the dealer’s account is suspended). |
| 403 | not_connected | The dealer hasn’t connected your app, or has disconnected it. |
| 403 | insufficient_scope | The key or connection doesn’t have the permission this endpoint needs. |
| 403 | module_not_enabled | The dealer doesn’t use the part of Torque this endpoint needs. |
| 404 | not_found | The thing you asked for doesn’t exist for this dealer. |
| 409 | already_exists | That car or customer is already there. The message gives its id so you can update it instead. |
| 409 | job_closed | The workshop job has been invoiced, so it can’t be changed. |
| 409 | finance_not_set_up | The dealer hasn’t set up finance quotes in Torque. |
| 409 | limit_reached | You already have the most webhooks allowed for this dealer. |
| 429 | rate_limited | Too many requests. Wait for the Retry-After time. |
| 500 | server_error | Something went wrong on our side. It is safe to retry a GET. |
| 503 | unavailable | An outside service (DVLA or the finance provider) didn’t answer. Try again shortly. |
partner key onlyThe dealers that have connected your app, and what each one allows. Use dealerId as the Torque-Dealer-Id header.
{
"data": [
{
"dealerId": "3f6c2a1e-8d4b-4c7a-9e21-5b0d7f9a1c42",
"dealerName": "Example Motors",
"scopes": ["dealer:read", "stock:read", "leads:write"],
"connectedAt": "2026-11-07T09:30:00.000Z"
}
]
}dealer:read{
"data": {
"id": "3f6c2a1e-8d4b-4c7a-9e21-5b0d7f9a1c42",
"name": "Example Motors",
"legalName": "Example Motors Ltd",
"addressLine1": "12 High Street",
"town": "Exampleton",
"region": "Exampleshire",
"postcode": "EX1 2AB",
"country": "United Kingdom",
"phone": "01234 567890",
"email": "sales@example-motors.co.uk"
}
}Any field the dealer hasn't filled in is null.
stock:readCars that are in stock, available and advertised, newest on the forecourt first. limit is 1 to 100 (default 50); use offset to page through. total is the full count.
{
"data": [
{
"id": "b1d9e7a2-3c4f-4e5a-8b6c-7d8e9f0a1b2c",
"registration": "AB12CDE",
"make": "Ford",
"model": "Focus",
"variant": "1.0 EcoBoost ST-Line 5dr",
"year": 2021,
"colour": "Blue",
"fuelType": "Petrol",
"transmission": "Manual",
"mileage": 24500,
"bodyType": "Hatchback",
"price": 14995,
"previousPrice": 15495,
"images": ["https://.../1.jpg", "https://.../2.jpg"],
"videos": [],
"description": "One owner, full service history...",
"featured": false,
"onForecourtSince": "2026-10-28"
}
],
"total": 37,
"limit": 50,
"offset": 0
}previousPrice is only set when the car has been reduced. videos is only filled when the dealer has chosen to show the video publicly.
stock:readReturns { "data": { ...one car, same fields as above } }. A car that is sold, reserved or no longer advertised returns 404.
leads:writeCreates a lead in the dealer's Sales Leads (or, for a test drive, a request in Sales Appointments), marked as sent through the API by your app or key. Returns 201.
| Field | Type | Notes |
|---|---|---|
| type | string, required | "enquiry", "test_drive" or "sell_your_car" |
| customer.name | string, required | Up to 120 characters |
| customer.email | string | Email or phone is required |
| customer.phone | string | Email or phone is required |
| vehicleId | string | Optional. A car id from GET /stock for this dealer |
| message | string | Optional. Up to 2,000 characters |
| preferredDate | string | YYYY-MM-DD. Required for test_drive |
| preferredTime | string | Optional, for test_drive, e.g. "14:30" |
| partExchange.registration | string | Required for sell_your_car; optional part-exchange on an enquiry |
| partExchange.mileage | number | Optional |
| partExchange.condition | string | Optional |
curl -X POST https://torquegms.com/api/v1/leads \
-H "Authorization: Bearer tdms_partner_xxxxxxxxxxxxxxxx" \
-H "Torque-Dealer-Id: 3f6c2a1e-8d4b-4c7a-9e21-5b0d7f9a1c42" \
-H "Content-Type: application/json" \
-d '{
"type": "enquiry",
"customer": { "name": "Sam Taylor", "email": "sam@example.com", "phone": "07700 900123" },
"vehicleId": "b1d9e7a2-3c4f-4e5a-8b6c-7d8e9f0a1b2c",
"message": "Is this still available? Could I see it on Saturday?"
}'{ "data": { "id": "6a7b8c9d-0e1f-4a2b-9c3d-4e5f6a7b8c9d", "type": "enquiry" } }bookings:writeCreates a pending booking on the dealer's Bookings page for staff to confirm with the customer. It doesn't reserve a slot by itself. Returns 201.
| Field | Type | Notes |
|---|---|---|
| customer.name | string, required | Up to 120 characters |
| customer.email | string | Email or phone is required |
| customer.phone | string | Email or phone is required |
| vehicleRegistration | string | Optional |
| service | string | Optional, e.g. "Full service", "MOT", "Diagnostic" |
| preferredDate | string | Optional, YYYY-MM-DD |
| preferredTime | string | Optional, e.g. "09:00" |
| notes | string | Optional. Up to 2,000 characters |
curl -X POST https://torquegms.com/api/v1/bookings \
-H "Authorization: Bearer tdms_live_xxxxxxxxxxxxxxxx" \
-H "Content-Type: application/json" \
-d '{
"customer": { "name": "Alex Smith", "phone": "07700 900456" },
"vehicleRegistration": "AB12CDE",
"service": "MOT",
"preferredDate": "2026-11-20",
"notes": "Brake warning light came on last week."
}'{ "data": { "id": "9f8e7d6c-5b4a-4c3d-8e2f-1a0b9c8d7e6f", "status": "pending" } }stock:writestock:writePOST adds a car to the dealer's stock. It is available but not advertised unless you send "advertised": true. A registration that is already in stock and not sold returns 409 already_exists with the existing id, so a retry can't add a car twice. Returns 201.
PATCH changes only the fields you send, on any car in the dealer's stock (advertised or not). Setting salesStatus to sold takes the car off the adverts.
| Field | Type | Notes |
|---|---|---|
| registration | string | Required on POST. Letters and numbers, up to 10 |
| make, model | string | Required on POST |
| variant, colour | string | Optional |
| vin | string | Optional, up to 17 characters |
| year | number | Optional |
| mileage | number | Optional |
| price | number | Optional. The advertised price |
| fuelType | string | Petrol, Diesel, Electric, Hybrid, Petrol Hybrid, Diesel Hybrid or LPG |
| transmission | string | Manual, Automatic or Semi-Automatic |
| bodyType | string | Hatchback, Saloon, Estate, SUV, Coupe, Convertible, MPV, Van or Pickup |
| description | string | Advert text, up to 5,000 characters |
| images | string[] | Up to 50 https:// image links, in order |
| features | string[] | Up to 100 short feature names |
| advertised | boolean | Whether the car is advertised |
| salesStatus | string | "available", "reserved" or "sold" |
curl -X PATCH https://torquegms.com/api/v1/stock/b1d9e7a2-3c4f-4e5a-8b6c-7d8e9f0a1b2c \
-H "Authorization: Bearer tdms_live_xxxxxxxxxxxxxxxx" \
-H "Content-Type: application/json" \
-d '{ "price": 14495, "mileage": 24800 }'Both return the car with the same fields as GET /stock, plus vin, features, salesStatus and advertised. Cost, margin and purchase details can never be read or written through the API.
customers:readcustomers:readcustomers:writecustomers:writeThe list is newest first. Find someone with email or phone, or pick up changes with updatedSince (a date or timestamp).
{
"data": {
"id": "5c1d2e3f-4a5b-4c6d-8e7f-9a0b1c2d3e4f",
"firstName": "Sam",
"lastName": "Taylor",
"companyName": null,
"email": "sam@example.com",
"mobile": "07700 900123",
"phone": null,
"address": {
"houseNumber": "4", "buildingName": null, "street": "Mill Lane",
"town": "Exampleton", "county": null, "postcode": "EX1 3CD"
},
"preferredContact": "email",
"marketingOptIn": false,
"createdAt": "2026-11-07T10:15:00.000Z",
"updatedAt": "2026-11-07T10:15:00.000Z"
}
}To add or change a customer, send the same field names. firstName and lastName are required on POST, plus at least one of email, mobile or phone. preferredContact is "email", "phone" or "sms". Marketing consent is off unless you send "marketingOptIn": true, so only send that if the customer agreed. An email address the dealer already has returns 409 already_exists with the existing id. PATCH changes only the fields you send.
jobs:readjobs:readjobs:writejobs:writePOST opens a job for one of the dealer's customers. Name the vehicle with vehicleId, or send vehicle with a registration (and optionally make, model, colour, year, fuelType): we use the customer's vehicle with that registration, or add it. Returns 201.
To find a car's jobs, add registration to the list, e.g. GET /jobs?registration=AB12CDE. Spaces and case don't matter, and only this dealer's vehicles are matched. No match returns an empty list. Every job also includes a vehicle object with the car's registration, make, model, variant, year, colour, fuelType and vin, so you don't need a second lookup.
| Field | Type | Notes |
|---|---|---|
| customerId | string, required on POST | A customer id from GET /customers |
| vehicleId or vehicle | string or object | Required on POST, as above |
| title | string | Required on POST, e.g. "Full service" |
| customerConcerns | string | Optional. What the customer reported |
| diagnosis | string | Optional |
| workCarriedOut | string | Optional |
| description | string | Optional |
| mileageIn, mileageOut | number | Optional |
| status | string | pending, in_progress, awaiting_parts, with_subcontractor, quality_check, completed or ready_for_collection |
curl -X PATCH https://torquegms.com/api/v1/jobs/0d1e2f3a-4b5c-4d6e-8f7a-9b0c1d2e3f4a \
-H "Authorization: Bearer tdms_partner_xxxxxxxxxxxxxxxx" \
-H "Torque-Dealer-Id: 3f6c2a1e-8d4b-4c7a-9e21-5b0d7f9a1c42" \
-H "Content-Type: application/json" \
-d '{ "status": "ready_for_collection", "workCarriedOut": "Oil and filter changed.", "mileageOut": 24812 }'{
"data": {
"id": "0d1e2f3a-4b5c-4d6e-8f7a-9b0c1d2e3f4a",
"jobNumber": "JOB-MH7K2Q",
"title": "Full service",
"status": "ready_for_collection",
"customerId": "5c1d2e3f-4a5b-4c6d-8e7f-9a0b1c2d3e4f",
"vehicleId": "7e8f9a0b-1c2d-4e3f-8a4b-5c6d7e8f9a0b",
"vehicle": {
"id": "7e8f9a0b-1c2d-4e3f-8a4b-5c6d7e8f9a0b",
"registration": "AB12CDE",
"make": "Ford",
"model": "Focus",
"variant": "1.0 EcoBoost Titanium",
"year": 2019,
"colour": "Blue",
"fuelType": "Petrol",
"vin": "WF0NXXGCHNKA12345"
},
"bookingId": null,
"customerConcerns": "Service due",
"diagnosis": null,
"workCarriedOut": "Oil and filter changed.",
"description": null,
"mileageIn": 24800,
"mileageOut": 24812,
"startedAt": "2026-11-07T09:02:00.000Z",
"completedAt": "2026-11-07T11:40:00.000Z",
"createdAt": "2026-11-07T08:55:00.000Z",
"updatedAt": "2026-11-07T11:40:00.000Z"
}
}Invoicing stays with the dealer's staff: a job can't be marked invoiced through the API, and an invoiced job returns 409 job_closed. Prices, parts and payments are never included.
vehicle-check:readLooks up a UK registration with the DVLA, adds its MOT history from the DVSA, and prices a service and MOT for that car using the dealer's own Service Pricing in Torque. Send { "registration": "AB12CDE" }.
{
"data": {
"registration": "AB12CDE",
"make": "FORD",
"colour": "BLUE",
"fuelType": "PETROL",
"engineCapacity": 999,
"yearOfManufacture": 2021,
"motDue": "2027-03-14",
"motExpired": false,
"taxDue": "2027-04-01",
"taxStatus": "Taxed",
"dealerPrices": { "minorService": 149, "majorService": 249, "mot": 54.85 },
"motHistory": { ... }
}
}dealerPrices is null if the dealer hasn't set up Service Pricing, and motHistory is null if the DVSA can't be reached. A registration the DVLA doesn't hold returns 404.
finance:readHP and PCP quotes on one of the dealer's advertised cars, from the lenders on the dealer's own panel in Torque.
| Field | Type | Notes |
|---|---|---|
| vehicleId | string, required | An advertised car id from GET /stock |
| term | number | Months, 12 to 60. Default 48 |
| deposit | number | Cash deposit. Default 0 |
| annualMileage | number | 1,000 to 50,000. Default 10,000 |
| partExchangeValue | number | Comes off the amount financed. Default 0 |
{
"data": {
"hp": [
{
"lenderName": "Example Finance",
"productName": "Hire Purchase",
"term": 48,
"monthlyPayment": 312.45,
"finalPayment": 0,
"cashPrice": 14995,
"deposit": 1500,
"amountOfCredit": 13495,
"totalChargeForCredit": 1502.6,
"totalAmountPayable": 16497.6,
"apr": 9.9,
"rateOfInterest": 5.1,
"annualMileage": 10000,
"excessMileageRate": 0,
"firstPayment": 312.45
}
],
"pcp": [ ... same fields ... ]
}
}A dealer without a lender panel set up returns 409 finance_not_set_up. Show quotes with the lender's and dealer's regulatory wording, as you would on any finance advert.
leasing:readleasing:writeThe dealer's live leasing deals, cheapest monthly price first.
{
"data": [
{
"id": "2a3b4c5d-6e7f-4a8b-9c0d-1e2f3a4b5c6d",
"make": "Ford",
"model": "Transit Custom",
"derivative": "2.0 EcoBlue 136ps Limited",
"bodyType": "Panel Van",
"fuelType": "Diesel",
"transmission": "Manual",
"enginePower": "136ps",
"loadLength": "2.55m",
"loadHeight": "1.40m",
"isElectric": false,
"images": ["https://.../1.jpg"],
"monthlyPrice": 299,
"initialPayment": 1794,
"contractLengthMonths": 36,
"annualMileage": 10000,
"leaseType": "business",
"updatedAt": "2026-11-07T06:00:00.000Z"
}
],
"total": 12, "limit": 50, "offset": 0
}POST /leasing/enquiries sends an enquiry into the dealer's Leasing enquiries list, marked as sent through the API. It takes customer (as for POST /leads), optional dealId (an id from the list above), optional message, and optional preferredContactMethod ("phone", "email", "sms" or "any"). Returns 201 { "data": { "id": "...", "status": "new" } }.
the event's permissionanyanyAsk us to POST to your server the moment something happens at a dealer.
| Field | Type | Notes |
|---|---|---|
| lead.created | leads:read | A new sales lead arrived, from any source. |
| booking.created | bookings:read | A new service booking arrived, from any source. |
| vehicle.sold | stock:read | A car in stock was marked sold. |
| job.completed | jobs:read | A workshop job was completed (sent once per job). |
curl -X POST https://torquegms.com/api/v1/webhooks \
-H "Authorization: Bearer tdms_partner_xxxxxxxxxxxxxxxx" \
-H "Torque-Dealer-Id: 3f6c2a1e-8d4b-4c7a-9e21-5b0d7f9a1c42" \
-H "Content-Type: application/json" \
-d '{ "url": "https://example.com/torque/webhooks", "events": ["lead.created", "vehicle.sold"] }'The response includes a secret starting whsec_. It is shown once: store it to check signatures. The URL must be a public https:// address. You can have up to 5 webhooks per dealer. Webhooks belong to your key and that dealer: partners add them separately for each dealer.
Each message looks like this. data is the lead, booking, car or job:
POST https://example.com/torque/webhooks
Content-Type: application/json
Torque-Event: lead.created
Torque-Delivery: 4e5f6a7b-8c9d-4e0f-a1b2-c3d4e5f6a7b8
Torque-Signature: t=1762509600,v1=5f2b...e91c
{
"id": "4e5f6a7b-8c9d-4e0f-a1b2-c3d4e5f6a7b8",
"type": "lead.created",
"createdAt": "2026-11-07T10:00:00.000Z",
"dealerId": "3f6c2a1e-8d4b-4c7a-9e21-5b0d7f9a1c42",
"data": {
"id": "6a7b8c9d-0e1f-4a2b-9c3d-4e5f6a7b8c9d",
"createdAt": "2026-11-07T10:00:00.000Z",
"status": "new",
"source": "website",
"customer": { "name": "Sam Taylor", "email": "sam@example.com", "phone": "07700 900123" },
"vehicleId": "b1d9e7a2-3c4f-4e5a-8b6c-7d8e9f0a1b2c",
"vehicleInterest": "Ford Focus",
"vehicleRegistration": "AB12CDE",
"message": "Is this still available?",
"partExchangeRegistration": null
}
}Check the signature. Work out HMAC-SHA256 of <t>.<raw body> with your secret and compare it with v1. Reject old timestamps (over 5 minutes) to stop replays.
// Node.js
const crypto = require("crypto");
function isFromTorque(rawBody, header, secret) {
const { t, v1 } = Object.fromEntries(header.split(",").map((p) => p.split("=")));
if (Math.abs(Date.now() / 1000 - Number(t)) > 300) return false;
const expected = crypto.createHmac("sha256", secret).update(t + "." + rawBody).digest("hex");
return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(v1));
}Answer with any 2xx within 10 seconds. Otherwise we try again after 1 minute, 5 minutes, 30 minutes, 2 hours, 6 hours, 12 hours and 24 hours, then give up. We don't follow redirects. Messages usually arrive within a minute or two, may occasionally arrive twice or out of order, so use Torque-Delivery to ignore repeats. If your key is revoked, the dealer disconnects you or takes away the permission, messages stop straight away.
This is version 1. We may add new fields and endpoints to v1, so ignore fields you don't recognise. Anything that would break your integration goes in a new version, and we'll tell partners well in advance.
Use of the API is covered by our API terms, and you must handle any personal data you receive in line with data protection law. Questions, or need something the API doesn't do yet? Email hello@torquedms.com.