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

# Enrich a person: full profile with the work email, and the mobile when asked (paid)

> Send one of: linkedinUrl; email (a work email); fullName, or firstName and lastName, with domain. A profile found costs 1 credit; with includePhone and a phone found, 5. Nothing is charged when no one is found, and a repeat within 30 days of a paid one is free. A profile enriched in the last 30 days is served as stored.

**Cost:** 1 credit when the person is found; 5 credits with `includePhone` and a phone found. Free when the person isn't found, and free again within 30 days for what you already paid for.



## OpenAPI

````yaml /openapi.json post /v1/enrich-person
openapi: 3.1.0
info:
  title: LeadVector API
  version: '1'
  description: >-
    Find and verify business emails and mobile numbers, enrich people and
    companies, and run your email campaigns, mailboxes and inbox. Send your API
    key in the `x-api-key` header.
servers:
  - url: https://prod.leadvector.app
    description: Production
security:
  - access-key: []
tags:
  - name: Authentication
    description: Check that an API key works.
  - name: Lookups
    description: >-
      Find business emails and mobile numbers, verify emails, and find the
      person behind an email.
  - name: Enrichment
    description: The full profile of a person or a company.
  - name: Campaigns
    description: Email campaigns and their sequences.
  - name: Leads
    description: A campaign's leads.
  - name: Email accounts
    description: The mailboxes campaigns send from, and their warmup.
  - name: Inbox
    description: Replies to your campaigns, in one inbox.
  - name: Webhooks
    description: Subscribe URLs to events, and read the events sent.
  - name: Campaign events
    description: >-
      A campaign's lifecycle: created, launched, paused, resumed, stopped,
      completed, deleted.
  - name: Lead events
    description: A lead joining a campaign, replying, being labelled, finishing or failing.
  - name: Email events
    description: Each step's email to a lead, sent or failed.
  - name: Inbox events
    description: Mail the inbox receives, and the replies and forwards sent from it.
  - name: Email account events
    description: A mailbox's connection, pause, cooldown, warmup health and deletion.
  - name: Lookup events
    description: >-
      A single lookup’s result, in the app, the extension or the API: an email
      or a mobile found, an email verified, a person or a company enriched.
  - name: Bulk job events
    description: A bulk job (a file of lookups) completing or failing.
  - name: List events
    description: A contact saved to one of the team’s lists.
  - name: Credit events
    description: The team’s credits running low, or out.
  - name: Test event
    description: The event an endpoint gets when you send it a test.
paths:
  /v1/enrich-person:
    post:
      tags:
        - Enrichment
      summary: >-
        Enrich a person: full profile with the work email, and the mobile when
        asked (paid)
      description: >-
        Send one of: linkedinUrl; email (a work email); fullName, or firstName
        and lastName, with domain. A profile found costs 1 credit; with
        includePhone and a phone found, 5. Nothing is charged when no one is
        found, and a repeat within 30 days of a paid one is free. A profile
        enriched in the last 30 days is served as stored.


        **Cost:** 1 credit when the person is found; 5 credits with
        `includePhone` and a phone found. Free when the person isn't found, and
        free again within 30 days for what you already paid for.
      operationId: ApiV1Controller_enrichPerson
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PersonEnrichmentDto'
      responses:
        '201':
          description: PERSON_ENRICHED / NO_RESULT_FOUND
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PersonEnrichmentResponseDto'
        '400':
          description: >-
            LOOKUP_INPUT_REQUIRED / LOOKUP_INPUT_CONFLICT / DOMAIN_REQUIRED /
            FULL_NAME_REQUIRED / PERSONAL_EMAIL_NOT_SUPPORTED / validation
            messages
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponseDto'
        '401':
          description: API_KEY_REQUIRED / INVALID_API_KEY
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponseDto'
        '403':
          description: >-
            INSUFFICIENT_CREDITS / NO_ACTIVE_PLAN, or ACCOUNT_DEACTIVATED /
            TEAM_DEACTIVATED
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/CreditErrorResponseDto'
                  - $ref: '#/components/schemas/AccountBlockedErrorResponseDto'
        '429':
          description: RATE_LIMIT_EXCEEDED, with a Retry-After header
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RateLimitErrorResponseDto'
      security:
        - access-key: []
components:
  schemas:
    PersonEnrichmentDto:
      type: object
      properties:
        linkedinUrl:
          type: string
          example: https://www.linkedin.com/in/jane-doe
          description: LinkedIn profile URL of the person.
        email:
          type: string
          example: jane.doe@acme.com
          description: Work email of the person (not a personal address).
        fullName:
          type: string
          example: Jane Doe
          description: >-
            Full name of the person, with domain. Or send firstName and
            lastName.
        firstName:
          type: string
          example: Jane
          description: First name of the person, with lastName and domain.
        lastName:
          type: string
          example: Doe
          description: Last name of the person, with firstName and domain.
        domain:
          type: string
          example: acme.com
          description: Company domain (without @), with the name.
        includePhone:
          type: boolean
          example: false
          default: false
          description: >-
            Also find the mobile number. A person with a phone costs 5 credits
            instead of 1; without one found, 1.
    PersonEnrichmentResponseDto:
      type: object
      properties:
        success:
          type: boolean
          example: true
        message:
          type: string
          example: PERSON_ENRICHED
          description: PERSON_ENRICHED | NO_RESULT_FOUND
        data:
          anyOf:
            - $ref: '#/components/schemas/PersonEnrichmentResultDto'
            - type: 'null'
      required:
        - success
        - message
        - data
    ApiErrorResponseDto:
      type: object
      properties:
        statusCode:
          type: number
          example: 401
        message:
          description: >-
            A code in capitals; the list of messages when the body fails
            validation; `Internal server error` for a 500.
          oneOf:
            - type: string
            - type: array
              items:
                type: string
          example: INVALID_API_KEY
        error:
          type: string
          description: The status's name.
          example: Unauthorized
        traceId:
          type: string
          description: Quote it when you contact support.
          example: 4f1c2b7e9a0d4c3b8e6f5a2d1c0b9e8f
        timestamp:
          type: string
          example: '2026-11-03T09:41:12.000Z'
        path:
          type: string
          example: /v1/find-email
      required:
        - statusCode
        - message
        - traceId
        - timestamp
        - path
    CreditErrorResponseDto:
      type: object
      properties:
        statusCode:
          type: number
          example: 401
        message:
          description: The error's code.
          oneOf:
            - type: string
            - type: array
              items:
                type: string
          example: INSUFFICIENT_CREDITS
          enum:
            - INSUFFICIENT_CREDITS
            - NO_ACTIVE_PLAN
        error:
          type: string
          description: The status's name.
          example: Unauthorized
        traceId:
          type: string
          description: Quote it when you contact support.
          example: 4f1c2b7e9a0d4c3b8e6f5a2d1c0b9e8f
        timestamp:
          type: string
          example: '2026-11-03T09:41:12.000Z'
        path:
          type: string
          example: /v1/find-email
        code:
          type: string
          enum:
            - INSUFFICIENT_CREDITS
            - NO_ACTIVE_PLAN
          example: INSUFFICIENT_CREDITS
        feature:
          type: string
          example: EMAIL_FINDER
        required:
          type: number
          description: Credits the lookup needs, in hundredths of a credit.
          example: 100
        remaining:
          type: number
          description: Credits left on the plan, in hundredths of a credit.
          example: 40
      required:
        - statusCode
        - message
        - traceId
        - timestamp
        - path
        - code
    AccountBlockedErrorResponseDto:
      type: object
      properties:
        statusCode:
          type: number
          example: 401
        message:
          description: The error's code.
          oneOf:
            - type: string
            - type: array
              items:
                type: string
          example: ACCOUNT_DEACTIVATED
          enum:
            - ACCOUNT_DEACTIVATED
            - TEAM_DEACTIVATED
        error:
          type: string
          description: The status's name.
          example: Unauthorized
        traceId:
          type: string
          description: Quote it when you contact support.
          example: 4f1c2b7e9a0d4c3b8e6f5a2d1c0b9e8f
        timestamp:
          type: string
          example: '2026-11-03T09:41:12.000Z'
        path:
          type: string
          example: /v1/find-email
      required:
        - statusCode
        - message
        - traceId
        - timestamp
        - path
    RateLimitErrorResponseDto:
      type: object
      properties:
        statusCode:
          type: number
          example: 401
        message:
          description: The error's code.
          oneOf:
            - type: string
            - type: array
              items:
                type: string
          example: RATE_LIMIT_EXCEEDED
        error:
          type: string
          description: The status's name.
          example: Unauthorized
        traceId:
          type: string
          description: Quote it when you contact support.
          example: 4f1c2b7e9a0d4c3b8e6f5a2d1c0b9e8f
        timestamp:
          type: string
          example: '2026-11-03T09:41:12.000Z'
        path:
          type: string
          example: /v1/find-email
        limit:
          type: number
          description: Calls allowed per window.
          example: 10
        windowSeconds:
          type: number
          example: 60
        retryAfterSeconds:
          type: number
          description: Seconds until the next call is allowed.
          example: 6
      required:
        - statusCode
        - message
        - traceId
        - timestamp
        - path
        - limit
        - windowSeconds
        - retryAfterSeconds
    PersonEnrichmentResultDto:
      type: object
      properties:
        uuid:
          type: string
          example: 0190c3f4-7a2b-7c1d-9e8f-123456789abc
        firstName:
          example: Jane
          type:
            - string
            - 'null'
        lastName:
          example: Doe
          type:
            - string
            - 'null'
        fullName:
          example: Jane Doe
          type:
            - string
            - 'null'
        headline:
          example: Head of Sales at Acme
          type:
            - string
            - 'null'
        summary:
          description: About section
          type:
            - string
            - 'null'
        photoUrl:
          description: The provider's picture URL, which may expire
          type:
            - string
            - 'null'
        linkedinUrl:
          example: linkedin.com/in/jane-doe
          type:
            - string
            - 'null'
        twitterUrl:
          type:
            - string
            - 'null'
        githubUrl:
          type:
            - string
            - 'null'
        facebookUrl:
          type:
            - string
            - 'null'
        linkedinConnections:
          example: 500
          type:
            - number
            - 'null'
        location:
          $ref: '#/components/schemas/EnrichedLocationDto'
        workEmail:
          description: Null when no work email is known
          anyOf:
            - $ref: '#/components/schemas/EnrichedWorkEmailDto'
            - type: 'null'
        phone:
          description: >-
            Only with includePhone: null when none is found, or none with its
            calling code
          anyOf:
            - $ref: '#/components/schemas/EnrichedPhoneDto'
            - type: 'null'
        currentPosition:
          anyOf:
            - $ref: '#/components/schemas/EnrichedPositionDto'
            - type: 'null'
        experiences:
          type: array
          items:
            $ref: '#/components/schemas/EnrichedExperienceDto'
        education:
          type: array
          items:
            $ref: '#/components/schemas/EnrichedEducationDto'
        certifications:
          type: array
          items:
            $ref: '#/components/schemas/EnrichedCertificationDto'
        skills:
          example:
            - Negotiation
          type: array
          items:
            type: string
        languages:
          type: array
          items:
            $ref: '#/components/schemas/EnrichedLanguageDto'
        enrichedAt:
          type: string
          example: '2026-10-21T09:30:00.000Z'
          description: When the profile was last enriched
      required:
        - uuid
        - firstName
        - lastName
        - fullName
        - headline
        - summary
        - photoUrl
        - linkedinUrl
        - twitterUrl
        - githubUrl
        - facebookUrl
        - linkedinConnections
        - location
        - workEmail
        - phone
        - currentPosition
        - experiences
        - education
        - certifications
        - skills
        - languages
        - enrichedAt
    EnrichedLocationDto:
      type: object
      properties:
        city:
          example: San Francisco
          type:
            - string
            - 'null'
        state:
          example: California
          type:
            - string
            - 'null'
        country:
          example: United States
          type:
            - string
            - 'null'
        countryCode:
          example: US
          description: ISO 3166-1 alpha-2
          type:
            - string
            - 'null'
        timeZone:
          example: America/Los_Angeles
          description: IANA time zone
          type:
            - string
            - 'null'
      required:
        - city
        - state
        - country
        - countryCode
        - timeZone
    EnrichedWorkEmailDto:
      type: object
      properties:
        address:
          type: string
          example: jane.doe@acme.com
        status:
          example: valid
          description: >-
            Verification status (valid, catch_all, unknown, …); null if not
            verified
          type:
            - string
            - 'null'
      required:
        - address
        - status
    EnrichedPhoneDto:
      type: object
      properties:
        number:
          type: string
          example: '+14155550100'
          description: E.164
        nationalNumber:
          type: string
          example: '4155550100'
        callingCode:
          type: string
          example: '+1'
        countryCode:
          example: US
          type:
            - string
            - 'null'
      required:
        - number
        - nationalNumber
        - callingCode
        - countryCode
    EnrichedPositionDto:
      type: object
      properties:
        title:
          example: Head of Sales
          type:
            - string
            - 'null'
        seniority:
          example: Director
          type:
            - string
            - 'null'
        departments:
          example:
            - Sales
          type: array
          items:
            type: string
        functions:
          example:
            - Business Development
          type: array
          items:
            type: string
        startDate:
          example: 2023-04
          description: YYYY-MM, or YYYY when only the year is known
          type:
            - string
            - 'null'
        company:
          anyOf:
            - $ref: '#/components/schemas/EnrichedCompanyDto'
            - type: 'null'
      required:
        - title
        - seniority
        - departments
        - functions
        - startDate
        - company
    EnrichedExperienceDto:
      type: object
      properties:
        title:
          example: Head of Sales
          type:
            - string
            - 'null'
        companyName:
          example: Acme
          type:
            - string
            - 'null'
        companyDomain:
          example: acme.com
          type:
            - string
            - 'null'
        companyLinkedinUrl:
          example: linkedin.com/company/acme
          type:
            - string
            - 'null'
        description:
          type:
            - string
            - 'null'
        location:
          example: San Francisco, CA, US
          type:
            - string
            - 'null'
        employmentType:
          example: Full-time
          type:
            - string
            - 'null'
        workArrangement:
          example: Hybrid
          type:
            - string
            - 'null'
        startDate:
          example: 2023-04
          description: YYYY-MM, or YYYY when only the year is known
          type:
            - string
            - 'null'
        endDate:
          example: null
          description: YYYY-MM, or YYYY when only the year is known
          type:
            - string
            - 'null'
        isCurrent:
          type: boolean
          example: true
        seniority:
          example: Director
          type:
            - string
            - 'null'
        departments:
          example:
            - Sales
          type: array
          items:
            type: string
      required:
        - title
        - companyName
        - companyDomain
        - companyLinkedinUrl
        - description
        - location
        - employmentType
        - workArrangement
        - startDate
        - endDate
        - isCurrent
        - seniority
        - departments
    EnrichedEducationDto:
      type: object
      properties:
        school:
          example: Stanford University
          type:
            - string
            - 'null'
        schoolLinkedinUrl:
          example: https://www.linkedin.com/school/stanford-university
          type:
            - string
            - 'null'
        degree:
          example: Bachelor of Science
          type:
            - string
            - 'null'
        fieldOfStudy:
          example: Computer Science
          type:
            - string
            - 'null'
        grade:
          type:
            - string
            - 'null'
        startDate:
          example: '2010'
          description: YYYY-MM, or YYYY when only the year is known
          type:
            - string
            - 'null'
        endDate:
          example: '2014'
          description: YYYY-MM, or YYYY when only the year is known
          type:
            - string
            - 'null'
      required:
        - school
        - schoolLinkedinUrl
        - degree
        - fieldOfStudy
        - grade
        - startDate
        - endDate
    EnrichedCertificationDto:
      type: object
      properties:
        name:
          type: string
          example: AWS Solutions Architect
        authority:
          example: Amazon Web Services
          type:
            - string
            - 'null'
        url:
          type:
            - string
            - 'null'
        licenseNumber:
          type:
            - string
            - 'null'
        startDate:
          example: 2020-01
          description: YYYY-MM, or YYYY when only the year is known
          type:
            - string
            - 'null'
        endDate:
          example: 2023-01
          description: YYYY-MM, or YYYY when only the year is known
          type:
            - string
            - 'null'
      required:
        - name
        - authority
        - url
        - licenseNumber
        - startDate
        - endDate
    EnrichedLanguageDto:
      type: object
      properties:
        name:
          type: string
          example: French
        code:
          example: FR
          type:
            - string
            - 'null'
      required:
        - name
        - code
    EnrichedCompanyDto:
      type: object
      properties:
        name:
          example: Acme
          type:
            - string
            - 'null'
        domain:
          example: acme.com
          type:
            - string
            - 'null'
        linkedinUrl:
          example: linkedin.com/company/acme
          type:
            - string
            - 'null'
        industry:
          example: Software Development
          type:
            - string
            - 'null'
        size:
          example: 1200
          description: Employee count, when LeadVector holds it
          type:
            - number
            - 'null'
        city:
          example: San Francisco
          type:
            - string
            - 'null'
        country:
          example: US
          description: ISO 3166-1 alpha-2
          type:
            - string
            - 'null'
        description:
          type:
            - string
            - 'null'
      required:
        - name
        - domain
        - linkedinUrl
        - industry
        - size
        - city
        - country
        - description
  securitySchemes:
    access-key:
      type: apiKey
      in: header
      name: x-api-key
      description: Your API key, from the API keys page of the app.

````

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