---
title: "Verify employment"
description: "POST /v1/person/verify-employment — pre-flight whether to send to this person (dry-run)."
canonical: "https://kingminos.com/docs/api/person-verify-employment/"
sourceKind: "source-mdx"
---

import TryItLink from '../../../../components/docs/TryItLink.astro';
import CapabilityPricing from '../../../../components/docs/CapabilityPricing.astro';
import Credits from '../../../../components/docs/Credits.astro';

`POST https://api.kingminos.com/v1/person/verify-employment`

<TryItLink method="POST" path="/v1/person/verify-employment" />

Pre-flight before email. Send `email` and, when you have it, `expected_company` (`domain`, `website`, `name`, or `identifiers[]`). Optional `first_name`, `last_name`, and `linkedin_url` tighten matching. Top-level fields or a nested `person` object are equivalent.

The decision shape is **`answer.outcome`** (send/block bucket) plus optional **`result.zoominfo_contact_id`** when a ZoomInfo key is connected and a contact id can be attached after the employment decision — id attach only; it does not change the send/block bucket.

There is no web search on this capability. One email validator runs per request.

```bash
curl 'https://api.kingminos.com/v1/person/verify-employment' \
  -H 'Authorization: Bearer <your-key>' \
  -H 'Content-Type: application/json' \
  -d '{
    "email": "harris@outboundsync.com",
    "expected_company": { "domain": "outboundsync.com" },
    "external_ref": "contact-demo-1"
  }'
```

## What comes back

The envelope is schema version `2`. Branch on `answer.outcome` for sequencing — not on raw bounce or employment strings alone.

| Layer | Fields | Use |
| --- | --- | --- |
| Control | `answer.outcome`, `es_decision`, `answer.confidence`, `answer.summary` | Send vs block bucket. |
| Employment | `result.employment` | `still_there`, `left`, or `unknown` (layer 2 when the job-change hop ran). |
| Mailbox | `result.email_validation` | Bounce status, catch-all, role, SEG when present. |
| Employer | `result.current_company`, `result.company_name`, `result.company_domain` | Where the person works now. |
| Expected | `result.expected_company_name`, `result.expected_company_domain` | Echo of the request anchor. |
| CRM ids | `result.zoominfo_company_id`, `result.zoominfo_contact_id` | When returned by connected keys. |
| Label | `result.soft_miss` | Deterministic audit label — not a fifth outcome. |
| Audit | `result.evidence` | Debug only (`X-Router-Explain: full`); omit on `minimal`. |
| Billing | `usage.credits`, `usage.hops` | What ran and what was billed. |

**Decision outcomes** (`answer.outcome`):

| Outcome | Typical use |
| --- | --- |
| `high_confidence_send` | Safe to send on the current path. |
| `low_confidence_send` | Send with caution or human review. |
| `low_confidence_block` | Hold — weak evidence. |
| `high_confidence_block` | Do not send (hard bounce, left employer, etc.). |
| `no_decision` | Insufficient input or provider miss. |

The four send/block answers map `es_decision` → `hit`. Catch-all, SEG, role, and employment nuance inform the bucket and live in `answer.summary` and `result.email_validation`, not as separate outcome values.

You are only charged when an answer is delivered: `still_there`, `left`, or a definitive invalid mailbox. `unknown`, errors, timeouts, and empty results bill **0**. Any hop served by your own key (BYOK) bills a flat **0.1** credit.

Business misses stay HTTP `200`.

## Paths and price

OutboundSync sets `routing.path` explicitly. Omit `routing.path` to use `balance`. `value`, `auto`, `coverage`, `fast`, and `name_only` are **`400 invalid_routing`** on this capability.

| `path` | What it does | Credit cap | Credits on a delivered answer |
| --- | --- | --- | --- |
| `speed` | Email validation plus mailbox-vs-expected-company domain check. No paid profile lookup, no job-change hop. Confidence caps at `low` on speed — only a hard-bounce block is `high`. Use `balance` or `accuracy` to block on employment left. | 0.5 | 0.5 |
| `balance` (default) | Validate, then a paid LinkedIn profile lookup when there is no LinkedIn URL, then a job-change check when `expected_company` is present. | 13.5 | 0.5–13.5 |
| `accuracy` | Same as `balance`, plus an independent corroboration lookup. Empty or failed corroboration lowers confidence — no separate abstain SKU. | 14.5 | 0.5–14.5 |

The credit cap is each path's default `max_provider_credits`.

`routing.allow_paid_linkedin_lookup` defaults to `true`. Set `false` to skip the paid email→profile hop on `balance` / `accuracy`. While it is on, `max_provider_credits` must be ≥ 13 (find + job-change) or the API returns `400 invalid_routing`. Opting out lifts that floor.

**Validators:** the default path uses the house email validator. **Findymail** is a BYOK alternate validator only when the tenant or request explicitly selects it (`routing.only: ["findymail"]` or an explicit `order`). Never call both validators on the same request.

After the employment decision, when a **ZoomInfo** key is connected and a contact id is still missing, a ZoomInfo contact lookup by email may attach `result.zoominfo_contact_id`. A ZoomInfo miss, error, or `not_configured` keeps the employment answer. Contact id is not required for `es_decision: hit`.

## Input

| Field | Notes |
| --- | --- |
| `email` | Required for meaningful answers. |
| `expected_company` | Anchor employer for domain check and job-change logic. |
| `linkedin_url` | Preferred profile for the job-change check; otherwise profile discovery on `balance` / `accuracy` unless opted out. |
| `first_name` / `last_name` | Match-only corroboration. |
| `routing` | `path`, `allow_paid_linkedin_lookup`, `only`, `ignore`, `max_provider_credits`. |
| `external_ref`, `dry_run`, `compliance` | Same as other capabilities. |

## Soft-miss labels

`result.soft_miss` is present on every completed run. Use it for logging, not control flow.

| Label | Meaning |
| --- | --- |
| `still_there_clear` | Strong still-employed signal. |
| `left_clear` | Strong left signal. |
| `ambiguous_current` | Employment unclear. |
| `never_worked` | No evidence at expected employer. |
| `missing_linkedin` | Profile hop skipped or failed. |
| `email_ok_job_unknown` | Mailbox OK, job status unknown. |
| `vendor_conflict` | Sources disagree. |
| `catch_all_or_seg_or_role` | Deliverability guardrail. |
| `insufficient_input` | Missing required context. |
| `not_configured` | Required BYOK not stored. |
| `max_credits_reached` | Budget cap before run. |
| `provider_error` | Vendor failure. |
| `other` | Residual bucket. |

## Explain and cache

Prefer `X-Router-Explain: minimal` for CRM callouts. Use `full` for `result.evidence`.

`Idempotency-Key` replays a completed run.

## Errors

`400` with one of:

- `validation_failed`
- `invalid_routing`
- `invalid_compliance` / `invalid_explain`
- `zi_credentials_required` when ZoomInfo was required and no key is stored

`401` unauthorized. `403` scope denied. `409` idempotency states. `429` rate or budget limits — the `Idempotency-Key` is not spent.

`451 subject_suppressed` — the `email` or `linkedin_url` is on the global suppression list. Checked before cache, vendors, or credits. **0 credits.** Do not retry.

`503` store unavailable — retryable with the same `Idempotency-Key`.
