---
title: "Prepare an address share (step 1 of 2)"
method: POST
path: "/api/conversations/{id}/address/prepare"
tags: ["Orders"]
---

# Prepare an address share (step 1 of 2)

`POST /api/conversations/{id}/address/prepare`

## Request

- Base URL: `https://clearlist.me`
- URL: `https://clearlist.me/api/conversations/{id}/address/prepare`
- Auth: one of:
  - API key in header `X-ClearList-API-Key`
  - OAuth 2 (authorization code, authorization URL `https://clearlist.me/oauth/authorize`, token URL `https://clearlist.me/api/oauth/token`, scopes: `write`)

Resolves who would receive the seller's address in this conversation and returns a single-use confirmation token. DISCLOSES NOTHING: no message is written and the buyer cannot tell this was called. Show the seller the returned recipient name and email and get their explicit yes before calling the confirm endpoint. The address and recipient are frozen here, so nothing sent at step 2 can change either. Only a buyer who verified their email by reserving can receive an address; an enquiry-only conversation returns 403 BUYER_NOT_VERIFIED.

## Request body

- object
  - `address` string: Only when the account has no street address on file, or the seller wants a different one for this pickup. Used for this share only and never saved to the account.

## Response `200`

Recipient resolved and a confirmation token minted. Nothing disclosed.

- object
  - `success` boolean
  - `data` object
    - `confirmation_token` string
    - `expires_at` string, date-time
    - `recipient` object
      - `name` string
      - `email` string: The buyer's email, or an empty string when the conversation has none. Not guaranteed to be a valid address, so do not treat it as one.
    - `address` string
    - `address_source` 'account' | 'supplied'
    - `conversation_id` string

## Other responses

- `400`: Address supplied but empty or over 500 characters.
- `401`: Missing or invalid credential.
- `403`: Read-only key, not your conversation, or BUYER_NOT_VERIFIED: the buyer has only sent an enquiry and has not verified their email, so an agent cannot share an address with them.
- `404`: Conversation not found.
- `409`: NO_ADDRESS_ON_FILE: no street address stored for this account. Ask the seller and pass it as `address`.
- `429`: Too many address shares in the last hour.
- `500`: Failed to prepare the address share.

---

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