Journeys API

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, "miraTerms": 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 holds the handover'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:

Every step of a journey you started through the API is sent to your webhook endpoint, signed. See Webhooks and events for signing, retries and the full event catalogue.

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.

Journey errors are below. Errors every API shares (keys, rate limits) are in Keys, errors and limits.

• 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.