Skip to main content
POST
List the people connected to a person

Authorizations

Authorization
string
header
required

An API key, orbb_sk_…, created in the console; or the console’s session token. See Authentication.

Body

application/json
id
string
required

Names the person whose connections are listed: a LinkedIn profile URL, or the public identifier from one (the part after /in/). Spaces around it are ignored; a blank value is answered 400 invalid_body. An id no person matches is answered 404 person_not_found; one that several people have held, 422 ambiguous_person with candidates.

A LinkedIn member token (ACoAA…) is not a public identifier: it is answered 404 person_not_found.

See also /v1/resolve, to find the id from an email or a name.

Required string length: 1 - 512
types
enum<string>[]

Restricts the answer to these connection types: CAREER (worked at the same company at the same time), EDUCATION (studied at the same school), INVESTOR (held investor roles at the same companies), LINKEDIN_COMMENTS (one commented on the other’s LinkedIn post). An empty array, or a member that is not a connection type, is answered 400 invalid_types.

A type listed twice counts once. With on_miss: RESEARCH, only the listed types are researched.

See also on_miss.

Default: every type.

Required array length: 1 - 64 elements
Available options:
CAREER,
EDUCATION,
INVESTOR,
LINKEDIN_COMMENTS
Maximum string length: 64
min_strength
number
default:0

Leaves out people whose connection strength is below this value; stronger connections score higher, and 0 keeps everyone. A value outside the range is answered 400 invalid_min_strength.

total and the pages count only the people kept.

See also limit, cursor.

Required range: 0 <= x <= 1
limit
integer
default:25

Sets the maximum number of people returned in one answer. A value outside the range, or one that is not an integer, is answered 400 invalid_limit.

When more people match, the answer carries next_cursor; pass it as cursor with the same body to read the next page. People are ordered by strength, strongest first.

See also cursor.

Required range: 1 <= x <= 100
cursor
string

Continues a listing from the previous answer’s next_cursor, with the rest of the body unchanged. Absent or blank reads the first page. A value that does not decode as a cursor is answered 400 invalid_cursor.

A cursor is a position in the order, not a query: one from another query, or with other types or min_strength, is not refused and starts at that position in the new order.

Each page reads the data as it stands at that call, so a connection whose strength changed between pages can be listed twice or not at all.

See also limit, next_cursor.

Maximum string length: 512
on_miss
enum<string>
default:UNKNOWN

Sets what happens to a requested type not yet researched for the people asked about. UNKNOWN answers from what is known and reports the type in the answer’s coverage; RESEARCH researches the requested types first, then answers. Any other value is answered 400 invalid_body.

RESEARCH takes longer, and is more often answered 202 with a job to read through /v1/job. A type researched recently is mostly not researched again; on circle and paths, force researches it anyway.

See also max_tokens, force, /v1/job, Jobs, Billing, Rate limits.

Available options:
UNKNOWN,
RESEARCH
force
boolean
default:false

With on_miss: RESEARCH, researches every requested type again, even one researched recently. Without RESEARCH it has no effect, and is not refused.

See also on_miss, types.

max_tokens
number

Sets the tokens reserved for research on top of the call’s price. Taken only with on_miss: RESEARCH: with any other on_miss, even within the range, it is answered 400 invalid_max_tokens; so is a value outside the range, or one with more than 3 decimals.

The range starts above zero: to research nothing, leave out RESEARCH.

See also on_miss, Billing.

Default: 2 with on_miss: RESEARCH.

Required range: 0.001 <= x <= 600

Response

A page of the person’s connections.

subject
object
required

The person whose connections are listed: id of a circle, target of paths.

research_state
object
required

What research the API has done for the subject.

hit
enum<string>
required

RESEARCHED when the last research of every requested type completed for the subject and none is out of date; UNKNOWN otherwise, a research running now included (for a person known under several ids, see research_state.status).

Available options:
RESEARCHED,
UNKNOWN
basis
enum<string>
required

What the answer is based on. NETWORK_ONLY, the only value today: connections inferred from public professional profiles and activity.

Available options:
NETWORK_ONLY
coverage
object
required

For each requested type, what the subject’s research found, with the limits that apply to the whole answer.

data
object[]
required

The page of connections, strongest first. It can hold fewer than limit entries even when next_cursor is present.

total
number
required

The number of connections that match types and min_strength; the pages can list fewer. Counting stops at a cap; see total_capped.

total_capped
boolean
required

True when counting stopped at the cap: there are at least total connections.

generated_at
string<date-time>
required

When the answer was made. For an answer read through /v1/job, earlier than the read.

next_cursor
string

Present when more connections follow; absent on the last page. See cursor.