---
title: "Create a hand-off: returns an id and a sign-up link carrying the partner tag, move date and new address. Read-only — no account is created until the person signs up."
method: POST
path: "/v1/handoffs"
tags: ["core"]
---

# Create a hand-off: returns an id and a sign-up link carrying the partner tag, move date and new address. Read-only — no account is created until the person signs up.

`POST /v1/handoffs`

## Request

- Base URL: `https://www.putroots.com`
- URL: `https://www.putroots.com/v1/handoffs`
- Auth: one of:
  - HTTP bearer
  - HTTP bearer

When someone has just signed a lease, accepted an offer, or otherwise has a move coming: returns a PutRoots link that pre-fills their move date and new address and attributes them to you. Nothing is created on their behalf — they sign up themselves by opening the link. Use the returned id with GET /v1/handoffs/{id} to see which stage of the move they are in.

## Request body

- object
  - `trigger` string, required: What set the move off: lease_signed, offer_accepted, relocation_approved, or your own short label.
  - `stage` 'pre_arrival' | 'housing' | 'move_planning' | 'move_logistics' | 'activate' | 'settle' | 'stabilize': Which stage of the journey they are in right now, if you know it.
  - `d0` string: Move-in day, YYYY-MM-DD.
  - `to` string: The new address, as one line.
  - `profile_seed` object: Reserved. Accepted but not applied yet — the person fills their own profile after signing up.

## Response `200`

OK

- object
  - `source` unknown, required
  - `fetched_at` string, date-time, required
  - `id` string, required
  - `url` string, required
  - `partner` string, required
  - `trigger` string, required
  - `stage` string, nullable
  - `d0` string, nullable
  - `to` string, nullable
  - `dry_run` boolean, required: true when called with a pr_test_ key.

## Other responses

- `400`: Bad input — error says which field.
- `401`: No key / bad token.
- `403`: Key is fine but not for this: pending approval, revoked, scope missing, or an operation only the renter's own account may call.
- `404`: No such lead / hand-off / listing under this key.
- `409`: Conflict: the code is already registered.
- `429`: Rate limited; Retry-After in seconds.

---

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