Overlap

Developers

API reference

Add blind price matching to your own software. Your platform opens negotiations and receives outcomes. Each party, or an agent acting for it, submits its sealed figure with its own party token, so your platform never needs to handle the figures.

Authentication

Firm endpoints use an API key from Workspace → API and webhooks, sent as a bearer token. API access is included with every paid plan. Keys are shown once; store them as secrets.

curl https://xelcome.com/api/v1/me \
  -H "Authorization: Bearer ovl_live_..."

Party endpoints use a party token instead. Each negotiation has two, one per side, and a party token can only see and act for its own side. Requests are limited to 120 per minute per key.

Matching rules

  • The seller seals the lowest it will accept; the buyer seals the most it will pay. One figure per side per round.
  • When both are in: if buyer ≥ seller, the negotiation resolves at the midpoint, rounded half up to the cent.
  • Otherwise the round closes. No one learns either figure or the size of the gap.
  • In later rounds a seller can’t raise its figure and a buyer can’t lower it.
  • Up to 3 rounds. Negotiations expire after 30 days. Sealed figures are erased when a negotiation ends.

Amounts are integers in the smallest currency unit (cents).

POST/api/v1/negotiations

Opens a negotiation and returns both party tokens and their hosted page URLs. Give each party only its own token or URL.

FieldDescription
titleRequired. Up to 200 characters, shown to both parties.
descriptionOptional. Up to 2,000 characters.
seller_label, buyer_labelOptional display names. Default “Seller” and “Buyer”.
seller_email, buyer_emailOptional. Used for result notices and, with send_invites, to email each party its link.
send_invitesOptional boolean. Email each party its hosted link, so your system never handles it.
max_roundsOptional, 1 to 3. Default 3.
currencyOptional ISO code. Default USD.
external_idOptional. Your reference; must be unique per firm.
curl -X POST https://xelcome.com/api/v1/negotiations \
  -H "Authorization: Bearer ovl_live_..." \
  -H "Content-Type: application/json" \
  -d '{"title":"Equipment purchase #4471","seller_label":"Acme Supply","buyer_label":"Riverside Clinic","external_id":"deal_4471"}'
{
  "id": "neg_8mQ2tP4vXy7kR3cB",
  "external_id": "deal_4471",
  "title": "Equipment purchase #4471",
  "status": "open",
  "round": 1,
  "max_rounds": 3,
  "submitted": { "seller": false, "buyer": false },
  "resolved_price_cents": null,
  "parties": {
    "seller": { "token": "...", "url": "https://xelcome.com/n/..." },
    "buyer":  { "token": "...", "url": "https://xelcome.com/n/..." }
  }
}
GET/api/v1/negotiations/{id}

Returns the current state. It tells you whether each side has submitted in the current round, never what it submitted. status is one of open, resolved, no_agreement, cancelled or expired.

GET/api/v1/negotiations

Lists negotiations created through the API, newest first. Query parameters: status, external_id, limit (1 to 100), starting_after (an id, for paging). The response has data and has_more.

POST/api/v1/negotiations/{id}/cancel

Cancels an open negotiation for both sides and erases any sealed figures.

Party endpoints

For software or an AI agent acting for one side. Authenticate with that side’s party token.

GET/api/v1/party

Returns this side’s view: status, round, whether each side has submitted, your own figures, and the resolved price once there is one.

POST/api/v1/party/submissions

Seals this side’s figure for the current round. Send amount_cents (integer) or amount (decimal). The response includes outcome: waiting, resolved, next_round or no_agreement.

curl -X POST https://xelcome.com/api/v1/party/submissions \
  -H "Authorization: Bearer <party token>" \
  -H "Content-Type: application/json" \
  -d '{"amount_cents": 1250000}'

Webhooks

Set an https endpoint in API and webhooks. Overlap posts JSON events: negotiation.figure_submitted, negotiation.round_closed, negotiation.resolved, negotiation.no_agreement, negotiation.cancelled and negotiation.expired. Payloads hold the negotiation state, never figures. Failed deliveries are retried with backoff for about 15 hours.

Verify each request with the Overlap-Signature header, formatted t=<unix time>,v1=<signature>, where the signature is the hex HMAC-SHA256 of "<t>.<raw body>" using your webhook secret. Reject requests older than five minutes.

$expected = hash_hmac('sha256', $t . '.' . $rawBody, $secret);
if (! hash_equals($expected, $v1) || abs(time() - $t) > 300) {
    http_response_code(400);
    exit;
}

Errors

Errors return a 4xx status and a body like {"error": {"code": "movement_rule", "message": "..."}}. Common codes: unauthorized, plan_required, rate_limited, not_found, invalid_amount, already_submitted, movement_rule, closed, duplicate_external_id.