---
title: "Share the address (step 2 of 2)"
method: POST
path: "/api/conversations/{id}/address"
tags: ["Orders"]
---

# Share the address (step 2 of 2)

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

## Request

- Base URL: `https://clearlist.me`
- URL: `https://clearlist.me/api/conversations/{id}/address`
- 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`)

Sends the seller's address to the buyer. IRREVERSIBLE: the buyer receives it in the thread and by email, and the seller is emailed a record of every share. A first-party session sends `{ address }`. An API key must send `{ confirmation_token }` from the prepare endpoint and NO address — the string was frozen at step 1 and cannot be changed here. An API key arriving without a valid token is refused with CONFIRMATION_REQUIRED.

## Headers

- `Idempotency-Key` string

## Request body

- object
  - `confirmation_token` string: Required for API-key callers. From the prepare endpoint.
  - `address` string: First-party sessions only. Ignored when a confirmation_token is present.

## Response `200`

Address sent. The buyer has it and the seller has been emailed a record.

- object
  - `success` boolean
  - `data` object
    - `message_id` string
    - `type` 'address_share'
    - `created_at` string, date-time

## Other responses

- `400`: Address missing or over 500 characters (first-party path).
- `401`: Missing or invalid credential.
- `403`: Read-only key, not your conversation, CONFIRMATION_REQUIRED (an API key with no token), or INVALID_CONFIRMATION (the token is unknown, expired, already used, minted by another seller, or minted for a different conversation). Note the first two carry no `code`. Only the wrong-conversation case sets `retryable: true`, leaving the token usable; every other reason is terminal and retrying it will not succeed.
- `404`: Conversation not found.
- `409`: `code: idempotency_conflict`. A request with this Idempotency-Key is still being processed. Retry the same request with the same key after a few seconds: if the first request succeeded the retry replays its response; if it failed, or has been pending for over a minute, the retry runs the operation again.
- `422`: `code: idempotency_key_reuse`. While an earlier request with this Idempotency-Key is still running or succeeded within the last 24h, the key was sent to the same operation with a different body (compared byte for byte) or from a different kind of credential (signed-in session, API key, or OAuth token). Nothing was executed and the original record is untouched, so retrying with this key repeats the 422. Send the request with a new key.
- `429`: Too many confirmation attempts in the last hour.
- `500`: Failed to share the address.
- `503`: The seller account could not be read, so the share was refused rather than performed without a record.

---

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