API Reference

contacts

8 endpoints

GET/api/v1/contacts

List Contacts

List your contacts.

Use detail=full for complete profile data, detail=summary for basic info. Use activity_uuid to filter contacts met at a specific activity. Use type to filter by contact type (saved, dropped). Use visited_after to filter contacts with recent visits. Use sort_by=last_visited to sort by most recently visited. Use sort_order=asc to reverse the sort direction (e.g. oldest first).

Query parameters

page	integer	Page number default: 1 · ≥ 1
page_size	integer	Items per page default: 20 · ≥ 1 · ≤ 100
detail	enum	Response detail level: 'full' for ProfileData, 'summary' for basic info default: "summary"
search	string \| null	Search by name or username
activity_uuid	string \| null	Filter by activity UUID (contacts met at this activity)
type	string \| null	Filter by contact type (saved, dropped)
visited_after	string (date-time) \| null	Filter contacts with visits after this datetime (ISO 8601)
sort_by	enum \| null	Sort order: 'created_at' (default) or 'last_visited'
sort_order	enum \| null	Sort direction: 'asc' or 'desc' (default)
default_backend	string	default: "primary"

Responses

200Successful Response

PaginatedResponse_ContactDetailResponse_ | PaginatedResponse_ContactSummaryResponse_

401Authentication failed

Field	Type	Description
errors*	object	Map of field names to error messages. Use '_root' for form-level errors.
message*	string	Human-readable error summary
code	string \| null	Machine-readable error code

403Insufficient permissions

Field	Type	Description
errors*	object	Map of field names to error messages. Use '_root' for form-level errors.
message*	string	Human-readable error summary
code	string \| null	Machine-readable error code

422Validation error

Field	Type	Description
errors*	object	Map of field names to error messages. Use '_root' for form-level errors.
message*	string	Human-readable error summary
code	string \| null	Machine-readable error code

Example request

curl -X GET "https://api.davi.social/api/v1/contacts" \
  -H "Authorization: Bearer <token>"

POST/api/v1/contacts

Create Contact

Save a contact, and record the encounter that produced it.

Name the contact by identifier (a card, wallet, username, user_id or link), by profile_page_uuid, or by name + email for someone with no Davi account. Saving someone already in your contacts adds a visit rather than a duplicate.

An identifier must resolve to a claimed Davi profile — an identity that resolves to no account, or to an account with no profile, is rejected rather than saved as an anonymous contact, because the two are different records and guessing between them loses the distinction.

Attribution (via_client_id) is taken from the caller's token, not the request body.

Query parameters

default_backend

string

default: "primary"

Request body*application/json

Field

Type

Description

identifier

IdentifierRef | null

Identity to save (card, wallet, username, user_id, or link)

object · IdentifierRef

Field	Type	Description
type*	enum	How to interpret `value`
value*	string	Identifier value (card uid, wallet address, username, user uuid, or Davi link)

profile_page_uuid

string | string (uuid) | null

UUID of the profile page to save as a contact

name

string | null

Name of the anonymous contact (paired with `email`)

max length 255

position

string | null

Job position/title of the anonymous contact

max length 255

company

string | null

Company/organization of the anonymous contact

max length 255

string | null

Email of the anonymous contact (paired with `name`)

max length 255

visited_at

string (date-time) | null

Timestamp when the contact was encountered.

activity_session_uuid

string | string (uuid) | null

UUID of the activity session where the contact was met

notes

string | null

Notes about this encounter

max length 1000

via_client_id

string | null

Ignored. Attribution is derived server-side from the caller's access token; a client_id sent here is an unverified claim about another app and is discarded.

Responses

200Successful Response

Field

Type

Description

uuid*

string

type

string

default: "saved"

is_registered

boolean

default: false

name

string

default: ""

string | null

position

string | null

company

string | null

phone_number

string | null

image_url

string

default: ""

username

string | null

profile_page_uuid

string | null

visit_count

integer

default: 0

saved_at*

string (date-time)

last_visited_at

string (date-time) | null

met_at

ActivitySessionContext | null

object · ActivitySessionContext

Field	Type	Description
session_uuid*	string
session_name*	string
activity_uuid*	string
activity_name*	string
session_date*	string (date-time)

profile

ProfileData | null

object · ProfileData

Field

Type

Description

imageUrl

string

default: ""

name

string

default: ""

first_name

string

default: ""

last_name

string

default: ""

shortDescription

string

default: ""

longDescription

string

default: ""

callToAction

CallToAction | null

object · CallToAction

Field	Type	Description
type*	enum
label*	string
url*	string

currentRole

CurrentRole | null

object · CurrentRole

Field	Type	Description
title*	string
company*	string

customBackground

CustomBackground | null

object · CustomBackground

Field	Type	Description
background	string \| null
backgroundColor	string \| null
backgroundImage	string \| null
backgroundPosition	string \| null
backgroundSize	string \| null
backgroundRepeat	string \| null
backgroundAttachment	string \| null

avatarFrame

string | null

socialLinks

ProfileLink[]

array items · ProfileLink

Field	Type	Description
label*	string
url*	string

links

ProfileLink[]

array items · ProfileLink

Field	Type	Description
label*	string
url*	string

longDescriptionContent

object[]

stickers

object[]

visits

ContactVisitResponse[]

default: []

array items · ContactVisitResponse

Field

Type

Description

uuid*

string

visited_at*

string (date-time)

activity_session_uuid

string | null

via_client_id

string | null

met_at

ActivitySessionContext | null

object · ActivitySessionContext

Field	Type	Description
session_uuid*	string
session_name*	string
activity_uuid*	string
activity_name*	string
session_date*	string (date-time)

notes

string | null

created_at*

string (date-time)

400Invalid request

Field	Type	Description
errors*	object	Map of field names to error messages. Use '_root' for form-level errors.
message*	string	Human-readable error summary
code	string \| null	Machine-readable error code

401Authentication failed

Field	Type	Description
errors*	object	Map of field names to error messages. Use '_root' for form-level errors.
message*	string	Human-readable error summary
code	string \| null	Machine-readable error code

403Insufficient permissions

Field	Type	Description
errors*	object	Map of field names to error messages. Use '_root' for form-level errors.
message*	string	Human-readable error summary
code	string \| null	Machine-readable error code

409Resource already exists

Field	Type	Description
errors*	object	Map of field names to error messages. Use '_root' for form-level errors.
message*	string	Human-readable error summary
code	string \| null	Machine-readable error code

422Validation error

Field	Type	Description
errors*	object	Map of field names to error messages. Use '_root' for form-level errors.
message*	string	Human-readable error summary
code	string \| null	Machine-readable error code

Example request

curl -X POST "https://api.davi.social/api/v1/contacts" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{ /* request body */ }'

GET/api/v1/contacts/activities

List Contact Activities

Activities where you have met contacts, with the count met at each.

Bounded by how many activities you have attended, so it returns one page.

Query parameters

default_backend

string

default: "primary"

Responses

200Successful Response

Field

Type

Description

total_items*

integer

Total number of items available

total_pages*

integer

Total number of pages available

current_page*

integer

Current page number

items*

ContactActivityResponse[]

List of items on the current page

array items · ContactActivityResponse

Field	Type	Description
activity_uuid*	string
activity_name*	string
activity_slug*	string
organization_uuid*	string
contact_count*	integer	Number of contacts met at this activity

401Authentication failed

Field	Type	Description
errors*	object	Map of field names to error messages. Use '_root' for form-level errors.
message*	string	Human-readable error summary
code	string \| null	Machine-readable error code

403Insufficient permissions

Field	Type	Description
errors*	object	Map of field names to error messages. Use '_root' for form-level errors.
message*	string	Human-readable error summary
code	string \| null	Machine-readable error code

422Validation error

Field	Type	Description
errors*	object	Map of field names to error messages. Use '_root' for form-level errors.
message*	string	Human-readable error summary
code	string \| null	Machine-readable error code

Example request

curl -X GET "https://api.davi.social/api/v1/contacts/activities" \
  -H "Authorization: Bearer <token>"

GET/api/v1/contacts/{contact_uuid}

Get Contact

Get a single contact with all visits.

Returns the contact details along with the full visit history.

Path parameters

contact_uuid*

string

Query parameters

default_backend

string

default: "primary"

Responses

200Successful Response

Field

Type

Description

uuid*

string

type

string

default: "saved"

is_registered

boolean

default: false

name

string

default: ""

string | null

position

string | null

company

string | null

phone_number

string | null

image_url

string

default: ""

username

string | null

profile_page_uuid

string | null

visit_count

integer

default: 0

saved_at*

string (date-time)

last_visited_at

string (date-time) | null

met_at

ActivitySessionContext | null

object · ActivitySessionContext

Field	Type	Description
session_uuid*	string
session_name*	string
activity_uuid*	string
activity_name*	string
session_date*	string (date-time)

profile

ProfileData | null

object · ProfileData

Field

Type

Description

imageUrl

string

default: ""

name

string

default: ""

first_name

string

default: ""

last_name

string

default: ""

shortDescription

string

default: ""

longDescription

string

default: ""

callToAction

CallToAction | null

object · CallToAction

Field	Type	Description
type*	enum
label*	string
url*	string

currentRole

CurrentRole | null

object · CurrentRole

Field	Type	Description
title*	string
company*	string

customBackground

CustomBackground | null

object · CustomBackground

Field	Type	Description
background	string \| null
backgroundColor	string \| null
backgroundImage	string \| null
backgroundPosition	string \| null
backgroundSize	string \| null
backgroundRepeat	string \| null
backgroundAttachment	string \| null

avatarFrame

string | null

socialLinks

ProfileLink[]

array items · ProfileLink

Field	Type	Description
label*	string
url*	string

links

ProfileLink[]

array items · ProfileLink

Field	Type	Description
label*	string
url*	string

longDescriptionContent

object[]

stickers

object[]

visits

ContactVisitResponse[]

default: []

array items · ContactVisitResponse

Field

Type

Description

uuid*

string

visited_at*

string (date-time)

activity_session_uuid

string | null

via_client_id

string | null

met_at

ActivitySessionContext | null

object · ActivitySessionContext

Field	Type	Description
session_uuid*	string
session_name*	string
activity_uuid*	string
activity_name*	string
session_date*	string (date-time)

notes

string | null

created_at*

string (date-time)

401Authentication failed

Field	Type	Description
errors*	object	Map of field names to error messages. Use '_root' for form-level errors.
message*	string	Human-readable error summary
code	string \| null	Machine-readable error code

403Insufficient permissions

Field	Type	Description
errors*	object	Map of field names to error messages. Use '_root' for form-level errors.
message*	string	Human-readable error summary
code	string \| null	Machine-readable error code

404Resource not found

Field	Type	Description
errors*	object	Map of field names to error messages. Use '_root' for form-level errors.
message*	string	Human-readable error summary
code	string \| null	Machine-readable error code

422Validation error

Field	Type	Description
errors*	object	Map of field names to error messages. Use '_root' for form-level errors.
message*	string	Human-readable error summary
code	string \| null	Machine-readable error code

Example request

curl -X GET "https://api.davi.social/api/v1/contacts/{contact_uuid}" \
  -H "Authorization: Bearer <token>"

PATCH/api/v1/contacts/{contact_uuid}

Update Contact

Update an anonymous contact's details.

Only anonymous contacts can be updated. Registered contacts cannot have their details modified (they come from the user's profile).

Provide only the fields you want to update.

Path parameters

contact_uuid*

string

Query parameters

default_backend

string

default: "primary"

Request body*application/json

Field	Type	Description
name	string \| null	max length 255
position	string \| null	max length 255
company	string \| null	max length 255
email	string \| null	max length 255

Responses

200Successful Response

Field

Type

Description

uuid*

string

type

string

default: "saved"

is_registered

boolean

default: false

name

string

default: ""

string | null

position

string | null

company

string | null

phone_number

string | null

image_url

string

default: ""

username

string | null

profile_page_uuid

string | null

visit_count

integer

default: 0

saved_at*

string (date-time)

last_visited_at

string (date-time) | null

met_at

ActivitySessionContext | null

object · ActivitySessionContext

Field	Type	Description
session_uuid*	string
session_name*	string
activity_uuid*	string
activity_name*	string
session_date*	string (date-time)

profile

ProfileData | null

object · ProfileData

Field

Type

Description

imageUrl

string

default: ""

name

string

default: ""

first_name

string

default: ""

last_name

string

default: ""

shortDescription

string

default: ""

longDescription

string

default: ""

callToAction

CallToAction | null

object · CallToAction

Field	Type	Description
type*	enum
label*	string
url*	string

currentRole

CurrentRole | null

object · CurrentRole

Field	Type	Description
title*	string
company*	string

customBackground

CustomBackground | null

object · CustomBackground

Field	Type	Description
background	string \| null
backgroundColor	string \| null
backgroundImage	string \| null
backgroundPosition	string \| null
backgroundSize	string \| null
backgroundRepeat	string \| null
backgroundAttachment	string \| null

avatarFrame

string | null

socialLinks

ProfileLink[]

array items · ProfileLink

Field	Type	Description
label*	string
url*	string

links

ProfileLink[]

array items · ProfileLink

Field	Type	Description
label*	string
url*	string

longDescriptionContent

object[]

stickers

object[]

visits

ContactVisitResponse[]

default: []

array items · ContactVisitResponse

Field

Type

Description

uuid*

string

visited_at*

string (date-time)

activity_session_uuid

string | null

via_client_id

string | null

met_at

ActivitySessionContext | null

object · ActivitySessionContext

Field	Type	Description
session_uuid*	string
session_name*	string
activity_uuid*	string
activity_name*	string
session_date*	string (date-time)

notes

string | null

created_at*

string (date-time)

400Invalid request

Field	Type	Description
errors*	object	Map of field names to error messages. Use '_root' for form-level errors.
message*	string	Human-readable error summary
code	string \| null	Machine-readable error code

401Authentication failed

Field	Type	Description
errors*	object	Map of field names to error messages. Use '_root' for form-level errors.
message*	string	Human-readable error summary
code	string \| null	Machine-readable error code

403Insufficient permissions

Field	Type	Description
errors*	object	Map of field names to error messages. Use '_root' for form-level errors.
message*	string	Human-readable error summary
code	string \| null	Machine-readable error code

404Resource not found

Field	Type	Description
errors*	object	Map of field names to error messages. Use '_root' for form-level errors.
message*	string	Human-readable error summary
code	string \| null	Machine-readable error code

422Validation error

Field	Type	Description
errors*	object	Map of field names to error messages. Use '_root' for form-level errors.
message*	string	Human-readable error summary
code	string \| null	Machine-readable error code

Example request

curl -X PATCH "https://api.davi.social/api/v1/contacts/{contact_uuid}" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{ /* request body */ }'

DELETE/api/v1/contacts/{contact_uuid}

Remove Contact

Remove a contact and all its visits.

Path parameters

contact_uuid*

string

Query parameters

default_backend

string

default: "primary"

Responses

200Successful Response

Field	Type	Description
message*	string	Success or status message

401Authentication failed

Field	Type	Description
errors*	object	Map of field names to error messages. Use '_root' for form-level errors.
message*	string	Human-readable error summary
code	string \| null	Machine-readable error code

403Insufficient permissions

Field	Type	Description
errors*	object	Map of field names to error messages. Use '_root' for form-level errors.
message*	string	Human-readable error summary
code	string \| null	Machine-readable error code

404Resource not found

Field	Type	Description
errors*	object	Map of field names to error messages. Use '_root' for form-level errors.
message*	string	Human-readable error summary
code	string \| null	Machine-readable error code

422Validation error

Field	Type	Description
errors*	object	Map of field names to error messages. Use '_root' for form-level errors.
message*	string	Human-readable error summary
code	string \| null	Machine-readable error code

Example request

curl -X DELETE "https://api.davi.social/api/v1/contacts/{contact_uuid}" \
  -H "Authorization: Bearer <token>"

POST/api/v1/contacts/{contact_uuid}/visits

Add Contact Visit

Add a visit to an existing contact.

Records a new encounter/interaction with the contact. Attribution (via_client_id) is taken from the caller's token, not the request body.

Path parameters

contact_uuid*

string

Query parameters

default_backend

string

default: "primary"

Request body*application/json

Field	Type	Description
visited_at*	string (date-time)	Timestamp when the contact was encountered
activity_session_uuid	string \| string (uuid) \| null	UUID of the activity session where the contact was met
notes	string \| null	Notes about this encounter max length 1000
via_client_id	string \| null	Ignored. Attribution is derived server-side from the caller's access token; a client_id sent here is an unverified claim about another app and is discarded.

Responses

200Successful Response

Field

Type

Description

uuid*

string

visited_at*

string (date-time)

activity_session_uuid

string | null

via_client_id

string | null

met_at

ActivitySessionContext | null

object · ActivitySessionContext

Field	Type	Description
session_uuid*	string
session_name*	string
activity_uuid*	string
activity_name*	string
session_date*	string (date-time)

notes

string | null

created_at*

string (date-time)

400Invalid request

Field	Type	Description
errors*	object	Map of field names to error messages. Use '_root' for form-level errors.
message*	string	Human-readable error summary
code	string \| null	Machine-readable error code

401Authentication failed

Field	Type	Description
errors*	object	Map of field names to error messages. Use '_root' for form-level errors.
message*	string	Human-readable error summary
code	string \| null	Machine-readable error code

403Insufficient permissions

Field	Type	Description
errors*	object	Map of field names to error messages. Use '_root' for form-level errors.
message*	string	Human-readable error summary
code	string \| null	Machine-readable error code

409Resource already exists

Field	Type	Description
errors*	object	Map of field names to error messages. Use '_root' for form-level errors.
message*	string	Human-readable error summary
code	string \| null	Machine-readable error code

422Validation error

Field	Type	Description
errors*	object	Map of field names to error messages. Use '_root' for form-level errors.
message*	string	Human-readable error summary
code	string \| null	Machine-readable error code

Example request

curl -X POST "https://api.davi.social/api/v1/contacts/{contact_uuid}/visits" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{ /* request body */ }'

DELETE/api/v1/contacts/{contact_uuid}/visits/{visit_uuid}

Remove Contact Visit

Remove a specific visit from a contact.

Cannot remove the last visit - use the delete contact endpoint instead.

Path parameters

contact_uuid*	string
visit_uuid*	string

Query parameters

default_backend

string

default: "primary"

Responses

200Successful Response

Field	Type	Description
message*	string	Success or status message

401Authentication failed

Field	Type	Description
errors*	object	Map of field names to error messages. Use '_root' for form-level errors.
message*	string	Human-readable error summary
code	string \| null	Machine-readable error code

403Insufficient permissions

Field	Type	Description
errors*	object	Map of field names to error messages. Use '_root' for form-level errors.
message*	string	Human-readable error summary
code	string \| null	Machine-readable error code

404Resource not found

Field	Type	Description
errors*	object	Map of field names to error messages. Use '_root' for form-level errors.
message*	string	Human-readable error summary
code	string \| null	Machine-readable error code

422Validation error

Field	Type	Description
errors*	object	Map of field names to error messages. Use '_root' for form-level errors.
message*	string	Human-readable error summary
code	string \| null	Machine-readable error code

Example request

curl -X DELETE "https://api.davi.social/api/v1/contacts/{contact_uuid}/visits/{visit_uuid}" \
  -H "Authorization: Bearer <token>"