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

# Asynchronous Single Contact Enrichment

> Enrich a single contact record with email, phone, and / or personal email data

Enqueue a single contact for waterfall enrichment. The endpoint returns
immediately with an `enrichment_id` and `status: "pending"`; the waterfall
runs asynchronously in the background.

## When to use this endpoint

Use the async endpoint when:

* You can accept results via webhook, or you can poll for them later.
* You're enriching at scale and don't want to hold an HTTP connection per contact.
* You want to retain the enrichment result on the contact record for later retrieval via [`GET /contacts/{id}`](/api-reference/endpoints/contacts/single_enrich).

If you need results inline (Chrome extension, interactive UI, real-time
workflow), use the [synchronous endpoint](/api-reference/endpoints/contacts/sync_single_enrich) instead.

## Enrichment Types

Pass `enrichment_type` as an array containing one of:

* `["email"]` — Find and validate the professional email
* `["phone"]` — Find phone numbers (requires `linkedin_url`)
* `["personal_email"]` — Find a personal email (requires `linkedin_url` **and** account-level consent — see below)

<Note>
  Requesting `personal_email` requires the authenticated user to have
  consented to personal email enrichment in their account settings.
  If consent is missing, the API responds with `422 Unprocessable Entity`
  and the message `"You can't use the personal email enrichment feature
      without consenting with our terms of use"`. This consent gate is required
  for GDPR compliance.
</Note>

## Required Fields

`enrichment_type` is always required. The other required fields depend on its
value (the **Body** section below shows this per type):

| `enrichment_type`    | Additional required fields                                                          |
| -------------------- | ----------------------------------------------------------------------------------- |
| `["email"]`          | `firstname`, `lastname`, **and** one of `linkedin_url`, `domain`, or `company_name` |
| `["phone"]`          | `linkedin_url`                                                                      |
| `["personal_email"]` | `linkedin_url`                                                                      |

Email enrichment needs the contact's name plus at least one identifier — a
`linkedin_url` on its own is enough, or company context (`domain` or
`company_name`). Phone and personal email enrichment run off the `linkedin_url`
alone, so `firstname`/`lastname` are not required for them.

## Receiving results

You have two options:

1. **Webhook** — pass `webhook_url` in the request. We POST the final result
   to that URL once the waterfall completes.
2. **Polling** — call [`GET /contacts/{id}`](/api-reference/specs/enrichments)
   with the returned `enrichment_id`. While the waterfall is running the
   `status` is `pending`; once it has completed (with or without data) the
   `status` flips to `finished`.

## Custom Fields

Pass `custom: { ... }` in the request to attach arbitrary correlation data
(e.g. your CRM record ID). The same payload is echoed back on
`GET /contacts/{id}` and on the webhook callback.

## Pricing

Each enrichment consumes credits based on the requested `enrichment_type` and
the providers used. Check your account credits via the
[Account Credits endpoint](/api-reference/endpoints/miscellaneous/account-credits).


## OpenAPI

````yaml enrichments POST /contacts/single_enrich
openapi: 3.0.1
info:
  title: Pipecorn List API
  description: Pipecorn List API
  license:
    name: MIT
  version: 1.0.0
servers:
  - url: https://app.pipecorn.com/api/v2/
security:
  - defaultApiKey: []
paths:
  /contacts/single_enrich:
    post:
      summary: Enrich a single contact
      description: Enriches a single contact with specified data points.
      requestBody:
        description: Contact information for enrichment
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EnrichmentRequest'
            example:
              firstname: Mathieu
              lastname: Brun-Picard
              domain: pipecorn.com
              company_name: Pipecorn
              linkedin_url: https://www.linkedin.com/in/mathieu-brun-picard/
              webhook_url: https://webhook.site/8b53c96f-f2cd-4c24-bc09-b3c2176d7ea8
              enrichment_type:
                - phone
              custom:
                hubspot_id: '4447901'
      responses:
        '200':
          description: >-
            Enrichment request accepted. The waterfall runs asynchronously; poll
            `GET /contacts/{id}` (using the returned `enrichment_id`) or wait
            for the `webhook_url` callback to retrieve final results.
          content:
            application/json:
              schema:
                type: object
                properties:
                  enrichment_id:
                    type: string
                    format: uuid
                    description: >-
                      The ID of the enrichment request. Use it to poll `GET
                      /contacts/{id}`.
                  first_name:
                    type: string
                    description: The contact's first name
                  last_name:
                    type: string
                    description: The contact's last name
                  status:
                    type: string
                    enum:
                      - pending
                    description: >-
                      Always `pending` on creation; the waterfall runs
                      asynchronously.
                  custom:
                    type: object
                    description: Custom fields passed in the request
                    additionalProperties: true
              example:
                enrichment_id: 123e4567-e89b-12d3-a456-426614174000
                first_name: Mathieu
                last_name: Brun-Picard
                status: pending
                custom:
                  hubspot_id: '4447901'
        '422':
          description: >-
            Unprocessable Entity. Returned when validation fails (e.g.
            unsupported `enrichment_type` value, missing required identifiers),
            when the user has not consented to personal email enrichment but
            requested `personal_email`, or when there are not enough credits.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                insufficient_credits:
                  summary: Insufficient credits
                  value:
                    error: 422
                    message: Not enough enrichment credits left
                personal_email_consent_missing:
                  summary: Personal email consent missing
                  value:
                    error: 422
                    message: >-
                      You can't use the personal email enrichment feature
                      without consenting with our terms of use
components:
  schemas:
    EnrichmentRequest:
      type: object
      properties:
        webhook_url:
          type: string
          format: uri
          description: Webhook URL to receive enrichment results
        phone_country_codes:
          type: array
          items:
            type: string
            description: ISO 3166-1 alpha-2 country code (e.g. "US", "FR", "GB")
          description: >-
            Optional. Restrict phone enrichment to phone numbers from these
            countries. When omitted, the user's account-level default phone
            country codes are applied.
        custom:
          type: object
          description: >-
            Custom fields to include with the enrichment that will be returned
            in the webhook (like crm id, etc.)
          additionalProperties: true
      oneOf:
        - title: Email enrichment
          required:
            - enrichment_type
            - firstname
            - lastname
          properties:
            enrichment_type:
              type: array
              maxItems: 1
              items:
                type: string
                enum:
                  - email
              description: Set to ["email"] to find and validate the professional email.
            firstname:
              type: string
              description: First name of the contact.
            lastname:
              type: string
              description: Last name of the contact.
            linkedin_url:
              type: string
              format: uri
              description: LinkedIn profile URL of the contact.
              example: https://www.linkedin.com/in/mathieu-brun-picard/
            domain:
              type: string
              description: Company domain.
              example: pipecorn.com
            company_name:
              type: string
              description: Company name.
              example: Pipecorn
          anyOf:
            - required:
                - linkedin_url
            - required:
                - domain
            - required:
                - company_name
          description: >-
            Requires `firstname`, `lastname`, and at least one identifier:
            `linkedin_url`, `domain`, or `company_name`.
        - title: Phone enrichment
          required:
            - enrichment_type
            - linkedin_url
          properties:
            enrichment_type:
              type: array
              maxItems: 1
              items:
                type: string
                enum:
                  - phone
              description: Set to ["phone"] to find phone numbers.
            linkedin_url:
              type: string
              format: uri
              description: LinkedIn profile URL of the contact.
              example: https://www.linkedin.com/in/mathieu-brun-picard/
          description: >-
            Requires only the contact's `linkedin_url` (`firstname`/`lastname`
            are not needed).
        - title: Personal email enrichment
          required:
            - enrichment_type
            - linkedin_url
          properties:
            enrichment_type:
              type: array
              maxItems: 1
              items:
                type: string
                enum:
                  - personal_email
              description: Set to ["personal_email"]. Requires per-user GDPR consent.
            linkedin_url:
              type: string
              format: uri
              description: LinkedIn profile URL of the contact.
              example: https://www.linkedin.com/in/mathieu-brun-picard/
          description: >-
            Requires the contact's `linkedin_url` and account-level GDPR consent
            (`firstname`/`lastname` are not needed).
    Error:
      required:
        - error
        - message
      type: object
      properties:
        error:
          type: integer
          format: int32
        message:
          type: string
  securitySchemes:
    defaultApiKey:
      type: apiKey
      in: header
      description: Your API key
      name: X-API-KEY

````