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

Compute an HMAC-SHA256 over a Unix timestamp, a literal full stop, and the exact request body you are about to send. Send it alongside the token:

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

signed payload = "<t>." + rawRequestBody
key            = your signing secret (shared out of band)

Signature verification is off until a signing secret is configured on our side, so you can integrate on the bearer token first and add signing when ready. Once the secret is configured it is mandatory — there is no per-request way to skip 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.

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.

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. The buyer is emailed their purchase confirmation with the schedule.
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, and every account holder is emailed a link to sign it.

Creates the sale, its purchasers and its deposit schedule; marks the unit sold; emails the buyer their confirmation.

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",
      "sin":       "123456789"
    }
  ],
  "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 an API-mode project does not run. 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, 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,
  "superseded":   ["A00035-19"]     // only when a live sale was cancelled
}

200 OK — this transaction id is already on file

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

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 superseded and named in the response. But if that sale has collected deposits or a signed PAD, nothing happens and the answer is 409 supersede_blocked, carrying the evidence.

Two real sales on one lot is a question about named people's money, so it goes to an operator rather than being resolved by a webhook.

Turns banking collected in your app into a PAD agreement, unsigned, and emails each account holder a link to sign it here.

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.
• 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.

Cancels the sale and everything downstream of it that has not already been paid.

Pending and scheduled deposits are cancelled; paid ones are left alone. Any PAD is deactivated, and the unit is handed back — unless another live sale still holds it.

200 { id, cancelled } 404 sale_not_found 422 sale_already_cancelled

Replaces the whole deposit schedule, which invalidates the active PAD.

A new agreement must then be signed before anything can be collected.

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.

Nothing about the PAD is emailed at sale creation, because at that moment there is no agreement to sign.

Limits