Briefs

POST /v2/briefs

Writes short intro notes on a single person from the public web: who they are now, what has changed for them lately, and what to open the conversation with. It is the step after you have found someone and before you contact them.

Like an enrichment, a brief is the derived layer. It is written from public pages, it can be wrong, and it is not the board record. Read it before you rely on it.

A brief runs live research, so creating one takes seconds rather than milliseconds, sometimes up to a minute. Create one for the people you are about to contact, not for every result.

Create a brief

Point at a license you already have:

curl https://api.zuse.live/v2/briefs \
  -H "Authorization: Bearer $ZUSE_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 2c9f6a3e-1d47-4b0a-8e55-7a1c4f0b9d21" \
  -d '{ "license_id": 48211 }'

Or name the person yourself. The role and the employer make the brief sharper, so pass them when you know them, for example from an enrichment:

curl https://api.zuse.live/v2/briefs \
  -H "Authorization: Bearer $ZUSE_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 2c9f6a3e-1d47-4b0a-8e55-7a1c4f0b9d22" \
  -d '{ "first_name": "Jane", "last_name": "Doe", "city": "Los Angeles", "state": "CA",
        "title": "Veterinarian", "current_employer": "Example Animal Hospital" }'

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

Send an Idempotency-Key. A brief costs real money each time it runs, and with a key a retry returns the first brief and is not charged again. See Idempotency.

Response

201 Created, with a Location header pointing at the stored brief.

{
  "data": {
    "id": "brf_6f0c1d2e3a4b4c5d8e9f0a1b2c3d4e5f",
    "license_id": 48211,
    "status": "completed",
    "matched": true,
    "summary": "Associate veterinarian at a 24-hour hospital with an emergency and critical-care caseload.",
    "overview": {
      "employer": "Example Animal Hospital, a 24-hour hospital",
      "focus": "Emergency and critical care, small animal",
      "setting": "Urban ER, recently corporate-owned"
    },
    "triggers": [
      { "date": "June 2026", "text": "The hospital was acquired by a corporate group." },
      { "date": "March 2026", "text": "Completed a continuing-education track in emergency ultrasound." }
    ],
    "talking_points": [
      "Ask how scheduling has changed since the acquisition.",
      "Lead with the caseload, not the title."
    ],
    "sources": ["https://example.org/team", "https://example.com/news/acquisition"],
    "layer": "derived"
  },
  "billing": { "operation": "brief", "cost_usd": 0.25, "credit_remaining_usd": 9.75 }
}

The suggestions are a starting point for a person to edit, not a script. You are the sender of anything you write from them, and the laws on commercial email and calls apply to you.

Get a brief

GET /v2/briefs/{id}

Returns the stored brief, in the same shape, for 24 hours after it was written. Free. After 24 hours the id returns 404.

The notes themselves stay on your team's records. Ask for the same person again and they are returned from there: from_records is true, written_at says when they were written, and nothing is charged. Send "refresh": true to have new ones written, at the usual price.

Billing

Intro notes are their own operation (brief in billing and usage): $0.25 when matched is true, free when there was not enough to write one, free when the research itself fails (502 or 503), and free when your team already has notes for the person (from_records is true). The limit is 10 a minute and 100 a day, counting misses, separate from Background's. See Rate limits.

Background and Intro notes are separate requests. Running both for one person costs $0.50.

Errors