---
title: "Run (or return the existing) Person Intelligence snapshot"
method: POST
path: "/api/me/intelligence/person"
tags: ["me", "intelligence"]
---

# Run (or return the existing) Person Intelligence snapshot

`POST /api/me/intelligence/person`

## Request

- Base URL: `https://api.signalraven.ai`
- URL: `https://api.signalraven.ai/api/me/intelligence/person`
- Auth: none declared

Explicit refresh (ruling 2026-10-06): the newest ready snapshot for (customer, person slug) is returned with cached: true however old it is, until refresh: true is sent; a refresh is honoured once that snapshot is 7 days old (before that the same snapshot is returned with refreshAvailableAt). Optional sourceCompanyReportId anchors the run to a Buying Committee entry (§4.3 dual-FK guard verifies ownership; cross-tenant → 404).

## Request body

- PostPersonIntelligenceBody
  - `personUrl` string, required: LinkedIn person URL — /in/<slug>. Canonicalized via normalizeLinkedinUrl.
  - `sourceCompanyReportId` string, uuid, nullable: Optional — set when running Person IX from an Account IX Buying Committee row. Verified against caller customer_id before accepting (dual-FK guard §10.3.1 #4). 404 on cross-tenant.
  - `initialProfile` object, nullable: Optional seed for the profile jsonb so Recent Activity + workspace render the natural name before worker enrichment completes. Worker markPersonReady overwrites with authoritative actor data.
    - `fullName` string, nullable
    - `currentTitle` string, nullable
    - `currentCompany` string, nullable
  - `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 `201`

Snapshot queued or returned from cache

- PostPersonIntelligenceResponse
  - `snapshotId` string, uuid, required
  - `slug` string, required
  - `status` 'queued' | 'running' | 'ready' | 'failed', required
  - `cached` boolean, required: true when an existing ready snapshot was returned and nothing was spent (cached snapshots are returned until you ask for a refresh; a refresh is possible once the snapshot is 7 days old); false when a run was enqueued.
  - `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).
  - `started` boolean

## Other responses

- `400`: Validation error / bad URL
- `402`: Insufficient credits
- `403`: Insufficient role
- `404`: sourceCompanyReportId not owned by caller

---

[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)