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

# Enrich profile

> Use this endpoint to enrich a LinkedIn profile and its primary company




## OpenAPI

````yaml /openapi.yaml post /v1/enrich
openapi: 3.0.3
info:
  title: TalkToHumans Public API
  version: 1.0.0
  license:
    name: Proprietary
  description: >
    Read and organize the LinkedIn workspace data your team already manages in
    TalkToHumans: accounts, people, tags, notes, sequence state, conversations,
    and views.
servers:
  - url: https://api.talktohumans.app
    description: TalkToHumans API
security:
  - bearerAuth: []
tags:
  - name: Organization
    description: Workspace details for the current API key.
  - name: LinkedIn
    description: >-
      Accounts, contacts, companies, and conversations already synced into
      TalkToHumans.
  - name: Enrich
    description: Profile enrichment for LinkedIn people and companies.
  - name: Views
    description: Saved TalkToHumans views and lists.
paths:
  /v1/enrich:
    post:
      tags:
        - Enrich
      summary: Enrich profile
      description: |
        Use this endpoint to enrich a LinkedIn profile and its primary company
      operationId: enrichProfile
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EnrichProfileRequest'
            examples:
              linkedinUrl:
                summary: Enrich by LinkedIn URL
                value:
                  account_id: '42'
                  linkedin_url: https://www.linkedin.com/in/jane-doe/
              contactId:
                summary: Enrich an existing contact
                value:
                  account_id: '42'
                  contact_id: '123'
      responses:
        '200':
          description: LinkedIn profile and primary company enrichment data.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EnrichProfileEnvelope'
              example:
                data:
                  linkedin_enrichment:
                    profile:
                      participant:
                        provider: linkedin
                        provider_participant_id: urn:li:fsd_profile:abc
                        kind: member
                        public_identifier: jane-doe
                        profile_url: https://www.linkedin.com/in/jane-doe/
                        first_name: Jane
                        last_name: Doe
                        full_name: Jane Doe
                        headline: Founder at Acme
                        avatar_url: >-
                          https://media.licdn.com/dms/image/example/profile-displayphoto.jpg
                        background_cover_url: >-
                          https://media.licdn.com/dms/image/example/profile-cover.jpg
                        primary_company:
                          provider: linkedin
                          provider_participant_id: urn:li:fsd_company:123
                        primary_company_name: Acme
                        primary_role_title: Founder
                        profile_fetched_at: '2026-05-31T12:00:00Z'
                        updated_at: '2026-05-31T12:00:00Z'
                      languages:
                        - language: English
                          metadata_json: null
                      experiences:
                        - company:
                            provider: linkedin
                            provider_participant_id: urn:li:fsd_company:123
                          company_name: Acme
                          title: Founder
                          employment_type: Full-time
                          location: San Francisco Bay Area
                          start_at: 2021-01
                          end_at: null
                          is_current: true
                          description: Building business software for sales teams.
                          metadata_json: null
                      educations:
                        - school:
                            provider: linkedin
                            provider_participant_id: urn:li:fsd_company:987
                          school_name: Stanford University
                          degree: MBA
                          field_of_study: Business Administration
                          start_at: '2014'
                          end_at: '2016'
                          description: null
                          metadata_json: null
                      locations:
                        - source: linkedin
                          sort_order: 0
                          is_primary: true
                          is_headquarter: false
                          linkedin_text: San Francisco Bay Area
                          display_text: San Francisco, California, United States
                          country_code: US
                          region_code: US-CA
                          country: United States
                          country_full: United States
                          state: California
                          city: San Francisco
                          geographic_area: San Francisco Bay Area
                          line1: null
                          line2: null
                          postal_code: null
                          description: null
                          metadata_json: null
                      industries:
                        - sort_order: 0
                          industry_urn: urn:li:industry:4
                          provider_industry_id: '4'
                          name: Software Development
                          title: Software Development
                          hierarchy: Technology > Software
                          metadata_json: null
                    company:
                      participant:
                        provider: linkedin
                        provider_participant_id: urn:li:fsd_company:123
                        kind: company
                        public_identifier: acme
                        profile_url: https://www.linkedin.com/company/acme/
                        full_name: Acme
                        headline: Software Development
                        avatar_url: >-
                          https://media.licdn.com/dms/image/example/company-logo.jpg
                        background_cover_url: >-
                          https://media.licdn.com/dms/image/example/company-cover.jpg
                        headcount: 51-200
                        employee_count: 120
                        website_url: https://acme.example
                        follower_count: 12000
                        about: Acme builds business software.
                        profile_fetched_at: '2026-05-31T12:00:00Z'
                        updated_at: '2026-05-31T12:00:00Z'
                      languages:
                        - language: English
                          metadata_json: null
                      experiences:
                        - company: null
                          company_name: Acme
                          title: Company profile
                          employment_type: null
                          location: San Francisco, CA
                          start_at: null
                          end_at: null
                          is_current: true
                          description: null
                          metadata_json: null
                      educations:
                        - school: null
                          school_name: null
                          degree: null
                          field_of_study: null
                          start_at: null
                          end_at: null
                          description: null
                          metadata_json: null
                      locations:
                        - source: linkedin
                          sort_order: 0
                          is_primary: true
                          is_headquarter: true
                          linkedin_text: San Francisco, CA
                          display_text: San Francisco, California, United States
                          country_code: US
                          region_code: US-CA
                          country: United States
                          country_full: United States
                          state: California
                          city: San Francisco
                          geographic_area: San Francisco Bay Area
                          line1: null
                          line2: null
                          postal_code: null
                          description: null
                          metadata_json: null
                      industries:
                        - sort_order: 0
                          industry_urn: urn:li:industry:4
                          provider_industry_id: '4'
                          name: Software Development
                          title: Software Development
                          hierarchy: Technology > Software
                          metadata_json: null
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '502':
          $ref: '#/components/responses/BadGateway'
components:
  schemas:
    EnrichProfileRequest:
      type: object
      additionalProperties: false
      description: >
        Provide exactly one target: `contact_id`, `provider_participant_id`,
        `linkedin_url`, or `public_identifier`.
      oneOf:
        - required:
            - contact_id
        - required:
            - provider_participant_id
        - required:
            - linkedin_url
        - required:
            - public_identifier
      properties:
        account_id:
          type: string
          description: >-
            LinkedIn account ID returned by `GET /v1/accounts`. Required when
            the workspace has multiple LinkedIn accounts.
          pattern: ^[1-9][0-9]*$
        contact_id:
          type: string
          description: Contact ID returned by `GET /v1/contacts`.
          pattern: ^[1-9][0-9]*$
        provider_participant_id:
          type: string
          description: LinkedIn participant ID, such as `urn:li:fsd_profile:abc`.
        linkedin_url:
          type: string
          format: uri
          description: LinkedIn profile URL.
        public_identifier:
          type: string
          description: LinkedIn public identifier from a profile URL.
        force:
          type: boolean
          description: >-
            Refresh cached enrichment data even when fresh data is already
            available.
          default: false
    EnrichProfileEnvelope:
      type: object
      additionalProperties: false
      required:
        - data
      properties:
        data:
          $ref: '#/components/schemas/EnrichProfileResponse'
    EnrichProfileResponse:
      type: object
      additionalProperties: false
      required:
        - linkedin_enrichment
      properties:
        linkedin_enrichment:
          $ref: '#/components/schemas/LinkedInEnrichment'
    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
            - 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.
    LinkedInEnrichment:
      type: object
      additionalProperties: false
      description: >-
        LinkedIn profile enrichment data. The profile is enriched first, then
        the current primary company is enriched when available.
      properties:
        profile:
          $ref: '#/components/schemas/EnrichedParticipantSnapshot'
        company:
          $ref: '#/components/schemas/EnrichedParticipantSnapshot'
    EnrichedParticipantSnapshot:
      type: object
      additionalProperties: false
      required:
        - participant
        - languages
        - experiences
        - educations
        - locations
        - industries
      properties:
        participant:
          $ref: '#/components/schemas/EnrichedParticipant'
        languages:
          type: array
          items:
            $ref: '#/components/schemas/EnrichedLanguage'
        experiences:
          type: array
          items:
            $ref: '#/components/schemas/EnrichedExperience'
        educations:
          type: array
          items:
            $ref: '#/components/schemas/EnrichedEducation'
        locations:
          type: array
          items:
            $ref: '#/components/schemas/EnrichedLocation'
        industries:
          type: array
          items:
            $ref: '#/components/schemas/EnrichedIndustry'
    EnrichedParticipant:
      type: object
      additionalProperties: false
      required:
        - provider
        - provider_participant_id
        - kind
        - updated_at
      properties:
        provider:
          type: string
        provider_participant_id:
          type: string
        kind:
          type: string
          description: Participant kind, usually `member` or `company`.
        public_identifier:
          type: string
          nullable: true
        profile_url:
          type: string
          format: uri
          nullable: true
        first_name:
          type: string
          nullable: true
        last_name:
          type: string
          nullable: true
        full_name:
          type: string
          nullable: true
        headline:
          type: string
          nullable: true
        avatar_url:
          type: string
          format: uri
          nullable: true
        background_cover_url:
          type: string
          format: uri
          nullable: true
        headcount:
          type: string
          nullable: true
        employee_count:
          type: integer
          nullable: true
        founding_date:
          type: string
          nullable: true
        website_url:
          type: string
          format: uri
          nullable: true
        profile_action_label:
          type: string
          nullable: true
        profile_action_url:
          type: string
          format: uri
          nullable: true
        follower_count:
          type: integer
          nullable: true
        connections_count:
          type: integer
          nullable: true
        primary_company:
          $ref: '#/components/schemas/ParticipantKey'
        primary_company_name:
          type: string
          nullable: true
        primary_role_title:
          type: string
          nullable: true
        about:
          type: string
          nullable: true
        profile_fetched_at:
          type: string
          format: date-time
          nullable: true
        updated_at:
          type: string
          format: date-time
    EnrichedLanguage:
      type: object
      additionalProperties: false
      required:
        - language
      properties:
        language:
          type: string
        metadata_json:
          type: string
          nullable: true
    EnrichedExperience:
      type: object
      additionalProperties: false
      required:
        - is_current
      properties:
        company:
          $ref: '#/components/schemas/ParticipantKey'
        company_name:
          type: string
          nullable: true
        title:
          type: string
          nullable: true
        employment_type:
          type: string
          nullable: true
        location:
          type: string
          nullable: true
        start_at:
          type: string
          nullable: true
        end_at:
          type: string
          nullable: true
        is_current:
          type: boolean
        description:
          type: string
          nullable: true
        metadata_json:
          type: string
          nullable: true
    EnrichedEducation:
      type: object
      additionalProperties: false
      properties:
        school:
          $ref: '#/components/schemas/ParticipantKey'
        school_name:
          type: string
          nullable: true
        degree:
          type: string
          nullable: true
        field_of_study:
          type: string
          nullable: true
        start_at:
          type: string
          nullable: true
        end_at:
          type: string
          nullable: true
        description:
          type: string
          nullable: true
        metadata_json:
          type: string
          nullable: true
    EnrichedLocation:
      type: object
      additionalProperties: false
      required:
        - source
        - sort_order
        - is_primary
        - is_headquarter
      properties:
        source:
          type: string
        sort_order:
          type: integer
          format: int32
        is_primary:
          type: boolean
        is_headquarter:
          type: boolean
        linkedin_text:
          type: string
          nullable: true
        display_text:
          type: string
          nullable: true
        country_code:
          type: string
          nullable: true
        region_code:
          type: string
          nullable: true
        country:
          type: string
          nullable: true
        country_full:
          type: string
          nullable: true
        state:
          type: string
          nullable: true
        city:
          type: string
          nullable: true
        geographic_area:
          type: string
          nullable: true
        line1:
          type: string
          nullable: true
        line2:
          type: string
          nullable: true
        postal_code:
          type: string
          nullable: true
        description:
          type: string
          nullable: true
        metadata_json:
          type: string
          nullable: true
    EnrichedIndustry:
      type: object
      additionalProperties: false
      required:
        - sort_order
      properties:
        sort_order:
          type: integer
          format: int32
        industry_urn:
          type: string
          nullable: true
        provider_industry_id:
          type: string
          nullable: true
        name:
          type: string
          nullable: true
        title:
          type: string
          nullable: true
        hierarchy:
          type: string
          nullable: true
        metadata_json:
          type: string
          nullable: true
    ParticipantKey:
      type: object
      additionalProperties: false
      nullable: true
      required:
        - provider
        - provider_participant_id
      properties:
        provider:
          type: string
        provider_participant_id:
          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, or invalid 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
    Forbidden:
      description: >-
        API access is not enabled for the workspace, or the credential cannot
        access the requested workspace.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            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
    NotFound:
      description: Requested resource was not found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            code: not_found
            message: participant not found
    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
    BadGateway:
      description: Upstream provider request failed.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            code: upstream_error
            message: Enrichment provider request failed
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: 'Pass your API key as `Authorization: Bearer <api_key>`.'

````