States

The five connection states, what each one means for your writes and reads, the Connection object, and the status webhook.

The state machine#

text

 (agency clicks Connect, or staff attach a sandbox)   (you redeem)            (staff certify the first batch)
 ─────────────▶ pending ──────────────────────────────▶ certifying ───────────────▶ active ◀──────┐
                   │ code lapses: stays pending;               │ staff send back: stays certifying  │ resume
                   │ a new code on the same connection         │                                    │
                                                                                          paused ────┘
                   certifying | active | paused ── pause (agency or staff) ──▶ paused
                   any state except revoked ── revoke (agency, you, staff, system) ──▶ revoked (final)

State	Meaning	Listing writes	`GET /connections/{id}`	Reconcile view
`pending`	a code was issued, not redeemed yet	409 `connection_not_active`	404 `connection_not_found`	409 `connection_not_active`
`certifying`	redeemed; your first pushes wait for staff	accepted; valid items answer `needs_review`	200	allowed
`active`	certified; pushes import automatically	accepted	200	allowed
`paused`	the agency or staff paused it	409 `connection_not_active` (`details.status = "paused"`)	200	allowed
`revoked`	ended for good; listings were released	409 `connection_not_active` (`details.status = "revoked"`)	200, `status: "revoked"`	409 `connection_not_active`

A pending connection is never visible to you: it is the agency's intent until you redeem its code, so GET /connections/{id} answers 404 exactly as for an unknown id. A revoked connection stays readable (and a repeated DELETE answers 200): to notice a revoke, read status on GET /connections/{id} or listen for connection.status_changed; the 409 comes from writes and the reconcile view (GET /connections/{id}/listings).

A connection paused while certifying resumes to certifying, never straight to active. See Pause by the agency and Revoke.

The Connection object#

GET /connections/{id} (and redeem, list and disconnect) return:

json

{ "connection": { "id": "9b1d6c2e-4f3a-4c8e-9a71-2d5e8f0b3c44", "status": "active", "environment": "sandbox",
    "agency": { "name": "Test agencija", "register_number": "123/2024", "verification_status": "verified",
                "listing_quota": { "used": 0, "limit": 50 }, "photo_limit": 30 },
    "created_at": "…", "redeemed_at": "…", "certified_at": "…", "paused": null,
    "counts": { "live": 0, "paused": 0, "review": 0, "failed": 0 }, "last_push_at": null } }

agency is what you may know about the agency: its name, Register of Brokers number, verification status, listing quota and photo limit. Its internal id is never returned.
paused is { at, by, reason } while paused, else null.
counts groups the listings of the connection: live, paused, in review, failed.

See GET /connections/{id} in the reference.

The status webhook#

Every change fires connection.status_changed with status and details: { by, reason }: redeem (certifying), certify (active), pause by the agency or staff (paused), resume (active), revoke (revoked). Staff sending a certifying connection back fires connection.certification_rejected instead, with the note. See Events and deliveries.

Last updated 13 Oct 2026