Journeys API

Send your company's developer key as a bearer token on every request:Authorization: Bearer ms_live_.... Keys are created, rotated and given an expiry in MIRA Business under Settings, API Keys, by the company owner. Rotating a key stops the old one immediately.

A key belongs to one company. A dealer's key can start every journey type; a broker's key can start every finance sale. Everything a key can see is limited to journeys its company started.

Test keys (ms_test_) run the same API against simulated journeys. They never create a real customer or handover, never charge your wallet, and never email a customer: journey emails go to your company admin instead, marked TEST. Photos you send are still checked, then thrown away. Responses and webhooks say"livemode": false.

A test journey moves on by itself every few seconds. To force an outcome, callPOST /{journeyId}/simulate with an event from the catalogue marked simulatable. Live and test data never mix: a live key cannot see test journeys, and the other way round.

Starting a journey needs an Idempotency-Key header (8 to 255 letters, digits, or . _ : -), unique per journey. Use something from your own system, such as your deal number. Sending the same key again with the same body returns the original journey with status 200 and an Idempotent-Replayed: trueheader instead of starting a second one, so it is always safe to retry after a timeout or a 503. The same key with a different body is refused withIDEMPOTENCY_KEY_REUSED. If a request fails, nothing is kept and you can retry with the same key.

Every response uses the same envelope. On failure, errors[0].code is the stable code to act on.

{
  "success": true,
  "data": {
    "id": "0192f1c2-6f3b-7d2a-9d6e-1a2b3c4d5e6f",
    "type": "IDENTITY_DELIVERY",
    "status": "ACTIVE",
    "livemode": false,
    "externalReference": "DMS-88213",
    "customerReference": "5f1c7a9e-6f3b-4d2a-9d6e-1a2b3c4d5e6f",
    "delivery": null,
    "finance": null,
    "identity": { "status": null },
    "nextAction": "CUSTOMER_TO_VERIFY_IDENTITY",
    "createdAt": "2026-09-25T10:15:02Z"
  },
  "message": "Journey started",
  "errors": null
}

{
  "success": false,
  "data": null,
  "message": "Identity verification is not set up for this company. Configure it in MIRA Business first.",
  "errors": [{ "field": "journey", "code": "EKYC_NOT_CONFIGURED", "message": "..." }]
}

POST https://api.motorsync.co.uk/api/v1/journeys. Use the customer's own email address: it is where MIRA sends their sign-in links. The journey identifies the customer with its own customerReference. Pick the journey that matches what has already happened outside MIRA:

curl -X POST https://api.motorsync.co.uk/api/v1/journeys \
  -H "Authorization: Bearer ms_test_..." \
  -H "Idempotency-Key: deal-88213" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "IDENTITY_DELIVERY",
    "externalReference": "DMS-88213",
    "customer": {
      "firstName": "Jane", "lastName": "Doe",
      "email": "jane@example.com", "mobile": "07700900000"
    },
    "vehicle": { "registration": "AB21XYZ", "make": "BMW", "model": "3 Series", "year": 2021 },
    "delivery": { "type": "HOME_DELIVERY" },
    "finance": { "panelName": "iVendi", "panelReference": "IV-123456", "lender": "Close Brothers" }
  }'

Required means the request is refused without it. Codes must be sent exactly as listed. Anything not listed for a journey type is refused rather than ignored, so you never believe a field is being used when it is not.

For a financed sale already approved on your own panel. No finance application is needed: MIRA records it as approved, with your panelName, panelReference and lender if you send them. The customer is asked to verify their identity straight away. You are told the result through identity.* events, and as soon as they are verified the handover is created. No photo is needed.

For a handover with no finance application in MIRA. delivery.saleType says which kind of sale it is:

curl -X POST https://api.motorsync.co.uk/api/v1/journeys \
  -H "Authorization: Bearer ms_test_..." \
  -H "Idempotency-Key: deal-88215" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "DELIVERY",
    "customer": { "firstName": "Alex", "lastName": "Khan", "email": "alex@example.com" },
    "vehicle": { "registration": "EF23GHI" },
    "delivery": { "type": "HOME_DELIVERY", "saleType": "CASH_SALE" }
  }'

For a FINANCE_SALE, send the request as multipart/form-data with a journey JSON part and a customerFace part: a JPEG or PNG up to 5 MB showing exactly one clear face. It is stored without its metadata and checked before anything is created. Using someone's face this way needs their explicit consent, which you confirm in customerFace.biometricConsent. It is recorded with the handover.

curl -X POST https://api.motorsync.co.uk/api/v1/journeys \
  -H "Authorization: Bearer ms_test_..." \
  -H "Idempotency-Key: deal-88214" \
  -F 'journey={
    "type": "DELIVERY",
    "customer": { "firstName": "Sam", "lastName": "Lee", "email": "sam@example.com" },
    "vehicle": { "registration": "CD22ABC" },
    "delivery": { "type": "IN_STORE", "saleType": "FINANCE_SALE" },
    "customerFace": {
      "source": "IN_PERSON_PHOTO",
      "biometricConsent": {
        "given": true, "capturedAt": "2026-09-25T10:15:00Z",
        "method": "SIGNED_IN_PERSON", "noticeVersion": "privacy-v3", "capturedBy": "Front desk"
      }
    }
  };type=application/json' \
  -F 'customerFace=@sam.jpg;type=image/jpeg'

If the video keeps failing to match, replace the photo with PUT /{journeyId}/customer-face while no video is being checked.

Choose how the application reaches a lender with finance.panelSubmission:

"type": "FINANCE_IDENTITY_DELIVERY",
"finance": {
  "panelSubmission": "ALREADY_SUBMITTED",
  "panelName": "iVendi",
  "panelReference": "IV-123456",
  "lender": "Close Brothers",
  "vehiclePrice": 15000, "loanTerm": 48, "depositAmount": 1000
}

For SUBMIT_VIA_MIRA the application goes to the panel as soon as it is accepted, so it must be complete and use the codes listed in Request fields, with at least 3 years of address history and the consents the customer gave you. It is sent with the current job and address first.

"type": "FINANCE_IDENTITY_DELIVERY",
"customer": { ..., "title": "MRS", "mobile": "07700900000", "dateOfBirth": "1990-04-12" },
"finance": {
  "panelSubmission": "SUBMIT_VIA_MIRA",
  "vehiclePrice": 15000, "loanTerm": 48, "depositAmount": 1000, "monthlyBudget": 350,
  "maritalStatus": "MARRIED", "drivingLicenceType": "FULL_UK", "validUkPassport": true,
  "employmentHistory": [{
    "employmentType": "CURRENT", "employmentStatus": "FULL_TIME_EMPLOYMENT", "employer": "Acme Ltd",
    "jobTitle": "Engineer", "monthlyIncome": 3200, "timeAtEmployerYears": 4, "timeAtEmployerMonths": 2
  }],
  "addressHistory": [{
    "addressType": "CURRENT", "buildingNumber": "12", "street": "High Street", "city": "Leeds",
    "postcode": "LS1 4AB", "timeAtAddressYears": 5, "timeAtAddressMonths": 0, "residentialStatus": "TENANT_PRIVATE"
  }],
  "consents": {
    "infoAccuracy": true, "motorsyncTerms": true, "providerTerms": true, "dataSharing": true,
    "creditCheck": true, "identityVerification": true, "providerName": "CarMoney"
  }
}

The customer is asked to verify their identity once the application is recorded (for SUBMIT_VIA_MIRA, once the panel has accepted it), while the decision is pending. The handover is created only when finance is approved and identity is verified, in either order. A declined application, or one that could not be submitted to the panel (finance_enquiry.submission_failed), ends the journey.

Before accepting a journey that includes an identity check, MIRA checks that identity verification is set up for your company, that a finance panel is set up for SUBMIT_VIA_MIRA, and that the wallets that pay for the checks have enough credit. Each check is billed exactly as when your team starts it in MIRA.

status is ACTIVE, COMPLETED, CANCELLED or EXPIRED. delivery has the handoverdelivery.status follows the handover,apos;s statusand, for DELIVERY journeys, its saleType. identity appears on FINANCE_IDENTITY_DELIVERY and IDENTITY_DELIVERY, finance on FINANCE_IDENTITY_DELIVERY only (a cash-sale DELIVERY's identity step shows in delivery.status), and nextAction says what the journey is waiting for:

A new customer gets a welcome email first. Then, at each step that needs them (verify identity, confirm the delivery address, record the handover video) they get an email with a one-time sign-in link that opens the MIRA app on that step. They also hear when finance is approved or updated and when the handover is complete. Emails are sent in your company's name.

Add an endpoint in MIRA Business under Settings, Webhooks: one for live events and, separately, one for test events. It must be HTTPS on port 443 or 8443 and reachable from the public internet. You see its signing secret once, when you add it or replace it.

MIRA sends a POST for each event on journeys you started through the API. By default that is every event; in settings you can choose only some, by name or by whole group (a group also covers events added to it later). The test event is always sent. Events carry ids and statuses only, never personal details: callGET /api/v1/journeys/{journeyId} for more.

POST /your/webhook/path
Mira-Event-Id: 0192f1d0-2a4b-7c3d-8e9f-0a1b2c3d4e5f
Mira-Event-Type: delivery.completed
Mira-Timestamp: 1759140000
Mira-Signature: t=1759140000,v1=<64 hex characters>

{
  "id": "0192f1d0-2a4b-7c3d-8e9f-0a1b2c3d4e5f",
  "type": "delivery.completed",
  "apiVersion": "1.0.0",
  "livemode": true,
  "createdAt": "2026-10-02T14:03:11Z",
  "data": {
    "journeyId": "0192f1c2-6f3b-7d2a-9d6e-1a2b3c4d5e6f",
    "journeyType": "IDENTITY_DELIVERY",
    "journeyStatus": "COMPLETED",
    "externalReference": "DMS-88213",
    "customerReference": "5f1c7a9e-6f3b-4d2a-9d6e-1a2b3c4d5e6f",
    "deliveryStatus": "COMPLETED"
  }
}

Check every request. Mira-Signature ist=<unix seconds>,v1=<hex>, where v1 is HMAC-SHA256 of t + "." + raw bodykeyed with your secret. Compute it over the exact bytes you received, compare in constant time, and reject at more than 5 minutes old so an old request cannot be replayed.

const crypto = require('crypto')

// rawBody must be the exact bytes received, before any JSON parsing.
function verifyMiraSignature(rawBody, header, secret, toleranceSeconds = 300) {
  const parts = Object.fromEntries(header.split(',').map((p) => p.split('=')))
  const t = Number(parts.t)
  if (!t || Math.abs(Date.now() / 1000 - t) > toleranceSeconds) return false
  const expected = crypto.createHmac('sha256', secret).update(`${t}.${rawBody}`).digest('hex')
  const given = Buffer.from(parts.v1 || '', 'hex')
  return given.length === 32 && crypto.timingSafeEqual(given, Buffer.from(expected, 'hex'))
}

Answer quickly. Any 2xx within 10 seconds counts as delivered. Redirects are not followed. Anything else is retried after 1 minute, 5 minutes, 30 minutes, 2, 6, 12 and 24 hours, then given up on. The same event can arrive more than once and out of order, so useMira-Event-Id to ignore repeats and createdAt or a fresh GET for the latest state.

If nothing reaches an endpoint for three days, MIRA turns it off and emails your company admin. Fix it, save the URL again to turn it back on, and resend what you missed from the delivery log.

Every event has id, type, apiVersion, livemode,createdAt and data (journeyId, journeyType, journeyStatus, externalReference, customerReference, deliveryStatus, and financeStatus and identityStatus on finance journeys).

• 500 requests a minute per key; beyond that, 429.
• Customer photos up to 5 MB, JPEG or PNG.
• List pages up to 100 journeys.
• Webhook responses within 10 seconds.