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

# Request an Email Enrichment

> Starts an asynchronous lookup of a work or personal email address for a LinkedIn profile. Returns immediately with a request `_id` and a `status` of `pending`; the result is delivered later either by polling `GET /v1/api/enrichment/email/{id}` or via the optional `callback_url` webhook. Each completed lookup costs 1 enrichment credit (charged only when an email is found). Requires a positive credit balance.

Starts an **asynchronous** lookup of a work or personal email address for a LinkedIn profile.

The call returns immediately with a request `_id` and a `status` of `pending`. The actual lookup runs in the background — collect the result either by [polling](/api-reference/endpoint/get-email-enrichment) the returned `_id`, or by providing a `callback_url` that we POST to when the lookup finishes.

<Note>
  Each **completed** lookup costs **1 enrichment credit**. Credits are charged only when an email is found (`status: "completed"`), never for `not-found`. The request is rejected with `402` if the team has no remaining credits — check your balance with [Get Enrichment Credits](/api-reference/endpoint/get-enrichment-credits).
</Note>

### Request Body

| Field          | Type          | Required | Description                                                                      |
| -------------- | ------------- | -------- | -------------------------------------------------------------------------------- |
| `linkedin_url` | string        | Yes      | LinkedIn profile URL. Must be a `linkedin.com/in/<username>` URL.                |
| `type`         | string        | Yes      | Email type to find — `work` or `personal`.                                       |
| `callback_url` | string (URL)  | No       | Webhook POSTed when the enrichment finishes. Retried up to 3 times with backoff. |
| `external_id`  | string (≤256) | No       | Opaque value echoed back in the callback for client-side correlation.            |

### Example Request

```json theme={null}
{
  "linkedin_url": "https://www.linkedin.com/in/janedoe",
  "type": "work",
  "callback_url": "https://example.com/webhooks/enrichment",
  "external_id": "lead-42"
}
```

### Response (201)

```json theme={null}
{
  "_id": "507f1f77bcf86cd799439011",
  "status": "pending",
  "linkedin_url": "https://www.linkedin.com/in/janedoe"
}
```

Persist the `_id` — it is the handle for polling and the identifier referenced in the callback.

### Callback payload

If you supplied a `callback_url`, we POST a JSON body to it once the lookup resolves:

```json theme={null}
{
  "request_id": "507f1f77bcf86cd799439011",
  "status": "completed",
  "enrichment_type": "work_email",
  "email": { "email": "jane@acme.com", "type": "work" },
  "linkedin_url": "https://www.linkedin.com/in/janedoe",
  "external_id": "lead-42"
}
```

`status` is `completed` (with `email`) or `not-found` (`email` is `null`). Delivery is attempted up to 3 times; if every attempt fails, fall back to polling.

### Errors

| Status | Description                                                                                                      |
| ------ | ---------------------------------------------------------------------------------------------------------------- |
| 400    | Validation failed — `linkedin_url` is not a `linkedin.com/in/<username>` URL, or `type` is not `work`/`personal` |
| 402    | Insufficient enrichment credits                                                                                  |


## OpenAPI

````yaml POST /v1/api/enrichment/email
openapi: 3.0.1
info:
  title: Salesfinity API
  description: API documentation for Salesfinity platform
  license:
    name: MIT
  version: 1.0.0
servers:
  - url: https://client-api.salesfinity.co
security:
  - ApiKeyAuth: []
paths:
  /v1/api/enrichment/email:
    post:
      tags:
        - Enrichment
      summary: Request an email enrichment
      description: >-
        Starts an asynchronous lookup of a work or personal email address for a
        LinkedIn profile. Returns immediately with a request `_id` and a
        `status` of `pending`; the result is delivered later either by polling
        `GET /v1/api/enrichment/email/{id}` or via the optional `callback_url`
        webhook. Each completed lookup costs 1 enrichment credit (charged only
        when an email is found). Requires a positive credit balance.
      operationId: enrich-email
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EnrichEmailDTO'
      responses:
        '201':
          description: >-
            Enrichment request accepted. Poll the returned _id, or wait for the
            callback.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EmailEnrichmentRequestDTO'
        '400':
          description: >-
            Validation failed (e.g. linkedin_url is not a
            linkedin.com/in/<username> URL, or type is not work|personal)
        '402':
          description: Insufficient enrichment credits. Top up to continue.
components:
  schemas:
    EnrichEmailDTO:
      type: object
      required:
        - linkedin_url
        - type
      properties:
        linkedin_url:
          type: string
          description: LinkedIn profile URL. Must be a linkedin.com/in/<username> URL.
          example: https://www.linkedin.com/in/username
        type:
          type: string
          enum:
            - work
            - personal
          description: Which email type to find.
        callback_url:
          type: string
          format: uri
          description: >-
            Optional. Webhook URL POSTed when the enrichment finishes. Retried
            up to 3 times.
          example: https://example.com/webhooks/enrichment
        external_id:
          type: string
          maxLength: 256
          description: >-
            Optional. Echoed back in the callback payload for client-side
            correlation.
          example: lead-42
    EmailEnrichmentRequestDTO:
      type: object
      properties:
        _id:
          type: string
          description: >-
            Enrichment request ID. Use this to poll GET
            /v1/api/enrichment/email/{id}.
          example: 507f1f77bcf86cd799439011
        status:
          type: string
          enum:
            - pending
            - processing
            - completed
            - not-found
            - failed
          description: >-
            Current state of the request. `completed` means an email was found;
            `not-found` means none was available.
        linkedin_url:
          type: string
          example: https://www.linkedin.com/in/username
        enrichment_type:
          type: string
          enum:
            - work_email
            - personal_email
          description: Present once the lookup resolves. Reflects the requested email type.
        email:
          type: object
          nullable: true
          description: >-
            Populated when status is `completed`. Null when status is
            `not-found`.
          properties:
            email:
              type: string
              example: john@acme.com
            type:
              type: string
              example: work
        external_id:
          type: string
          description: The external_id supplied on the original request, if any.
          example: lead-42
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key

````