Docs / API and agents
References API
Add, correct and remind trade references (applicant and credit team), answer by private link (public), and the reference portal reads.
Four controllers in apps/services/src/references. Public routes are credentialed by an unguessable, expiring link token, not a session.
Routes#
| Method and path | Who | What |
|---|---|---|
POST /reference/:token/respond, POST /reference/saved/:token/respond | public, link token | answer or decline |
GET /reference/:token/view, GET /reference/saved/:token/view | public, link token | what the reference page shows |
POST /applications/:id/references | the applicant who owns the application | add a reference (max 10) |
PATCH /applications/:id/references/:refId | owner | correct the email or phone; the old link stops working |
DELETE /applications/:id/references/:refId | owner | remove a reference that has no response, message or document |
POST /applications/:id/remind-all | owner (with references.remind), or supplier with references.remind | remind every pending reference |
POST /references/:id/remind | owner (with references.remind), or supplier with references.remind (only suppliers may ask for an update) | remind one reference |
PATCH /references/:id/settings | supplier with references.settings | automatic re-review interval: body { "autoRereviewDays": 1..3650 }, or null to turn it off |
GET /references/:id/history | supplier with references.view, or staff | response revisions |
POST/PATCH/DELETE /saved-references[/:id], POST /saved-references/:id/remind | session | the applicant's reusable reference contacts |
GET /reference-portal/summary, inbox, history, messages | session | the signed-in reference provider's portal |
Answering#
A response needs certified: true, recommendation (highly, recommend, neutral, do-not) and a non-empty signedByName; payment timeliness, NSF, balances, terms and notes are optional. A drawn signature image must decode as PNG or JPEG. { "declined": true, "declineReason": "..." } declines. The response claims the current link and request version in one transaction and writes an immutable revision.
| Status | When |
|---|---|
| 200 | { ok: true } |
| 400 | invalid response or signature |
| 404 | unknown link |
| 409 | already answered or the request changed since the page loaded |
| 410 | the link expired; ask the sender for a fresh one |
| 413 | body too large |
| 429 | 10 attempts per IP per hour |
Managing references#
Every reference request and update request email names the sender (company and postal address), and ends with a line telling the reference how to stop further requests (reply or write to support with "stop"; support handles it by hand today). Reminders rotate the private link. Limits: 50 reminders per user per hour, at least 24 hours between reminders to one reference (429), four hours between reminder batches. A declined reference cannot be reminded and a responded one only through an update request (409). Reference contacts with a response, message or document cannot be removed or edited (409). Non-owners get 403 or 404.
Lifecycle#
A reference is PENDING until it answers (RESPONDED) or declines (DECLINED). Each private link lives 90 days from the moment it was minted; an expired link answers 410 on view and on respond, and only a reminder mints a fresh one.
- Reminders and update requests rotate the link: the old link stops working and the response must match the current link and request version (otherwise 409). A reminder to a reference that is
RESPONDEDis refused (409) unless it is an update request, which starts a new cycle; both answers stay in the history. DECLINEDis terminal for reminders (409).- Automatic chase (the
rereview-referencesjob, daily 08:30 UTC, see Scheduled jobs): aPENDINGreference is re-sent a reminder every 3 days after the last send, at most 3 times, only when the supplier's published credit form has the reference auto-chase feature on and the application is not yetAPPROVEDorDECLINED. A recipient who muted reference email is skipped and the clock moves on; two simultaneous runs queue one reminder. - Automatic re-review: when a supplier sets
autoRereviewDayson aRESPONDEDreference, the same job sends an update request once that many days have passed since the last response or reminder. It does not depend on the auto-chase feature. Turning the interval off stops it. - The credit desk calls a pending reference late when it was neither sent nor reminded for 3 days.
- At most 10 references per application (the 11th is 409, including when additions race). A slot is freed only by removing an unanswered reference. No reference can be added after a final decision.
The status
NO_RESPONSEexists in the data model and the "closed" filter, but no code sets it today; an unanswered reference staysPENDINGand shows as expired once its link lapses.