Skip to main content

​
Overview

The Contacts domain stores people, organizations, and the relationships between them. Data models are built on vCard (RFC 6350) with extensions for interaction tracking, affiliations, and flexible tagging. Contacts are the connective tissue of Backside.app. Other domains (CRM deals, calendar attendees, task assignees) reference contacts by UUID rather than duplicating data. A contact updated in one place is updated everywhere.

​
Data Model

​
Entities

EntityDescription
ContactA person, organization, or group. The core entity.
ChannelA communication channel (email, phone, social, custom) attached to a contact.
AddressA physical or mailing address attached to a contact.
DateA significant date (birthday, anniversary, custom) attached to a contact.
RelationshipA typed connection between two contacts (reports_to, spouse, friend, etc.).
AffiliationA person’s role at an organization (title, department, start/end dates).
InteractionA logged touchpoint (meeting, call, email, note) with one or more contacts.
TagA label for categorizing contacts. Tags are tenant-scoped.
GroupA named collection of contacts for bulk operations.

​
Contact kinds

Every contact has a kind field:
KindDescription
personAn individual human
organizationA company, team, or institution
groupA named collection (mailing list, family, etc.)

​
Key Concepts

​
Communication channels

Channels store how you reach someone. Each channel has a type (email, phone, twitter, linkedin, custom) and a value.
  • Emails are stored lowercased for consistent matching
  • Phones should use E.164 format (+15551234567) for reliable lookup
  • Use GET /api/v1/contacts/find-by-channel?type=email&[email protected] to find a contact by email or phone

​
Relationships

Relationships connect two contacts with a typed, directional link. Default types include reports_to, works_with, manages, spouse, partner, parent, child, sibling, friend, and other. Custom types can be added per tenant. Relationships have a from_contact_id and to_contact_id. The direction matters: “Alice reports_to Bob” is different from “Bob reports_to Alice”.

​
Affiliations

Affiliations link a person to an organization with role details: title, department, start date, end date. A person can have multiple affiliations (current and past employers).

​
Interaction history

Log meetings, calls, emails, and other touchpoints. Each interaction has a type, occurred_at timestamp, summary, optional body, and can involve multiple contacts (participant_ids). Interactions are immutable — log them, don’t edit them.

​
Tags and groups

Tags are lightweight labels (e.g., “VIP”, “investor”, “friend”). Tag definitions are tenant-scoped. Apply the same tag to multiple contacts. Groups are named collections for bulk operations. A contact can belong to multiple groups.

​
Soft delete

Deleted contacts are soft-deleted (deleted_at is set). They no longer appear in list/search results but can be restored. Related entities (channels, addresses, etc.) are cascade-deleted.

​
Full-text search

Search across display names, emails, phones, company names, titles, and tags using the q parameter on GET /api/v1/contacts.

​
MCP Tools

ToolDescription
contacts_searchFind contacts by name, email, phone, or any field
contacts_getGet full details for a specific contact
contacts_createAdd a new person, organization, or group
contacts_updateUpdate contact information
contacts_deleteRemove a contact
contacts_list_relationshipsSee who is connected to whom
contacts_log_interactionRecord a meeting, call, or other touchpoint
contacts_find_by_channelLook up a contact by email or phone
See the MCP guide for setup instructions.

​
API Endpoints

See the API Reference for the full endpoint list with request/response details.

​
Examples

​
Create a contact and add an email

# Create a person
curl -X POST https://api.backside.app/api/v1/contacts \
  -H "Authorization: Bearer bsk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "display_name": "Jane Doe",
    "kind": "person"
  }'

# Add an email channel (use the contact ID from the response)
curl -X POST https://api.backside.app/api/v1/contacts/{id}/channels \
  -H "Authorization: Bearer bsk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "channel_type": "email",
    "value": "[email protected]",
    "label": "work"
  }'

​
Search contacts

curl "https://api.backside.app/api/v1/contacts?q=jane&limit=10" \
  -H "Authorization: Bearer bsk_live_..."

​
Log an interaction

curl -X POST https://api.backside.app/api/v1/contacts/{id}/interactions \
  -H "Authorization: Bearer bsk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "interaction_type": "meeting",
    "summary": "Discussed Q2 roadmap",
    "occurred_at": "2026-04-07T14:00:00Z",
    "participant_ids": ["uuid-of-other-contact"]
  }'