Enrichments

POST /v2/enrichments

Researches a single person and returns findings with a source for each field. This is the derived layer: it is useful context, but it is not the board record and is not verified by Zuse.

For what to say to the person, rather than facts about them, see Briefs.

An enrichment runs live research, so creating one takes seconds rather than milliseconds. Create one for the people you are going to act on, not for every result.

Create an enrichment

Point at a license you already have:

curl https://api.zuse.live/v2/enrichments \
  -H "Authorization: Bearer $ZUSE_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 7b1e0b0e-6f0a-4a5e-9a51-2f3a6b0c9d11" \
  -d '{ "license_id": 48211 }'

Or name the person yourself:

curl https://api.zuse.live/v2/enrichments \
  -H "Authorization: Bearer $ZUSE_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 7b1e0b0e-6f0a-4a5e-9a51-2f3a6b0c9d12" \
  -d '{ "first_name": "Jane", "last_name": "Doe", "city": "Los Angeles", "state": "CA" }'

Any field you send alongside license_id overrides what the index holds.

Research is kept on your team's records

The first time anyone on your team researches a person, through the API, the console, the MCP server, Slack or the workspace, what is found is kept on your team's records. Asking about the same person again returns it from there: from_records is true, billing.cost_usd is 0, nothing is researched, and the request does not count towards the research limits.

To research the person again on purpose, send "refresh": true. That is a new, charged run, and it replaces what is on file.

curl https://api.zuse.live/v2/enrichments \
  -H "Authorization: Bearer $ZUSE_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "license_id": 48211, "refresh": true }'

A person is recognised by their license (state, license type and number), or, when no license is given, by name and state. A different city or a different license number is treated as a different person, so two people who share a name are never mixed up. A run that matched nobody keeps nothing, so asking again looks again.

Your team's records are yours alone. Another customer who researches the same person starts from the license record and receives none of what your team found.

Always send an Idempotency-Key

This is the one call that costs real money each time it runs. If your connection drops while it is running, you cannot tell whether it finished. With an Idempotency-Key, sending the same request again returns the first result and is not charged again. See Idempotency.

Response

201 Created, with a Location header pointing at the new enrichment.

{
  "data": {
    "id": "enr_3f2b8c1d9a7e4f60b5c2d1e0f9a8b7c6",
    "license_id": 48211,
    "status": "completed",
    "matched": true,
    "profile": {
      "university": "UC Davis School of Veterinary Medicine",
      "currentEmployerWebsite": "https://example-animal-hospital.com",
      "credentials": "DVM",
      "email": "jdoe@example-animal-hospital.com",
      "phone": null,
      "city": "Los Angeles",
      "state": "CA",
      "linkedin": "https://www.linkedin.com/in/example"
    },
    "employment": {
      "title": "Associate Veterinarian",
      "current_employer": "Example Animal Hospital",
      "current_employer_as_of": "2026-08-14",
      "education": "UC Davis School of Veterinary Medicine"
    },
    "sources": {
      "university": ["https://example-animal-hospital.com/team"],
      "email": ["https://example-animal-hospital.com/team"]
    },
    "citations": ["https://example-animal-hospital.com/team"],
    "as_of": "2026-08-14",
    "layer": "derived",
    "note": null,
    "from_records": false,
    "researched_at": "2026-10-06T17:04:11+00:00"
  },
  "billing": { "operation": "enrich", "cost_usd": 0.25, "credit_remaining_usd": 9.75 }
}

email and phone are returned only when they are publicly listed for that person. The research is instructed to leave out a clinic's general or front-desk line rather than present it as a personal number. Still, confirm any contact detail before relying on it.

Get an enrichment

GET /v2/enrichments/{id}

Returns the same body again, free, for 24 hours after it was created. After that the id returns 404. Only the account that created an enrichment can read it.

The id is for retries and short-lived references. The research itself stays on your team's records: create an enrichment for the same person again and it is returned from there, free.

Billing

Charged $0.25 when matched is true. A run that finds no confident match is free, and so is one where the research itself fails (502 or 503). A person your team has already researched is free (from_records is true) unless you send refresh. An account can create up to 100 enrichments a day, counting misses, and 10 a minute. See Rate limits.

Errors

People who have asked to be left out

A licensed professional can ask Zuse not to enrich them. A request for such a person is answered with 403 and the code enrichment_unavailable, before any research is run and at no charge. Do not retry it.

The match is by license number when you send one, and otherwise by name and state. Two people with the same first and last name in the same state cannot be told apart from a name alone, so a request for either is refused. Send license_id or a license number to avoid that.