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

# Tell whether two people know each other

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

Tells whether two people likely know each other, and why: the verdict, the strength of the connection, the evidence for each requested type found, and what was checked.

Checked in order: the body (`400 invalid_body`), `a` equal to `b` (`400 same_person`), `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`).

> Two different values that name the same person are answered `400 same_person` only once the job has matched them: after a `202`, that answer comes from `/v1/job`.

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



## OpenAPI

````yaml POST /v1/edge
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/edge:
    post:
      summary: Tell whether two people know each other
      description: >-
        Body: `{ "a": …, "b": … }`, plus the optional fields below.


        Tells whether two people likely know each other, and why: the verdict,
        the strength of the connection, the evidence for each requested type
        found, and what was checked.


        Checked in order: the body (`400 invalid_body`), `a` equal to `b` (`400
        same_person`), `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`).


        > Two different values that name the same person are answered `400
        same_person` only once the job has matched them: after a `202`, that
        answer comes from `/v1/job`.


        See also [`/v1/circle`](/api-reference/circle), [Jobs](/api/jobs),
        [Billing](/api/billing), [Rate limits](/api/rate-limits).
      operationId: edge
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EdgeBody'
            example:
              a: maya-okafor
              b: daniel-reyes
      responses:
        '200':
          description: The connection between `a` and `b`.
          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/EdgeAnswer'
              example:
                a:
                  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
                b:
                  key: daniel-reyes
                  publicId: daniel-reyes
                  full_name: Daniel Reyes
                  role: Head of Partnerships
                  company: Contoso
                  companyPublicId: company/contoso
                  resolution:
                    status: RESOLVED
                    method: PUBLIC_ID
                basis: NETWORK_ONLY
                verdict: POSSIBLE
                verdict_reason: SHARED_HISTORY
                strength:
                  value: 0.61
                  label: STRONG
                  witnesses:
                    career: 0.61
                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
                counter_evidence: []
                coverage:
                  examined:
                    - CAREER
                  searched_no_result:
                    - INVESTOR
                  unavailable: []
                  not_examined:
                    - EDUCATION
                    - LINKEDIN_COMMENTS
                  limits:
                    - type: EDUCATION
                      reason: NEVER_ALONE
                    - type: LINKEDIN_COMMENTS
                      reason: NO_LIVE_SEARCH
                hit: RESEARCHED
        '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_types`: `types` is empty, or holds a member that is not a
            connection type. Send known types, or leave `types` out for every
            type.


            - `same_person`: `a` and `b` name the same person: equal values are
            answered at once; two different values that match the same person,
            once the job has matched them. Send two different people.


            - `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'
            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'
        '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:
    EdgeBody:
      type: object
      properties:
        a:
          description: >-
            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`](/api-reference/circle).
          type: string
          minLength: 1
          maxLength: 512
        b:
          description: >-
            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`](/api-reference/circle).
          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
        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
        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:
        - a
        - b
      additionalProperties: false
    EdgeAnswer:
      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
        a:
          description: The person given as `a`; the subject of the evidence.
          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
        b:
          description: The person given as `b`.
          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
        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
      required:
        - verdict
        - verdict_reason
        - evidence
        - counter_evidence
        - coverage
        - hit
        - a
        - b
        - basis
    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.