SMS API for garages: automating MOT reminders

A garage that does MOTs already holds the one date a reminder needs, because it printed the expiry on the certificate. Getting that date out of the garage management system (or the spreadsheet, or the big diary on the counter) and into a text at the right moment, every day, without anyone having to remember, is the job an SMS API does well. This is the plumbing for automated MOT reminder texts: where the due dates come from, including DVSA's MOT history API for cars you didn't test yourself, when to send, how to stop a re-run texting anyone twice, and what to do with the replies and the failures.

The wording itself is in our post on MOT reminder texts for garages, with six examples from the reminder to the fail sheet.

Where the MOT due dates come from

For a car you tested, you have the expiry date already. Your garage software stored it when the test was logged, and most systems will export it with the customer's mobile number as a CSV, or let a script read it from the database. That covers your MOT customers.

The gap is the cars you service but don't test, the ones that went elsewhere last year, and new customers whose paperwork is in a glovebox somewhere. DVSA publishes that data through the MOT history API. Its documentation says the API covers "cars, motorcycles and vans and their MOT tests in Great Britain (England, Scotland and Wales) since 2005, and Northern Ireland since 2017", plus lorries, trailers, buses and coaches from 2018. It's a REST API with JSON responses and ordinary HTTP status codes.

You look a vehicle up by registration, at GET /v1/trade/vehicles/registration/{registration}, or by VIN. A vehicle that has been tested comes back with its make, model, first used date, a hasOutstandingRecall field and an array called motTests. Each test carries a completedDate, a testResult of PASSED or FAILED (the specification says "Only Passed or Failed tests are included", so abandoned tests don't appear), an expiryDate and the odometer reading. A car too new to have had an MOT comes back in a different shape, with a motTestDueDate described as the "Date the first MOT test is due". Under GOV.UK's rules that's normally the third anniversary of registration, although some vehicles need testing at one year old.

There's a bulk route as well ("The bulk file is generated every Sunday", with daily delta files covering "the past 24 hours"), but a garage looking up a few hundred registrations a month one at a time won't need it.

Getting access to the MOT history API

You register on DVSA's documentation site as an organisation, a business or an individual, giving a name, contact email and postal address. DVSA says it "can take up to 5 working days" to review the request and send the key, longer in busy periods.

Authentication is OAuth 2.0 with the client credentials flow. Registration gets you a client ID, a client secret, a scope URL, an access token URL and an API key. You swap the client ID and secret for an access token issued by Microsoft Entra ID (what used to be Azure Active Directory), and "Access tokens are valid for 60 minutes from issue", so cache the token and reuse it within the hour. Every request then carries two headers: Authorization: Bearer with the token, and X-API-Key with the key.

Client secrets "expire every 2 years", with warning emails 30 and 14 days before. And "If you do not use your API key for 90 days, it will be revoked", which matters for a garage that only checks a car now and then (a daily job that makes even one lookup keeps it alive). The rate limits are generous:

Go over them and you get a 429 Too Many Requests. Go over the daily quota and the key is restricted "for 24 hours from the point you have exceeded the limit". No garage is going to make half a million lookups in a day, but a loop that fires requests with no pause can hit the burst limit of 10 in a fraction of a second, so put a short wait between calls and back off when a 429 arrives, as DVSA's page describes.

When an MOT reminder text should go out

The timing comes from a rule on GOV.UK's "getting an MOT" page: "You can get an MOT up to a month (minus a day) before it runs out and keep the same renewal date." Its example is an MOT running out on 15 May, where the earliest test that keeps the date is 16 April. Test earlier and "the renewal date for the following year will change to one year (minus a day) from the date the vehicle last passed its MOT."

That has a consequence for the code. A lot of reminder systems schedule the text eleven months after the last test, which is fine for a car that was tested on its due date and wrong for one tested early. Say a car due on 15 May passed on 20 April. Its new expiry is 15 May next year, nearly thirteen months after the test, so an eleven months rule would text the customer on 20 March, almost four weeks before they can book without losing days. Time the reminder from expiryDate instead. Sending it 35 days before expiry puts it in the customer's phone about a week before the window opens, which leaves time to find a slot.

GOV.UK's free reminder service also texts or emails anyone who signed up "one month before your car, van or motorcycle MOT is due", so yours will often land the same week. Yours names the garage and lets them book, which theirs doesn't.

The volume won't be flat either. DVSA's quarterly figures for cars and vans (classes 3 and 4) show 7,259,696 tests in April to June 2024, then 8,651,489, 8,245,954 and 8,967,189 in the next three quarters, and the year before ran from 6,706,658 in spring to 8,954,606 in January to March. Expect some days with three reminders and some with thirty.

The daily job, step by step

The simplest design is a job that runs once a day, mid morning, and texts the cars whose expiry is 35 days away. It beats scheduling a year of texts in advance, because by the time a reminder is due the customer may have sold the car, had it tested elsewhere or opted out.

1. Pick the vehicles whose expiry date is 35 days from today, that have a mobile number on file, and whose owner hasn't opted out.
2. For any car you didn't test, look it up on the MOT history API first. If the newest test in motTests is later than the one you hold, it's been tested already; update your record and skip it. If the lookup comes back 404, skip it and flag the record for the desk.
3. Fill in the template, and keep it inside 160 characters of the GSM alphabet so it's one SMS part.
4. Send it with POST /messages, an Idempotency-Key header built from your vehicle id and the expiry date (something like mot-v1842-2026-12-09), and the same value as client_ref.
5. Store the message id the API returns against the vehicle.

Step 4 saves an awkward phone call. If the job crashes halfway and someone runs it again, or a connection drops and your code retries, the same key goes with the same request. CaptiFi Connect answers a repeat with the first request's result and meta.replayed set to true, and sends nothing. Because the expiry date is in the key, next year's reminder gets a new key without anyone having to think about it. Our post on sending a text exactly once covers the retry loop in more detail.

CaptiFi Connect does take a schedule_at time up to a year ahead, and POST /messages/{id}/cancel stops a scheduled text and refunds it. But credits are taken when a send is accepted, so a year of scheduled reminders sits on your balance, and every sale or early test means a cancel.

On timing within the day: CaptiFi Connect holds campaign and list sends to its quiet hours (21:00 to 09:00 London time by default), but a text sent to a single number through the API goes when you send it. Run the job in working hours, when the desk can pick up the replies.

Replies, BOOK keywords and failures

A reminder that ends "Reply BOOK" needs something on the other end. With a keyword set up for BOOK, CaptiFi Connect sends an automatic reply (the online booking link, or "we'll call you today") as soon as one arrives. On a shared number, keywords work for people you've texted in the last 30 days, which covers a reply to a reminder; on a dedicated number they work for anyone. Anything that isn't a keyword lands in the two-way inbox for a person to answer.

Your own system hears about all of it through webhooks. There are six events, signed with HMAC SHA-256. For a reminder job, four matter:

• message.delivered marks the reminder as reached, and client_ref comes back on it, so you can match it to the vehicle without looking anything up.
• message.failed means the text didn't get through. Flag the record so the desk can phone or email, and check the number next time the customer is in.
• message.received carries the reply's text and the number it came from. Match on the number to find the customer and show the reply against their car.
• opt_out.created fires when someone texts STOP. Set the no reminders flag in your own records as well, so the opt-out survives a change of software.

CaptiFi Connect suppresses an opted out number on its own side regardless, so a reminder to it is refused with the reason opted_out, but your own records should never need that safety net.

Build it against a test key first. Keys starting cc_test_ send nothing and cost nothing but still fire the delivery webhooks, so you can run a whole day's job against real data and watch the events arrive. The test keys page lists what they skip.

Is an MOT reminder a marketing text?

Usually, yes. The ICO's guidance says a message that "actively promotes or encourages people to make use of a particular service" is likely to be direct marketing, and a text inviting someone to book their MOT with you does that. The soft opt-in covers it for your own customers: the ICO says you can text someone who is "an existing customer who bought (or negotiated to buy) a similar product or service from you in the past", provided "you gave them a simple way to opt out both when you first collected their details and in every message you have sent". So collect the number with a line about MOT reminders, keep "Reply STOP to opt out" on every reminder, and make sure the STOP reaches your records.

A car you found through the MOT history API but whose owner has never been your customer is a different matter. The soft opt-in doesn't cover prospects, so having a registration and a due date is no reason to text anyone.

Common questions

Can my garage software send MOT reminders by text?

Yes, if it can export due dates or run a script. A daily job reads the cars due in 35 days and posts each reminder to an SMS API such as CaptiFi Connect's, with an idempotency key so a re-run can't send twice. Many garages start with a CSV export and a scheduled script, then move it into the software later.

Can I use the DVSA MOT history API to find when a customer's MOT is due?

Yes. After registering with DVSA, a lookup by registration or VIN returns each test with its expiry date, or a first MOT due date for a newer car. Registration can take up to 5 working days, and an unused key is revoked after 90 days.

Do I need consent to send MOT reminder texts?

A reminder that invites a booking is likely to be marketing under PECR. For your own past customers the soft opt-in applies, provided you offered an opt-out when you took the number and include one in every text. People who have never been your customers need to have given consent.

How far ahead should an MOT reminder text go?

A car can be tested up to a month (minus a day) before its MOT runs out without moving the renewal date. A reminder around 35 days before expiry gives the customer about a week to book into that window, and it should be worked out from the expiry date, not the date of the last test.