---
title: "POST /v1/enrich"
method: POST
path: "/v1/enrich"
tags: ["GTM verbs"]
---

# POST /v1/enrich

`POST /v1/enrich`

## Request

- Base URL: `https://api.layrcake.dev`
- URL: `https://api.layrcake.dev/v1/enrich`
- Auth: HTTP bearer

## Headers

- `Idempotency-Key` string

## Request body

- object
  - `person` object, required
    - `full_name` string
    - `first_name` string
    - `last_name` string
    - `email` string
    - `linkedin_url` string, uri
    - `company_name` string
    - `company_domain` string: Company website domain or URL, e.g. acme.com or https://www.acme.com/about
    - `title` string
  - `want` string[]: What to look up. work_email and profile run the email lookup (5 credits on a hit), which returns a mobile number too when its source has one. mobile_phone also runs a separate mobile search when the email lookup found none: 17 credits when that search finds one, 5 when the mobile came with the email, nothing when no mobile is found; a mobile_phone-only request that finds only an email is free and returns nothing. Where this isn't applied for your key yet, every call runs the same email lookup whatever this lists.
  - `max_credits` string: Spend ceiling for this call, in credits. If the most the call can cost is above it, the call is refused before anything is reserved or charged.
  - `route` 'balanced' | 'cheapest' | 'broadest' | 'fastest': Source preference for this call: balanced (the default), cheapest (the lowest-cost sources), broadest (the sources expected to find the most) or fastest. The price doesn't change with it. Where route choice isn't available to this key yet, only balanced is accepted.
  - `budget_credits` number: Spend ceiling for this call, in credits. The same ceiling as max_credits, as a number: send one or the other. If the most the call can cost is above it, the call is refused before anything is reserved or charged. It is a ceiling only: it never lets the call use a dearer source. Where spend ceilings aren't available to this key yet, a request that sets it is refused with the reason.
  - `dry_run` boolean: Return this call's plan instead of running it, as of evaluated_at: the most it can cost, how many sources could answer, what budget_credits changes, and every limit the real call would trip. Nothing is looked up, reserved or charged, and a later call may differ. Where previews aren't available to this key yet, a request that sets it is refused with the reason.

## Response `200`

Successful outcome

- object
  - `result` union, required
    - object
      - `outcome` 'hit' | 'partial' | 'miss', required
      - `contact` object, nullable, required
        - `fingerprint` string, required
        - `full_name` string, nullable, required
        - `title` string, nullable, required
        - `company_name` string, nullable, required
        - `company_domain` string, nullable, required
        - `work_email` string, nullable, required
        - `work_email_status` 'valid' | 'catch_all' | 'unknown' | 'not_found', nullable, required
        - `email_verdict` 'valid' | 'invalid' | 'catch_all_valid' | 'catch_all_unknown' | 'unknown' | 'risky', nullable
        - `mobile_phone` string, nullable, required
        - `linkedin_url` string, nullable, required
        - `location` string, nullable, required
        - `observed_at` string, nullable, required
      - `from_cache` boolean, required
      - `dropped_to_fit` string[]: Present only when budget_credits or max_credits was below the price of the mobile search: the wants listed were dropped so the email lookup fits.
    - object
      - `dry_run` true, required
      - `advisory` true, required
      - `evaluated_at` string, required
      - `plan` object, required
        - `verb` 'enrich', required
        - `plan_version` 3, required
        - `input_version` string, required
        - `credits_estimate` string, required
        - `would_exceed` string[], required
        - `warnings` string[], required
        - `would` object, required
          - `candidate_sources` integer, required
          - `maximum_credits` string, required
          - `budget_credits` string, nullable, required
  - `layrcake` object, required
    - `request_id` string, uuid, required
    - `credits_charged` string, required
    - `credits_available` string, required
    - `replayed` boolean
    - `route` object
      - `used` 'balanced' | 'cheapest' | 'broadest' | 'fastest', required
      - `source` 'request' | 'key' | 'guess' | 'default', required

## Other responses

- `4XX`: Caller, scope, confirmation, or credit error
- `5XX`: Provider or service error

---

[API](https://skmtc.dev/layrcake/apis/layrcake-api.md) · [All operations](https://skmtc.dev/layrcake/apis/layrcake-api/llms.txt) · [OpenAPI document](https://skmtc.dev/layrcake/apis/layrcake-api/revisions/24c80e33c274?raw)