Connecting your platform to Muuvo.

Muuvo handles the change of occupier for every tenancy you send: notifying the council and the water and energy suppliers, offering tenants broadband and energy, and switching the property onto a void tariff when tenants leave. Your job is to send each stage at the right moment. We queue everything and release it at the right time.

1. References passed
   Send the pre-tenancyPOST /tenancies as soon as references are passed, whether move-in is days or months away.
2. ≤ 2 hours
   Utility and council data availableSuppliers, meter serial numbers and MPAN/MPRN are added to the property, usually instantly.
3. Move-in
   Tenants move inComplete the check-in inventory and take meter readings.
4. Target +5 days
   Send the move-in readingsPOST /tenancies/{id}/start ideally within five days of move-in. The longer readings wait, the more likely billing issues become.
5. Notice given
   Send the end of tenancyPOST /tenancies/{id}/end as soon as notice is given, and more than five days before move-out. Most arrive around 60 days ahead.
6. −5 days
   Void switch releasedMuuvo releases the property to British Gas, our void partner.
7. Move-out
   Send closing readingsCall /end again with the closing readings and the tenants' forwarding address.
8. +30 days
   Void period coveredZero standing charge for 30 days from move-out, plus a £30 bill credit for the landlord.

Each letting agency you work with is set up as its own company within Muuvo, with its own API key. Send each agency's tenancies using that agency's key. This is how we know which agency a tenancy belongs to, who to contact, and where agency-addressed void bills should go.

• We set them up for you. Send us each agency's name, phone number, email and office address. We can do this one at a time as agencies join, or in bulk from a list.
• Or create them yourself. If you'd rather create agencies from within your own platform, POST /companies is available as part of our V2 API. Ask your Muuvo contact for the V2 documentation and access.

Send the agency's key in the X-Muuvo-Key header on every request. Staging keys are issued at the start of your integration. Production keys are issued once your test data has been signed off.

curl https://agent.muuvostaging.com/services/tenancies/{tenancyId} \
  -H "X-Muuvo-Key: YOUR_AGENCY_KEY" \
  -H "Accept: application/json"

Every create and update returns the same response shape. Keep the resultId: it's the ID of the record you just created.

{
  "resultCode": "string",
  "resultId": 0,
  "Errors": [
    "string"
  ]
}

Records build on each other. Create them in this order and keep each returned ID for the next step.

1. LandlordPOST /landlords returns the landlord ID.
2. PropertyPOST /properties with the landlordId and the property address. Returns the property ID, and we start matching meters and council straight away.
3. Pre-tenancyPOST /tenancies with the propertyId, dates and service options. Returns the tenancy ID.
4. TenantsPOST /tenancies/{tenancyId}/tenants once for each tenant.
5. StartPOST /tenancies/{tenancyId}/start with the move-in readings.
6. EndPOST /tenancies/{tenancyId}/end when notice is given, then again at move-out with closing readings.

Endpoint reference

Select an endpoint to see its fields and an example request and response.

Fill in a tenancy and copy the request body for POST /tenancies. It contains every field in the Swagger definition, in the same order; anything left blank is sent empty. The summary shows what Muuvo will do with it.

These fields on the tenancy decide what Muuvo does on your behalf. Set them on every pre-tenancy.

Send each stage as early as you can. Everything sits in our queue until the right moment, so early is never too early.

Enter the dates for a tenancy to see when each call is due and when the void switch is released.

Between tenancies, the landlord is usually liable for the bills. The void service takes the cost out of that gap. It only works if we know about the move-out early, which is why we ask for the end of tenancy as soon as notice is given.

• Five days before move-out, we release the property to British Gas, our void partner, so the supply goes live in the landlord's name.
• From move-out day, the landlord gets a zero standing charge for 30 days and a £30 bill credit.
• Send the move-out data more than five days before move-out. Most partners send it around 60 days ahead, as soon as notice is given.
• Void bills under £30 and under 30 days are zeroed. This saves landlords and agents a lot of money, and commission is available on every switch.
• We don't switch properties that don't qualify, for example where a new tenancy has already started or is about to.

When you create a property, Muuvo matches it against the national database and adds the council, water supplier, energy suppliers and meter details. You can read them back with either ID.

Each create call makes a new record, so posting the same tenancy twice creates two tenancies. To avoid this:

• Store the landlord, property and tenancy IDs we return against your own records.
• Use PUT with the stored ID for any change or correction. Don't post the record again.
• Before creating a tenancy, check whether you already hold a Muuvo tenancy ID for it.

• Completion. When the council, water and energy have all been notified, we send a letting agent receipt to the agency. This is the last step for both a move-in and a move-out. A matching confirmation through the API is being planned.
• Monthly reports. Everything is reported against the tenancy ID. You'll receive monthly reports covering the agencies in your portfolio, including services taken and commission.
• Webhooks. There are no webhooks at present. Posting sales outcomes back against each tenancy is something we can look at with you.

1. Get a staging keyWe issue a staging key and point you to the staging Swagger.
2. Build and test on stagingStaging test data doesn't need cleaning up. Submit new data freely, or ask us to remove records.
3. Send real-shaped test dataA handful of new tenancies and end tenancies, as described below.
4. Sign-offMuuvo checks the data is complete and the timings are right.
5. ProductionWe issue production keys for each agency, for use with https://agent.muuvo.co.uk/services.

What we check before sign-off

• New tenancies sent when references are passed, with tenants added
• Move-in readings with their reading dates
• End tenancies sent at notice, then again with closing readings and dates
• Forwarding addresses on move-out
• Liable parties and voidBillCorrespondenceAddress set correctly
• Service flags set as recommended in this guide

• Dates. Send dates as DD-MM-YYYY. Dates come back as YYYY-MM-DD. We're confirming this applies to every field, including date of birth.
• Date of birth casing. Send dateOfBirth. Home buyer and tenant lead records return it as dateofBirth.
• Meter numbers. Store MPAN and MPRN as text, not numbers, so leading zeros are kept.
• Rate limits. Rate limits apply. Your Muuvo contact will confirm the current limits.
• Deletes. Tenancies, tenants, tenant leads and home buyers can be deleted. Landlords and properties can't be deleted through the API; ask us if you need one removed.