Review flows

Sometimes Grihafy cannot be sure about something in your floor plan. A review step pauses the analysis and asks you to confirm it. This page explains when that happens, what to send and what it means for the status and your credit.

What can be reviewed

Choose a review mode

You choose when to be asked with the required reviewMode field on submit. If you send northAngle yourself, Grihafy does not detect or review north.

How to decide

1. Do you know north for every image? Send northAngle and skip north review.
2. Do you want a person to confirm north when it is uncertain? Use north_if_low_confidence.
3. Do you want to confirm the rooms every time? Use rooms, or north_and_rooms for both.
4. Otherwise use auto. Room review can still be requested when the detected rooms look invalid or the image shows several flats, so handle it.

What a paused analysis looks like

The analysis has status review_required. review.stage says what it needs (north or rooms) and expiresAt is when it expires. If you use webhooks you also receive analysis.review_required.

{
  "id": "507f1f77bcf86cd799439011",
  "status": "review_required",
  "review": { "stage": "north", "north": { "...": "..." }, "rooms": null },
  "expiresAt": "2026-10-20T10:00:00.000Z"
}

Send your answer

Send the north angle to POST /v1/analyses/{id}/north or the rooms to POST /v1/analyses/{id}/rooms. Either answers 202 and the analysis goes back to queued. If the answer does not match the stage, or the analysis already moved on, you get 409 invalid_state; read the analysis again.

curl -X POST https://api.grihafy.com/v1/analyses/<id>/north \
  -H "Authorization: Bearer gfy_live_..." \
  -H "Content-Type: application/json" \
  -d '{"northAngle": 90}'

Plans with several flats

If one image shows several flats, every review mode pauses for rooms, because only you can choose what to analyze. The room review lists each room with its flat and marks shared building areas such as lobbies and lifts. Shared areas are returned with sharedArea: true and are not scored.

• Send primaryUnitLabel with the rooms to choose the flat to analyze first. The default is the first flat.
• Send analyzeAllUnits: true to queue every other flat too, with its detected rooms accepted. A flat that cannot be queued stays at review_required.
• Send treatAsOneHome: true if the image is one home. No flats are split.

Each other flat is its own analysis, listed in unit.siblings. Unless you queued it, it waits at review_required and you answer its review the same way. Each waiting flat sends its own analysis.review_required event, so you can ignore that event for flats you queued with analyzeAllUnits.

Statuses and your credit

The credit is held when you submit and stays held through review. Answering a review does not hold a second credit, and the other flats of a multi-flat plan do not hold credits of their own. See Credits.

If nobody answers

A paused analysis waits for about 7 days. After that it becomes expired and the credit is returned. The other flats of a multi-flat plan expire on the same deadline and send analysis.expired, but they hold no credit, so nothing is returned for them. Submit the image again if you still need it. You can also delete a paused analysis; the credit is returned.

Test keys pause too. See Sandbox for which modes pause there.