Skip to content

Verify employment

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

Try it in the console

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.

Terminal window
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"
}'

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.

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.

pathWhat it doesCredit capCredits on a delivered answer
speedEmail 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.50.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.50.5–13.5
accuracySame as balance, plus an independent corroboration lookup. Empty or failed corroboration lowers confidence — no separate abstain SKU.14.50.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.

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.

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.

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

Idempotency-Key replays a completed run.

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.