​
Overview

The contacts list is built automatically. When an escrow moves to active status — meaning both parties have confirmed — the counterparty is added to each user’s contact book. No manual action is needed. Contacts are useful for:
  • Pre-filling the counterparty field when creating a new escrow with a past trading partner
  • Showing a trusted network of people the user has successfully transacted with

​
Fetching contacts

GET /contact-list
Authorization: Bearer <token>

{
  "success": true,
  "status": 200,
  "data": [
    {
      "id": "c1d2e3f4-a5b6-7890-abcd-ef1234567890",
      "contact_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "escrow_id": "d4e5f6a7-b8c9-0123-defa-234567890123",
      "created_at": "2026-03-10T12:00:00Z",
      "profile": {
        "first_name": "Chidi",
        "last_name": "Obi",
        "username": "chidiobi"
      }
    }
  ]
}
Each contact entry carries the escrow_id that created the relationship, so you can link back to the original transaction context.

​
Deleting a contact

Contacts can be removed manually: 
DELETE /contact-delete?id=<uuid>
Authorization: Bearer <token>
id is the contact record ID (not the contact_id of the user). Deletion only removes the contact from the authenticated user’s list — it does not affect the other party’s contacts.
Deleting a contact does not affect any active or historical escrows. It only removes the entry from the contacts list.

​
How contacts are created

The contact relationship is created by a database trigger when an escrow transitions to active. Both participants are added to each other’s contact list simultaneously. The same trigger prevents duplicate entries if the two users transact again.