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

# Enrich a lead

> Queues the enrichment of one lead: its LinkedIn profile data, email address, phone number, or any combination.
Name the lead by `lead_uuid`, or by `linkedin_profile_url`; a URL that matches no lead in the workspace creates one first.
Exactly one of the two must be given.

Everything that would make the enrichment fail is checked before anything is queued: the lead must have a
LinkedIn profile URL, at least one requested option must still be missing on the lead (an option already present,
or that a previous enrichment could not find, is skipped and reported), no enrichment may already be pending for
the lead, and the workspace must have enough credits. A request that fails a check queues nothing and says why,
returning the lead where one was resolved.

Enrichment spends credits: 1 for an email, 10 for a phone number, 0.25 for profile data on its own. The credits
are reserved when the enrichment is dispatched and settled when it completes; what is not found is released.
An agency-managed workspace spends from its agency's pool, and which key you use decides whether it may.
An agency key, calling on a linked workspace, may always spend the pool. The workspace's own key may spend it
only where the agency has enabled direct spending for that workspace, and then only within the monthly cap the
agency set for it; without that, the request is refused and nothing is queued. A workspace billed independently
spends its own credits, where neither setting applies.

The response does not wait for the enrichment. It returns 202 once the request is queued; the enriched fields
appear on the lead when the supplier answers, usually within minutes.




## OpenAPI

````yaml /api-reference/openapi.yaml post /workspaces/{workspace_uuid}/leads/enrich
openapi: 3.0.3
info:
  title: ReachBoost API
  version: '1'
  description: >
    ## Welcome

    The ReachBoost API enables you to take your LinkedIn outreach to the next
    level by integrating ReachBoost directly into your tech stack, workflows, or
    AI agents. With our API, you can automate actions, enrich personalization,
    and build solutions tailored to your outreach strategies.


    ## Authentication


    All requests must include your API key in the `X-Api-Key` header.


    ```

    X-Api-Key: <your_api_key_here>

    ```


    You can find your API key in your ReachBoost account settings.


    ## Base URL


    ```

    https://app.reachboost.io/api/v1

    ```


    Workspace-scoped endpoints use:


    ```

    https://app.reachboost.io/api/v1/workspaces/{workspace_uuid}

    ```


    Your `workspace_uuid` is your unique identifier for the workspace. You can
    find it on the integrations page under the API tab.


    ## Rate Limits


    Requests are limited to **100 requests per minute per API key**. The
    allowance is shared across

    all endpoints: a single API key has one budget, not one budget per resource.
    The window is a

    fixed one-minute window aligned to the clock minute.


    Every response to a request with a recognised API key carries these headers:


    | Header | Meaning |

    |---|---|

    | `X-RateLimit-Limit` | Requests allowed in the current window |

    | `X-RateLimit-Remaining` | Requests left in the current window |

    | `X-RateLimit-Reset` | Unix timestamp when the current window resets |

    | `X-RateLimit-Resource` | Which limit the request counted against |


    When the limit is exceeded the API returns `429 Too Many Requests` with a
    `Retry-After` header

    (seconds until the window resets) and a body of the form:


    ```json

    {
      "error": "Rate limit exceeded. Please try again later.",
      "code": "rate_limit_exceeded",
      "retry_after": 17
    }

    ```


    Recommended client behaviour:


    1. If `Retry-After` is present, wait that many seconds before retrying.

    2. Otherwise, if `X-RateLimit-Remaining` is `0`, wait until
    `X-RateLimit-Reset`.

    3. Otherwise back off exponentially with jitter and cap your retries.


    Note that write requests are not idempotent, so retrying a `POST` or `PATCH`
    after a timeout may

    repeat the operation. Please contact support if you need a higher limit.


    ## Pagination


    List endpoints return paginated results. Control pagination with the `page`
    and `per_page` query parameters.


    | Parameter | Default | Maximum |

    |---|---|---|

    | `page` | `1` | — |

    | `per_page` | `50` | `100` |


    All paginated responses share the same envelope:


    ```json

    {
      "current_page": 1,
      "per_page": 50,
      "total_count": 120,
      "total_pages": 3,
      "next_page": 2,
      "prev_page": null,
      "data": [ ... ]
    }

    ```


    ## Errors


    The API uses standard HTTP status codes.


    | Code | Meaning |

    |---|---|

    | `400` | Bad Request — invalid parameters |

    | `401` | Unauthorized — missing or invalid API key |

    | `404` | Not Found |

    | `413` | Payload Too Large — request body exceeds 1 MB |

    | `422` | Unprocessable Entity — validation error |

    | `429` | Too Many Requests — rate limit exceeded |

    | `500` | Internal Server Error |


    Error responses always include an `error` field:


    ```json

    { "error": "Human-readable error message" }

    ```


    ## Building a flow campaign


    A flow campaign is a tree of steps. Each lead starts at "start", runs each
    step in

    turn, and follows the outcome that step produced to the next one. Every path
    ends

    at an end step. Create the campaign with `POST /campaigns` (CLI: `campaigns
    create`)

    and `flow_enabled: true`, then set its steps with `PUT
    /campaigns/{campaign_uuid}/flow`

    (CLI: `campaigns replace-flow`). Nothing is sent until the campaign is
    published with

    `POST /campaigns/{campaign_uuid}/publish` (CLI: `campaigns publish`).


    ### Step types and their outcomes


    | Step | Settings | Outcomes |

    |---|---|---|

    | connection_request | message_content, fallback_message,
    send_empty_connection_request, wait_before | accepted, not_accepted |

    | follow_up | message_content, fallback_message, wait_before | replied,
    not_replied |

    | voice_note | voice_note_id, wait_before | replied, not_replied |

    | email | subject, message_content, fallback_subject, fallback_message,
    wait_before | replied, not_replied |

    | profile_visit | wait_before | next |

    | profile_follow | wait_before | next |

    | like_last_post | wait_before | next |

    | withdraw | wait_before | next |

    | push_to_integration | integration_kind, integration_id, reference,
    wait_before | next |

    | enrichment | options, wait_before | next |

    | condition | rows, match, wait_before | met, not_met |

    | end | wait_before | none |


    A step with the outcome next has one exit. end has none: it finishes the
    lead.


    ### Which step may follow which outcome


    | After | May be followed by |

    |---|---|

    | start | profile_visit, profile_follow, like_last_post, follow_up,
    voice_note, connection_request, email, condition, enrichment,
    push_to_integration |

    | profile_visit | profile_follow, like_last_post, follow_up, voice_note,
    connection_request, email, withdraw, condition, enrichment,
    push_to_integration, end |

    | profile_follow | profile_visit, like_last_post, follow_up, voice_note,
    connection_request, email, withdraw, condition, enrichment,
    push_to_integration, end |

    | like_last_post | profile_visit, profile_follow, follow_up, voice_note,
    connection_request, email, withdraw, condition, enrichment,
    push_to_integration, end |

    | connection_request / accepted | profile_visit, like_last_post, follow_up,
    voice_note, email, condition, enrichment, push_to_integration, end |

    | connection_request / not_accepted | profile_visit, like_last_post, email,
    withdraw, condition, enrichment, push_to_integration, end |

    | follow_up / replied | condition, enrichment, push_to_integration, end |

    | voice_note / replied | condition, enrichment, push_to_integration, end |

    | follow_up / not_replied | profile_visit, like_last_post, follow_up,
    voice_note, email, condition, enrichment, push_to_integration, end |

    | voice_note / not_replied | profile_visit, like_last_post, follow_up,
    voice_note, email, condition, enrichment, push_to_integration, end |

    | email / replied | end |

    | email / not_replied | profile_visit, profile_follow, like_last_post,
    follow_up, voice_note, connection_request, email, withdraw, condition,
    enrichment, push_to_integration, end |

    | withdraw | profile_visit, profile_follow, like_last_post, email,
    condition, enrichment, push_to_integration, end |

    | push_to_integration | profile_visit, profile_follow, like_last_post,
    follow_up, voice_note, connection_request, email, withdraw, condition,
    enrichment, push_to_integration, end |

    | condition / met | profile_visit, profile_follow, like_last_post,
    connection_request, follow_up, voice_note, email, withdraw, condition,
    enrichment, push_to_integration, end |

    | condition / not_met | profile_visit, profile_follow, like_last_post,
    connection_request, follow_up, voice_note, email, withdraw, condition,
    enrichment, push_to_integration, end |

    | enrichment | profile_visit, profile_follow, like_last_post,
    connection_request, follow_up, voice_note, email, withdraw, enrichment,
    push_to_integration, condition, end |


    ### Waits


    settings.wait_before is { "amount": 3, "unit": "days" }, with unit days or
    weeks.

    It is how long the step waits before it runs.


    - On the step that follows not_accepted it is required, and it is how long
    to wait for the connection request to be accepted. 3 weeks is a common
    choice.

    - On the step that follows not_replied it is how long to wait for a reply.
    It is required after email; leave it out after follow_up or voice_note to
    continue immediately.


    ### Messages


    connection_request, follow_up and email take settings.message_content. Email
    also takes

    settings.subject. A connection request can be sent without a note by setting

    send_empty_connection_request to true and leaving message_content out.


    Merge tags are written with double square brackets: [[first_name]],
    [[last_name]], [[job_role]], [[company_name]],
    [[linkedin_account.first_name]], [[linkedin_account.last_name]].

    Any other spelling, such as {first_name} or {{first_name}}, is sent to the
    lead as

    literal text.


    A message that uses a merge tag needs settings.fallback_message: the text
    sent when

    the lead is missing that value. An email subject that uses a merge tag needs

    settings.fallback_subject the same way. A fallback cannot use merge tags
    itself.


    ### Voice notes


    A voice_note step sends a recorded audio message on LinkedIn, and counts as
    a follow-up for

    limits and statistics. Upload the audio first with `POST
    /campaigns/{campaign_uuid}/voice_notes` (CLI: `campaigns upload-voice-note`)

    (MP3, M4A, WAV or WebM, at most 12 MB and 60 seconds), then set the returned
    id as

    settings.voice_note_id. Leave voice_note_id out to keep the note the step
    already has.

    It is only sent to 1st-degree connections.


    ### Conditions


    A condition step checks the lead and continues on met or not_met.
    settings.rows is a

    list of checks, all of which must pass. settings.match can only be "all".


    - Lead fields: first_name, last_name, linkedin_profile_url, email,
    phone_number, city, country_code, job_role, company_name, company_domain.
    Operators: equals, not_equals, contains, not_contains, empty, not_empty. All
    but
      empty and not_empty need a "value".
      Example: { "field": "city", "op": "equals", "value": "Amsterdam" }
    - { "field": "connection_degree", "op": "is_first_degree" }: the lead is
    already a connection.

    - { "field": "connected_to_sender", "op": "any_of", "value": [sender uuids]
    }: the lead is
      connected to one of these senders.

    ### Other steps


    - enrichment: settings.options lists what to look up, from linkedin_profile,
    email, phone.

    - push_to_integration: settings.integration_kind is one of hubspot, webhook,
    and
      settings.integration_id comes from `GET /integrations` (CLI: `integrations list`).

    ### Rules


    A flow that breaks any of these is refused, and nothing is saved.


    - The flow must start with a step connected from Start.

    - Start can connect to only one first step.

    - Every branch must have a next step.

    - Each outcome can have only one next step.

    - Steps cannot merge; each step has at most one incoming connection.

    - Every path must end with an End step.

    - Only one connection request is allowed.

    - A connection request cannot follow a follow-up.

    - A follow-up cannot sit on the not-accepted branch after a connection
    request.

    - Only one withdraw is allowed.

    - Withdraw requires a connection request in the flow.

    - Withdraw must sit on the not-accepted branch.

    - Only one Profile follow is allowed.

    - A Profile follow cannot come after a connection request or a follow-up:
    sending the request already follows the lead, and a connection is followed
    too.

    - Only one Like last post is allowed.

    - After a reply, only Condition, Enrich, Push to Integration and End are
    allowed.

    - Set a wait on this step. This branch cannot continue immediately.

    - Wait must be a positive amount in days or weeks.

    - Wait is not allowed on the first step after Start.

    - Wait on End is only allowed on a branch that requires a wait.

    - Message cannot be blank.

    - Subject cannot be blank.

    - Add a fallback message when the primary uses merge tags.

    - Add a fallback subject when the subject uses merge tags.

    - Add a fallback message when the message uses merge tags.

    - Fallback content cannot use variables.

    - Conditions can only be combined with AND.

    - Add at least one condition.

    - Enter a value for this condition.

    - Select at least one sender.

    - Choose at least one enrichment option.

    - Select an integration to push the lead to.

    - Record or upload a voice note for this step.


    Publishing, and changing a campaign that has already run:


    - Select at least one audience before publishing.

    - Add at least one step before publishing.

    - This campaign's flow structure is locked. You can still edit the limits,
    step content and wait times.

    - This step cannot be removed because it already has campaign activity.


    ### Example


    Visit the profile, send a connection request, and follow up twice. Withdraw
    the

    request if it is not accepted within 3 weeks.


    ```json

    {
      "nodes": [
        {
          "ref": "visit",
          "type": "profile_visit"
        },
        {
          "ref": "connect",
          "type": "connection_request",
          "settings": {
            "message_content": "Hi [[first_name]], I'd like to connect.",
            "fallback_message": "Hi, I'd like to connect."
          }
        },
        {
          "ref": "follow_up_1",
          "type": "follow_up",
          "settings": {
            "wait_before": {
              "amount": 2,
              "unit": "days"
            },
            "message_content": "Thanks for connecting, [[first_name]]!",
            "fallback_message": "Thanks for connecting!"
          }
        },
        {
          "ref": "follow_up_2",
          "type": "follow_up",
          "settings": {
            "wait_before": {
              "amount": 3,
              "unit": "days"
            },
            "message_content": "Just following up on my last message."
          }
        },
        {
          "ref": "withdraw",
          "type": "withdraw",
          "settings": {
            "wait_before": {
              "amount": 3,
              "unit": "weeks"
            }
          }
        },
        {
          "ref": "end_replied",
          "type": "end"
        },
        {
          "ref": "end_replied_late",
          "type": "end"
        },
        {
          "ref": "end_no_reply",
          "type": "end"
        },
        {
          "ref": "end_withdrawn",
          "type": "end"
        }
      ],
      "edges": [
        {
          "from": "start",
          "to": "visit",
          "outcome": "next"
        },
        {
          "from": "visit",
          "to": "connect",
          "outcome": "next"
        },
        {
          "from": "connect",
          "to": "follow_up_1",
          "outcome": "accepted"
        },
        {
          "from": "connect",
          "to": "withdraw",
          "outcome": "not_accepted"
        },
        {
          "from": "follow_up_1",
          "to": "end_replied",
          "outcome": "replied"
        },
        {
          "from": "follow_up_1",
          "to": "follow_up_2",
          "outcome": "not_replied"
        },
        {
          "from": "follow_up_2",
          "to": "end_replied_late",
          "outcome": "replied"
        },
        {
          "from": "follow_up_2",
          "to": "end_no_reply",
          "outcome": "not_replied"
        },
        {
          "from": "withdraw",
          "to": "end_withdrawn",
          "outcome": "next"
        }
      ]
    }

    ```


    ## Webhooks


    Webhooks let ReachBoost push real-time events to your own endpoint.
    Configure webhooks from the integrations page under the API tab, or through
    the API with the [Webhooks endpoints](#reachboost-api/tag/webhooks):

    1. Set a destination URL

    2. Select which events you want to receive


    ### Delivery


    Each subscribed event is delivered as an HTTP `POST` with a JSON body and a
    `Content-Type: application/json` header. A delivery is considered successful
    on a `2xx` response. Failed deliveries are retried up to **3 times** with
    exponential backoff (2, 4, then 8 minutes). Requests time out after 30
    seconds.


    Every payload includes an `event_type` field identifying the event, and a
    `timestamp_utc` (ISO 8601, UTC) marking when it occurred. When lead
    enrichment is enabled on the webhook, enrichment fields such as `email` and
    `phone_number` are included when available.


    ### Objects and events


    ReachBoost pushes four objects. Each object is delivered by one or more
    events, distinguished by the `event_type` field.


    #### Campaign Activity


    Fired as a lead moves through a campaign's connection and messaging steps.


    | Event | Description |

    |---|---|

    | `connection_request_sent` | A connection request was sent to the lead. |

    | `connection_request_accepted` | The lead accepted the connection request.
    |

    | `connection_request_withdrawn` | A pending connection request was
    withdrawn. |

    | `follow_up_message_sent` | A follow-up message was sent to the lead. |

    | `message_replied` | The lead replied to a message. |


    ```json

    {
      "event_type": "connection_request_accepted",
      "profile_uuid": "9001c8bc-146c-484f-a377-06c4a90ebe72",
      "first_name": "Jane",
      "last_name": "Doe",
      "linkedin_url": "https://www.linkedin.com/in/jane-doe",
      "sender_name": "John Doe",
      "sender_uuid": "6b8accff-7460-431e-9e2f-aeeac7c6916f",
      "campaign_name": "Example Campaign",
      "campaign_uuid": "9a4330fd-4d82-490f-a6a5-eaaabf5ea4dd",
      "message_content": "Thanks for connecting!",
      "message_sequence": 1,
      "reply_content": "Happy to connect.",
      "email": "jane@example.com",
      "phone_number": "+1 555 0100",
      "timestamp_utc": "2026-07-24T10:15:00Z"
    }

    ```


    `reply_content` is included only for `message_replied`. `message_sequence`
    is `null` when not applicable.


    #### Message


    Fired when a message is sent or received in the unified inbox.


    | Event | Description |

    |---|---|

    | `message_success` | A message was successfully sent or received. |


    ```json

    {
      "event_type": "message_success",
      "message_uuid": "4f79dc94-5568-4661-bca7-f8769798d4a8",
      "conversation_uuid": "cf3ca4a0-ae1e-45d2-8bca-8a9ac6b3669f",
      "profile_uuid": "9001c8bc-146c-484f-a377-06c4a90ebe72",
      "first_name": "Jane",
      "last_name": "Doe",
      "linkedin_url": "https://www.linkedin.com/in/jane-doe",
      "sender_name": "John Doe",
      "sender_uuid": "6b8accff-7460-431e-9e2f-aeeac7c6916f",
      "status": "success",
      "direction": "out",
      "content": "Great speaking with you.",
      "delivered_at_utc": "2026-07-24T10:20:00Z",
      "email": "jane@example.com"
    }

    ```


    #### Lead Status


    Fired when a lead's status changes in your pipeline.


    | Event | Description |

    |---|---|

    | `lead_status_engaged` | Lead moved to Engaged. |

    | `lead_status_interested` | Lead moved to Interested. |

    | `lead_status_hot_lead` | Lead moved to Hot lead. |

    | `lead_status_meeting_booked` | Lead moved to Meeting booked. |

    | `lead_status_won` | Lead moved to Won. |

    | `lead_status_not_interested` | Lead moved to Not interested. |

    | `lead_status_lost` | Lead moved to Lost. |


    ```json

    {
      "event_type": "lead_status_interested",
      "profile_uuid": "9001c8bc-146c-484f-a377-06c4a90ebe72",
      "first_name": "Jane",
      "last_name": "Doe",
      "linkedin_url": "https://www.linkedin.com/in/jane-doe",
      "lead_status": "interested",
      "previous_lead_status": "engaged",
      "email": "jane@example.com",
      "timestamp_utc": "2026-07-24T10:25:00Z"
    }

    ```


    #### Campaign Profile


    Fired when a lead reaches a terminal state within a campaign.


    | Event | Description |

    |---|---|

    | `lead_finished` | The lead completed the campaign. |

    | `lead_failed` | The lead could not be processed and stopped with a
    failure. |


    ```json

    {
      "event_type": "lead_failed",
      "profile_uuid": "9001c8bc-146c-484f-a377-06c4a90ebe72",
      "first_name": "Jane",
      "last_name": "Doe",
      "linkedin_url": "https://www.linkedin.com/in/jane-doe",
      "sender_name": "John Doe",
      "sender_uuid": "6b8accff-7460-431e-9e2f-aeeac7c6916f",
      "campaign_name": "Example Campaign",
      "campaign_uuid": "9a4330fd-4d82-490f-a6a5-eaaabf5ea4dd",
      "status": "failed",
      "email": "jane@example.com",
      "timestamp_utc": "2026-07-24T10:30:00Z"
    }

    ```
  contact:
    name: ReachBoost Support
    url: https://reachboost.io
servers:
  - url: https://app.reachboost.io/api/v1
    description: Production
security:
  - ApiKeyAuth: []
tags:
  - name: Statistics
    description: >-
      Campaign performance metrics for a date range, with optional sender and
      campaign filters.
  - name: Leads
    description: Manage leads, including lead tags and custom fields.
  - name: Lead Lists
    description: Manage lead lists in your workspace via API.
  - name: Campaigns
    description: Manage campaigns in your workspace via API.
  - name: Campaign Messages
    description: Manage messages from campaigns via API.
  - name: Senders
    description: Manage LinkedIn senders connected to your workspace via API.
  - name: Unified Inbox
    description: Read conversations and send messages through the unified inbox via API.
  - name: Tags
    description: Manage tags used to organize leads in your workspace via API.
  - name: Workspaces
    description: Manage all workspaces in your agency.
  - name: Users
    description: >-
      Manage the members of a workspace and the invitations that bring new
      members in. Both resources live here.
  - name: Webhooks
    description: >-
      Manage the outbound webhooks of a workspace, the URLs that receive a POST
      for each chosen event. Not available on agency workspaces.
  - name: Integrations
    description: >-
      The integrations a flow campaign's Push to Integration step can send leads
      to. Not available on agency workspaces.
paths:
  /workspaces/{workspace_uuid}/leads/enrich:
    post:
      tags:
        - Leads
      summary: Enrich a lead
      description: >
        Queues the enrichment of one lead: its LinkedIn profile data, email
        address, phone number, or any combination.

        Name the lead by `lead_uuid`, or by `linkedin_profile_url`; a URL that
        matches no lead in the workspace creates one first.

        Exactly one of the two must be given.


        Everything that would make the enrichment fail is checked before
        anything is queued: the lead must have a

        LinkedIn profile URL, at least one requested option must still be
        missing on the lead (an option already present,

        or that a previous enrichment could not find, is skipped and reported),
        no enrichment may already be pending for

        the lead, and the workspace must have enough credits. A request that
        fails a check queues nothing and says why,

        returning the lead where one was resolved.


        Enrichment spends credits: 1 for an email, 10 for a phone number, 0.25
        for profile data on its own. The credits

        are reserved when the enrichment is dispatched and settled when it
        completes; what is not found is released.

        An agency-managed workspace spends from its agency's pool, and which key
        you use decides whether it may.

        An agency key, calling on a linked workspace, may always spend the pool.
        The workspace's own key may spend it

        only where the agency has enabled direct spending for that workspace,
        and then only within the monthly cap the

        agency set for it; without that, the request is refused and nothing is
        queued. A workspace billed independently

        spends its own credits, where neither setting applies.


        The response does not wait for the enrichment. It returns 202 once the
        request is queued; the enriched fields

        appear on the lead when the supplier answers, usually within minutes.
      operationId: enrichLead
      parameters:
        - $ref: '#/components/parameters/WorkspaceUuid'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EnrichLeadRequest'
            examples:
              by_uuid:
                summary: An existing lead
                value:
                  lead_uuid: 550e8400-e29b-41d4-a716-446655440010
                  enrichment_options:
                    - linkedin_profile
                    - email
                    - phone
              by_url:
                summary: A lead by LinkedIn URL, created if it does not exist yet
                value:
                  linkedin_profile_url: https://www.linkedin.com/in/jane-doe
                  enrichment_options:
                    - email
      responses:
        '202':
          description: >-
            Enrichment queued. Credits are reserved when the queued job
            dispatches, not in this request. While this one is pending, another
            request for the same lead that still has something to enrich is
            refused with 409.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EnrichLeadAccepted'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          description: The lead named by `lead_uuid` does not exist in this workspace.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error: Lead not found
        '409':
          description: An enrichment for this lead is already pending. Nothing was queued.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EnrichLeadRefused'
              example:
                error: An enrichment for this lead is already in progress
        '422':
          description: >-
            The request is invalid, there is nothing left to enrich, or the
            workspace cannot pay for it. Nothing was queued.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EnrichLeadRefused'
              examples:
                identifiers:
                  value:
                    error: Give either lead_uuid or linkedin_profile_url
                unknown_option:
                  value:
                    error: >-
                      enrichment_options contains an unknown option: fax.
                      Allowed: linkedin_profile, email, phone
                nothing_to_enrich:
                  value:
                    error: >-
                      Nothing to enrich: the lead already has email, or a
                      previous enrichment found none
                insufficient_credits:
                  value:
                    error: >-
                      Insufficient credits: this enrichment needs 11.0 credits
                      and 0.5 are available
                monthly_cap:
                  value:
                    error: >-
                      This workspace has reached its monthly credit cap; nothing
                      more can be enriched this cycle
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '503':
          description: >-
            The request passed every check but could not be queued. Nothing was
            changed, not even a lead created from the URL; retry.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error: >-
                  The enrichment could not be queued. Nothing was changed; try
                  again shortly
components:
  parameters:
    WorkspaceUuid:
      name: workspace_uuid
      in: path
      required: true
      description: Your unique workspace identifier.
      schema:
        type: string
        format: uuid
        example: YOUR_WORKSPACE_UUID
  schemas:
    EnrichLeadRequest:
      type: object
      required:
        - enrichment_options
      description: Exactly one of `lead_uuid` and `linkedin_profile_url` must be given.
      oneOf:
        - required:
            - lead_uuid
          not:
            required:
              - linkedin_profile_url
        - required:
            - linkedin_profile_url
          not:
            required:
              - lead_uuid
      properties:
        lead_uuid:
          type: string
          format: uuid
          description: An existing lead in the workspace.
        linkedin_profile_url:
          type: string
          description: >-
            A LinkedIn profile URL. Normalised the same way as on lead creation;
            a URL that matches no lead creates one.
          example: https://www.linkedin.com/in/jane-doe
        enrichment_options:
          type: array
          minItems: 1
          description: >-
            What to enrich. An unknown name refuses the request; a repeated one
            counts once.
          items:
            type: string
            enum:
              - linkedin_profile
              - email
              - phone
    EnrichLeadAccepted:
      type: object
      required:
        - lead
        - enrichment
      properties:
        lead:
          $ref: '#/components/schemas/Lead'
        enrichment:
          type: object
          required:
            - uuid
            - queued
            - options
            - skipped_options
            - credits
          properties:
            uuid:
              type: string
              format: uuid
              description: >-
                The enrichment record. Its outcome is visible in the workspace's
                Settings, under enrichment history.
            queued:
              type: boolean
              enum:
                - true
            options:
              type: array
              description: The options that were queued, in the order requested.
              items:
                type: string
                enum:
                  - linkedin_profile
                  - email
                  - phone
            skipped_options:
              type: array
              description: >-
                Requested options the lead already has, or that a previous
                enrichment could not find. Not queued and not charged.
              items:
                type: string
                enum:
                  - linkedin_profile
                  - email
                  - phone
            credits:
              type: number
              description: >-
                The credits the queued options cost, reserved at dispatch and
                settled on completion.
              example: 11
      example:
        lead:
          uuid: 550e8400-e29b-41d4-a716-446655440010
          first_name: Jane
          last_name: Doe
          linkedin_profile_url: https://www.linkedin.com/in/jane-doe
          email: null
          phone_number: null
        enrichment:
          uuid: 7c2f0c1e-5b1a-4a7e-9d8e-2b1f6f3c9a10
          queued: true
          options:
            - email
            - phone
          skipped_options:
            - linkedin_profile
          credits: 11
    Error:
      type: object
      properties:
        error:
          type: string
        code:
          type: string
          description: >-
            Present on refusals a script may need to tell apart, for example
            `flow_campaign_use_flow_endpoint` when a campaign message write
            targets a flow campaign.
    EnrichLeadRefused:
      type: object
      required:
        - error
      description: The refusal, with the lead when the request named or created one.
      properties:
        error:
          type: string
        lead:
          $ref: '#/components/schemas/Lead'
    Lead:
      type: object
      properties:
        uuid:
          type: string
          format: uuid
        first_name:
          type: string
          nullable: true
        last_name:
          type: string
          nullable: true
        company_name:
          type: string
          nullable: true
        job_role:
          type: string
          nullable: true
        linkedin_profile_url:
          type: string
          nullable: true
          example: https://www.linkedin.com/in/johndoe
        profile_headline:
          type: string
          nullable: true
        lead_status:
          type: string
          nullable: true
        email:
          type: string
          nullable: true
        phone_number:
          type: string
          nullable: true
        company_domain:
          type: string
          nullable: true
        company_linkedin_url:
          type: string
          nullable: true
        company_headcount:
          type: integer
          nullable: true
        company_industry:
          type: string
          nullable: true
        city:
          type: string
          nullable: true
        country_code:
          type: string
          nullable: true
        tags:
          type: array
          items:
            $ref: '#/components/schemas/TagSummary'
        custom_fields:
          type: array
          maxItems: 100
          items:
            $ref: '#/components/schemas/CustomField'
        blacklisted:
          type: boolean
        updated_at:
          type: string
          format: date-time
        created_at:
          type: string
          format: date-time
      example:
        uuid: e29b0fd5-30a4-4451-9955-b75ce7ed3d9b
        first_name: John
        last_name: Doe
        job_role: CEO
        company_name: Example Company
        profile_headline: CEO at Example Company
        linkedin_profile_url: https://www.linkedin.com/in/john-doe
        lead_status: won
        email: john.doe@example.com
        phone_number: +1 555 0100
        company_domain: example.com
        company_linkedin_url: https://www.linkedin.com/company/example
        company_headcount: 250
        company_industry: Software
        city: Amsterdam
        country_code: NL
        tags:
          - uuid: 63e53626-0e29-444a-8924-37450ba7ebea
            name: LinkedIn
          - uuid: 17bd2143-d3fa-45ea-9c36-a6fd23ef9e5a
            name: Customer
        custom_fields:
          - name: custom_value_1
            value: Example value
            created_at: '2026-04-07T14:43:17+02:00'
            updated_at: '2026-04-07T14:43:17+02:00'
        blacklisted: false
        updated_at: '2025-11-10T12:00:00+01:00'
        created_at: '2025-11-01T12:00:00+01:00'
    RateLimitError:
      type: object
      properties:
        error:
          type: string
          example: Rate limit exceeded. Please try again later.
        code:
          type: string
          example: rate_limit_exceeded
        retry_after:
          type: integer
          description: Seconds until the current rate-limit window resets.
          example: 17
    TagSummary:
      type: object
      properties:
        uuid:
          type: string
          format: uuid
        name:
          type: string
    CustomField:
      type: object
      properties:
        name:
          type: string
          maxLength: 100
        value:
          oneOf:
            - type: string
              maxLength: 7500
            - type: number
            - type: boolean
          description: >-
            A string, number or boolean; null, objects and arrays are rejected.
            Stored as text, and the 7500-character limit applies to that text
            form, so it bounds numbers and booleans too.
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
      required:
        - name
        - value
  responses:
    Unauthorized:
      description: Unauthorized
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: Invalid API key
    Forbidden:
      description: Forbidden
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: Endpoint only available for agency workspaces
    TooManyRequests:
      description: >
        Too Many Requests — the API key exceeded its rate limit. Wait for the
        period given by

        `Retry-After` before retrying.
      headers:
        X-RateLimit-Limit:
          $ref: '#/components/headers/XRateLimitLimit'
        X-RateLimit-Remaining:
          $ref: '#/components/headers/XRateLimitRemaining'
        X-RateLimit-Reset:
          $ref: '#/components/headers/XRateLimitReset'
        X-RateLimit-Resource:
          $ref: '#/components/headers/XRateLimitResource'
        Retry-After:
          $ref: '#/components/headers/RetryAfter'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/RateLimitError'
          example:
            error: Rate limit exceeded. Please try again later.
            code: rate_limit_exceeded
            retry_after: 17
  headers:
    XRateLimitLimit:
      description: Requests allowed in the current rate-limit window.
      schema:
        type: integer
        example: 100
    XRateLimitRemaining:
      description: Requests left in the current rate-limit window.
      schema:
        type: integer
        example: 42
    XRateLimitReset:
      description: Unix timestamp at which the current rate-limit window resets.
      schema:
        type: integer
        example: 1787660460
    XRateLimitResource:
      description: Which rate limit the request counted against.
      schema:
        type: string
        example: default
    RetryAfter:
      description: Seconds to wait before retrying.
      schema:
        type: integer
        example: 17
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-Api-Key
      description: Your secret ReachBoost API key.

````

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