List the tenant's ring relationships, ranked by relationship strength.

curl --request GET \
  --url https://production-api.joinrings.com/v1/relationships \
  --header 'x-api-key: <api-key>'

const options = {method: 'GET', headers: {'x-api-key': '<api-key>'}};

fetch('https://production-api.joinrings.com/v1/relationships', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://production-api.joinrings.com/v1/relationships",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "x-api-key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://production-api.joinrings.com/v1/relationships"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("x-api-key", "<api-key>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://production-api.joinrings.com/v1/relationships")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["x-api-key"] = '<api-key>'

response = http.request(request)
puts response.read_body

{
  "items": [
    {}
  ],
  "page": 123,
  "per_page": 123,
  "total": 123
}

Relationships

List ring relationships

Served from a precomputed relationship cache (refreshed every ~2h), so it can sort by relationship_quality (RQ) and PathPower — unlike the live persons list, which only sorts by name or last activity date. Each item is one external person with their embedded primary company, RQ, PathPower, priority signals, AI scores, entity lists and emails.

Filter by location with person_city, person_state, person_country (AND). Spell the state (Florida) or pass a two-letter code with person_country (FL + US); a code alone returns 400. Prefer these over paging the list and filtering client-side.

Internal ring members are excluded. Returns 503 while that cache has not been built for the tenant yet.

GET

relationships

List the tenant's ring relationships, ranked by relationship strength.

curl --request GET \
  --url https://production-api.joinrings.com/v1/relationships \
  --header 'x-api-key: <api-key>'

const options = {method: 'GET', headers: {'x-api-key': '<api-key>'}};

fetch('https://production-api.joinrings.com/v1/relationships', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://production-api.joinrings.com/v1/relationships",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "x-api-key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://production-api.joinrings.com/v1/relationships"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("x-api-key", "<api-key>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://production-api.joinrings.com/v1/relationships")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["x-api-key"] = '<api-key>'

response = http.request(request)
puts response.read_body

{
  "items": [
    {}
  ],
  "page": 123,
  "per_page": 123,
  "total": 123
}

Authorizations

x-api-key

string

header

required

Query Parameters

page

integer

default:1

Page number, 1-indexed. Clamped to >= 1.

per_page

integer

default:10

Results per page (default 10). Clamped to the range 1-50 (values outside are silently capped, not rejected).

after

string | null

Opaque cursor from a previous response's next_cursor. When supplied, the page starts immediately after the last record of that response and page is ignored — unlike page, this cannot skip or repeat records when the data changes mid-scan. Filters and sort must stay identical for the whole scan; changing one is a 400. Not supported by every list endpoint — those that support it return next_cursor.

sort_by

string | null

Field to sort by. Common values: 'relationship_quality', 'priority_score', 'last_activity_date' (default), 'company_score', 'person_name', 'company_name' — but any relationship field works (e.g. 'job_title', 'oldest_signal_created_at'). 'relationship_quality'/'priority_score' are aliases for the underlying 'highest_rq'/'highest_priority_score' columns. An unrecognized value silently falls back to 'last_activity_date' rather than erroring.

order

enum<string>

default:desc

Sort order. Valid values: 'asc' (ascending) or 'desc' (descending).

Available options:

asc,

desc

relationship_quality

string | null

Comma-separated integers (1-3) to filter by exact match against each person's highest Relationship Quality (RQ) score across the ring.

priority_score

string | null

Comma-separated integers (1-3) to filter by exact match against each person's highest Priority Score across the ring.

company_score_from

integer | null

Filter by the person's primary company's AI score (company_score). Exclusive bound: matches scores strictly greater than this value (not >=).

company_score_to

integer | null

Filter by the person's primary company's AI score (company_score). Exclusive bound: matches scores strictly less than this value (not <=).

person_city

string | null

Case-insensitive substring on the person's city (e.g. 'Los Angeles'). AND with person_state / person_country.

person_state

string | null

Person's state/region. Full name ('Florida') works on its own. A two-letter code ('FL', 'NY') is ISO 3166-2 and requires person_country ('FL' + country=US → Florida); a code without country returns 400. AND with city/country.

person_country

string | null

Person's country, name or ISO code ('US', 'United States'). Required next to a two-letter person_state. AND with city/state. Returns 400 if unrecognized.

Response

200 - application/json

A page of relationships, ranked by relationship strength.

Each item in items is one external person with their primary company, relationship quality (RQ), PathPower, priority signals, AI scores, entity list memberships, and emails. total is the number of relationships matching the request across all pages.

items

Items · object[]

required

page

integer

required

per_page

integer

required

total

integer | null

Introduction

Person

Company

Opportunity

Activity

Meetings

Note

Task

Recommended Paths

PathPower

Relationships

AI Summary

Entity Lists

Users

List ring relationships

Authorizations

Query Parameters

Response