Verify employment
POST https://api.kingminos.com/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.
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
Section titled “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
Section titled “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.
| 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
Section titled “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
Section titled “Explain and cache”Prefer X-Router-Explain: minimal for CRM callouts. Use full for result.evidence.
Idempotency-Key replays a completed run.
Errors
Section titled “Errors”400 with one of:
validation_failedinvalid_routinginvalid_compliance/invalid_explainzi_credentials_requiredwhen 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.