List the calling user's own relationships, ranked by their RQ.

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

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

fetch('https://production-api.joinrings.com/v1/relationships/mine', 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/mine",
  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/mine"

	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/mine")

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

My relationships

Served from a per-user precomputed relationship cache. This is the individual counterpart to GET /v1/relationships: it returns only the people the bound user knows, sorted by that user’s own relationship_quality, and skips the team aggregation / overlay enrichment that the ring-wide endpoint does.

Supports the same person_city / person_state / person_country location filters as GET /v1/relationships.

Requires a user-bound API key (USER-scoped, or a tenant key with the x-rings-user-id header) — returns 400 otherwise. Returns an empty list when the user has no relationships yet.

GET

relationships

mine

List the calling user's own relationships, ranked by their RQ.

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

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

fetch('https://production-api.joinrings.com/v1/relationships/mine', 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/mine",
  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/mine"

	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/mine")

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

My relationships

Authorizations

Query Parameters

Response