/api/v1/applicants/{id}
Update an applicant's contact details.
- Scope
applicants:write- Rate limit
- 100 requests / min
- Idempotency
Idempotency-Keysupported
Authentication
Send your key as Authorization: Bearer …. It must carry the scope applicants:write; a key without it receives 403 forbidden.
Path parameters
idstringrequiredHeaders
Idempotency-KeystringReplays the first response for a repeated request. Reusing a key with a different body is idempotency_key_reused (409), never a silent replay.
Request body
application/jsonrequiredThe field names below are exact and any other key is refused; per-field types are not published yet.
nametype not publishedphonetype not publishedRefused parameters15
Sending any of these returns 400 validation_error naming the field. Each entry explains what to do instead.
email'email' is not accepted: the applicant id is DERIVED from the lowercased email (apl_ + a hash of your organization id and that address), so changing it would change the id in the URL of this very request. It would not rename the applicant either — cases that cannot be rewritten keep the old address, leaving one person split across two ids with partial history under each. To onboard a corrected address, submit an application under it with POST /v1/underwrite.
applicant_email'applicant_email' is not accepted; see 'email', which is not accepted either: the applicant id is derived from the email address.
status'status' is not accepted: it is DERIVED, not stored. An applicant is 'active' when any of their cases was updated in the last 90 days and 'inactive' otherwise, and there is no column to set. Updating a case's contact details is itself activity.
type'type' is not accepted: the applicant type (individual or business) is an UNDERWRITING INPUT — it selects the rules an application is analyzed under — not a contact detail. Changing it on an analyzed case would mean the decision was made under rules the record no longer claims.
applicant_type'applicant_type' is not accepted; the parameter is named 'type', and it is not accepted either: the applicant type is an underwriting input, not a contact detail.
credit_score'credit_score' is not accepted: it is read from the bureau report on the applicant's most recent case carrying one. Nothing may assert a score.
total_applications'total_applications' is not accepted: it is a count of the applicant's cases.
active_loans'active_loans' is not accepted: it is a count of the applicant's open loans.
total_borrowed'total_borrowed' is not accepted: it is a sum over the applicant's originated loans.
assigned_to'assigned_to' is not accepted: an underwriter is assigned to a CASE, not to an applicant. This endpoint does not address individual cases.
assignedTo'assignedTo' is not accepted: an underwriter is assigned to a CASE, not to an applicant.
id'id' is not accepted: the applicant is taken from the URL path, and the id is derived rather than assigned.
applicant_id'applicant_id' is not accepted: the applicant is taken from the URL path.
case_id'case_id' is not accepted: this endpoint updates the applicant, which is every one of their cases that can still be changed. To address one case, use the case endpoints.
idempotency_key'idempotency_key' is not accepted as a body field: send it as the 'Idempotency-Key' HTTP header.
Response
200application/jsonSerializedApplicantUpdateidstringrequiredapl_… — stable for a given applicant email within your organization.
namestringrequiredtypestringrequiredindividual | business
emailstringrequiredphonestring | nullrequirednullablecredit_scorenumber | nullrequirednullableBureau score on the most recent case carrying a credit report; null when none.
total_applicationsnumberrequiredactive_loansnumberrequiredtotal_borrowednumberrequiredWhole dollars: the original principal of every loan made to this applicant, summed.
statusstringrequiredactive | inactive
last_activitystring | nullrequirednullabledate_addedstring | nullrequirednullablecases_updatednumberrequiredCases whose contact details were rewritten. Always at least 1 — a request that would update none is a 409, never a 200 with a zero here.
cases_preservednumberrequiredCases left untouched because they carry a decision or evidence.
Errors
The statuses this operation can return, with the error.code values behind each. Every error body is the shared envelope described under Errors in Getting started.
400validation_error401unauthorized403forbidden404not_found409conflictidempotency_key_reused429rate_limit_exceeded500internal_error