Your workspace
your organisation's workspace
A ring is one organisation’s private world in Rings — its people, companies,
deals, and relationship graph. All API keys belong to exactly one ring, and
nothing crosses between rings. When you see “tenant” in the API, it means the
same thing; “ring” is the product word, “tenant” the technical one.
someone on your team
A colleague inside your ring — a Rings user at your firm. Their email and
calendar activity is what builds the graph. Ring members are excluded from
relationship lists, which are about the outside world.
workspace administrator
A ring member with administrative rights over the workspace. Ringmasters can
act on records they do not own — for example, deleting any note in the ring
or editing any entity list. Ordinary members can only change their own.
Internal people are ring members. External people are everyone else —
founders, LPs, candidates, counterparties. Relationship scores always measure
an internal person’s connection to an external one.
Some data belongs to a specific person rather than the whole ring — your
meetings, your tasks, your own relationships. Endpoints returning that data
need to know which member is asking. Either use a user-scoped API key, or
send
x-rings-user-id with a ring-scoped one. Without it you get 403.
See the API reference.The entities
a human
Anyone your ring knows about — a contact, a founder, a candidate, or a ring
member. Identified by
person_uuid. Carries emails, job title, current
company, and relationship scores.an organisation
Identified by
company_uuid. Carries domain, location, industry tags,
headcount, funding attributes, and relationship scores. People are linked to
companies through affiliations.a person-company link
The connection between a person and a company — where someone works, or used
to. A person’s
current_company comes from their highest-priority
affiliation, so it can change without anyone editing the record.an email or a meeting
A single interaction: one email, or one calendar event. Activities are the
raw material of the graph — every relationship score ultimately traces back
to them. They arrive automatically from connected mailboxes and calendars;
you do not create them through the API.
a calendar activity
A calendar-event activity where a ring member is a participant. The meetings
endpoints are a view over calendar activity scoped to a specific member,
which is why they need user context.
a deal or workstream
Whatever your firm is trying to move forward — a deal, a fundraise, a
mandate, a search. Has a type and a stage, an owner, a value, and a
probability. Opportunities can nest: a parent opportunity can have
sub-opportunities beneath it.
your pipeline's shape
Each ring defines its own types (for example “Investment” or “Fundraise”),
and each type has its own ordered stages. Stages belong to a type, so fetch
the type first, then its stages. Both are UUIDs, not free text — resolve them
before creating an opportunity.
written context
Rich-text notes — meeting write-ups, call summaries, diligence observations.
A note has a subject, an HTML body, and associations to the entities it is
about. Notes are searchable by meaning, not just keyword.
a follow-up
An actionable item with an optional assignee, due date, and reminders. Tasks
are either
RING (visible to everyone in the ring) or PERSONAL (visible
only to their creator — other members get a 404).a named collection
A saved group of people or companies — a target list, a portfolio, a
conference roster. A list holds one kind only: a person list cannot contain
companies. Lists return member UUIDs, which you then hydrate.
a link between records
How a note, task, or opportunity attaches to the people and companies it
concerns. One note can be associated with several entities at once. This is
the join that makes “everything we know about Acme” answerable.
Relationship intelligence
These are the scores that make Rings more than a contact database.evidence of a relationship
The underlying record that one ring member has a relationship with one
external person, inferred from their shared activity. Signals are what
every score below is computed from. A person with no signals has no scores —
which is why some fields come back
null rather than zero.1–3, per member
How strong one specific ring member’s relationship with one specific person
is.
1 is weak, 3 is strong. RQ is per-member, so the same external person
can be a 3 for one colleague and null for another.The canonical field is priority_management.rq. Ignore rq_manual and
rq_math — they are inputs, not the answer.0.0–1.0, whole ring
How strong your organisation’s overall relationship with a person or
company is — the ring-wide view, where RQ is the per-member one. A person’s
PathPower is derived from the RQ signals every member has with them. A
company’s PathPower averages the top five person scores among people
affiliated with it.
score is the raw 0.0–1.0 value and score_display is the same number
as 0–100. PathPower answers “how well do we know them”, not “who should
make the intro” — for that, use recommended paths.who should make the intro
Given a target person or company, the ranked list of ring members best placed
to open the door, each with the hops connecting them to the target. This is
the endpoint behind “who can introduce me to Acme”. PathPower gives you a
number; recommended paths give you a name and a route.
the quick version
The top two ring members with the strongest connection to a person or
company, precomputed and returned inline on detail and list responses. Use it
when you want the headline without a second call; use recommended paths when
you need the full ranking and the hops. Refreshed every few hours, so it can
trail a very recent introduction.
last_contact_at and last_activity_date are the same value under two
names: the most recent interaction anyone in the ring had with that entity.
last_engaged_at, which appears inside strongest relationships, is narrower
— the last interaction between that particular member and the entity.Data model details
Some people and companies come from shared reference data available to every
ring; others your team created or enriched privately. When both exist, your
ring’s version wins, and lookups rank your records above global ones. This is
why a company can appear with details nobody at your firm entered.
Every request is scoped to your ring. When a record exists in Rings but your
ring cannot see it, the API returns
404 — the same response as a record
that does not exist. This is deliberate: it prevents one ring learning what
another holds. Read 404 as “not available to you”, not “no such record”.Ring-defined fields on companies and opportunities, keyed by field UUID
rather than name. Writing them replaces the whole object — there is no
per-key merge, so send every key you want to keep.
Every entity is identified by a UUID, and almost every endpoint takes one.
When you start from an email address, a domain, or a name, resolve it first
with a lookup endpoint. To resolve several at once, use the batch lookup
endpoints rather than looping.
Quick reference
Where to go next
Quickstart
Make your first call.
API Reference
Every endpoint in detail.
MCP Guide
Give an AI agent access to the graph.