> ## Documentation Index
> Fetch the complete documentation index at: https://docs.orbb.com/llms.txt
> Use this file to discover all available pages before exploring further.

# List the people connected to a person

> Body: `{ "id": … }`, plus the optional fields below.

Lists the people connected to one person, strongest first, a page at a time. Each entry carries the other person, the verdict and strength of the connection, and its evidence; the answer also says what research has been done for the person.

Checked in order: the body (`400 invalid_body`), `limit`, `min_strength`, `cursor`, `types`, `max_tokens`; with `on_miss: RESEARCH` only, the research and resolve jobs still running (`429 research_busy`); then, for every call, the balance (`402`).

See also [`/v1/paths`](/api-reference/paths), [`/v1/resolve`](/api-reference/resolve), [Jobs](/api/jobs), [Billing](/api/billing), [Rate limits](/api/rate-limits).



## OpenAPI

````yaml POST /v1/circle
openapi: 3.1.0
info:
  title: Orbb API
  version: v1
  description: >-
    Who knows whom, and how well: the people connected to a person, the
    connection between two people, and the person behind an email or a name.
    Every call is a `POST` with a JSON body, except `GET /v1/openapi.json`.


    Read [Authentication](/api/authentication), [Errors](/api/errors),
    [Jobs](/api/jobs), [Billing](/api/billing) and [Rate
    limits](/api/rate-limits) before your first integration.
servers:
  - url: https://api.orbb.com
    description: Production
security:
  - bearer: []
paths:
  /v1/circle:
    post:
      summary: List the people connected to a person
      description: >-
        Body: `{ "id": … }`, plus the optional fields below.


        Lists the people connected to one person, strongest first, a page at a
        time. Each entry carries the other person, the verdict and strength of
        the connection, and its evidence; the answer also says what research has
        been done for the person.


        Checked in order: the body (`400 invalid_body`), `limit`,
        `min_strength`, `cursor`, `types`, `max_tokens`; with `on_miss:
        RESEARCH` only, the research and resolve jobs still running (`429
        research_busy`); then, for every call, the balance (`402`).


        See also [`/v1/paths`](/api-reference/paths),
        [`/v1/resolve`](/api-reference/resolve), [Jobs](/api/jobs),
        [Billing](/api/billing), [Rate limits](/api/rate-limits).
      operationId: circle
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CircleBody'
            example:
              id: maya-okafor
              limit: 2
      responses:
        '200':
          description: A page of the person’s connections.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
            RateLimit-Limit:
              $ref: '#/components/headers/RateLimit-Limit'
            X-Orbb-Reserved:
              $ref: '#/components/headers/X-Orbb-Reserved'
            X-Orbb-Balance:
              $ref: '#/components/headers/X-Orbb-Balance'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CircleAnswer'
              example:
                subject:
                  key: maya-okafor
                  publicId: maya-okafor
                  full_name: Maya Okafor
                  role: VP Engineering
                  company: Northwind Labs
                  companyPublicId: company/northwind-labs
                  resolution:
                    status: RESOLVED
                    method: PUBLIC_ID
                research_state:
                  status: RESEARCHED
                  types:
                    - type: CAREER
                      coverage: EXAMINED
                      stale: false
                    - type: EDUCATION
                      coverage: NOT_EXAMINED
                      stale: false
                    - type: INVESTOR
                      coverage: SEARCHED_NO_RESULT
                      stale: false
                    - type: LINKEDIN_COMMENTS
                      coverage: EXAMINED
                      stale: false
                hit: UNKNOWN
                basis: NETWORK_ONLY
                coverage:
                  examined:
                    - CAREER
                    - LINKEDIN_COMMENTS
                  searched_no_result:
                    - INVESTOR
                  unavailable: []
                  not_examined:
                    - EDUCATION
                  limits:
                    - type: EDUCATION
                      reason: NEVER_ALONE
                    - type: LINKEDIN_COMMENTS
                      reason: NO_LIVE_SEARCH
                data:
                  - person:
                      key: daniel-reyes
                      publicId: daniel-reyes
                      full_name: Daniel Reyes
                      role: Head of Partnerships
                      company: Contoso
                      companyPublicId: company/contoso
                    verdict: LIKELY_KNOW
                    verdict_reason: DIRECT_INTERACTION
                    strength:
                      value: 0.72
                      label: STRONG
                      witnesses:
                        career: 0.61
                        linkedin_comments: 0.5
                    evidence:
                      - type: CAREER
                        score: 0.61
                        summary: Worked together at Fabrikam for 3 years, until 2023
                        sources:
                          - provider: LINKEDIN_PROFILES
                            observed_at: '2026-10-02T08:14:00.000Z'
                        overlap_days: 1126
                        days_since_worked_together: 1050
                        company_count: 1
                        companies:
                          - public_id: company/fabrikam
                            name: Fabrikam
                            from: 2020-09
                            to: 2023-10
                      - type: LINKEDIN_COMMENTS
                        score: 0.5
                        summary: >-
                          1 LinkedIn comment between them; the best is rated
                          good
                        sources:
                          - provider: LINKEDIN_POST_COMMENTS
                            observed_at: '2026-09-23T03:28:41.496Z'
                        classification: good
                        comment_count: 1
                        comments:
                          - by: daniel-reyes
                            'on': maya-okafor
                            url: >-
                              https://www.linkedin.com/feed/update/urn:li:ugcPost:0000000000000000001?commentUrn=example
                            post_url: >-
                              https://www.linkedin.com/feed/update/urn:li:ugcPost:0000000000000000001
                            classification: good
                            confidence: 0.81
                            date: '2026-08-14T17:02:11.000Z'
                    counter_evidence: []
                    coverage:
                      examined:
                        - CAREER
                        - LINKEDIN_COMMENTS
                      searched_no_result:
                        - INVESTOR
                      unavailable: []
                      not_examined:
                        - EDUCATION
                      limits: []
                    hit: RESEARCHED
                    observed_at: '2026-10-02T08:14:00.000Z'
                  - person:
                      key: priya-natarajan
                      publicId: priya-natarajan
                      full_name: Priya Natarajan
                      role: Director of Product
                      company: Northwind Labs
                      companyPublicId: company/northwind-labs
                    verdict: POSSIBLE
                    verdict_reason: SHARED_HISTORY
                    strength:
                      value: 0.44
                      label: MODERATE
                      witnesses:
                        career: 0.44
                    evidence:
                      - type: CAREER
                        score: 0.44
                        summary: Work together at Northwind Labs, for 8 months so far
                        sources:
                          - provider: LINKEDIN_PROFILES
                            observed_at: '2026-10-02T08:14:00.000Z'
                        overlap_days: 243
                        days_since_worked_together: 0
                        company_count: 1
                        companies:
                          - public_id: company/northwind-labs
                            name: Northwind Labs
                            from: 2026-03
                    counter_evidence: []
                    coverage:
                      examined:
                        - CAREER
                      searched_no_result:
                        - INVESTOR
                        - LINKEDIN_COMMENTS
                      unavailable: []
                      not_examined:
                        - EDUCATION
                      limits: []
                    hit: RESEARCHED
                    observed_at: '2026-10-02T08:14:00.000Z'
                next_cursor: eyJvZmZzZXQiOjJ9
                total: 214
                total_capped: false
                generated_at: '2026-11-16T13:34:10.280Z'
        '202':
          description: >-
            The answer is not ready: `job.status` is `PROCESSING`. Read it with
            `/v1/job`, passing `job.id`. See [Jobs](/api/jobs).
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
            RateLimit-Limit:
              $ref: '#/components/headers/RateLimit-Limit'
            X-Orbb-Reserved:
              $ref: '#/components/headers/X-Orbb-Reserved'
            X-Orbb-Balance:
              $ref: '#/components/headers/X-Orbb-Balance'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JobAnswer'
              example:
                job:
                  id: qry_6720f0c2a1b2c3d4e5f60718
                  status: PROCESSING
        '400':
          description: >-
            Bad Request.


            - `invalid_body`: The body could not be parsed (not valid JSON,
            larger than 16 kB, or not received in full), or does not match the
            operation’s body. See [Errors](/api/errors). Fix the body. `detail`
            names the field when there is one.


            - `invalid_limit`: `limit` is outside its range, or is not an
            integer. Send a `limit` within the range, or leave it out.


            - `invalid_types`: `types` is empty, or holds a member that is not a
            connection type. Send known types, or leave `types` out for every
            type.


            - `invalid_min_strength`: `min_strength` is outside its range. Send
            a value within the range, or leave it out.


            - `invalid_cursor`: `cursor` does not decode as a cursor. Pass an
            answer’s `next_cursor` as given, or leave `cursor` out to read the
            first page.


            - `invalid_max_tokens`: `max_tokens` is outside its range, has more
            than 3 decimals, or is sent without `on_miss: RESEARCH`. Fix the
            value, or leave it out.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
            RateLimit-Limit:
              $ref: '#/components/headers/RateLimit-Limit'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: >-
            Unauthorized.


            - `invalid_session`: A token in the form of a session token (three
            parts separated by dots) was refused: expired, or not a session of
            the console. Sign in to the console again, or use an API key.


            - `invalid_api_key`: The `Authorization` header is missing or is not
            `Bearer <token>`, or the key is unknown, revoked or expired. The
            answer is the same whatever the reason. Check the key, or create a
            new one in the console.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '402':
          description: >-
            Payment Required.


            - `insufficient_balance`: The balance does not cover what the call
            reserves. Top up the balance, or lower `max_tokens`. See
            [Billing](/api/billing).


            - `billing_account_missing`: The account has no billing account yet.
            Create an API key in the console: the first key opens the billing
            account.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
            RateLimit-Limit:
              $ref: '#/components/headers/RateLimit-Limit'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: >-
            Not Found.


            - `person_not_found`: No person can be found by the id given. Check
            the id.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
            RateLimit-Limit:
              $ref: '#/components/headers/RateLimit-Limit'
            X-Orbb-Reserved:
              $ref: '#/components/headers/X-Orbb-Reserved'
            X-Orbb-Balance:
              $ref: '#/components/headers/X-Orbb-Balance'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          description: >-
            Unprocessable Entity.


            - `ambiguous_person`: Several people have held the id given;
            `candidates` lists them. Name the person by a candidate’s `publicId`
            instead.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
            RateLimit-Limit:
              $ref: '#/components/headers/RateLimit-Limit'
            X-Orbb-Reserved:
              $ref: '#/components/headers/X-Orbb-Reserved'
            X-Orbb-Balance:
              $ref: '#/components/headers/X-Orbb-Balance'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error: ambiguous_person
                candidates:
                  - key: jo-doe
                    publicId: jo-doe
                    full_name: Jo Doe
                    role: CEO
                    company: Acme
                  - key: jo-doe-1
                    publicId: jo-doe-1
                    full_name: Jo Doe
                    role: Engineer
                detail: Several people match. Retry with one candidate's id.
                request_id: 6720f0c2a1b2c3d4e5f60718
        '429':
          description: >-
            Too Many Requests.


            - `rate_limited`: The account made more calls in the last minute
            than `RateLimit-Limit` allows. Wait `Retry-After` seconds, then
            repeat the same request.


            - `too_many_concurrent`: The account has too many calls waiting for
            an answer at once. Wait for a call to be answered, or `Retry-After`
            seconds, then repeat the same request.


            - `research_busy`: The account has too many research and resolve
            jobs still running. Wait for a job to end, or `Retry-After` seconds,
            then call again. See [Rate limits](/api/rate-limits).
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
            RateLimit-Limit:
              $ref: '#/components/headers/RateLimit-Limit'
            Retry-After:
              $ref: '#/components/headers/Retry-After'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '503':
          description: >-
            Service Unavailable.


            - `unavailable`: The API could not complete the call, or could not
            check the token or the rate limits. Repeat the same request, backing
            off.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
            RateLimit-Limit:
              $ref: '#/components/headers/RateLimit-Limit'
            X-Orbb-Reserved:
              $ref: '#/components/headers/X-Orbb-Reserved'
            X-Orbb-Balance:
              $ref: '#/components/headers/X-Orbb-Balance'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    CircleBody:
      type: object
      properties:
        id:
          description: >-
            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`](/api-reference/resolve), to find the id
            from an email or a name.
          type: string
          minLength: 1
          maxLength: 512
        types:
          minItems: 1
          x-default: every type
          description: >-
            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.
          maxItems: 64
          type: array
          items:
            enum:
              - CAREER
              - EDUCATION
              - INVESTOR
              - LINKEDIN_COMMENTS
            type: string
            maxLength: 64
        min_strength:
          minimum: 0
          maximum: 1
          description: >-
            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`.
          default: 0
          type: number
        limit:
          type: integer
          minimum: 1
          maximum: 100
          description: >-
            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`.
          default: 25
        cursor:
          description: >-
            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`.
          type: string
          maxLength: 512
        on_miss:
          description: >-
            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`](/api-reference/job),
            [Jobs](/api/jobs), [Billing](/api/billing), [Rate
            limits](/api/rate-limits).
          default: UNKNOWN
          type: string
          enum:
            - UNKNOWN
            - RESEARCH
        force:
          description: >-
            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`.
          default: false
          type: boolean
        max_tokens:
          minimum: 0.001
          maximum: 600
          x-default: '`2` with `on_miss: RESEARCH`'
          description: >-
            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](/api/billing).


            Default: `2` with `on_miss: RESEARCH`.
          type: number
      required:
        - id
      additionalProperties: false
    CircleAnswer:
      type: object
      properties:
        subject:
          description: >-
            The person whose connections are listed: `id` of a circle, `target`
            of paths.
          type: object
          properties:
            key:
              description: >-
                The person’s key: the public identifier percent-decoded and
                lower-cased. Two people in the answers are the same person when
                their keys are equal.
              type: string
            publicId:
              description: >-
                The person’s current LinkedIn public identifier, the part after
                `/in/` of the profile URL. It is a valid `id`, `a`, `b` or
                `target` in any call. For a person with no known profile, the
                identifier as the call gave it, in the form of `key`.
              type: string
            full_name:
              description: The person’s name. Absent when no known profile carries one.
              type: string
            role:
              description: >-
                The title of the person’s current position; without one, the
                profile’s headline. Absent when the profile has neither, or no
                profile is known.
              type: string
            company:
              description: >-
                The name of the company of the current position shown. Absent
                when unknown.
              type: string
            companyPublicId:
              description: >-
                The LinkedIn page of that company, as `company/<slug>`, or
                `showcase/<slug>` for a showcase page. Absent when unknown.
              type: string
            resolution:
              description: How the id given in the call was matched to this person.
              type: object
              properties:
                status:
                  description: >-
                    `RESOLVED`: one profile matches. `AMBIGUOUS`: several
                    profiles match, listed in `candidates`. `UNRESOLVED`: no
                    profile matches.


                    In circle, edge and paths answers it is `RESOLVED`, or
                    `UNRESOLVED` for a person with no known profile whose
                    connections are known under the id given; an ambiguous id is
                    answered `422 ambiguous_person` instead.
                  type: string
                  enum:
                    - RESOLVED
                    - AMBIGUOUS
                    - UNRESOLVED
                method:
                  description: >-
                    What answered: `EMAIL` (the email), `NAME_COMPANY` (a search
                    by name, the name sent or one taken from the email, run
                    without an email or after the email alone found no one),
                    `PUBLIC_ID` (a public identifier), `LINKEDIN_URL` (a profile
                    URL); an email or name search answered `UNRESOLVED` names
                    the form searched, `EMAIL` when an email was sent, else
                    `NAME_COMPANY`; a lookup by id keeps its identifier method
                    whatever the status.
                  type: string
                  enum:
                    - PUBLIC_ID
                    - LINKEDIN_URL
                    - EMAIL
                    - NAME_COMPANY
                candidates:
                  description: >-
                    With `AMBIGUOUS` only: every matching profile. See also `422
                    ambiguous_person`.
                  type: array
                  items:
                    type: object
                    properties:
                      key:
                        description: >-
                          The person’s key: the public identifier
                          percent-decoded and lower-cased. Two people in the
                          answers are the same person when their keys are equal.
                        type: string
                      publicId:
                        description: >-
                          The person’s current LinkedIn public identifier, the
                          part after `/in/` of the profile URL. It is a valid
                          `id`, `a`, `b` or `target` in any call. For a person
                          with no known profile, the identifier as the call gave
                          it, in the form of `key`.
                        type: string
                      full_name:
                        description: >-
                          The person’s name. Absent when no known profile
                          carries one.
                        type: string
                      role:
                        description: >-
                          The title of the person’s current position; without
                          one, the profile’s headline. Absent when the profile
                          has neither, or no profile is known.
                        type: string
                      company:
                        description: >-
                          The name of the company of the current position shown.
                          Absent when unknown.
                        type: string
                      companyPublicId:
                        description: >-
                          The LinkedIn page of that company, as
                          `company/<slug>`, or `showcase/<slug>` for a showcase
                          page. Absent when unknown.
                        type: string
                    required:
                      - key
                      - publicId
              required:
                - status
                - method
          required:
            - key
            - publicId
            - resolution
        research_state:
          description: What research the API has done for the subject.
          type: object
          properties:
            status:
              description: >-
                The research state of the subject over the requested types.
                `RESEARCHED`: the last research of at least one type completed,
                and none is out of date. `STALE`: one completed and is out of
                date. `NEVER_RESEARCHED`: none completed; each has not run, is
                running (a re-run included), or failed.


                For a person known under several ids, a completed research under
                any of them counts before a running or failed one under another.
              type: string
              enum:
                - RESEARCHED
                - NEVER_RESEARCHED
                - STALE
            types:
              description: One entry per requested type, in the order requested.
              type: array
              items:
                type: object
                properties:
                  type:
                    description: The connection type.
                    type: string
                    enum:
                      - CAREER
                      - EDUCATION
                      - INVESTOR
                      - LINKEDIN_COMMENTS
                  coverage:
                    description: >-
                      `EXAMINED`: the last research of the type completed, and
                      at least one connection of the type is known.
                      `SEARCHED_NO_RESULT`: it completed, and none is.
                      `UNAVAILABLE`: the last research of the type failed, even
                      when an earlier one completed. `NOT_EXAMINED`: no research
                      of the type has completed, or one is running now, a re-run
                      included.
                    type: string
                    enum:
                      - EXAMINED
                      - SEARCHED_NO_RESULT
                      - UNAVAILABLE
                      - NOT_EXAMINED
                  stale:
                    description: >-
                      Whether the research is old enough to be out of date.
                      Never true for `LINKEDIN_COMMENTS`, which is kept current
                      as comments are found.
                    type: boolean
                  depth:
                    description: >-
                      How deep the last research of the type read; for a failed
                      one, the part that ran. Absent while a research of the
                      type runs, when none has ended, and when the last one
                      failed as a whole.
                    type: string
                    enum:
                      - STANDARD
                  completed_at:
                    description: >-
                      When the last research of the type ended, completed or
                      failed. Absent while a research of the type runs, and when
                      none has ended.
                    format: date-time
                    type: string
                  truncated:
                    description: >-
                      True when the source cut the last research short, so
                      connections can be missing. Absent while a research of the
                      type runs, when none has ended, when the last one failed
                      as a whole, and when none was recorded.
                    type: boolean
                  candidates:
                    description: >-
                      How many people the last research of the type considered.
                      Absent while a research of the type runs, and when not
                      recorded.
                    type: number
                  judged:
                    description: >-
                      How many of those people it assessed. Absent while a
                      research of the type runs, and when not recorded.
                    type: number
                required:
                  - type
                  - coverage
                  - stale
          required:
            - status
            - types
        hit:
          description: >-
            `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`).
          type: string
          enum:
            - RESEARCHED
            - UNKNOWN
        basis:
          description: >-
            What the answer is based on. `NETWORK_ONLY`, the only value today:
            connections inferred from public professional profiles and activity.
          type: string
          enum:
            - NETWORK_ONLY
        coverage:
          description: >-
            For each requested type, what the subject’s research found, with the
            limits that apply to the whole answer.
          type: object
          properties:
            examined:
              description: >-
                The types with a connection found. For a circle’s subject:
                researched, with at least one connection of the type.
              type: array
              items:
                type: string
                enum:
                  - CAREER
                  - EDUCATION
                  - INVESTOR
                  - LINKEDIN_COMMENTS
            searched_no_result:
              description: >-
                The types checked with nothing found. For a circle’s subject:
                researched, with no connection of the type.
              type: array
              items:
                type: string
                enum:
                  - CAREER
                  - EDUCATION
                  - INVESTOR
                  - LINKEDIN_COMMENTS
            unavailable:
              description: >-
                The types whose research failed: for a pair, a research run in
                this call; for a circle’s subject, a type whose last research
                failed, even when an earlier one completed (for a person known
                under several ids, see `research_state.status`).
              type: array
              items:
                type: string
                enum:
                  - CAREER
                  - EDUCATION
                  - INVESTOR
                  - LINKEDIN_COMMENTS
            not_examined:
              description: >-
                The types not checked. For a circle’s subject: no research of
                the type has completed, or one is running now, a re-run included
                (for a person known under several ids, see
                `research_state.status`).


                For a pair, `LINKEDIN_COMMENTS` with no connection found is
                always here: no comment found does not mean that none exists.
              type: array
              items:
                type: string
                enum:
                  - CAREER
                  - EDUCATION
                  - INVESTOR
                  - LINKEDIN_COMMENTS
            limits:
              description: >-
                What limits the answer for a type, one entry per type and
                reason.


                The limits a type always has (`NO_LIVE_SEARCH`, `NEVER_ALONE`)
                are stated once per answer: in a circle or paths answer on the
                top-level `coverage`, not on each entry of `data`.
              type: array
              items:
                type: object
                properties:
                  type:
                    description: The type the limit applies to.
                    type: string
                    enum:
                      - CAREER
                      - EDUCATION
                      - INVESTOR
                      - LINKEDIN_COMMENTS
                  reason:
                    description: >-
                      `SOURCE_LIMITED`: the source cut the research short, or
                      the shared companies of a career connection can no longer
                      be shown. `NO_LIVE_SEARCH`: comments are read from those
                      already known; a call never searches for new ones.
                      `EXCLUDED_BY_SCAN`: the research run in this call left the
                      other person out, so the pair was not checked.
                      `NEVER_ALONE`: an education match is shown only next to
                      another type. `STALE`: the research or the check of the
                      type is old enough to be out of date.
                    type: string
                    enum:
                      - SOURCE_LIMITED
                      - NO_LIVE_SEARCH
                      - EXCLUDED_BY_SCAN
                      - NEVER_ALONE
                      - STALE
                required:
                  - type
                  - reason
          required:
            - examined
            - searched_no_result
            - unavailable
            - not_examined
            - limits
        data:
          description: >-
            The page of connections, strongest first. It can hold fewer than
            `limit` entries even when `next_cursor` is present.
          type: array
          items:
            type: object
            properties:
              verdict:
                description: >-
                  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.
                type: string
                enum:
                  - LIKELY_KNOW
                  - POSSIBLE
                  - NO_EVIDENCE_FOUND
                  - UNKNOWN
              verdict_reason:
                description: >-
                  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`.
                type: string
                enum:
                  - DIRECT_INTERACTION
                  - SHARED_HISTORY
                  - SEARCHED_NO_RESULT
                  - UNAVAILABLE
                  - NOT_EXAMINED
              strength:
                description: >-
                  Present only when a requested type is found. Its absence is
                  not a zero: `verdict` says what is known.
                type: object
                properties:
                  value:
                    description: >-
                      How strong the connection is, 0 to 1.


                      In circle and paths answers it covers every type, not only
                      the requested ones, and is what the listing is ordered by
                      and `min_strength` filters on. In an edge answer it covers
                      the requested types found.


                      Each type found sets a lower bound on `value`, its entry
                      in `witnesses`; a second type found can raise it.
                    type: number
                  label:
                    description: >-
                      The band the value falls in, from `WEAK` up to
                      `VERY_STRONG`. Rely on it rather than on fixed cut-offs of
                      `value`.
                    type: string
                    enum:
                      - VERY_STRONG
                      - STRONG
                      - MODERATE
                      - WEAK
                  witnesses:
                    description: >-
                      The score of each type found, on the scale of `value`, 0
                      to 1. A type not found has no entry.
                    type: object
                    properties:
                      career:
                        description: The `CAREER` score.
                        type: number
                      education:
                        description: The `EDUCATION` score.
                        type: number
                      investor:
                        description: The `INVESTOR` score.
                        type: number
                      linkedin_comments:
                        description: The `LINKEDIN_COMMENTS` score.
                        type: number
                required:
                  - value
                  - label
                  - witnesses
              evidence:
                description: One entry per requested type found, with what was found.
                type: array
                items:
                  type: object
                  properties:
                    type:
                      description: The connection type this evidence is for.
                      type: string
                      enum:
                        - CAREER
                        - EDUCATION
                        - INVESTOR
                        - LINKEDIN_COMMENTS
                    score:
                      description: The type’s score, 0 to 1, as in `strength.witnesses`.
                      type: number
                    model_score:
                      description: >-
                        The match score of the type: for `INVESTOR`, 0, 0.5 or 1
                        per shared organization, summed; for `EDUCATION`, how
                        closely the degree names match. Absent for the other
                        types.
                      type: number
                    summary:
                      description: >-
                        One sentence that states the evidence, for display. Not
                        meant to be parsed.
                      type: string
                    sources:
                      description: Where the evidence comes from, and when it was observed.
                      type: array
                      items:
                        type: object
                        properties:
                          provider:
                            description: >-
                              The profile source the other person’s profile was
                              read from; `LINKEDIN_POST_COMMENTS` for comments.
                              Absent when the other person has no known profile.
                            type: string
                            enum:
                              - LINKEDIN_PROFILES
                              - MAIN_DATASET
                              - OLD_DATASET
                              - LINKEDIN_POST_COMMENTS
                          observed_at:
                            format: date-time
                            description: When the evidence was observed.
                            type: string
                        required:
                          - observed_at
                    overlap_days:
                      description: >-
                        `CAREER` only: the days both worked at the shared
                        companies at the same time. Absent for the other types.
                      type: number
                    days_since_worked_together:
                      description: >-
                        `CAREER` only: the days since they last worked at the
                        same company at the same time.
                      type: number
                    company_count:
                      description: >-
                        `CAREER` only: the number of companies both worked at
                        together. It can be more than `companies` lists.
                      type: number
                    companies:
                      description: >-
                        `CAREER`: the shared employers, with the months both
                        were there. Empty when the profiles no longer show the
                        overlap; `coverage.limits` then carries
                        `SOURCE_LIMITED`.


                        `INVESTOR`: the organizations where both held founder,
                        board or investor roles.


                        Absent for the other types.
                      type: array
                      items:
                        type: object
                        properties:
                          public_id:
                            description: >-
                              The organization’s LinkedIn page, as
                              `company/<slug>`, or `showcase/<slug>` for a
                              showcase page.
                            type: string
                          name:
                            description: The organization’s name. Absent when unknown.
                            type: string
                          from:
                            description: >-
                              `CAREER` only: the first month both were there,
                              `YYYY-MM`.
                            type: string
                          to:
                            description: >-
                              `CAREER` only: the last month both were there,
                              `YYYY-MM`. Absent while both are still there.
                            type: string
                          company_size:
                            description: >-
                              `INVESTOR` only: the organization’s number of
                              employees. Absent when unknown.
                            type: number
                          subject_titles:
                            description: >-
                              `INVESTOR` only: the subject’s founder, board or
                              investor titles there. The subject is the circle’s
                              person, or `a` in an edge.
                            type: array
                            items:
                              type: string
                          person_titles:
                            description: '`INVESTOR` only: the other person’s titles there.'
                            type: array
                            items:
                              type: string
                        required:
                          - public_id
                    windows:
                      description: >-
                        `INVESTOR` only: the months both held an investor role
                        at an organization. An organization without such a
                        period is in `companies` only.
                      type: array
                      items:
                        type: object
                        properties:
                          public_id:
                            description: >-
                              The organization’s LinkedIn page, as
                              `company/<slug>`, or `showcase/<slug>` for a
                              showcase page.
                            type: string
                          name:
                            description: The organization’s name. Absent when unknown.
                            type: string
                          from:
                            description: The first month of the period, `YYYY-MM`.
                            type: string
                          to:
                            description: >-
                              The last month of the period, `YYYY-MM`. Absent
                              while it goes on.
                            type: string
                        required:
                          - public_id
                          - from
                    schools:
                      description: >-
                        `EDUCATION` only: the schools both attended. Can be
                        empty.
                      type: array
                      items:
                        type: string
                    subject_degree:
                      description: >-
                        `EDUCATION` only: the subject’s degree. A blank string
                        in any of its fields means unknown.
                      type: object
                      properties:
                        name:
                          description: The name of the degree as listed.
                          type: string
                        degree:
                          description: The kind of degree.
                          type: string
                        fields:
                          description: The fields of study.
                          type: string
                    person_degree:
                      description: >-
                        `EDUCATION` only: the other person’s degree. A blank
                        string in any of its fields means unknown.
                      type: object
                      properties:
                        name:
                          description: The name of the degree as listed.
                          type: string
                        degree:
                          description: The kind of degree.
                          type: string
                        fields:
                          description: The fields of study.
                          type: string
                    same_start_year_month:
                      description: >-
                        `EDUCATION` only: not zero when both started at the
                        school in the same year and month.
                      type: number
                    classification:
                      description: >-
                        `LINKEDIN_COMMENTS` only: the best class among the
                        comments between them, from `very good` down to
                        `decent`. `irrelevant` is not sent.
                      type: string
                      enum:
                        - irrelevant
                        - decent
                        - good
                        - very good
                    comment_count:
                      description: >-
                        `LINKEDIN_COMMENTS` only: the number of comments between
                        them, in both directions.
                      type: number
                    comments:
                      description: >-
                        `LINKEDIN_COMMENTS` only: the best of the comments
                        between them, best first. It can hold fewer than
                        `comment_count`.
                      type: array
                      items:
                        type: object
                        properties:
                          by:
                            description: The `key` of the person who commented.
                            type: string
                          'on':
                            description: The `key` of the author of the post.
                            type: string
                          url:
                            description: The URL of the comment.
                            type: string
                          post_url:
                            description: >-
                              The URL of the post. Absent when the comment’s URL
                              is not a feed post’s.
                            type: string
                          classification:
                            description: >-
                              The class of the comment. `irrelevant` is not
                              sent.
                            type: string
                            enum:
                              - irrelevant
                              - decent
                              - good
                              - very good
                          confidence:
                            description: >-
                              The probability, 0 to 1, that the comment is of
                              that class.
                            type: number
                          date:
                            description: When the comment was written, ISO 8601.
                            type: string
                        required:
                          - by
                          - 'on'
                          - url
                          - classification
                          - confidence
                          - date
                  required:
                    - type
                    - score
                    - summary
                    - sources
              counter_evidence:
                description: >-
                  What weighs against the evidence found. Empty when nothing
                  does.
                type: array
                items:
                  type: object
                  properties:
                    kind:
                      description: >-
                        `LARGE_SHARED_ORGANIZATION`: the shared organization is
                        large enough that sharing it says little about knowing
                        each other.
                      type: string
                      enum:
                        - LARGE_SHARED_ORGANIZATION
                    type:
                      description: The type the evidence weighs against.
                      type: string
                      enum:
                        - CAREER
                        - EDUCATION
                        - INVESTOR
                        - LINKEDIN_COMMENTS
                    company_size:
                      description: >-
                        The organization’s number of employees, above 5000. For
                        `INVESTOR`, given only when every shared organization is
                        that large, and then the largest.
                      type: number
                  required:
                    - kind
                    - type
                    - company_size
              coverage:
                description: >-
                  For each requested type, whether the pair was checked and what
                  was found, with the limits that apply.
                type: object
                properties:
                  examined:
                    description: >-
                      The types with a connection found. For a circle’s subject:
                      researched, with at least one connection of the type.
                    type: array
                    items:
                      type: string
                      enum:
                        - CAREER
                        - EDUCATION
                        - INVESTOR
                        - LINKEDIN_COMMENTS
                  searched_no_result:
                    description: >-
                      The types checked with nothing found. For a circle’s
                      subject: researched, with no connection of the type.
                    type: array
                    items:
                      type: string
                      enum:
                        - CAREER
                        - EDUCATION
                        - INVESTOR
                        - LINKEDIN_COMMENTS
                  unavailable:
                    description: >-
                      The types whose research failed: for a pair, a research
                      run in this call; for a circle’s subject, a type whose
                      last research failed, even when an earlier one completed
                      (for a person known under several ids, see
                      `research_state.status`).
                    type: array
                    items:
                      type: string
                      enum:
                        - CAREER
                        - EDUCATION
                        - INVESTOR
                        - LINKEDIN_COMMENTS
                  not_examined:
                    description: >-
                      The types not checked. For a circle’s subject: no research
                      of the type has completed, or one is running now, a re-run
                      included (for a person known under several ids, see
                      `research_state.status`).


                      For a pair, `LINKEDIN_COMMENTS` with no connection found
                      is always here: no comment found does not mean that none
                      exists.
                    type: array
                    items:
                      type: string
                      enum:
                        - CAREER
                        - EDUCATION
                        - INVESTOR
                        - LINKEDIN_COMMENTS
                  limits:
                    description: >-
                      What limits the answer for a type, one entry per type and
                      reason.


                      The limits a type always has (`NO_LIVE_SEARCH`,
                      `NEVER_ALONE`) are stated once per answer: in a circle or
                      paths answer on the top-level `coverage`, not on each
                      entry of `data`.
                    type: array
                    items:
                      type: object
                      properties:
                        type:
                          description: The type the limit applies to.
                          type: string
                          enum:
                            - CAREER
                            - EDUCATION
                            - INVESTOR
                            - LINKEDIN_COMMENTS
                        reason:
                          description: >-
                            `SOURCE_LIMITED`: the source cut the research short,
                            or the shared companies of a career connection can
                            no longer be shown. `NO_LIVE_SEARCH`: comments are
                            read from those already known; a call never searches
                            for new ones. `EXCLUDED_BY_SCAN`: the research run
                            in this call left the other person out, so the pair
                            was not checked. `NEVER_ALONE`: an education match
                            is shown only next to another type. `STALE`: the
                            research or the check of the type is old enough to
                            be out of date.
                          type: string
                          enum:
                            - SOURCE_LIMITED
                            - NO_LIVE_SEARCH
                            - EXCLUDED_BY_SCAN
                            - NEVER_ALONE
                            - STALE
                      required:
                        - type
                        - reason
                required:
                  - examined
                  - searched_no_result
                  - unavailable
                  - not_examined
                  - limits
              hit:
                description: >-
                  `RESEARCHED` when at least one requested type was found or
                  checked for the pair; `UNKNOWN` otherwise.
                type: string
                enum:
                  - RESEARCHED
                  - UNKNOWN
              observed_at:
                description: >-
                  When the newest evidence was observed; with none, when the
                  newest check that found nothing was made. Absent when there is
                  neither.
                format: date-time
                type: string
              person:
                description: >-
                  The other person. With no known profile, only `key` and
                  `publicId` are present.
                type: object
                properties:
                  key:
                    description: >-
                      The person’s key: the public identifier percent-decoded
                      and lower-cased. Two people in the answers are the same
                      person when their keys are equal.
                    type: string
                  publicId:
                    description: >-
                      The person’s current LinkedIn public identifier, the part
                      after `/in/` of the profile URL. It is a valid `id`, `a`,
                      `b` or `target` in any call. For a person with no known
                      profile, the identifier as the call gave it, in the form
                      of `key`.
                    type: string
                  full_name:
                    description: >-
                      The person’s name. Absent when no known profile carries
                      one.
                    type: string
                  role:
                    description: >-
                      The title of the person’s current position; without one,
                      the profile’s headline. Absent when the profile has
                      neither, or no profile is known.
                    type: string
                  company:
                    description: >-
                      The name of the company of the current position shown.
                      Absent when unknown.
                    type: string
                  companyPublicId:
                    description: >-
                      The LinkedIn page of that company, as `company/<slug>`, or
                      `showcase/<slug>` for a showcase page. Absent when
                      unknown.
                    type: string
                required:
                  - key
                  - publicId
            required:
              - verdict
              - verdict_reason
              - evidence
              - counter_evidence
              - coverage
              - hit
              - person
        next_cursor:
          description: >-
            Present when more connections follow; absent on the last page. See
            `cursor`.
          type: string
        total:
          description: >-
            The number of connections that match `types` and `min_strength`; the
            pages can list fewer. Counting stops at a cap; see `total_capped`.
          type: number
        total_capped:
          description: >-
            True when counting stopped at the cap: there are at least `total`
            connections.
          type: boolean
        generated_at:
          format: date-time
          description: >-
            When the answer was made. For an answer read through `/v1/job`,
            earlier than the read.
          type: string
      required:
        - subject
        - research_state
        - hit
        - basis
        - coverage
        - data
        - total
        - total_capped
        - generated_at
    JobAnswer:
      type: object
      properties:
        job:
          description: >-
            A job whose answer is not ready (`202`, `PROCESSING`), or that
            failed (`200` from `/v1/job`, `FAILED`).
          type: object
          properties:
            id:
              description: The job’s id. Pass it to `/v1/job` to read the answer.
              type: string
            status:
              description: >-
                `PROCESSING` in a `202`: the job runs. `FAILED` in a `200` from
                `/v1/job`: the job failed; this is final. `DONE` in a resolve
                `200`.
              type: string
              enum:
                - PROCESSING
                - DONE
                - FAILED
          required:
            - id
            - status
      required:
        - job
    Error:
      type: object
      properties:
        error:
          description: 'The error code. Stable: branch on it.'
          type: string
          enum:
            - invalid_body
            - invalid_session
            - invalid_api_key
            - invalid_limit
            - invalid_types
            - invalid_min_strength
            - invalid_cursor
            - same_person
            - person_not_found
            - ambiguous_person
            - result_unavailable
            - not_found
            - too_many_keys
            - unavailable
            - rate_limited
            - too_many_concurrent
            - research_busy
            - insufficient_balance
            - invalid_max_tokens
            - billing_account_missing
        detail:
          description: >-
            A sentence that explains the error, for a person to read. Its
            wording can change: do not parse it.
          type: string
        request_id:
          description: The id of the request, the same as the `X-Request-Id` header.
          type: string
        candidates:
          description: 'With `422 ambiguous_person` only: every person the id matched.'
          type: array
          items:
            type: object
            properties:
              key:
                description: >-
                  The person’s key: the public identifier percent-decoded and
                  lower-cased. Two people in the answers are the same person
                  when their keys are equal.
                type: string
              publicId:
                description: >-
                  The person’s current LinkedIn public identifier, the part
                  after `/in/` of the profile URL. It is a valid `id`, `a`, `b`
                  or `target` in any call. For a person with no known profile,
                  the identifier as the call gave it, in the form of `key`.
                type: string
              full_name:
                description: The person’s name. Absent when no known profile carries one.
                type: string
              role:
                description: >-
                  The title of the person’s current position; without one, the
                  profile’s headline. Absent when the profile has neither, or no
                  profile is known.
                type: string
              company:
                description: >-
                  The name of the company of the current position shown. Absent
                  when unknown.
                type: string
              companyPublicId:
                description: >-
                  The LinkedIn page of that company, as `company/<slug>`, or
                  `showcase/<slug>` for a showcase page. Absent when unknown.
                type: string
            required:
              - key
              - publicId
      required:
        - error
        - detail
        - request_id
  headers:
    X-Request-Id:
      description: >-
        The id of the request. Every answer carries it; an error body repeats it
        as `request_id`. See Request ids.
      schema:
        type: string
    RateLimit-Limit:
      description: >-
        The calls the account may make per minute. On every answer past
        authentication: not on a `401`, nor on a `400 invalid_body` for a body
        that could not be parsed. See Rate limits.
      schema:
        type: integer
    X-Orbb-Reserved:
      description: >-
        The tokens the call reserved. On the answers of a call that reserved, a
        `202` included; not on a refusal before the reservation, nor on a `503`
        whose reservation was returned. `/v1/job` answers do not carry it. See
        Billing.
      schema:
        type: number
    X-Orbb-Balance:
      description: >-
        The tokens available after the reservation. On the same answers as
        `X-Orbb-Reserved`.
      schema:
        type: number
    Retry-After:
      description: The seconds to wait before calling again. On every `429`.
      schema:
        type: integer
  securitySchemes:
    bearer:
      type: http
      scheme: bearer
      description: >-
        An API key, `orbb_sk_…`, created in the console; or the console’s
        session token. See Authentication.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.