Vendor Assignment

Status: Accepted Owner: @bilal Last Updated: 2026-02-15

How vendors are assigned to issues and accept jobs via tokenised links.

Flow

Landlord assigns vendor → Token generated → Vendor notified (SMS + Email)
  → Vendor clicks link → Views job details → Accepts or declines
    → Accept: Issue → in_progress, landlord + tenant notified
    → Decline: Issue reverts, landlord can reassign
  → Vendor completes work → Marks complete via link → Issue resolved

Vendor Selection

Landlord sees available vendors filtered by trade, with:

• Rating + job count
• SLA response time
• Preferred vendors listed first

Token Lifecycle

See ADR-006 Vendor Acceptance Tokens for security details.

Property	Value
Format	32-char base64url (192 bits entropy)
Expiry	48 hours
Single use	Yes
Revocable	Yes (on reassignment)

stateDiagram-v2
    [*] --> Active : Created
    Active --> Used : Vendor accepts
    Active --> Expired : 48h passes
    Active --> Revoked : Reassigned
    Used --> [*]
    Expired --> [*]
    Revoked --> [*]

Acceptance Page

Vendor sees (no login required):

• Organisation name
• Property address + room
• Issue description + category + urgency
• Access instructions
• Tenant contact info
• [Accept Job] / [Decline] buttons

On accept:

• Token marked as used
• Issue status → in_progress
• vendor_accepted_at set
• Completion token generated
• Landlord + tenant notified

On decline:

• Issue status reverts
• Landlord notified with decline reason
• New vendor can be assigned

Job Completion

After acceptance, vendor has a completion link with:

• Job summary
• Notes field (what was done)
• [Mark Complete] button

On complete:

• Issue status → completed
• resolved_at set
• Resolution notes saved
• Tenant notified (“Your issue has been resolved”)

Notifications

Event	Landlord	Tenant	Vendor
Vendor assigned	—	—	SMS + Email (with token link)
Vendor accepts	SMS	SMS (“help is on the way”)	—
Vendor declines	SMS	—	—
Job completed	Email (digest)	SMS + Email	—

Edge Cases

Case	Handling
Token expired	”Link expired” message, suggest contacting landlord
Token already used	”Already accepted”, link to completion page
Vendor reassigned	Original token revoked, new token for new vendor
Multiple vendors	Currently one per issue. Future: primary + backup

Related

• ADR-006 Vendor Acceptance Tokens
• Issue Lifecycle
• Notifications