Skip to main content
POST
Tell whether two people know each other

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
a
string
required

Names one person of the pair, in the forms /v1/circle’s id takes. Spaces around it are ignored; a blank value is answered 400 invalid_body. A value no person matches is answered 404 person_not_found; one that several people have held, 422 ambiguous_person with candidates.

a equal to b is answered 400 same_person before any job starts. Two different values that name the same person, such as a URL and its public identifier, are answered 400 same_person once the job has matched them.

See also b, /v1/circle.

Required string length: 1 - 512
b
string
required

Names the other person of the pair, in the forms /v1/circle’s id takes. The values and refusals are those of a: 404 person_not_found, 422 ambiguous_person, and 400 same_person when it names the same person as a.

See also a, /v1/circle.

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
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
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

The connection between a and b.

verdict
enum<string>
required

Whether the two people likely know each other. LIKELY_KNOW: a comment between them was found. POSSIBLE: another requested type was found. NO_EVIDENCE_FOUND: every requested type that can be checked was checked, with nothing found. UNKNOWN: none of these; verdict_reason says why.

Available options:
LIKELY_KNOW,
POSSIBLE,
NO_EVIDENCE_FOUND,
UNKNOWN
verdict_reason
enum<string>
required

Why the verdict is what it is: DIRECT_INTERACTION for LIKELY_KNOW, SHARED_HISTORY for POSSIBLE, SEARCHED_NO_RESULT for NO_EVIDENCE_FOUND; for UNKNOWN, UNAVAILABLE when the research of a type failed in this call, otherwise NOT_EXAMINED.

Available options:
DIRECT_INTERACTION,
SHARED_HISTORY,
SEARCHED_NO_RESULT,
UNAVAILABLE,
NOT_EXAMINED
evidence
object[]
required

One entry per requested type found, with what was found.

counter_evidence
object[]
required

What weighs against the evidence found. Empty when nothing does.

coverage
object
required

For each requested type, whether the pair was checked and what was found, with the limits that apply.

hit
enum<string>
required

RESEARCHED when at least one requested type was found or checked for the pair; UNKNOWN otherwise.

Available options:
RESEARCHED,
UNKNOWN
a
object
required

The person given as a; the subject of the evidence.

b
object
required

The person given as b.

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
strength
object

Present only when a requested type is found. Its absence is not a zero: verdict says what is known.

observed_at
string<date-time>

When the newest evidence was observed; with none, when the newest check that found nothing was made. Absent when there is neither.