How it works
You send us one record per new tenancy. That's it: there's nothing supplier-specific for you to build.
/tenancies with your own reference.1Get your API key
Muuvo creates a key for your company and sends it to you privately. It looks like muuvo_live_….
Send it with every request in a header called X-Api-Key. Keep it on your server: never put it in a web page,
an app or an email. If you think it has been seen by someone else, tell Muuvo and they'll revoke it and issue a new one.
2Check you're connected
Call GET /ping. If your key is right you'll get your company name back.
A 401 response means the key is missing, mistyped or revoked.
3The address
Just send the flat's normal postal address, exactly as you hold it. We work out the building and its supplier from it.
How we recognise the building
- We look for the building name anywhere in the address (e.g. "Landmark East Tower"), or failing that the building's street address (e.g. "24 Marsh Wall").
- The postcode district must agree, so a street with the same name somewhere else won't be mistaken for one of our buildings.
- The flat number is read from the first line ("Flat 1607", "Apartment 12", "Apt 3B"). You can also send it separately as
apartment. - Capitals, punctuation, commas and "&" vs "and" don't matter.
GET /developments lists every building we cover, with its supplier, if you'd like to check an address before sending.
422 error and nothing is created.
Add "supplier" ("servus" or "cep") if you know it, or ask Muuvo to add the building. More suppliers will be added; your integration won't need to change.4Send a tenancy
Call POST /tenancies with the tenancy as JSON. Send whatever you have: we use what each supplier needs.
Example: a Servus building
The tenant is emailed their registration link straight away. The response includes the same link, if you'd like to show it in your own system.
Example: a CEP building
CEP also needs the landlord and (if there is one) the previous tenant. Muuvo checks the form and sends it to CEP.
What you get back
The full list of fields is in All fields.
5Test first
Add "test": true to any tenancy, or send the header X-Test-Mode: true.
We check every field, match the building and tell you exactly what would happen, but nothing is saved and no email is sent. Use it while you build, and keep a test call in your own checks.
6Check progress
Call GET /tenancies/{your reference} any time to see where a tenancy has got to.
| Status | Supplier | What it means |
|---|---|---|
invited | Servus | The tenant has been emailed their link and hasn't registered yet. We send reminders automatically. |
registration_started | Servus | The tenant has filled in their details but hasn't finished the Direct Debit. |
dd_complete | Servus | The Direct Debit form has been submitted. Muuvo is completing the paperwork. |
complete | Servus | Everything is done. |
already_registered | Servus | This tenant was already set up, so no invite was sent. |
removed | Servus | Muuvo removed this tenancy from the list. |
ready_to_send | CEP | The form is prepared and waiting for Muuvo to send it. |
sent_to_cep | CEP | Muuvo has sent the form to CEP. |
All fields
Everything you can send to POST /tenancies. Leave out anything you don't have.
| Field | Servus | CEP | Notes |
|---|---|---|---|
reference | Required | Required | Your unique ID for this tenancy. Sending it again updates the same record. |
address.addressLine1, .addressLine2, .addressLine3, .townOrCity, .county, .postcode | Required | Required | The flat's postal address, as you hold it. We find the building and supplier from it. .uprn is welcome too. |
supplier | Optional | servus or cep. Only needed if we can't recognise the address. | |
apartment | Optional | Flat number, if it isn't in addressLine1. | |
development | Optional | The building's name, if you happen to have it. | |
property_address | Optional | The whole address as one line, instead of address. | |
move_in_date | Optional | Required | Tenancy start date. YYYY-MM-DD (or DD/MM/YYYY). |
tenant.first_name | Required | Required | For CEP you can send tenant.name instead. |
tenant.last_name | Required | Optional | |
tenant.email | Required | Optional | For Servus, the invite goes to this address. |
tenant.phone | Optional | UK number, any format. | |
start_meter_reading | - | Optional | Meter reading at move-in. |
landlord.name, .address, .email, .phone | - | Optional | The flat's landlord (leaseholder). .address can be text or an address object like above. leaseholder works too. |
previous_tenant.name, .end_date, .end_meter_reading, .forwarding_address, .email, .phone | - | Optional | The outgoing tenant, if there is one. |
resend_invite | Optional | - | true to email the tenant their link again when you update a tenancy. |
test | Optional | true to check without saving or sending anything. | |
Responses & errors
What happened: action
| action | Meaning |
|---|---|
invite_sent | New Servus tenancy: the tenant has been emailed their link. (HTTP 201) |
form_created | New CEP tenancy: the form is ready for Muuvo. (HTTP 201) |
updated | You'd sent this reference before; we've updated the details. No new email. |
updated_and_invite_resent | Updated, and the tenant was emailed again (their email changed, or you sent resend_invite). |
linked_to_existing_invite | Muuvo had already invited this tenant; we've linked your reference to it. No duplicate email. |
already_registered | The tenant is already set up with the supplier. Nothing was sent. |
When something's wrong
Errors always look the same, so they're easy to log and show:
| HTTP | code | What to do |
|---|---|---|
| 400 | invalid_json | The body isn't valid JSON. Check your request. |
| 401 | unauthorised | The API key is missing, mistyped or revoked. |
| 404 | not_found | Wrong address, or no tenancy with that reference for your key. |
| 409 | already_sent | The CEP form for this tenancy has already gone to CEP, so it can't be changed. Contact Muuvo. |
| 422 | validation_failed | fields lists each problem, by field name. Fix and resend. |
| 502 | email_failed | We couldn't email the tenant (usually a bad address). Nothing was saved; fix the email and resend. |
| 500 | server_error | Something went wrong on our side. Retry after a short wait; it's safe to resend. |
Try it live
Send real requests from this page. Test mode is on until you switch it off, so nothing is saved or emailed.
Your key stays in this browser tab only and is sent straight to https://heat.muuvo.app/api/v1.
Go-live checklist
- Your key is stored on your server, not in any web page, app or email.
GET /pingreturns your company name.- You send the flat's full postal address, including the postcode.
- Each tenancy has a unique
referencefrom your system, and you resend the same one for updates. - You've tried a Servus and a CEP tenancy in test mode, and handled a
422by showing thefieldsmessages. - You retry on
500after a short wait (it's always safe to resend). - Switch test mode off, send one real tenancy with your own email as the tenant, and check the invite arrives.