Data model

Contacts

A person you keep in touch with. Carries identity (name, nickname, email, phone), context (company, address, social links), and lifecycle fields (birthday, anniversary, last_contacted_at). Acts as the parent for notes, activities, and reminders.

Model name: contact

Endpoints: 5

Max page size: 200

Fields

Per-field validation rules. Values that violate any constraint are rejected with 400 before they reach the database.

Field	Type	Constraints
city	`string`	max length`120`
name	`string`	max length`200`
tags	`tags`	-
color	`string`	max length`24`
email	`string`	max length`320`
notes	`string`	max length`8000`
phone	`string`	max length`64`
gender	`enum`	enum`male \| female \| other \| unspecified`
company	`string`	max length`200`
country	`string`	max length`120`
twitter	`url`	-
website	`url`	-
birthday	`string`	max length`32`
favorite	`bool`	-
linkedin	`url`	-
nickname	`string`	max length`120`
pronouns	`string`	max length`32`
allergies	`string`	max length`600`
job_title	`string`	max length`200`
food_prefs	`string`	max length`600`
how_we_met	`string`	max length`1000`
anniversary	`string`	max length`32`
address_line	`string`	max length`200`
avatar_blob_id	`string`	max length`64`
secondary_email	`string`	max length`320`
secondary_phone	`string`	max length`64`
last_contacted_at	`string`	max length`32`
stay_in_touch_topic	`string`	max length`400`
stay_in_touch_frequency	`enum`	enum`never \| weekly \| biweekly \| monthly \| quarterly \| yearly`

Mutability

Which fields can you send, and when? Anything without a marker is server-managed - sending it isn't an error, it's silently ignored.

Create-only - read from POST body.Patchable - read from PATCH body.Server-managed - ignored on the body.

Field	Type	Create	Patch
city	string
name	string
tags	tags
color	string
email	string
notes	string
phone	string
gender	enum
company	string
country	string
twitter	url
website	url
birthday	string
favorite	bool
linkedin	url
nickname	string
pronouns	string
allergies	string
job_title	string
food_prefs	string
how_we_met	string
anniversary	string
address_line	string
avatar_blob_id	string
secondary_email	string
secondary_phone	string
last_contacted_at	string
stay_in_touch_topic	string
stay_in_touch_frequency	enum

Fields marked create-only but not patchable are immutable after creation. Server-managed fields include id, timestamps, ownership, and status.

Filtering & sorting

Combinable on list endpoints. Repeating a filter key produces an IN clause; prefixing a sort key with - reverses direction. Example: ?status=open&status=blocked&sort=-created_at.

Filter keys

namedata__name

emaildata__email

companydata__company

citydata__city

countrydata__country

favoritedata__favorite

tagsdata__tags

genderdata__gender

stay_in_touch_frequencydata__stay_in_touch_frequency

statusstatus

is_archivedis_archived

owned_byowned_by

Sort keys

created_atcreated_at

updated_atupdated_at

namedata__name

companydata__company

last_contacted_atdata__last_contacted_at

birthdaydata__birthday

stay_in_touch_frequencydata__stay_in_touch_frequency

Default: name

Endpoints

Each endpoint below lists its HTTP method, path, and the PAT scope it needs. Code samples cover curl, JavaScript, TypeScript, Python, Rust, Java, and WebSocket.

GET/xapi2/data/contactcontact:list

List objects

Returns a paginated list of objects you can read. Default page size is 20; pass ?limit= to change (capped per type). Use ?after=<id> for keyset pagination on created_at-sorted lists, or ?offset= for offset paging.

curl -H "Authorization: Bearer pat_…" \
     "https://friendship-tracker.com/xapi2/data/contact?limit=20"

GET/xapi2/data/contact/{id}contact:read

Read one

Returns the object by id. 404 if it does not exist or you cannot read it (the two cases are intentionally conflated).

curl -H "Authorization: Bearer pat_…" \
     https://friendship-tracker.com/xapi2/data/contact/OBJECT_ID

POST/xapi2/data/contactcontact:create

Create

Creates a new object. Body is a flat JSON dict of field values. Server-side fields (id, timestamps, ownership) are filled automatically; only fields listed below as creatable are read from the body.

curl -H "Authorization: Bearer pat_…" \
     -H "Content-Type: application/json" \
     -X POST https://friendship-tracker.com/xapi2/data/contact \
     -d '{"name": "…"}'

PATCH/xapi2/data/contact/{id}contact:update

Update

Partial update. Only fields included in the body are touched; everything else is preserved. Same allow-list as create, minus the fields that are immutable post-create.

curl -H "Authorization: Bearer pat_…" \
     -H "Content-Type: application/json" \
     -X PATCH https://friendship-tracker.com/xapi2/data/contact/OBJECT_ID \
     -d '{"name": "…"}'

DELETE/xapi2/data/contact/{id}contact:delete

Delete

Removes the object. It vanishes from every default list immediately and stops being returned by read / list.

curl -H "Authorization: Bearer pat_…" \
     -X DELETE https://friendship-tracker.com/xapi2/data/contact/OBJECT_ID

Use in CLI

The same endpoints are also exposed via the Friendship Tracker CLI. For scripts, CI, and bulk imports it's usually the faster path.

friendshipcli contact list --limit 5
friendshipcli contact get <id>
friendshipcli contact create --name "Hello"
friendshipcli contact upsert --unique name --csv items.csv
friendshipcli contact schema   # fields & limits

Full command reference, profiles, CSV import, auto-retry, NDJSON streaming → /docs/cli