---
title: "Add or update seen entries"
method: POST
path: "/v1/seen"
tags: ["Lists"]
---

# Add or update seen entries

`POST /v1/seen`

## Request

- Base URL: `https://api.recruitmcp.com`
- URL: `https://api.recruitmcp.com/v1/seen`
- Auth: one of:
  - HTTP bearer
  - OAuth 2 (authorization code, authorization URL `https://recruitmcp.com/oauth/authorize`, token URL `https://recruitmcp.com/oauth/token`, scopes: `lists:write`)
  - OAuth 2 (authorization code, authorization URL `https://recruitmcp.com/oauth/authorize`, token URL `https://recruitmcp.com/oauth/token`, scopes: `sourcing:spend`)

Up to 1000 people. An entry matching an existing one (same profile, or same name and employer) is updated. Use external_ids to keep your ATS ids next to each person.

Scope: `lists:write`. A key with `sourcing:spend` is also accepted.

## Headers

- `Idempotency-Key` string
- `RecruitMCP-Version` '2026-10-13'
- `RecruitMCP-Customer` string

## Request body

- object
  - `entries` SeenEntryInput[], required
    - `profile_url` string
    - `profile_id` string
    - `full_name` string
    - `current_employer` string
    - `status` 'seen' | 'shortlisted' | 'contacted' | 'rejected' | 'do_not_contact'
    - `note` string
    - `tags` string[]
    - `external_ids` object

## Response `200`

The stored entries.

- SeenList
  - `object` 'list', required
  - `data` SeenEntry[], required
    - `id` string, required
    - `object` 'seen_entry', required
    - `status` 'seen' | 'shortlisted' | 'contacted' | 'rejected' | 'do_not_contact', required
    - `profile_url` string, nullable
    - `full_name` string, nullable
    - `current_employer` string, nullable
    - `note` string, nullable
    - `tags` string[]
    - `external_ids` object: Your ids for this person, for example {"ats": "cand_123"}.
    - `updated_at` string, date-time, nullable
  - `next_cursor` string, nullable, required: Pass as cursor for the next page. Null on the last page.
  - `has_more` boolean, required

## Other responses

- `400`: `invalid_request` (do not retry): A field is missing or has a value this endpoint does not accept. `unsupported_version` (do not retry): RecruitMCP-Version is not a supported version.
- `401`: `unauthorized` (do not retry): Missing bearer API key.
- `403`: `forbidden` (do not retry): This customer is disabled. `insufficient_scope` (do not retry): This key does not include the scope this endpoint requires.
- `429`: `rate_limited` (retry): Per-key rate limit exceeded.

## Changes

- **2026-10-20** `ad27b35513a6`: 4 warning, 2 info
  - added the new `approval_forced` enum value to the `error/code` response property for the response status `400`
  - added the new `approval_forced` enum value to the `error/code` response property for the response status `401`
  - added the new `approval_forced` enum value to the `error/code` response property for the response status `403`
  - added the new `approval_forced` enum value to the `error/code` response property for the response status `429`
  - …2 more

[Operation history](https://skmtc.dev/recruitmcp/apis/recruitmcp-api/changes/v1/seen/post.md)

---

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