---
title: "Start a Person Intelligence snapshot (scope write:intelligence)"
method: POST
path: "/api/v1/intelligence/people"
tags: ["v1"]
---

# Start a Person Intelligence snapshot (scope write:intelligence)

`POST /api/v1/intelligence/people`

## Request

- Base URL: `https://api.signalraven.ai`
- URL: `https://api.signalraven.ai/api/v1/intelligence/people`
- Auth: HTTP bearer

Explicit refresh (2026-10-06): if a snapshot for this person exists it is returned with cached: true (200) however old it is, and nothing is spent, until refresh: true is sent. A refresh is honoured once the newest snapshot is 7 days old; before that the same snapshot is returned with refreshAvailableAt. A new run (202) spends credits and requires an active workspace. For ongoing weekly checks use /api/v1/intelligence/monitoring.

## Request body

- V1RunPersonBody
  - `personUrl` string, required: A LinkedIn profile URL (/in/<slug>).
  - `sourceCompanyReportId` string, uuid: Optional Account Intelligence report this person came from (must be in your workspace; 404 otherwise).
  - `refresh` boolean: Ask for a new report. Without it the newest ready report is returned (cached: true) however old it is. A refresh is honoured only once that report is 7 days old; before that the same report is returned with refreshAvailableAt. A refresh spends credits like a first run.

## Response `200`

Existing snapshot returned (nothing spent)

- V1RunResponse
  - `data` V1RunOutcome, required
    - `id` string, required
    - `slug` string, required
    - `status` 'queued' | 'running' | 'ready' | 'failed', required
    - `cached` boolean, required: true when an existing report was returned and nothing was spent (cached reports are returned until you ask for a refresh; a refresh is possible once the report is 7 days old); false when a run was enqueued (202).
    - `refreshAvailableAt` string, date-time: Present on a cached response while the report is younger than 7 days: the ISO time from which a refresh request will start a new run (readyAt + 7 days).
  - `_meta` V1Meta, required
    - `mode` 'live' | 'sample', required
    - `notice` string
    - `cta` object
      - `text` string, required
      - `url` string, required

## Other responses

- `202`: Run enqueued; poll GET /api/v1/intelligence/people/{id}
- `400`: Missing or invalid personUrl
- `403`: Insufficient scope or inactive workspace
- `404`: sourceCompanyReportId not in this workspace

---

[API](https://skmtc.dev/signalraven/apis/zygnal-api.md) · [All operations](https://skmtc.dev/signalraven/apis/zygnal-api/llms.txt) · [OpenAPI document](https://skmtc.dev/signalraven/apis/zygnal-api/revisions/36e1d9b9d604?raw)