Other

Create a prospect

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

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

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" }),
});
post/v1/prospects

Request

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

Headers

Idempotency-Keystring

Supported for safe retry. Reuse the same key to receive the cached response without repeating the operation.

X-Request-Idstring

Optional caller-supplied request identifier. Values must match ^[A-Za-z0-9_-]{1,128}$; a valid value is echoed in the response X-Request-Id header, otherwise the API generates one.

Request body

person_idstring required
owner_user_idstring 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_notestring 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_labelstring nullable
last_contacted_atstring nullable
last_reviewed_atstring nullable

Response

Success

object required

Changes

No recorded changes to this operation across all 1 revision of this API.