---
title: "Create a prospect"
method: POST
path: "/v1/prospects"
tags: ["Other"]
---

# Create a prospect

`POST /v1/prospects`

## Request

- Base URL: `https://api.yardstick.team`
- URL: `https://api.yardstick.team/v1/prospects`
- Auth: HTTP bearer

Create a prospect

**Required scopes:** `prospects:write`

Creates CRM relationship state for an existing Person; it never creates the Person. If `person_id` is unavailable in the caller's organization and live/test partition, the response is 404 `person_not_found` with `param: person_id`.

**Example (curl):**

```bash
curl -X POST https://api.yardstick.team/v1/prospects \
  -H 'Authorization: Bearer ys_sk_live_…' \
  -H 'Content-Type: application/json' \
  -d '{"person_id":"per_abc123"}'
```

**Example (TypeScript):**

```ts
await fetch("https://api.yardstick.team/v1/prospects", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.YS_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ person_id: "per_abc123" }),
});
```

## Headers

- `Idempotency-Key` string
- `X-Request-Id` string

## Request body

- object
  - `person_id` string, required
  - `owner_user_id` string, uuid, nullable: The teammate who owns this prospect. Omit the field and the prospect is owned by the human whose API key you are using; send `null` to leave it unowned. The user must be an active member of this organization, or the request is refused with `400 invalid_request_body`. Creating a prospect with an owner records the transition but creates no handoff task. Changing an existing prospect's owner separately creates a handoff task for the new owner unless it is an unassignment, self-assignment, or the owner has no resolvable email. Once a `next_follow_up_at` is set, the owner gets a distinct “Follow up with …” task; a prospect created here and left unowned has nobody to receive that task.
  - `owner_handoff_note` string, nullable: An optional note stored with the permanent owner-change timeline entry. On create, it requires a non-null owner; creating the prospect still does not mint a handoff task.
  - `source_label` string, nullable
  - `last_contacted_at` string, nullable
  - `last_reviewed_at` string, nullable

## Response `200`

Success

- object

## Other responses

- `400`: Invalid request
- `401`: Authentication failure
- `403`: Permission denied (scope or feature flag)
- `404`: Resource not found. The error uses the resource-specific code and param names the exact body field or path parameter that referenced it.
- `409`: Conflict (e.g. idempotency key reuse with different body)
- `429`: Rate limited
- `500`: Internal error

---

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