Skip to main content

​
Overview

Accurately recording when a credit score is pulled and used for a credit decision is essential — and anchored in the Fair Credit Reporting Act (FCRA). The FCRA mandates the fair and accurate use of credit information. Because scores fluctuate over time, capturing the exact moment of retrieval guarantees decisions are based on current, relevant data and provides a transparent audit trail that protects both the institution and the applicant. A credit score record captures a score returned by a vendor, the moment it was requested, and the decision it informed. It is always associated with a customer, and its id is linked to the credit application it supported. Key characteristics:
  • Customer-scoped — every credit score is tied to a customer_id.
  • Point-in-time — score_requested_time records exactly when the score was retrieved.
  • Sourced — type, vendor_name, and version identify where the score came from (e.g. FICO 8 from Equifax).
  • Application-linked — attach one or more score ids to an application via its credit_score_ids field.
Provide all credit scores used for each credit decision across the account lifecycle: account opening, denied line-increase request, penalty-based APR increase, account closure, and more. If more than one score is used for an application, add all relevant score IDs to the application’s credit_score_ids field.

​
Prerequisites

This guide assumes you are familiar with:

​
The credit score object

See the API reference for the full schema.

​
Recording a credit score

1

Record the credit score

When a FICO score is used for a decision on a Line of Credit application, record it with POST /v2/credit_scores:
The response includes the system-generated id:
2

Link the score to the application

Associate the score with the applicant on the Line of Credit application using PATCH /v2/applications/{APPLICATION_ID}. Add all relevant score IDs to credit_score_ids:

​
Best practices

Record every credit score used in a decision, and set score_requested_time to when the score was actually pulled — scores change over time, and the timestamp anchors your FCRA audit trail.
  • Record all scores used — if multiple scores inform one decision, capture each and add every id to the application’s credit_score_ids.
  • Set an accurate source — use source_of_score to reflect the lifecycle event (opening, line increase, APR change, closure).
  • Identify the score fully — populate type, vendor_name, and version so reviewers know exactly which model produced the score.
  • Pair with adverse actions — when a score leads to a denial or less favorable terms, also record an adverse action.

Adverse Actions

Record the reasons behind an adverse credit decision.

Credit Applications

Link credit scores to the applications they inform.

Line of Credit Accounts

The credit accounts these decisions open.

​
API reference