Contacts | Zuse Docs

POST /v2/contacts

Finds a person in People Data Labs from what you know about them (name, place, LinkedIn profile, employer, license) and returns every email and phone it holds. Each fact it reports is then checked against what Zuse already holds on that person, so you know whether it is the right person before you reach out.

This is the derived layer: from a data provider, not the board record.

Create a contact

Point at a license you already have:

bash

curl https://api.zuse.live/v2/contacts \
  -H "Authorization: Bearer $ZUSE_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 2f0d5f9e-1c3b-4a0e-8e7a-6b5c4d3e2f10" \
  -d '{ "license_id": 48211 }'

Or name the person, with their profile from a web search:

bash

curl https://api.zuse.live/v2/contacts \
  -H "Authorization: Bearer $ZUSE_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 2f0d5f9e-1c3b-4a0e-8e7a-6b5c4d3e2f11" \
  -d '{ "first_name": "Andrea", "last_name": "Laired", "city": "Tempe", "state": "AZ",
        "linkedin_url": "https://www.linkedin.com/in/andrea-laired-51393371" }'

Field	Type	Description
`license_id`	integer	The `id` of a license from professionals or licenses. Name, place and license are taken from the index.
`first_name`, `last_name`	string	Required when `license_id` is not sent.
`city`, `state`, `postal_code`	string	Where they live or work.
`linkedin_url`	string	Their LinkedIn profile. The surest way to match the right person.
`current_employer`	string	Where they work now.
`email`, `phone`	string	Anything already known. Helps the match; never replaced.
`license_number`, `license_state`	string	License details, when naming the person yourself.
`refresh`	boolean	Buy the record again even though your team already holds it.

With a LinkedIn profile, email or phone, the match must be very sure (People Data Labs likelihood 6 or more out of 10). With only a name and place, it can be less sure, and the cross-check below decides whether to trust it.

Response

json

{
  "data": {
    "id": "con_5f1d0c8e9a3b4c2d8e7f6a5b4c3d2e1f",
    "status": "completed",
    "matched": true,
    "name": "Andrea Laired",
    "personal_email": "andrea.laired@gmail.com",
    "work_email": null,
    "email": "andrea.laired@gmail.com",
    "phone": "(480) 555-0142",
    "linkedin_url": "https://www.linkedin.com/in/andrea-laired-51393371",
    "emails": [
      { "address": "andrea.laired@gmail.com", "tier": "recommended", "verification": "verified" },
      { "address": "alaired@yahoo.com", "tier": "historical", "last_seen": "2021-03-02", "num_sources": 2 }
    ],
    "phones": [
      { "number": "+14805550142", "display": "(480) 555-0142", "tier": "mobile", "valid": true }
    ],
    "likelihood": 8,
    "confidence": "confirmed",
    "cross_check": [
      { "field": "name", "label": "Name", "ours": "Andrea Laired", "pdl": "Andrea Laired", "agrees": true },
      { "field": "state", "label": "State", "ours": "AZ", "pdl": "Arizona", "agrees": true },
      { "field": "current_employer", "label": "Employer", "ours": "Green Bulldog", "pdl": "Green Bulldog", "agrees": true }
    ],
    "from_records": false,
    "note": null,
    "layer": "derived"
  },
  "billing": { "operation": "contact", "cost_usd": 0.6, "credit_remaining_usd": 9.4 }
}

Which email and phone to use

Nothing People Data Labs returns is dropped. Each address and number carries a tier:

Tier	Meaning	For outreach
`recommended`	The best current personal email (`personal_email`).	Yes
`work`	The current work email (`work_email`).	Yes
`personal`	Other personal emails on record.	Verify first
`historical`, `possible`	Older or lower-confidence emails.	Verify first
`mobile`	The personal mobile phone.	Yes
`listed`, `possible`	Other phones, and lower-confidence ones.	Verify first

An email or phone that exists but cannot be shown yet comes back masked, with masked: true: *******@*****.com or (XXX)-XXX-XXXX, and revealing_soon is true. A masked value is never charged for and never written onto your team's record of the person; ask again later to see it.

recommended and work emails are checked with an email verifier; a rejected one is marked in verification, not removed. A phone that is not a valid US number is marked valid: false.

Is it the right person?

confidence is:

confirmed: the name agrees, and so does the LinkedIn profile, or the state together with the city, employer or school.
likely: the name and state agree.
check: something disagrees. The record may be someone else: it is returned, but nothing on your team's record of the person is filled in from it.

Where a fact differs (agrees: false), both values are kept. Nothing your team already has is replaced.

Get a contact

GET /v2/contacts/{id} returns a result you already paid for, for 24 hours. Free.

Billing

$0.60 when the person is found with an email or phone. Free when People Data Labs has no confident match, and free when your team already holds the record (from_records: true) unless you send refresh. Up to 20 a minute and 300 a day. See Pricing and metering.

Also in

MCP: the find_contact tool. See MCP server.
Slack: contact 3 in a thread, or @Zuse contact Jane Doe, Tempe, AZ. See Zuse in Slack.
Workspace: Contact on any profile.

People who have asked to be left out

Someone who has asked not to be researched is refused with 403 before anything runs, and nothing is charged.