Relationship Intelligence

New person

New person saves the name and email. The person comes back with that name, and People can open them.

post/v1/relationships

Request

Base URL: / (relative, and the document was published on a file host, not at the API’s origin)
URL: /v1/relationships
Auth: HTTP bearer

Request body

accountDomainstring

Domain from the email address.

displayNamestring required

Full name.

Person or company.

primaryEmailstring

Email address.

summarystring

Notes.

Example request

{
  "accountDomain": "example.com",
  "displayName": "Jordan Buyer",
  "kind": "person",
  "primaryEmail": "buyer@example.com",
  "summary": "Warm lead from the April demo."
}

Response

The person New person saves.

accountDomainstring

Account domain.

categoriesstring[] required

Source-backed company categories.

commitmentCountinteger

Commitments currently recorded on this relationship.

companyDescriptionstring

Source-backed company description.

companyEnrichedAtstring date-time nullable

When the company profile was last enriched.

companyEnrichmentDataobject

Facts the company list shows.

companyEnrichmentRefsobject

Citation URLs keyed by enriched company field.

displayNamestring required

Human display name.

emailThreadCountinteger

Observed email threads currently attached to this relationship.

engagement'unknown' | 'increasing' | 'steady' | 'declining' | 'dormant' required

Direction of engagement.

health'unknown' | 'healthy' | 'needs_attention' | 'critical' required

Explainable health state; never a magic score.

idstring uuid required

Stable UUID primary key.

Relationship kind.

lastChangedAtstring date-time nullable

Last material state change.

lastTouchAtstring date-time nullable

Last observed touch.

Commercial lifecycle.

linkedinUrlstring

Verified public LinkedIn company URL.

milestonesstring[] required

Reached relationship milestones.

nextActionstring

Recommended next action.

nextActionAtstring date-time nullable

Next planned action.

openActionsinteger

Open queue actions for this relationship.

peopleCountinteger

Active people currently attached to this relationship.

primaryEmailstring

Primary email address.

projectedAtstring date-time nullable

Explicit evaluation time used by the projector.

projectorVersioninteger required

Deterministic projector version.

resourceRefsstring[] required

Canonical product:type:externalId references.

risksstring[] required

Current relationship risks.

sentiment'unknown' | 'positive' | 'mixed' | 'negative' required

Observed sentiment.

stateHashstring

Stable hash of canonical projected values and winning assertions.

stateReasonstring

Evidence-backed explanation of the projected state.

stateVersioninteger required

Monotonic projection version.

status'active' | 'dormant' | 'closed' | 'archived' required

Lifecycle/status slug. Subscription rows use billing states; background task runs use queued/running/succeeded/failed/stopped.

summarystring

Bounded relationship summary.

Example response

{
  "accountDomain": "example.com",
  "categories": [
    "Artificial intelligence"
  ],
  "commitmentCount": 4,
  "companyDescription": "Builds AI infrastructure for customer operations.",
  "companyEnrichedAt": "2026-09-06T08:00:00Z",
  "companyEnrichmentData": {
    "employee_range": "201-500 employees (2026)",
    "funding_summary": "$80M total; Series C, $35M, 2025-10-10",
    "growth_signals": "Hiring in 2026",
    "headquarters": "San Francisco, California, United States",
    "revenue_range": "$40M-$60M (2025)"
  },
  "displayName": "Jordan Buyer",
  "emailThreadCount": 12,
  "engagement": "declining",
  "health": "needs_attention",
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "kind": "person",
  "lastChangedAt": "2026-07-25T16:00:00Z",
  "lastTouchAt": "2026-04-10T15:00:00Z",
  "lifecycle": "evaluation",
  "linkedinUrl": "https://www.linkedin.com/company/acme",
  "milestones": [
    "Proposal shared."
  ],
  "nextAction": "Confirm the security review owner.",
  "nextActionAt": "2026-07-01T00:00:00Z",
  "openActions": 1,
  "peopleCount": 3,
  "primaryEmail": "buyer@example.com",
  "projectedAt": "2026-07-25T16:00:00Z",
  "projectorVersion": 2,
  "resourceRefs": [
    "hubspot:company:123"
  ],
  "risks": [
    "Security review has no owner."
  ],
  "sentiment": "mixed",
  "stateHash": "sha256:454f195e2389d36fd49e5c9b9656b7b47a3629332a84eb570edf3fa5248851e1",
  "stateReason": "Security review was promised, but no owner or meeting exists.",
  "stateVersion": 4,
  "status": "active",
  "summary": "Asked for pricing in April; wants a follow-up in July."
}

Changes

No operation changes recorded.