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

# Find a person by LinkedIn profile, email, or name and company

> Body: one of `{ "id": … }`, `{ "email": … }` or `{ <name>, <company field> }`, where the name is `full_name`, or `first_name` with `last_name`, and the company field is any of `company`, `company_domain`, `company_linkedin_url`; `email` also takes the name and company fields, and `on_miss` goes with any form but `id`.

Finds the person behind an email address, a name with a company, or a LinkedIn profile. An `email` or name resolve searches; a resolve by `id` looks the profile up with no search.

> A person that cannot be identified is answered `200` with `resolution.status` `UNRESOLVED`, not an error, an `id` with no known profile included. `404 person_not_found` answers only an `id` that is neither a profile URL nor a public identifier.

Checked in order: the body (`400 invalid_body`), the research and resolve jobs still running (`429 research_busy`), then the balance (`402`).

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



## OpenAPI

````yaml POST /v1/resolve
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/resolve:
    post:
      summary: Find a person by LinkedIn profile, email, or name and company
      description: >-
        Body: one of `{ "id": … }`, `{ "email": … }` or `{ <name>, <company
        field> }`, where the name is `full_name`, or `first_name` with
        `last_name`, and the company field is any of `company`,
        `company_domain`, `company_linkedin_url`; `email` also takes the name
        and company fields, and `on_miss` goes with any form but `id`.


        Finds the person behind an email address, a name with a company, or a
        LinkedIn profile. An `email` or name resolve searches; a resolve by `id`
        looks the profile up with no search.


        > A person that cannot be identified is answered `200` with
        `resolution.status` `UNRESOLVED`, not an error, an `id` with no known
        profile included. `404 person_not_found` answers only an `id` that is
        neither a profile URL nor a public identifier.


        Checked in order: the body (`400 invalid_body`), the research and
        resolve jobs still running (`429 research_busy`), then the balance
        (`402`).


        See also [`/v1/circle`](/api-reference/circle), [Jobs](/api/jobs),
        [Billing](/api/billing), [Rate limits](/api/rate-limits).
      operationId: resolve
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ResolveBody'
            example:
              full_name: Maya Okafor
              company: Northwind Labs
      responses:
        '200':
          description: >-
            Whether, and how, the person was identified; the person, when
            `RESOLVED`.
          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/ResolveAnswer'
              example:
                resolution:
                  status: RESOLVED
                  method: NAME_COMPANY
                person:
                  key: maya-okafor
                  publicId: maya-okafor
                  full_name: Maya Okafor
                  role: VP Engineering
                  company: Northwind Labs
                  companyPublicId: company/northwind-labs
        '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.
          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'
        '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:
    ResolveBody:
      type: object
      properties:
        id:
          description: >-
            Looks up a person by a LinkedIn profile URL, or the public
            identifier from one (the part after `/in/`), with no search. A blank
            string counts as absent. Sent with any other field, `on_miss`
            included, it is answered `400 invalid_body`.


            A well-formed id with no known profile is answered `200` with
            `resolution.status` `UNRESOLVED`; one that several people have held,
            `200` with `AMBIGUOUS`. A value that is neither a profile URL nor a
            public identifier is answered `404 person_not_found`.


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


            See also `email`, `422 ambiguous_person`.
          type: string
          maxLength: 512
        email:
          description: >-
            Searches for the person behind an email address. A blank string
            counts as absent. Without `email` or `id`, the body needs a name
            (`full_name`, or `first_name` and `last_name`) and a company field
            (`company`, `company_domain` or `company_linkedin_url`); any other
            body is answered `400 invalid_body`.


            When the email finds no one, a web search by name follows: the name
            sent with it (`full_name`, or `first_name` and `last_name`), or one
            taken from the address, with any company field; the name and company
            also choose which current position the answer shows.


            See also `id`, `first_name`, `on_miss`.
          type: string
          maxLength: 512
        full_name:
          description: >-
            Searches by the person’s whole name, written `First Last` or `Last,
            First`; titles and degree suffixes are dropped, and with no comma
            the first word is the first name, the rest the last name. A blank
            string counts as absent. Sent with `first_name` or `last_name`, it
            is answered `400 invalid_body`. Without `email` or `id`, the body
            needs a name (`full_name`, or `first_name` and `last_name`) and a
            company field (`company`, `company_domain` or
            `company_linkedin_url`); any other body is answered `400
            invalid_body`.


            A name of one word, or written without spaces, has no last name:
            send it in `first_name` and `last_name` instead. Without `email` or
            `id`, such a `full_name` is answered `400 invalid_body`; beside an
            `email` it is accepted and not searched.


            See also `first_name`, `last_name`, `company`, `email`.
          type: string
          maxLength: 512
        first_name:
          description: >-
            Searches by the person’s first name, always sent with `last_name`,
            and with a company field when there is no `email`. A blank string
            counts as absent. Sent without `last_name`, or with `full_name`, it
            is answered `400 invalid_body`. Without `email` or `id`, the body
            needs a name (`full_name`, or `first_name` and `last_name`) and a
            company field (`company`, `company_domain` or
            `company_linkedin_url`); any other body is answered `400
            invalid_body`.


            See also `last_name`, `company`, `email`.
          type: string
          maxLength: 512
        last_name:
          description: >-
            Searches by the person’s last name, always sent with `first_name`,
            and with a company field when there is no `email`. A blank string
            counts as absent. Sent without `first_name`, or with `full_name`, it
            is answered `400 invalid_body`. Without `email` or `id`, the body
            needs a name (`full_name`, or `first_name` and `last_name`) and a
            company field (`company`, `company_domain` or
            `company_linkedin_url`); any other body is answered `400
            invalid_body`.


            See also `first_name`, `company`, `email`.
          type: string
          maxLength: 512
        company:
          description: >-
            Names the person’s company, as it is usually written. A blank string
            counts as absent. Without `email` or `id`, the body needs a name
            (`full_name`, or `first_name` and `last_name`) and a company field
            (`company`, `company_domain` or `company_linkedin_url`); any other
            body is answered `400 invalid_body`. The company also chooses which
            current position the answer shows.


            See also `first_name`, `email`.
          type: string
          maxLength: 512
        company_domain:
          description: >-
            Names the web domain of the person’s company, such as `acme.com`. A
            blank string counts as absent. Without `email` or `id`, the body
            needs a name (`full_name`, or `first_name` and `last_name`) and a
            company field (`company`, `company_domain` or
            `company_linkedin_url`); any other body is answered `400
            invalid_body`.


            A work `email`’s domain is used as a company domain too; a personal
            address’s is not.


            See also `company`, `email`.
          type: string
          maxLength: 512
        company_linkedin_url:
          description: >-
            Names the LinkedIn page of the person’s company: a company, school
            or showcase page (`linkedin.com/company/…`, `/school/…`,
            `/showcase/…`); any other URL is answered `400 invalid_body`. A
            blank string counts as absent. Without `email` or `id`, the body
            needs a name (`full_name`, or `first_name` and `last_name`) and a
            company field (`company`, `company_domain` or
            `company_linkedin_url`); any other body is answered `400
            invalid_body`.


            See also `company`.
          type: string
          maxLength: 512
        on_miss:
          x-default: '`UNKNOWN`'
          description: >-
            Sets how far the search goes. `UNKNOWN` searches the profiles
            already known and public web pages; `RESEARCH` also queries a
            further profile source, and does not reuse an earlier search for the
            same person that found no one. Any other value, or `on_miss` sent
            with `id`, is answered `400 invalid_body`.


            A resolve takes no `max_tokens`.


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


            Default: `UNKNOWN`.
          type: string
          enum:
            - UNKNOWN
            - RESEARCH
      additionalProperties: false
    ResolveAnswer:
      type: object
      properties:
        resolution:
          description: >-
            Whether, and how, the person was identified. Present in every
            resolve `200`; a body with `job` only is a job answer.
          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
        person:
          description: >-
            The person found. Present only when `resolution.status` is
            `RESOLVED`.
          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
        job:
          description: >-
            The job that searched, with `status` `DONE`. Absent in a resolve by
            `id`.
          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
    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.