Rings AI

associations and optional per-note idempotency. Each entry is created independently using the same path as `POST /v1/notes` (full body, excerpt, owner and inline `associations`). A single failing row comes back as status ERROR without sinking the rest of the batch; results are returned in input order. Supplying `idempotency_key` per note makes the import safely re-runnable: re-submitting the same key returns the existing note (status SKIPPED) instead of creating a duplicate. This is the note half of the bulk import flow — create the people first via `POST /v1/persons/batch`, then attach their notes here. A person/company created moments earlier may not yet be visible to this endpoint — newly written records become readable after a short sync delay. If a note's association can't be resolved, that note is NOT created and is returned with status ERROR and a retryable message — wait briefly for the entity to sync, then re-submit the same `idempotency_key`.

post_create_notes_batch

Use this instead of repeated `POST /v1/opportunities` calls whenever 2+ records are created, e.g. importing deals from a spreadsheet or adding attendee sub-opportunities under an event. Each item takes the same fields as the single-record endpoint: name, type_uuid and stage_uuid required; associations, custom_fields, parent_uuid, owner_user_uuid and the rest optional. Resolve the type and stage once (GET /v1/opportunity-types and GET /v1/opportunity-types/{type_uuid}/stages) and companies/people with the lookup batch endpoints before calling this. Items are created in order, each on its own, and returned in input order with a `status`: CREATED with the new `uuid`, or ERROR with the message the single endpoint would have returned (e.g. "Unknown stage_uuid"). One bad item never fails the others and leaves no row behind. Never resend an item that came back CREATED; that makes a duplicate. A sub-opportunity needs an existing parent: create the parent first and pass its uuid as `parent_uuid`. A person or company created moments ago may come back as "Association target not found"; retry just those items shortly. Returns 400 for an empty list or more than 100 items.

post_create_opportunities_batch

Required fields: name, type_uuid, stage_uuid. If the user hasn't specified an opportunity type or stage, ask them before calling this endpoint. To discover valid IDs, first call GET /v1/opportunity-types to choose a type_uuid (and inspect its pinning_config to learn whether a person/company association is required), then call GET /v1/opportunity-types/{type_uuid}/stages to choose a stage_uuid for that type. A stage_uuid is only valid for the type_uuid it belongs to. Optional: details, value, probability, source_date, intro_date, close_date, intro_person_uuid, owner_user_uuid, associations (to link persons/companies). owner_user_uuid takes a user uuid from GET /v1/users; the person uuid an existing opportunity reports under `owner` is accepted too. Defaults to the calling user. An owner that resolves to neither returns 400, as does an intro_person_uuid that isn't a person in the tenant. An association target that can't be found returns 404 and nothing is created. Returns the new opportunity UUID and timestamps on success (201). To create 2+ opportunities, use `POST /v1/opportunities/batch` instead.

post_create_opportunity

All fields are optional. If the provided `email` matches an existing person in the tenant, the existing record is updated in place and its UUID is returned (deduplication by email). Returns the UUID and rings_updated_at timestamp on success.

post_create_person

For each entry: if `email` or `linkedin_url` matches an existing tenant-visible person, that person is returned (status MATCHED) without a write; otherwise a new tenant-source record is created (status CREATED). This mirrors the matching of `GET /v1/persons/lookup` and the dedupe of `POST /v1/persons` — the per-item create runs the same `upsert_person` path, so a batch entry behaves exactly like a single create. Items are processed independently — a single failing row comes back as status ERROR without sinking the rest of the batch. Results are returned in input order. Duplicate identifiers within the same batch resolve to one record: a later row sharing an email/linkedin_url with an earlier row comes back MATCHED against the first row's UUID rather than creating a second person (an earlier create isn't yet visible to the matcher mid-batch). This is the bulk primitive for an import flow: look people up first (`POST /v1/persons/lookup/batch`), then create the unmatched remainder here, then attach notes (`POST /v1/notes/batch`).

post_create_persons_batch

Creates a task and optionally assigns it to users and associates it with entities (persons, companies, opportunities, etc.) in a single atomic operation. Returns the new task id on success. Enum values (case-sensitive, uppercase): - status: DRAFT | ACTIVE | COMPLETED | ARCHIVED (default: ACTIVE) - priority: LOW | MEDIUM | HIGH - visibility: RING (all tenant members) | PERSONAL (creator only, default: RING) - reminder_type: MINUTES | HOURS | DAYS | WEEKS (requires reminder_value)

post_create_task_endpoint

Returns 404 when the intro doesn't exist or was found in an email you can't access.

delete_delete_intro

Only the note's owner or a ringmaster may delete it. Returns 204 on success, 404 when the note isn't visible to the caller's tenant, and 403 when the caller is neither the owner nor a ringmaster.

delete_delete_note

Returns 204 on success and 404 when the association doesn't exist or doesn't belong to the referenced note.

delete_delete_note_association

Removes the caller's tenant-scoped opportunities for the given UUIDs, cascades to their sub-opportunities (deleting a parent deletes every descendant in the same ring), then deletes any associations that reference the removed rows (as either the association parent or the associated entity). The cascade only ever touches rows and associations for UUIDs actually deleted from this tenant's ring, so a UUID belonging to another tenant can't have its associations wiped even if it's included in the request. UUIDs that don't resolve to a tenant-scoped opportunity are silently skipped (not an error) -- `deleted_count` reports how many opportunities were actually removed, including cascaded sub-opportunities. Always returns 200, even when `deleted_count` is 0. Returns 400 if more than 100 UUIDs are submitted in one request (the cap applies to the requested UUIDs, not the cascade).

delete_delete_opportunities

Returns 204 on success, 404 if the association doesn't exist or doesn't belong to the referenced opportunity. To remove 2+ links, use `DELETE /v1/opportunities/associations/batch` instead.

delete_delete_opportunity_association

`current_company` reads as null afterward. Returns 204 on success (including when the person had no current company to begin with), and 404 if the person UUID is not visible to your tenant.

delete_remove_current_company

Removes membership only — the companies or persons themselves are untouched. Idempotent: a UUID that isn't currently a member is omitted from the response's `entity_uuids`, which reports only the memberships this call removed. Returns 404 when the list doesn't exist for the API key's tenant, and 409 when the list's membership is rule-owned (a dynamic list whose members Rings updates automatically, which would restore the entity).

delete_remove_entity_list_members

Use this instead of repeated `DELETE /v1/opportunities/{uuid}/associations/{association_uuid}` calls. Name each link by `{opportunity_uuid, association_uuid}`, or by `{opportunity_uuid, entity_uuid, entity_type}` when you know the linked record but not the association uuid. Results come back in input order with a `status`: REMOVED, NOT_FOUND (no such link on that opportunity — nothing deleted) or ERROR (`error` says why). One bad item never fails the others. Removing a pinned link does not pin another. Returns 400 for an empty list or more than 100 items.

delete_remove_opportunity_associations_batch

PERSONAL tasks can only be deleted by their creator; RING tasks can be deleted by any tenant member.

delete_delete_task_endpoint

Returns 404 when the association doesn't exist or doesn't belong to the given task.

delete_delete_task_association

The caller must be a participant on the email or hold delegated access to its mailbox, and the mailbox owner's mail connection must be active. Activity lists are not gated this way, so check `is_current_user_participant` on the list row before calling. Returns: - 403 without user context, for a non-email activity, or when the owner's mail connection is inactive - 404 when the caller may not read this email (retrying will not help) or the provider no longer has the message

get_get_activity_body

Scoped to the caller's tenant. Only emails are returned — calendar events don't belong to a thread. The response is metadata-only. Clients render a thread by fetching this list and then calling `/activities/{id}/body` for whichever messages they want to expand. Applies the same participant-or-delegated-access check as `/body`, so it is not a fallback when `/body` returns 404. Returns: - 403 without user context - 404 when the caller may not read this activity, it does not exist, or it has no thread

get_get_activity_thread

Parameters: - entity: person | company (required) - uuids: comma-separated list of entity UUIDs (max 100) Returns a score entry for every UUID in the input list. UUIDs with no PathPower data are included with score=null and strength_label=null. When score is present, strength_label is one of: weak, moderate, strong, very_strong (lowercase, underscore-separated PathPower bands).

get_get_bulk_pathpower

Returns the full company record including: - strongest_relationships: top 2 internal team members with the strongest connection into the company (use for "who internally knows Acme" without needing recommended-paths) - pathpower: overall relationship strength score (0.0-1.0) - next_meeting_at / my_next_meeting_at: the next scheduled meeting with anyone at the company, tenant-wide and for the calling user - last_activity_date, entity list memberships, industry tags, Rings AI operating and investor scores, custom field values, location and social URLs. Returns 404 if the company is not visible to your tenant.

get_get_company

Generates a live summary using the same pipeline as the web app. Returns 404 when the entity is not found.

get_get_company_ai_summary

Returns a paginated list of emails and calendar meetings where any participant is associated with the company, ordered by date descending. Filter parameters: - type: email | meeting — omit to return both - date_from: ISO date (YYYY-MM-DD), inclusive - date_to: ISO date (YYYY-MM-DD), inclusive Pagination: - page: Page number (default: 1) - per_page: Results per page (default: 10) - include_total: return total/total_is_approximate (default: false)

get_get_company_activities

"who internally knows people at this company" / "best path into" queries. Returns internal team members ranked by connection strength to people at the target company, each with 2-hop relationship paths. Use this to find who on the team can make introductions at a specific company. Each result includes the connector's name, relationship quality (rq), and the path hops linking them to contacts at the company. The response also carries a top-level `top_external_contacts` array — the company's top 5 external contacts ranked by PathPower, each with their role `tags` and two strongest internal connectors. This array is independent of pagination.

get_get_company_recommended_paths

Designed for MCP and AI agent clients that need to resolve "me", "my", or "I" into concrete UUIDs before calling other endpoints (e.g. fetching activity history or relationship data for the current user). Returns null fields when the API key is tenant-scoped with no user context.

get_get_me

Requires user context: the meeting is only returned when the calling user is an internal participant on it.

get_get_meeting

Tenant-scoped. Returns the full HTML body; if the body is temporarily unavailable the response falls back to the excerpt rather than erroring.

get_get_note

Returns the complete opportunity including stage, type, owner, intro person, associated persons and companies, custom fields, days in current stage, notes/files count, and activity dates. Returns 404 if the opportunity is not visible in the tenant's ring. Each associated person/company carries `city`, `state` and `country`, so an opportunity's geography can be read off the record itself instead of looking every association up individually.

get_get_opportunity

Each item records one move: `from_stage` -> `to_stage`, the timestamp it happened (`entered_at`), when the opportunity left that stage again (`exited_at`, null while it is still there), and how long it sat there (`days_in_stage`). The first transition of an opportunity has a null `from_stage` — that is the opportunity being created in its initial stage, not a move out of an unknown stage. Use this to answer pipeline-velocity questions ("how long did this deal spend in each stage", "where did it stall") that the point-in-time `days_in_stage` on `GET /v1/opportunities/{uuid}` can't. Stage names are resolved for stages that still exist in the tenant; a stage deleted since the transition returns its UUID with a null `name`. The full stage list for a type is available from `GET /v1/opportunity-types/{type_uuid}/stages`. Works for sub-opportunities as well as top-level ones. Returns 404 if the opportunity is not visible in the tenant's ring.

get_get_opportunity_stage_history

Returns the full person record including: - strongest_relationships: top 2 internal team members with the strongest connection to this person (use for "who internally knows X" without needing recommended-paths) - pathpower: overall relationship strength score (0.0–1.0) - priority_management.rq: the canonical relationship quality score (0–3). Ignore rq_manual and rq_math — use rq as the single source of truth. - Secondary emails, phone numbers, entity list memberships, company affiliation. Returns 404 if the person is not visible in the tenant's Explorer view.

get_get_person

Generates a live summary using the same pipeline as the web app. Returns 404 when the entity is not found.

get_get_person_ai_summary

Returns a paginated list of emails and calendar meetings where the person was a participant, ordered by date descending. Each item includes participants, from/to addresses (for emails), start/end times (for meetings), and attachment counts. Filter parameters: - type: email | meeting — omit to return both - date_from: ISO date (YYYY-MM-DD), inclusive - date_to: ISO date (YYYY-MM-DD), inclusive Pagination: - page: Page number (default: 1) - per_page: Results per page (default: 10) - include_total: return total/total_is_approximate (default: false)

get_get_person_activities

"who knows this person" / "introduce me to" / "path to" queries. Returns internal team members ranked by connection strength, each with 2-hop relationship paths showing how they connect to the target person. Use this instead of PathPower when you need actual introduction paths, not just a score. Each result includes the connector's name, relationship quality (rq), and the path hops linking them to the target.

get_get_person_recommended_paths

Returns the full task including assignments. PERSONAL tasks are only returned for their creator; RING tasks are visible to any tenant member. Returns 404 when the task doesn't exist or isn't visible to the caller.

get_get_task_endpoint

Returns a paginated list of companies visible to the tenant. All filter parameters are optional — omitting all of them returns all companies. Filters compose with AND; comma-separated values within a single filter are OR-matched. See each parameter for exact semantics. Filters cover identity (`name`, `domain`, `linkedin_url`, `description`, social URLs), location (`city`, `state`, `country`), status (`operating_status`, `acquisition_status`, `ipo_status`), industry tags, investor and funding attributes, and numeric/date ranges (founding year, employee count, Rings scores, investment dates). Use `uuids` (comma-separated) to hydrate a known set of companies in one call — this is the batched counterpart to `GET /v1/companies/{uuid}`. To resolve a company you only know by domain or name, use `GET /v1/companies/lookup` instead. Sort parameters: - sort_by: name | last_activity_date (default: unsorted) - order: asc | desc (default: asc) Pagination: - page: Page number (default: 1) - per_page: Results per page, max 50 (default: 10) - after: Opaque cursor from a previous response's `next_cursor`. Resumes immediately after that response's last record, so concurrent writes can't shift rows between pages the way `page` allows. `total` is not computed on this path — use `has_more`. Every response carries `next_cursor`, including page-numbered ones, so a caller can start with `page` and switch to cursors mid-scan.

get_list_companies

Company reads return custom field values in `company_custom_fields`, keyed by each field's `key` (e.g. `sector_1697011571764_3`), not its `uuid`. Use this to find out what each key means — its display `name`, `type` and, for selects, the allowed `choices` — and to find the `key` to write a value under. Definitions rarely change, so fetch them once rather than per company.

get_list_company_custom_fields

Use `GET /v1/companies?uuids=...` or `GET /v1/persons?uuids=...` to hydrate the returned UUIDs into full records, depending on the list's `kind` (from `GET /v1/lists`). `city`, `state` and `country` filter members by where they are based — "who on this list is in LA" in one call, instead of paging every member and hydrating each one to check. They AND together. Members with no location on record are excluded when a location filter is set.

get_list_entity_list_members

Filter parameters (all optional): - name: Exact (case-sensitive) name match - search: Case-insensitive substring search on name - kind: PERSON or COMPANY

get_list_entity_lists

`is_positive` marks outcomes that count as a successful intro in `/v1/intros/insights`. Outcome and source type values here are what `outcome` and `source_type` accept on the other intro endpoints.

get_list_intro_options

Not for finding who *could* make an intro; use recommended paths for that. Typical uses: how the firm met someone (`entity_uuid` + `order=asc`), every intro a person made for the firm (`introducer_uuid`), or intros still waiting on an outcome (`has_outcome=false`). Resolve names to UUIDs first with the lookup endpoints; there is no free-text search here.

get_list_intros

Only meetings where the user appears as an internal calendar participant (same scope as in-app meeting tools) are returned. Supports filtering by date range, participant person/company, and title search. Results are sorted by start time descending (most recent first).

get_list_meetings