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

# Research a single contact

> Research one contact by searchResultId from contact search results or Contact enrich.

**Credits:** the contact is charged for the components it researches, at the prices in [Credits](https://docs.seamless.ai/core-concepts/credits#contact-research-costs). `researchTypes` defaults to email and phone, or to your Contact Data setting if it's set to emails or phones only. Credits for data that isn't found are refunded. The request is rejected with a 422 when your balance can't cover the contact, priced at the most it can cost.




## OpenAPI

````yaml /openapi.json post /contacts/research/single
openapi: 3.0.0
info:
  title: Seamless API
  description: >-
    Search and research Seamless.AI contacts and companies, and work with the
    records saved to your organization. Authentication, rate limits, and credits
    are covered at https://docs.seamless.ai.


    [Privacy Policy](https://seamless.ai/policies/privacy-policy)
  version: 1.0.0
  termsOfService: https://seamless.ai/policies/terms-of-use
servers:
  - url: https://api.seamless.ai/api/client/v1
    description: Seamless API
security: []
tags: []
paths:
  /contacts/research/single:
    post:
      tags:
        - Contact Research
      summary: Research a single contact
      description: >
        Research one contact by searchResultId from contact search results or
        Contact enrich.


        **Credits:** the contact is charged for the components it researches, at
        the prices in
        [Credits](https://docs.seamless.ai/core-concepts/credits#contact-research-costs).
        `researchTypes` defaults to email and phone, or to your Contact Data
        setting if it's set to emails or phones only. Credits for data that
        isn't found are refunded. The request is rejected with a 422 when your
        balance can't cover the contact, priced at the most it can cost.
      operationId: researchSingleContact
      requestBody:
        required: true
        content:
          application/json:
            examples:
              searchResultId:
                summary: Contact research via searchResultId
                value:
                  searchResultId: 708dbb34-3849-3c06-abd1-238b9a0295b3
              contact:
                summary: Contact research via contact
                value:
                  contact:
                    contactName: John Doe
                    companyName: Acme Corp
              jobChange:
                summary: Contact research with job change
                value:
                  isJobChange: true
                  contact:
                    contactName: Jane Doe
                    companyName: Acme Corp
                    title: Software Engineer
              phoneOnly:
                summary: Phone-only research
                value:
                  searchResultId: searchResultId1
                  researchTypes:
                    - phone
              phoneOnlyContact:
                summary: Phone-only research via contact
                value:
                  contact:
                    contactName: John Doe
                    companyName: Acme Corp
                  researchTypes:
                    - phone
            schema:
              type: object
              properties:
                searchResultId:
                  type: string
                  description: >-
                    A search result ID obtained from a prior /search/contacts
                    call. Provide either searchResultId or contact, not both.
                    The contact is charged for the components it researches (see
                    researchTypes and
                    [Credits](https://docs.seamless.ai/core-concepts/credits#contact-research-costs)).
                  example: 11ad7a1c-9a63-30e0-a1de-cd9a766805ca
                contact:
                  allOf:
                    - type: object
                      properties:
                        contactName:
                          type: string
                          description: >-
                            Full name of the contact to research. Required when
                            using companyName or domain for identification.
                          example: John Doe
                        companyName:
                          type: string
                          description: >-
                            Name of the company the contact is associated with.
                            Use together with contactName.
                          example: Acme Corp
                        title:
                          type: string
                          description: >-
                            Job title of the contact. Used alongside contactName
                            and companyName when isJobChange is true to match
                            the correct job change record.
                          example: Software Engineer
                        domain:
                          type: string
                          description: >-
                            Company website domain. Use as an alternative to
                            companyName together with contactName.
                          example: acme.com
                        email:
                          type: string
                          description: >-
                            Email address of the contact. Can be used as a
                            standalone identifier without contactName or
                            companyName.
                          example: john.doe@acme.com
                        liProfileUrl:
                          type: string
                          description: >-
                            LinkedIn public profile URL. Can be used as a
                            standalone identifier.
                          example: https://www.linkedin.com/in/johndoe
                        liSalesNavUrl:
                          type: string
                          description: >-
                            LinkedIn Sales Navigator profile URL. Can be used as
                            a standalone identifier.
                          example: https://www.linkedin.com/sales/lead/ACoAAA...
                        liRecruiterUrl:
                          type: string
                          description: >-
                            LinkedIn Recruiter profile URL. Can be used as a
                            standalone identifier.
                          example: >-
                            https://www.linkedin.com/talent/search/profile/AEMAA...
                  description: >
                    Contact enrich request. Provide either searchResultId or
                    contact, not both. Must include one of the following
                    combinations:

                    - contactName and companyName (optionally include title when
                    using isJobChange)

                    - contactName and domain

                    - email

                    - liProfileUrl

                    - liSalesNavUrl

                    - liRecruiterUrl
                isJobChange:
                  type: boolean
                  description: >-
                    When set to true, triggers a job change research for the
                    provided contact. Must be used together with contact; cannot
                    be used with searchResultId.
                  default: false
                  example: false
                listIds:
                  type: array
                  description: >
                    IDs of the contact lists to add the newly saved contact to.
                    A contact that was already researched is not saved again, so
                    it is not added to the lists.

                    The lists must already belong to the authenticated user; an
                    unknown ID fails the research request, which reports the
                    error when you poll for it.
                  maxItems: 50
                  items:
                    type: integer
                  example:
                    - 1234
                    - 5678
                skipDeduplicationCheck:
                  type: boolean
                  description: >
                    When true, research skips both duplicate checks and
                    researches the record again, which charges credits again.

                    By default a request is reported as `duplicate` when the
                    same record was researched in the last few minutes, and as
                    `contact-already-researched` when the contact is already
                    saved in your My Contacts. Within those few minutes, a
                    request for contact data the earlier research didn't get
                    (for example phone after an email-only research) is
                    researched onto that contact instead, and only the new data
                    is charged. Repeated IDs within a single request are always
                    collapsed into one research request.
                  default: false
                researchTypes:
                  type: array
                  description: >
                    Optional. Defaults to `["email", "phone"]`, or to the user's
                    Contact Data setting if it's set to emails or phones only.
                    Applies to every contact in the request, including contact
                    details and job changes.


                    Send `["email"]`, `["phone"]`, or `["email", "phone"]` (Full
                    Contact). Order doesn't matter, duplicates are removed, and
                    `null` is the same as leaving it out.


                    Each component is charged at its price. See
                    [Credits](https://docs.seamless.ai/core-concepts/credits#contact-research-costs)
                    for the default prices, custom pricing and refunds.


                    Rejected with:

                    - 400 `invalidArguments` when it isn't a non-empty array of
                    `email` and/or `phone`

                    - 403 `fullContactRequired` when your organization's Contact
                    Data is locked to Full Contact and you send one component

                    - 403 `component-disabled-for-org` when your organization
                    disabled a component you sent

                    - 403 `variable-credits-disabled` when your account isn't on
                    component-based pricing and you send one component
                  minItems: 1
                  uniqueItems: true
                  items:
                    type: string
                    enum:
                      - email
                      - phone
                  example:
                    - email
      responses:
        '202':
          description: The request ID for research
          headers:
            X-PublicAPI-Credits:
              description: >-
                Your projected balance once the contact is charged. The cost is
                an upper bound. Research runs after this response, so a contact
                already in your My Contacts, or a follow-up that identifies the
                same person differently, can cost less or nothing, and refunds
                for data that isn't found land when the research completes.
              schema:
                type: number
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    description: >-
                      Indicates whether the research request was accepted
                      successfully.
                    example: true
                  requestId:
                    type: string
                    description: >-
                      The request ID for the contact research request. Use it to
                      poll for results via /contacts/research/poll.
                    example: 6Ei5iKuSHzJXvqjVPWiZ_
        '400':
          description: >-
            Neither or both of searchResultId and contact provided, the contact
            is missing required properties, or researchTypes is not a non-empty
            array of email and/or phone
          content:
            application/json:
              schema:
                type: object
                required:
                  - msg
                properties:
                  msg:
                    description: A human readable error message
                    type: string
                  code:
                    description: Machine-readable error code, when one applies
                    type: string
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                type: object
                required:
                  - msg
                properties:
                  msg:
                    description: A human readable error message
                    type: string
                  code:
                    description: Machine-readable error code, when one applies
                    type: string
        '403':
          description: >
            The requested researchTypes aren't allowed for your organization.
            The `code` says why:

            - `fullContactRequired`: your organization's Contact Data is locked
            to Full Contact. Omit researchTypes or send both email and phone.

            - `component-disabled-for-org`: your organization disabled that
            component. Remove it from researchTypes.

            - `variable-credits-disabled`: your account isn't on component-based
            pricing. Omit researchTypes or send both email and phone.
          content:
            application/json:
              schema:
                type: object
                required:
                  - msg
                properties:
                  msg:
                    description: A human readable error message
                    type: string
                  code:
                    description: Machine-readable error code, when one applies
                    type: string
        '422':
          description: Insufficient credits or missing license
          content:
            application/json:
              schema:
                description: Insufficient credits or missing license
                type: object
                properties:
                  msg:
                    type: string
                  code:
                    type: string
                  data:
                    type: object
                    properties:
                      productCategory:
                        type: string
                      additionalCreditsNeeded:
                        type: number
                        description: >-
                          Credits missing to cover the whole request. Can be
                          fractional under custom pricing.
        '500':
          description: Unexpected error
          content:
            application/json:
              schema:
                type: object
                required:
                  - msg
                properties:
                  msg:
                    description: A human readable error message
                    type: string
                  code:
                    description: Machine-readable error code, when one applies
                    type: string
      security:
        - OAuth2:
            - publicAPI.v1.all
        - ApiKeyAuth: []
components:
  securitySchemes:
    OAuth2:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://login.seamless.ai/oauth/authorize
          tokenUrl: https://api.seamless.ai/api/client/v1/oauth/accessToken
          scopes:
            publicAPI.v1.all: Public API v1
    ApiKeyAuth:
      type: apiKey
      name: Token
      in: header
      description: API key passed via the Token header.

````

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