---
title: "Build a full public-footprint profile for a person."
method: POST
path: "/api/v1/dossier"
tags: ["People research"]
---

# Build a full public-footprint profile for a person.

`POST /api/v1/dossier`

## Request

- Base URL: `https://deepsearch.app`
- URL: `https://deepsearch.app/api/v1/dossier`
- Auth: HTTP bearer

Pass a candidate from /search (or a minimal person object) and stream a structured dossier - identity, contact, social accounts, locations, work, mentions and a written summary with cited sources. Reports are cached privately for each account: repeating the same request from the same account replays the cached report instantly and consumes no usage. Reports are not shared between accounts.

## Headers

- `Idempotency-Key` string
- `X-Request-Id` string
- `X-DeepSearch-Sandbox` 'true' | '1'
- `X-DeepSearch-Client` string

## Request body

- object
  - `person` object, required
    - `id` string
    - `name` string, required
    - `headline` string
    - `avatarUrl` string, uri
    - `avatarCandidates` string[]
    - `identityContext` 'account' | 'authority' | 'submitted'
    - `avatarContext` 'account' | 'authority' | 'submitted' | 'subject'
    - `initials` string
    - `location` string
    - `age` integer
    - `confidence` number
    - `tags` string[]
    - `primaryUsername` string
    - `primaryPlatform` 'instagram' | 'facebook' | 'x' | 'twitter' | 'tiktok' | 'linkedin' | 'youtube' | 'whatsapp' | 'telegram' | 'snapchat' | 'reddit' | 'threads' | 'bluesky' | 'mastodon' | 'pinterest' | 'twitch' | 'discord' | 'tinder' | 'bumble' | 'hinge' | 'onlyfans' | 'fansly' | 'patreon' | 'cameo' | 'vsco' | 'tumblr' | 'flickr' | 'strava' | 'apple_music' | 'bandcamp' | 'lastfm' | 'vimeo' | 'letterboxd' | 'goodreads' | 'quora' | 'github' | 'stack_overflow' | 'hacker_news' | 'npm' | 'kaggle' | 'medium' | 'substack' | 'product_hunt' | 'wellfound' | 'crunchbase' | 'behance' | 'dribbble' | 'soundcloud' | 'spotify' | 'orcid' | 'google_scholar' | 'researchgate' | 'academia' | 'linktree' | 'personal_website' | 'company_page' | 'other'
    - `primaryUrl` string, uri
    - `linkedProfileUrls` string[]
    - `seedEmail` string
    - `seedPhone` string
  - `refresh` boolean
  - `format` 'sse' | 'json'
  - `sandbox` boolean

## Response `200`

Success. With format=json a single object is returned; otherwise events stream as text/event-stream.

- DossierResponse
  - `request_id` string, required
  - `metadata` object, required
    - `api_version` 'v1', required
    - `operation` 'search' | 'dossier' | 'chat' | 'entity_search' | 'entity_dossier' | 'reverse_image' | 'vin', required
    - `request_id` string, required
    - `generated_at` string, required
    - `sandbox` boolean
  - `usage` object, required
    - `metered` boolean, required
    - `credits` number, required
    - `percentageCharged` number
    - `remainingPercent` number
    - `resetAt` string
    - `source` 'included' | 'extra' | 'mixed'
    - `allowanceSource` 'weekly' | 'coin'
    - `cached` boolean
    - `idempotencyKey` string
    - `replayed` boolean
    - `sandbox` boolean
  - `events` union[], required
    - union
      - object
        - `type` 'hit', required
        - `hit` union, required
          - object
            - `id` string, required
            - `name` string, required
            - `headline` string
            - `avatarUrl` string, uri
            - `avatarCandidates` string[]
            - `identityContext` 'account' | 'authority' | 'submitted'
            - `avatarContext` 'account' | 'authority' | 'submitted' | 'subject'
            - `initials` string, required
            - `location` string
            - `age` integer
            - `confidence` number, required
            - `tags` string[], required
            - `primaryUsername` string
            - `primaryPlatform` 'instagram' | 'facebook' | 'x' | 'twitter' | 'tiktok' | 'linkedin' | 'youtube' | 'whatsapp' | 'telegram' | 'snapchat' | 'reddit' | 'threads' | 'bluesky' | 'mastodon' | 'pinterest' | 'twitch' | 'discord' | 'tinder' | 'bumble' | 'hinge' | 'onlyfans' | 'fansly' | 'patreon' | 'cameo' | 'vsco' | 'tumblr' | 'flickr' | 'strava' | 'apple_music' | 'bandcamp' | 'lastfm' | 'vimeo' | 'letterboxd' | 'goodreads' | 'quora' | 'github' | 'stack_overflow' | 'hacker_news' | 'npm' | 'kaggle' | 'medium' | 'substack' | 'product_hunt' | 'wellfound' | 'crunchbase' | 'behance' | 'dribbble' | 'soundcloud' | 'spotify' | 'orcid' | 'google_scholar' | 'researchgate' | 'academia' | 'linktree' | 'personal_website' | 'company_page' | 'other'
            - `primaryUrl` string, uri
            - `linkedProfileUrls` string[]
            - `seedEmail` string
            - `seedPhone` string
            - `kind` 'person'
          - object
            - `id` string, required
            - `name` string, required
            - `legalName` string
            - `headline` string
            - `logoUrl` string, uri
            - `domain` string
            - `initials` string, required
            - `confidence` number, required
            - `tags` string[], required
            - `jurisdiction` string
            - `status` 'active' | 'dissolved' | 'unknown'
            - `seedDomain` string
            - `seedRegistryId` string
            - `seedRegistrySource` string
            - `kind` 'company', required
      - object
        - `type` 'text', required
        - `delta` string, required
      - object
        - `type` 'summary', required
        - `delta` string, required
      - object
        - `type` 'sources', required
        - `sources` object[], required
          - `id` string, required
          - `position` number, required
          - `url` string, required
          - `title` string, required
          - `domain` string, required
          - `snippet` string
          - `authorName` string
          - `authorImageUrl` string
          - `cited` boolean
          - `publishedAt` string
      - object
        - `type` 'related', required
        - `questions` string[], required
      - object
        - `type` 'section', required
        - `key` 'identity' | 'photos' | 'contact' | 'socials' | 'locations' | 'relatives' | 'work' | 'education' | 'mentions' | 'dating' | 'relationships', required
        - `data` unknown, required
      - object
        - `type` 'entity_section', required
        - `key` 'identity' | 'registration' | 'industry' | 'financials' | 'funding' | 'executives' | 'locations' | 'linkage' | 'contact' | 'mentions', required
        - `data` unknown, required
      - object
        - `type` 'vehicle_section', required
        - `key` 'identity' | 'engine' | 'safety' | 'recalls' | 'history', required
        - `data` unknown, required
      - object
        - `type` 'image_match', required
        - `match` object, required
          - `url` string, required
          - `sourceDomain` string, required
          - `title` string
          - `imageUrl` string
          - `thumbnailUrl` string
          - `date` string
          - `snippet` string
          - `matchKind` string
      - object
        - `type` 'similar_image', required
        - `image` object, required
          - `imageUrl` string, required
          - `title` string
          - `thumbnailUrl` string
          - `sourceUrl` string
          - `sourceDomain` string
      - object
        - `type` 'image_summary', required
        - `result` object, required
          - `matches` object[]
            - `url` string, required
            - `sourceDomain` string, required
            - `title` string
            - `imageUrl` string
            - `thumbnailUrl` string
            - `date` string
            - `snippet` string
            - `matchKind` string
          - `similar` object[]
            - `imageUrl` string, required
            - `title` string
            - `thumbnailUrl` string
            - `sourceUrl` string
            - `sourceDomain` string
          - `provider` string, required
      - object
        - `type` 'done', required
      - object
        - `type` 'error', required
        - `message` string, required
        - `code` string
      - object
        - `type` string, required
  - `status` 'partial'
  - `warning` string
  - `object` 'dossier_result', required
  - `cached` boolean, required
  - `dossier` object, required
    - `summary` string, required
    - `sections` object, required
      - `identity` object
        - `id` string
        - `name` string
        - `headline` string
        - `avatarUrl` string, uri
        - `avatarCandidates` string[]
        - `identityContext` 'account' | 'authority' | 'submitted'
        - `avatarContext` 'account' | 'authority' | 'submitted' | 'subject'
        - `initials` string
        - `location` string
        - `age` integer
        - `confidence` number
        - `tags` string[]
        - `primaryUsername` string
        - `primaryPlatform` 'instagram' | 'facebook' | 'x' | 'twitter' | 'tiktok' | 'linkedin' | 'youtube' | 'whatsapp' | 'telegram' | 'snapchat' | 'reddit' | 'threads' | 'bluesky' | 'mastodon' | 'pinterest' | 'twitch' | 'discord' | 'tinder' | 'bumble' | 'hinge' | 'onlyfans' | 'fansly' | 'patreon' | 'cameo' | 'vsco' | 'tumblr' | 'flickr' | 'strava' | 'apple_music' | 'bandcamp' | 'lastfm' | 'vimeo' | 'letterboxd' | 'goodreads' | 'quora' | 'github' | 'stack_overflow' | 'hacker_news' | 'npm' | 'kaggle' | 'medium' | 'substack' | 'product_hunt' | 'wellfound' | 'crunchbase' | 'behance' | 'dribbble' | 'soundcloud' | 'spotify' | 'orcid' | 'google_scholar' | 'researchgate' | 'academia' | 'linktree' | 'personal_website' | 'company_page' | 'other'
        - `primaryUrl` string, uri
        - `linkedProfileUrls` string[]
        - `seedEmail` string
        - `seedPhone` string
      - `photos` string[]
      - `contact` object
        - `emails` string[], required
        - `phones` string[], required
        - `whatsapp` boolean
        - `telegram` union
          - string
          - boolean
      - `socials` object[]
        - `platform` 'instagram' | 'facebook' | 'x' | 'twitter' | 'tiktok' | 'linkedin' | 'youtube' | 'whatsapp' | 'telegram' | 'snapchat' | 'reddit' | 'threads' | 'bluesky' | 'mastodon' | 'pinterest' | 'twitch' | 'discord' | 'tinder' | 'bumble' | 'hinge' | 'onlyfans' | 'fansly' | 'patreon' | 'cameo' | 'vsco' | 'tumblr' | 'flickr' | 'strava' | 'apple_music' | 'bandcamp' | 'lastfm' | 'vimeo' | 'letterboxd' | 'goodreads' | 'quora' | 'github' | 'stack_overflow' | 'hacker_news' | 'npm' | 'kaggle' | 'medium' | 'substack' | 'product_hunt' | 'wellfound' | 'crunchbase' | 'behance' | 'dribbble' | 'soundcloud' | 'spotify' | 'orcid' | 'google_scholar' | 'researchgate' | 'academia' | 'linktree' | 'personal_website' | 'company_page' | 'other', required
        - `handle` string
        - `url` string
        - `followers` number
        - `verified` boolean
      - `locations` object
        - `current` string
        - `addresses` string[], required: Approximate / public-record locations only - never precise
        - `past` string[], required
      - `relatives` object[]
        - `name` string, required
        - `relation` string
      - `work` object[]
        - `org` string, required
        - `title` string
        - `period` string
        - `current` boolean
      - `education` object[]
        - `school` string, required
        - `field` string
        - `period` string
      - `mentions` object[]
        - `title` string, required
        - `url` string, required
        - `source` string, required
        - `snippet` string
        - `date` string
        - `kind` 'article' | 'mention' | 'photo' | 'profile' | 'news'
      - `dating` object[]
        - `platform` string, required
        - `url` string
        - `note` string
      - `relationships` object[]
        - `partner` string, required
        - `status` string
        - `period` string
        - `note` string
        - `source` string
        - `sourceName` string
        - `current` boolean
        - `sourceType` 'confirmed' | 'reported' | 'rumored'
        - `confidence` number
    - `sources` object[], required
      - `id` string, required
      - `position` number, required
      - `url` string, required
      - `title` string, required
      - `domain` string, required
      - `snippet` string
      - `authorName` string
      - `authorImageUrl` string
      - `cited` boolean
      - `publishedAt` string

## Other responses

- `400`: The request body was missing, malformed, or failed validation.
- `401`: The API key is missing, invalid, or revoked. The body includes action/url/message - direct the user to sign up and create a key, then retry.
- `402`: The requested capability is unavailable on the user's plan, or included usage and extra credits are exhausted. The body includes action/url/message - direct the user to upgrade, add credits, or wait for the reset, then retry. Agents cannot pay directly.
- `403`: The API key lacks the scope required for this endpoint.
- `409`: The Idempotency-Key was reused with a different request body.
- `413`: The request body is larger than the API accepts.
- `429`: The caller exceeded the API rate limit. Retry after the reset time or Retry-After header.
- `503`: A temporary service-wide spend cap was reached. Retry later.

---

[API](https://skmtc.dev/deepsearch/apis/deepsearch-api.md) · [All operations](https://skmtc.dev/deepsearch/apis/deepsearch-api/llms.txt) · [OpenAPI document](https://skmtc.dev/deepsearch/apis/deepsearch-api/revisions/85fc8e2576a3?raw)