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

# Find email

> Finds a LinkedIn contact's work email.



## OpenAPI

````yaml /developers/openapi.yaml post /v1/contacts/{contact_id}/find-email
openapi: 3.0.3
info:
  title: TalkToHumans Public API
  version: 1.0.0
  license:
    name: Proprietary
  description: >
    Read and organize the LinkedIn organization data your team already manages
    in TalkToHumans: accounts, contacts, tags, notes, sequence state,
    conversations, and views.
servers:
  - url: https://api.talktohumans.app
    description: TalkToHumans API
security:
  - bearerAuth: []
tags:
  - name: Organization
    description: Organization details for the current API key.
  - name: LinkedIn
    description: LinkedIn accounts, contacts, companies, and conversations.
  - name: Activity
    description: Activity for organization reporting.
  - name: Enrich
    description: Profile enrichment for LinkedIn contacts and companies.
  - name: Views
    description: Saved TalkToHumans views.
paths:
  /v1/contacts/{contact_id}/find-email:
    post:
      tags:
        - Enrich
      summary: Find email
      description: Finds a LinkedIn contact's work email.
      operationId: findContactEmail
      parameters:
        - name: contact_id
          in: path
          required: true
          description: Contact ID returned by `POST /v1/contacts` or `GET /v1/contacts`.
          schema:
            type: string
            pattern: ^[1-9][0-9]*$
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FindContactInfoRequest'
            example:
              account_id: '42'
      responses:
        '200':
          description: Contact with the lookup result.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FindContactInfoEnvelope'
        '202':
          description: >-
            Lookup in progress. Check `contact_enrichment.work_email.status`
            with `GET
            /v1/contacts?contact_id={contact_id}&account_id={account_id}` after
            about five seconds.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FindContactInfoEnvelope'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          $ref: '#/components/responses/InsufficientCredits'
        '403':
          $ref: '#/components/responses/AccountScopedForbidden'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalServerError'
components:
  schemas:
    FindContactInfoRequest:
      type: object
      additionalProperties: false
      properties:
        account_id:
          type: string
          pattern: ^[1-9][0-9]*$
          description: >-
            LinkedIn account ID returned by `GET /v1/accounts`. Required when
            multiple accessible LinkedIn accounts exist.
        force:
          type: boolean
          default: false
          description: Refresh cached results, which may spend credits again.
    FindContactInfoEnvelope:
      type: object
      additionalProperties: false
      required:
        - data
      properties:
        data:
          $ref: '#/components/schemas/FindContactInfoResponse'
    FindContactInfoResponse:
      type: object
      additionalProperties: false
      required:
        - contact
      properties:
        contact:
          $ref: '#/components/schemas/Contact'
    Error:
      type: object
      additionalProperties: false
      required:
        - code
        - message
      properties:
        code:
          type: string
          description: Machine-readable error code.
          enum:
            - unauthorized
            - forbidden
            - not_found
            - bad_request
            - internal_error
            - conflict
            - rate_limit_exceeded
            - account_shared_access_required
            - billing_payment_failed
            - billing_subscription_incomplete
            - billing_subscription_expired
            - billing_grace_period
            - billing_feature_not_available
            - billing_insufficient_credits
            - billing_invalid
            - upstream_error
        message:
          type: string
          description: Human-readable error message.
        debug:
          type: string
          description: Development-only debug details.
    Contact:
      type: object
      additionalProperties:
        $ref: '#/components/schemas/CustomFieldValue'
      description: >
        LinkedIn contact. Registered custom field values may appear as
        additional top-level properties using

        each custom field's `key`, alongside the system fields documented below.
      required:
        - account_relationship_id
        - contact_id
        - contact_enrichment
        - provider_participant_id
        - account
        - name
        - relationship_status
        - tags
        - languages
        - experiences
        - educations
        - locations
        - app_url
      properties:
        account_relationship_id:
          type: string
        contact_id:
          type: string
          description: TalkToHumans contact ID.
        provider_participant_id:
          type: string
          description: LinkedIn participant ID.
        public_identifier:
          type: string
        account:
          $ref: '#/components/schemas/AccountSummary'
        name:
          type: string
        first_name:
          type: string
        last_name:
          type: string
        headline:
          type: string
        primary_role_title:
          type: string
        primary_company_name:
          type: string
        contact_enrichment:
          $ref: '#/components/schemas/ContactEnrichment'
        work_email:
          type: string
          description: Work email when email enrichment was found for this organization.
        phone:
          type: string
          description: >-
            Mobile phone number when phone enrichment was found for this
            organization.
        linkedin_url:
          type: string
          format: uri
        avatar_url:
          type: string
          format: uri
        background_cover_url:
          type: string
          format: uri
        about:
          type: string
        profile_action_label:
          type: string
        profile_action_url:
          type: string
          format: uri
        follower_count:
          type: integer
          nullable: true
        connections_count:
          type: integer
          nullable: true
        relationship_status:
          $ref: '#/components/schemas/RelationshipStatus'
        connection_invitation:
          $ref: '#/components/schemas/ConnectionInvitation'
        tags:
          type: array
          items:
            $ref: '#/components/schemas/APITag'
        notes_json:
          type: string
          description: Notes.
        languages:
          type: array
          items:
            $ref: '#/components/schemas/Language'
        experiences:
          type: array
          items:
            $ref: '#/components/schemas/Experience'
        educations:
          type: array
          items:
            $ref: '#/components/schemas/Education'
        locations:
          type: array
          items:
            $ref: '#/components/schemas/Location'
        company:
          $ref: '#/components/schemas/Company'
        last_interaction_at:
          type: string
          format: date-time
          nullable: true
        sequence:
          $ref: '#/components/schemas/Sequence'
        app_url:
          type: string
          format: uri
    CustomFieldValue:
      nullable: true
      description: >-
        Custom field value. Text fields return strings, number fields return
        numbers, boolean fields return booleans, and date fields return
        `YYYY-MM-DD` strings. Null appears only when a value is explicitly
        cleared or absent in a write response.
      oneOf:
        - type: string
        - type: number
        - type: boolean
    AccountSummary:
      type: object
      additionalProperties: false
      required:
        - account_id
        - display_name
        - provider_account_id
        - owner_user_id
      properties:
        account_id:
          type: string
          description: TalkToHumans account ID.
        display_name:
          type: string
        provider_account_id:
          type: string
          description: LinkedIn provider account ID.
        owner_user_id:
          type: string
          description: TalkToHumans user ID that owns the account.
    ContactEnrichment:
      type: object
      additionalProperties: false
      description: >-
        Work email and mobile phone lookup progress. Read contact results
        without starting a lookup or spending enrichment credits.
      required:
        - work_email
        - phone
      properties:
        work_email:
          $ref: '#/components/schemas/ContactEnrichmentState'
        phone:
          $ref: '#/components/schemas/ContactEnrichmentState'
    RelationshipStatus:
      type: string
      enum:
        - connected
        - not_connected
        - unknown
    ConnectionInvitation:
      type: object
      additionalProperties: false
      nullable: true
      required:
        - status
        - direction
      properties:
        status:
          type: string
          enum:
            - pending
        direction:
          type: string
          enum:
            - incoming
            - outgoing
            - unknown
        invite_id:
          type: string
        invite_state:
          type: string
        invite_type:
          type: string
        received_at:
          type: string
          format: date-time
          nullable: true
    APITag:
      type: object
      additionalProperties: false
      required:
        - name
        - color
      properties:
        name:
          type: string
        color:
          type: string
          enum:
            - green
            - orange
            - blue
            - red
            - purple
            - yellow
            - pink
            - grey
    Language:
      type: object
      additionalProperties: false
      required:
        - language
      properties:
        language:
          type: string
    Experience:
      type: object
      additionalProperties: false
      required:
        - experience_id
        - is_current
      properties:
        experience_id:
          type: string
        company_participant_id:
          type: string
        company_provider_participant_id:
          type: string
        company_name:
          type: string
        title:
          type: string
        employment_type:
          type: string
        location:
          type: string
        start_at:
          type: string
        end_at:
          type: string
        is_current:
          type: boolean
        description:
          type: string
    Education:
      type: object
      additionalProperties: false
      required:
        - education_id
      properties:
        education_id:
          type: string
        school_participant_id:
          type: string
        school_provider_participant_id:
          type: string
        school_name:
          type: string
        degree:
          type: string
        field_of_study:
          type: string
        start_at:
          type: string
        end_at:
          type: string
        description:
          type: string
    Location:
      type: object
      additionalProperties: false
      required:
        - is_primary
        - is_headquarter
      properties:
        linkedin_text:
          type: string
        display_text:
          type: string
        country_code:
          type: string
        region_code:
          type: string
        country:
          type: string
        country_full:
          type: string
        state:
          type: string
        city:
          type: string
        geographic_area:
          type: string
        is_primary:
          type: boolean
        is_headquarter:
          type: boolean
    Company:
      type: object
      additionalProperties:
        $ref: '#/components/schemas/CustomFieldValue'
      description: |
        A company.
      nullable: true
      required:
        - company_id
        - provider_participant_id
        - name
        - industries
        - locations
      properties:
        company_id:
          type: string
        provider_participant_id:
          type: string
        public_identifier:
          type: string
        name:
          type: string
        headline:
          type: string
        linkedin_url:
          type: string
          format: uri
        avatar_url:
          type: string
          format: uri
        background_cover_url:
          type: string
          format: uri
        headcount:
          type: string
        employee_count:
          type: integer
          nullable: true
        founding_date:
          type: string
        website_url:
          type: string
          format: uri
        follower_count:
          type: integer
          nullable: true
        about:
          type: string
        notes_json:
          type: string
          description: Notes
        industries:
          type: array
          items:
            $ref: '#/components/schemas/Industry'
        locations:
          type: array
          items:
            $ref: '#/components/schemas/Location'
        tags:
          type: array
          description: Tags
          items:
            $ref: '#/components/schemas/APITag'
    Sequence:
      type: object
      additionalProperties: false
      nullable: true
      required:
        - sequence_id
        - status
        - stop_if_person_replies
        - steps
      properties:
        sequence_id:
          type: string
        status:
          type: string
        stop_if_person_replies:
          type: boolean
        reply_guard_after:
          type: string
          format: date-time
          nullable: true
        next_step_id:
          type: string
        next_step_scheduled_for:
          type: string
          format: date-time
          nullable: true
        steps:
          type: array
          items:
            $ref: '#/components/schemas/SequenceStep'
    ContactEnrichmentState:
      type: object
      additionalProperties: false
      required:
        - status
      properties:
        status:
          type: string
          enum:
            - not_requested
            - enriching
            - found
            - not_found
            - failed
          description: >-
            Lookup status. Found values appear in the contact's `work_email` or
            `phone` field. Failed lookups can be retried with the find endpoint.
        error_code:
          type: string
          description: >-
            Failure code, present only when the lookup failed.
            `lookup_timed_out` means the lookup exceeded its expected duration.
    Industry:
      type: object
      additionalProperties: false
      properties:
        name:
          type: string
        title:
          type: string
        industry_urn:
          type: string
        provider_industry_id:
          type: string
        hierarchy:
          type: string
    SequenceStep:
      type: object
      additionalProperties: false
      required:
        - step_id
        - step_type
        - trigger_type
        - position
        - message_mode
        - state
      properties:
        step_id:
          type: string
        template_run_public_id:
          type: string
        step_type:
          type: string
        trigger_type:
          type: string
        position:
          type: integer
          format: int32
        scheduled_for:
          type: string
          format: date-time
          nullable: true
        message_mode:
          type: string
        state:
          type: string
  responses:
    BadRequest:
      description: Invalid request parameters.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            code: bad_request
            message: Invalid request parameters
    Unauthorized:
      description: Missing, malformed, invalid, or retired local API key.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            missingAuthorization:
              value:
                code: unauthorized
                message: Authorization header is required
            invalidAuthorizationFormat:
              value:
                code: unauthorized
                message: Authorization header must use Bearer scheme
            invalidAPIKey:
              value:
                code: unauthorized
                message: Invalid API key
    InsufficientCredits:
      description: Not enough credits available.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            code: billing_insufficient_credits
            message: Not enough credits available
    AccountScopedForbidden:
      description: >-
        API access is not enabled for the organization, the API key cannot
        resolve to an active organization user, or the credential cannot access
        the requested LinkedIn account.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            accountSharedAccessRequired:
              summary: Requested account is not accessible to this credential
              value:
                code: account_shared_access_required
                message: >-
                  This account is not shared-access enabled for API or MCP. Ask
                  an admin to enable shared access before using this account
                  from this credential.
            forbidden:
              value:
                code: forbidden
                message: you don't have access to this organization
            featureUnavailable:
              value:
                code: billing_feature_not_available
                message: >-
                  Feature 'TalkToHumansAPI' is not available in your current
                  plan
            insufficientCredits:
              value:
                code: billing_insufficient_credits
                message: Insufficient credits
            apiKeyPrincipalInvalid:
              value:
                code: forbidden
                message: >-
                  This API key is no longer linked to an active organization
                  user. Ask an organization admin to regenerate it
    RateLimited:
      description: >-
        Rate limit exceeded. Public routes allow 50 requests per 10 seconds per
        IP and endpoint.
      headers:
        Retry-After:
          description: Seconds to wait before retrying the request.
          schema:
            type: integer
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            code: rate_limit_exceeded
            message: Rate limit exceeded
    InternalServerError:
      description: Unexpected server error.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            code: internal_error
            message: An internal error occurred
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: 'Pass API key as `Authorization: Bearer <api_key>`.'

````