Partner Push API

Authenticating a request

Two layers. The token says who you are; the signature says this exact request came from you and has not been replayed.

1. Bearer token — required

Authorization: Bearer {your API secret}

Anything else is 401 invalid_token.

2. Request signature

An HMAC-SHA256, keyed with the signing secret issued alongside your token, sent in one header. There are two versions. Use v2. v1 is still accepted so existing integrations keep working, but it will be switched off.

New v2 — method, path and a single-use nonce

X-PropPay-Signature: t=1755624000,nonce=<nonce>,v2=<hex digest>

signed payload = "v2." + t + "." + METHOD + "." + path + "." + nonce + "." + rawRequestBody
key            = your signing secret (shared out of band)

Each nonce is accepted once per key. Sending the same signed request twice answers 401 invalid_signature the second time, so a retry must be re-signed with a new nonce (and, normally, a new t).

// Node
const t = Math.floor(Date.now() / 1000);
const nonce = crypto.randomBytes(16).toString("base64url");
const path = "/api/v1/partner/sales/48210/cancel";
const body = JSON.stringify({ reason: "Buyer withdrew" });
const v2 = crypto.createHmac("sha256", signingSecret)
  .update(`v2.${t}.POST.${path}.${nonce}.`)
  .update(body)
  .digest("hex");
// X-PropPay-Signature: t=<t>,nonce=<nonce>,v2=<v2>

A header that carries v2 is judged on v2 alone; a v1 value beside it is ignored, so you can send both while you migrate without weakening anything.

v1 — timestamp and body only (deprecated)

X-PropPay-Signature: t=1755624000,v1=<hex digest>

signed payload = "<t>." + rawRequestBody

v1 covers neither the method, the path nor a nonce, so a captured request can be replayed for up to five minutes and its signature is valid on any route with the same body. It is still accepted, and each use is counted per key. Once no key has used it for a full cycle it will be refused with 401 invalid_signature, “v1 signatures are no longer accepted”.

Signatures are required by default on every key, because the token and the signing secret are issued together. A key can be issued with signing switched off for a partner who has not built it yet; once you have, ask for a second key with it on and have the first revoked. There is deliberately no header, flag or payload field that skips verification on a key that requires it.

Only failed authentication counts against the rate limiter. Your legitimate 404s, 409s and 422s are never throttled at any volume.

Which projects accept a push

Only projects an operator has explicitly switched to API mode in PropPay LX. Everything else is refused.

Each PropPay project takes its data from exactly one direction, never both. Either PropPay pulls on a schedule and the upstream platform is the source of truth, or your system pushes over this API and PropPay owns the record from then on. Turning the API on for a project is what takes it off the pull.

One safety net stays on. Every 30 minutes (7 a.m.–7 p.m. Toronto) PropPay still reads your sales list for an API project, and imports only what a push should have delivered and did not: a sale it has no record of, once its transactionDate is an hour old, and a transaction we cancelled that you have since sold again (see POST /sales). A sale you pushed is never rewritten by it. A missed push is caught within the hour, but the push is still how a sale should arrive: it is immediate, and its response tells you what was stored.

Pushing to a project that has not been switched over returns 403 api_not_enabled. That is an operator action in PropPay LX, not something the API can change.

Routing to the right builder

externalProjectId names a source in your system, and a source can feed several builders — one community in our data feeds three — so a sale on one must also carry companyId.

One key per builder

Each PropPay project has its own key, and a key opens its own project and nothing else. On a multi-builder source that means one key per builder, not one per externalProjectId: every call must use the key of the project that owns the sale’s companyId. A single key used for the whole community answers 403 project_scope for every builder but its own — on /sales and on the by-sale routes (/pad, /documents, /cancel, /deposits) alike.

Choose the key from the companyId you are about to send, and keep using it for every later call on that sale.

Send the builder’s id from your companies roster — for Centurion that is 4605. Your SalesList stamps Centurion’s sales 3113, so we accept either for Centurion.

Identifiers

Every id in this API is yours, not ours. PropPay's own UUIDs are never accepted as input; they appear only in responses.

Send either spelling — the neutral one wins if both are present. Numeric ids are fine; they are read as strings.

Order of operations

Steps two and three are independent and can arrive in either order, minutes or days after the sale.

1. POST /sales Sale created, unit marked sold, deposit schedule seeded. Nothing is emailed.
2. POST /sales/:id/documents The APS is filed against the sale, visible to staff and to the buyer.
3. POST /sales/:id/pad The PAD agreement is generated unsigned, every account holder is emailed a link to sign it, and the purchaser gets their confirmation and schedule.

Creates the sale, its purchasers and its deposit schedule, and marks the unit sold. Emails nobody.

Request

{
  "externalTransactionId": "314363",
  "externalProjectId":     "A0035",
  "externalUnitId":        "23885",
  "transactionDate":       "2026-08-31",
  "basePrice":             749900,          // dollars
  "totalPrice":            764900,
  "closingDate":           "2027-06-15",
  "purchasers": [
    {
      "id":        "88214",
      "firstName": "Jane",
      "lastName":  "Doe",
      "email":     "jane.doe@example.com",
      "phone":     "905-555-0134"
    }
  ],
  "deposits": [
    { "index": 1, "title": "On signing",   "amount": 25000, "dueDate": "2026-09-07" },
    { "index": 2, "title": "30 days",      "amount": 25000, "dueDate": "2026-10-01" },
    { "index": 3, "title": "90 days",      "amount": 25000, "dueDate": "2026-11-30" },
    { "index": 4, "title": "On occupancy", "percentage": 5, "dueDate": "2027-06-15" }
  ]
}

Anything not in that table is ignored. firmDate, irrevocableDate, occupancyDate, discount, isInvestor, isFirstTimeBuyer, isForeignBuyer and purchasePurpose are real columns on our sale, but this endpoint does not read them — they are only ever filled by the scheduled pull, which on an API-mode project only imports sales you never pushed. Sending them is harmless and does nothing.

purchasers[]

Every field is optional and nothing in this array can fail the request — a purchaser is stored as far as it parses, so a misspelled key is dropped in silence rather than reported. The first element is the purchaser of record: they receive the confirmation when an agreement is generated, and they are the fallback for whatever accountHolder block you omit at /pad.

deposits[]

Every row lands as a PAD deposit and stays at awaiting_pad until an agreement is signed. Send the schedule in full — the buyer's confirmation prints exactly these rows.

Response

201 Created

{
  "id":           "4254815b…",
  "pad_required": true,
  "deposits":     4,                 // schedule rows actually stored
  "superseded":   ["A00035-19"]     // only when a live sale on the lot was cancelled
}

200 OK — this transaction id is already on file

{ "id", "pad_required", "idempotent": true }

Assert deposits against what you sent. A 0 there is the shape that produced a sale with no schedule and a PAD authorizing nothing.

Errors

Retries

Re-posting a known externalTransactionId returns 200 with idempotent: true.

Lots we have not mirrored yet

If the lot has never reached us, PropPay pulls the source on the fly rather than rejecting the sale. If a pull is already running, the answer is 409 unit_not_synced — retry shortly.

When the lot is already held

Another live sale on the same lot is cancelled first and named in the response as superseded. On a multi-builder source “the lot” is your externalUnitId across every builder’s project, so a lot one builder sold and another has now sold again cancels the first builder’s sale, and that builder’s staff are told. That includes a sale with collected deposits or a signed PAD: its PAD is deactivated and its uncollected debits stop, money already collected or in process is left where it is, and the builder’s staff are told so someone settles it.

Before 4 October 2026 that case answered 409 supersede_blocked. That response is no longer sent.

Turns banking collected in your app into a PAD agreement, unsigned, and emails each account holder a link to sign it here — and the purchaser their confirmation. Every buyer-facing email on this API leaves from this call.

Request

{
  "accountHolder": {
    "firstName": "Jane",
    "lastName":  "Doe",
    "address":   "123 Main Street",
    "city":      "Whitby",
    "province":  "ON",
    "phone":     "905-555-0134",
    "email":     "jane.doe@example.com"
  },
  "jointHolder": {
    "firstName": "John",
    "lastName":  "Doe",
    "email":     "john.doe@example.com"
  },
  "padCategory": "personal",
  "bank": {
    "bankName":    "RBC - Royal Bank of Canada",
    "institution": "003",
    "transit":     "12345",
    "account":     "1234567"
  },
  "voidCheque": "data:image/jpeg;base64,/9j/4AAQSk…"
}

The account holder is not always the purchaser

Whoever is named here is who the agreement asks a signature from and where the link goes. Send the holder block whenever the person funding the deposits differs from the purchaser of record; omit it and we use the purchaser. Fields merge individually — anything you send wins, anything you omit falls back.

When the holder is not a purchaser on the sale, PropPay notifies the sales team with both names in front of them. Nothing is blocked; the third-party-funder case is ordinary and expected.

A joint holder needs their own email

Both holders must sign before anything can be debited, and that address is the only place the second link can go. A joint PAD with nowhere to send the second invitation can never activate, so it is refused at the door rather than issued stuck.

Response

201 Created

{
  "saleId":     "1f0c…",
  "padId":      "9ab3…",
  "termFileNo": "LX0017-D-1",
  "status":     "awaiting_signature",
  "signers": [
    { "role": "account_holder", "email": "j•••e@example.com", "signed": false },
    { "role": "joint_holder",   "email": "j•••n@example.com", "signed": false }
  ],
  "invited": ["account_holder", "joint_holder"]
}

Addresses come back masked. The bank account is never echoed.

Errors

Retries and corrections

• Identical re-push — 200 idempotent: true, with the agreement already on file. Nothing is re-rendered and nobody is re-emailed. Comparison is on the values, not a payload hash, so reformatting (01234 against 1234) still matches. This holds only while that agreement is still live: if a schedule change has since retired it, the same push generates a fresh agreement and sends fresh invitations rather than handing back a retired one you could never escape.
• Changed details, nothing signed yet — the draft is replaced and fresh invitations go out.
• Changed details, something already signed — 409 pad_already_signed, nothing changes.

Files a PDF against the sale — the APS, an amendment or a schedule.

It appears in the console's Documents modal under Schedules & Supporting Documents and, because the buyer portal reads the same list, in front of the purchaser alongside the PAD they are asked to sign.

Request

{
  "kind": "aps",
  "document": "data:application/pdf;base64,JVBERi0xLjQK…"
}

The same bytes pushed twice are one document — content-addressed by SHA-256, so an APS re-sent on every sync does not stack copies in front of the buyer.

Response

201 Created

{ "saleId", "docId", "kind", "label", "bytes" }

200 OK — those exact bytes are already on file

{ …, "idempotent": true }

Errors: 403 api_not_enabled, 404 sale_not_found, 400 invalid_payload (not a PDF, too large, or an unknown kind), 500 document_upload_failed.

Tells PropPay LX the sale was cancelled on your side. It does not cancel the sale here.

A cancellation in your system never cancels a sale in PropPay LX by itself. The sale is flagged, every debit and payout on it is paused from that moment, everyone on the project is told, and one of the builder’s team decides in the console whether it stands — keep it (its debits resume) or cancel it. The first answer is final.

A repeat call for a sale already flagged answers idempotent: true, with status: "kept" once the builder has chosen to keep it. Nothing is written back to you either way: the integration is one-way, from your system to PropPay LX. Before 4 October 2026 this endpoint cancelled the sale outright and answered 200 { id, cancelled }.

The flag is cleared only by that person’s answer. PropPay’s scheduled read of your sales list never lifts it, even if the list goes on showing the sale as live for a while. A sale kept against your cancellation stays kept: cancelling it again is a new question only after you have re-written the deal with a later transactionDate. A deal re-sold under the same id is a new sale (see POST /sales).

202 { id, status: "held_for_review" } 404 sale_not_found 422 sale_already_cancelled

Replaces the whole deposit schedule, which invalidates any agreement on the sale — signed or still an unsigned draft.

A new agreement must then be signed before anything can be collected. A draft is retired too, not just a signed one: signing a draft binds whatever deposits are live at that moment, which after a replacement are not the rows it printed.

200 { id, deposits, pad_required: true } 422 paid_deposit_conflict if any deposit is paid or in process.

What the buyer receives

Templates are per-project and editable by the builder under Project Settings → Emails. Both already existed — this API is not introducing new buyer-facing copy.

A sale pushed on its own emails nobody. That is deliberate, and it is what makes POST /sales usable by itself: push the sale and the builder can see it and track its payments in PropPay, while the purchaser hears nothing until there is an agreement for them to sign. Both buyer-facing emails leave from /pad, where an agreement provably exists. The confirmation is deduped per sale, so re-issuing an agreement invites the holders again without re-announcing the purchase.

Limits