Contacts

Contact management operations

List all contacts

get

http://localhost:3001https://api.usebondery.com

/api/contacts

Retrieve all contacts for the authenticated user (excludes the user's own profile)

Authorizations

cookieAuth

sb-access-tokenstringRequired

Supabase session cookie for authentication

Responses

200

List of contacts

application/json

401

Authentication required or session expired

application/json

500

Internal server error

application/json

get

/api/contacts

HTTPcURLJavaScriptPython

GET /api/contacts HTTP/1.1
Host: localhost:3001
Accept: */*

{
  "contacts": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "firstName": "John",
      "middleName": "Michael",
      "lastName": "Doe",
      "title": "Software Engineer",
      "place": "San Francisco, CA",
      "notes": "Interested in AI and machine learning",
      "avatarColor": "blue",
      "avatar": "https://storage.example.com/avatars/contact123.jpg",
      "lastInteraction": "2026-01-15T10:30:00.000Z",
      "createdAt": "2026-01-01T00:00:00.000Z",
      "connections": [
        "text"
      ],
      "phone": "[phone]",
      "email": "[e-mail]",
      "linkedin": "john-doe-123456",
      "instagram": "johndoe",
      "whatsapp": "[phone]",
      "facebook": "john.doe.123",
      "website": "https://johndoe.com",
      "signal": "[phone]",
      "birthdate": "1990-01-01",
      "notifyBirthday": true,
      "importantDates": [
        {
          "id": "anniversary-2024",
          "name": "Anniversary",
          "date": "2024-06-15",
          "notify": true
        }
      ],
      "myself": false,
      "position": {
        "lat": 37.7749,
        "lng": -122.4194
      }
    }
  ],
  "totalCount": 42
}

Create a new contact

post

http://localhost:3001https://api.usebondery.com

/api/contacts

Create a new contact for the authenticated user

Authorizations

cookieAuth

sb-access-tokenstringRequired

Supabase session cookie for authentication

Body

application/json

firstNamestring · min: 1RequiredExample: John

lastNamestring · min: 1RequiredExample: Doe

linkedinstringOptional

LinkedIn profile ID (optional)

Example: john-doe-123456

Responses

201

Contact created successfully

application/json

400

Invalid input

application/json

401

Authentication required or session expired

application/json

500

Internal server error

application/json

post

/api/contacts

HTTPcURLJavaScriptPython

POST /api/contacts HTTP/1.1
Host: localhost:3001
Content-Type: application/json
Accept: */*
Content-Length: 66

{
  "firstName": "John",
  "lastName": "Doe",
  "linkedin": "john-doe-123456"
}

{
  "id": "123e4567-e89b-12d3-a456-426614174000"
}

Delete multiple contacts

delete

http://localhost:3001https://api.usebondery.com

/api/contacts

Delete multiple contacts by their IDs

Authorizations

cookieAuth

sb-access-tokenstringRequired

Supabase session cookie for authentication

Body

application/json

idsstring · uuid[] · min: 1RequiredExample: ["123e4567-e89b-12d3-a456-426614174000","987e6543-e21b-12d3-a456-426614174999"]

Responses

200

Contacts deleted successfully

application/json

400

Invalid input

application/json

401

Authentication required or session expired

application/json

500

Internal server error

application/json

delete

/api/contacts

HTTPcURLJavaScriptPython

DELETE /api/contacts HTTP/1.1
Host: localhost:3001
Content-Type: application/json
Accept: */*
Content-Length: 87

{
  "ids": [
    "123e4567-e89b-12d3-a456-426614174000",
    "987e6543-e21b-12d3-a456-426614174999"
  ]
}

{
  "message": "Contacts deleted successfully"
}

Get a single contact

get

http://localhost:3001https://api.usebondery.com

/api/contacts/{id}

Retrieve details of a specific contact by ID

Authorizations

cookieAuth

sb-access-tokenstringRequired

Supabase session cookie for authentication

Path parameters

idstring · uuidRequired

Contact ID

Responses

200

Contact details

application/json

401

Authentication required or session expired

application/json

404

Contact not found

application/json

500

Internal server error

application/json

get

/api/contacts/{id}

HTTPcURLJavaScriptPython

GET /api/contacts/{id} HTTP/1.1
Host: localhost:3001
Accept: */*

{
  "contact": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "firstName": "John",
    "middleName": "Michael",
    "lastName": "Doe",
    "title": "Software Engineer",
    "place": "San Francisco, CA",
    "notes": "Interested in AI and machine learning",
    "avatarColor": "blue",
    "avatar": "https://storage.example.com/avatars/contact123.jpg",
    "lastInteraction": "2026-01-15T10:30:00.000Z",
    "createdAt": "2026-01-01T00:00:00.000Z",
    "connections": [
      "text"
    ],
    "phone": "[phone]",
    "email": "[e-mail]",
    "linkedin": "john-doe-123456",
    "instagram": "johndoe",
    "whatsapp": "[phone]",
    "facebook": "john.doe.123",
    "website": "https://johndoe.com",
    "signal": "[phone]",
    "birthdate": "1990-01-01",
    "notifyBirthday": true,
    "importantDates": [
      {
        "id": "anniversary-2024",
        "name": "Anniversary",
        "date": "2024-06-15",
        "notify": true
      }
    ],
    "myself": false,
    "position": {
      "lat": 37.7749,
      "lng": -122.4194
    }
  }
}

Update a contact

patch

http://localhost:3001https://api.usebondery.com

/api/contacts/{id}

Update an existing contact's information

Authorizations

cookieAuth

sb-access-tokenstringRequired

Supabase session cookie for authentication

Path parameters

idstring · uuidRequired

Contact ID

Body

application/json

All fields are optional for updating a contact

firstNamestring · min: 1OptionalExample: John

middleNamestring · nullableOptionalExample: Michael

lastNamestring · nullableOptionalExample: Doe

titlestring · nullableOptionalExample: Software Engineer

placestring · nullableOptionalExample: San Francisco, CA

notesstring · nullableOptionalExample: Interested in AI

avatarColorstring · nullableOptionalExample: blue

avatarstring · uri · nullableOptionalExample: https://example.com/avatar.jpg

connectionsstring[] · nullableOptional

phonestring · nullableOptionalExample: [phone]

emailstring · email · nullableOptionalExample: [e-mail]

linkedinstring · nullableOptionalExample: john-doe-123456

instagramstring · nullableOptionalExample: johndoe

whatsappstring · nullableOptionalExample: [phone]

facebookstring · nullableOptionalExample: john.doe.123

websitestring · uri · nullableOptionalExample: https://johndoe.com

signalstring · nullableOptionalExample: [phone]

birthdatestring · date · nullableOptionalExample: 1990-01-01

notifyBirthdayboolean · nullableOptionalExample: true

importantDatesone of · nullableOptional

or

objectOptional

positionone of · nullableOptional

or

objectOptional

Responses

200

Contact updated successfully

application/json

400

Invalid input

application/json

401

Authentication required or session expired

application/json

500

Internal server error

application/json

patch

/api/contacts/{id}

HTTPcURLJavaScriptPython

PATCH /api/contacts/{id} HTTP/1.1
Host: localhost:3001
Content-Type: application/json
Accept: */*
Content-Length: 625

{
  "firstName": "John",
  "middleName": "Michael",
  "lastName": "Doe",
  "title": "Software Engineer",
  "place": "San Francisco, CA",
  "notes": "Interested in AI",
  "avatarColor": "blue",
  "avatar": "https://example.com/avatar.jpg",
  "connections": [
    "text"
  ],
  "phone": "[phone]",
  "email": "[e-mail]",
  "linkedin": "john-doe-123456",
  "instagram": "johndoe",
  "whatsapp": "[phone]",
  "facebook": "john.doe.123",
  "website": "https://johndoe.com",
  "signal": "[phone]",
  "birthdate": "1990-01-01",
  "notifyBirthday": true,
  "importantDates": [
    {
      "id": "anniversary-2024",
      "name": "Anniversary",
      "date": "2024-06-15",
      "notify": true
    }
  ],
  "position": {
    "lat": 37.7749,
    "lng": -122.4194
  }
}

{
  "message": "Contact updated successfully"
}

Merge duplicate contacts

post

http://localhost:3001https://api.usebondery.com

/api/contacts/merge

Merge the right contact into the left contact. The left contact survives.

Authorizations

cookieAuth

sb-access-tokenstringRequired

Supabase session cookie for authentication

Body

application/json

leftPersonIdstring · uuidRequired

rightPersonIdstring · uuidRequired

Responses

200

Contacts merged successfully

application/json

400

Invalid input

application/json

401

Authentication required or session expired

application/json

404

One or both contacts were not found

application/json

500

Internal server error

application/json

post

/api/contacts/merge

HTTPcURLJavaScriptPython

POST /api/contacts/merge HTTP/1.1
Host: localhost:3001
Content-Type: application/json
Accept: */*
Content-Length: 167

{
  "leftPersonId": "123e4567-e89b-12d3-a456-426614174000",
  "rightPersonId": "123e4567-e89b-12d3-a456-426614174000",
  "conflictResolutions": {
    "ANY_ADDITIONAL_PROPERTY": "left"
  }
}

{
  "personId": "123e4567-e89b-12d3-a456-426614174000",
  "userId": "123e4567-e89b-12d3-a456-426614174000",
  "mergedIntoPersonId": "123e4567-e89b-12d3-a456-426614174000",
  "mergedFromPersonId": "123e4567-e89b-12d3-a456-426614174000"
}

List active merge recommendations

get

http://localhost:3001https://api.usebondery.com

/api/contacts/merge-recommendations

Returns persisted active merge recommendations for the authenticated user.

Authorizations

cookieAuth

sb-access-tokenstringRequired

Supabase session cookie for authentication

Responses

200

Merge recommendations fetched successfully

application/json

401

Authentication required or session expired

application/json

500

Internal server error

application/json

get

/api/contacts/merge-recommendations

HTTPcURLJavaScriptPython

GET /api/contacts/merge-recommendations HTTP/1.1
Host: localhost:3001
Accept: */*

{
  "recommendations": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "leftPerson": {
        "id": "123e4567-e89b-12d3-a456-426614174000",
        "firstName": "John",
        "middleName": "Michael",
        "lastName": "Doe",
        "title": "Software Engineer",
        "place": "San Francisco, CA",
        "notes": "Interested in AI and machine learning",
        "avatarColor": "blue",
        "avatar": "https://storage.example.com/avatars/contact123.jpg",
        "lastInteraction": "2026-01-15T10:30:00.000Z",
        "createdAt": "2026-01-01T00:00:00.000Z",
        "connections": [
          "text"
        ],
        "phone": "[phone]",
        "email": "[e-mail]",
        "linkedin": "john-doe-123456",
        "instagram": "johndoe",
        "whatsapp": "[phone]",
        "facebook": "john.doe.123",
        "website": "https://johndoe.com",
        "signal": "[phone]",
        "birthdate": "1990-01-01",
        "notifyBirthday": true,
        "importantDates": [
          {
            "id": "anniversary-2024",
            "name": "Anniversary",
            "date": "2024-06-15",
            "notify": true
          }
        ],
        "myself": false,
        "position": {
          "lat": 37.7749,
          "lng": -122.4194
        }
      },
      "rightPerson": {
        "id": "123e4567-e89b-12d3-a456-426614174000",
        "firstName": "John",
        "middleName": "Michael",
        "lastName": "Doe",
        "title": "Software Engineer",
        "place": "San Francisco, CA",
        "notes": "Interested in AI and machine learning",
        "avatarColor": "blue",
        "avatar": "https://storage.example.com/avatars/contact123.jpg",
        "lastInteraction": "2026-01-15T10:30:00.000Z",
        "createdAt": "2026-01-01T00:00:00.000Z",
        "connections": [
          "text"
        ],
        "phone": "[phone]",
        "email": "[e-mail]",
        "linkedin": "john-doe-123456",
        "instagram": "johndoe",
        "whatsapp": "[phone]",
        "facebook": "john.doe.123",
        "website": "https://johndoe.com",
        "signal": "[phone]",
        "birthdate": "1990-01-01",
        "notifyBirthday": true,
        "importantDates": [
          {
            "id": "anniversary-2024",
            "name": "Anniversary",
            "date": "2024-06-15",
            "notify": true
          }
        ],
        "myself": false,
        "position": {
          "lat": 37.7749,
          "lng": -122.4194
        }
      },
      "score": 1,
      "reasons": [
        "fullName"
      ]
    }
  ]
}

Refresh merge recommendations

post

http://localhost:3001https://api.usebondery.com

/api/contacts/merge-recommendations/refresh

Recomputes and persists merge recommendations for the authenticated user.

Authorizations

cookieAuth

sb-access-tokenstringRequired

Supabase session cookie for authentication

Responses

200

Merge recommendations refreshed successfully

application/json

401

Authentication required or session expired

application/json

500

Internal server error

application/json

post

/api/contacts/merge-recommendations/refresh

HTTPcURLJavaScriptPython

POST /api/contacts/merge-recommendations/refresh HTTP/1.1
Host: localhost:3001
Accept: */*

{
  "success": true,
  "recommendationsCount": 1
}

Decline merge recommendation

patch

http://localhost:3001https://api.usebondery.com

/api/contacts/merge-recommendations/{id}/decline

Marks one merge recommendation as declined.

Authorizations

cookieAuth

sb-access-tokenstringRequired

Supabase session cookie for authentication

Path parameters

idstring · uuidRequired

Recommendation ID

Responses

200

Recommendation declined successfully

application/json

400

Invalid recommendation id

application/json

401

Authentication required or session expired

application/json

404

Recommendation not found

application/json

500

Internal server error

application/json

patch

/api/contacts/merge-recommendations/{id}/decline

HTTPcURLJavaScriptPython

PATCH /api/contacts/merge-recommendations/{id}/decline HTTP/1.1
Host: localhost:3001
Accept: */*

{
  "success": true
}

Upload contact photo

post

http://localhost:3001https://api.usebondery.com

/api/contacts/{id}/photo

Upload a profile photo for a contact

Authorizations

cookieAuth

sb-access-tokenstringRequired

Supabase session cookie for authentication

Path parameters

idstring · uuidRequired

Contact ID

Body

multipart/form-data

filestring · binaryOptional

Image file (JPEG, PNG, GIF, WebP, max 5MB)

Responses

200

Photo uploaded successfully

application/json

400

Invalid file or file too large

application/json

401

Authentication required or session expired

application/json

404

Contact not found

application/json

500

Internal server error

application/json

post

/api/contacts/{id}/photo

HTTPcURLJavaScriptPython

POST /api/contacts/{id}/photo HTTP/1.1
Host: localhost:3001
Content-Type: multipart/form-data
Accept: */*
Content-Length: 17

{
  "file": "binary"
}

{
  "success": true,
  "avatarUrl": "https://storage.example.com/avatars/user123/contact456.jpg?t=1234567890"
}

Delete contact photo

delete

http://localhost:3001https://api.usebondery.com

/api/contacts/{id}/photo

Remove the profile photo from a contact

Authorizations

cookieAuth

sb-access-tokenstringRequired

Supabase session cookie for authentication

Path parameters

idstring · uuidRequired

Contact ID

Responses

200

Photo deleted successfully

application/json

401

Authentication required or session expired

application/json

404

Contact not found

application/json

500

Internal server error

application/json

delete

/api/contacts/{id}/photo

HTTPcURLJavaScriptPython

DELETE /api/contacts/{id}/photo HTTP/1.1
Host: localhost:3001
Accept: */*

{
  "success": true
}