> ## Documentation Index
> Fetch the complete documentation index at: https://docs.synctera.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Credit Scores

> Record the credit scores used for each credit decision and associate them with the customer and application, providing an FCRA-compliant audit trail.

## 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 `id`s to an application via its `credit_score_ids` field.

<Info>
  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.
</Info>

## Prerequisites

This guide assumes you are familiar with:

* [Need to Know — Environments](/v2/reference/need-to-know#environments)
* [Need to Know — Authentication](/v2/reference/need-to-know#authentication)
* Credit [applications](/v2/reference/patchapplication)

## The credit score object

| Field                                 | Description                                                            |
| ------------------------------------- | ---------------------------------------------------------------------- |
| `id`                                  | Unique identifier (read-only, assigned on creation).                   |
| `customer_id`                         | **Required.** The customer the score belongs to.                       |
| `score`                               | The numeric credit score.                                              |
| `type`                                | The score type (e.g. `FICO`).                                          |
| `vendor_name`                         | The bureau or vendor that provided the score (e.g. `EQUIFAX`).         |
| `version`                             | The score model version (e.g. `8`).                                    |
| `source_of_score`                     | The lifecycle event the score was pulled for (e.g. `ACCOUNT_OPENING`). |
| `score_requested_time`                | When the score was retrieved from the vendor.                          |
| `creation_time` / `last_updated_time` | Timestamps (read-only).                                                |

```json theme={"system"}
{
  "id": "c387f46a-0a9e-44bc-82fa-aed68982e6a5",
  "customer_id": "4a666a01-d23a-47b1-8c20-2eb5a923da35",
  "score": 725,
  "type": "FICO",
  "vendor_name": "EQUIFAX",
  "version": "8",
  "source_of_score": "ACCOUNT_OPENING",
  "score_requested_time": "2023-09-19T19:15:45.861687Z",
  "creation_time": "2023-09-19T15:48:24.10184Z",
  "last_updated_time": "2023-09-19T20:14:45.861687Z"
}
```

See the [API reference](/v2/reference/createcreditscores) for the full schema.

## Recording a credit score

<Steps>
  <Step title="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](/v2/reference/createcreditscores):

    ```shell theme={"system"}
    curl \
      -X POST \
      -H "Authorization: Bearer $apikey" \
      -H 'Content-Type: application/json' \
      https://api.synctera.com/v2/credit_scores \
      --data-binary '
      {
        "customer_id": "4a666a01-d23a-47b1-8c20-2eb5a923da35",
        "score": 725,
        "score_requested_time": "2023-09-19T19:15:45.861687Z",
        "source_of_score": "ACCOUNT_OPENING",
        "type": "FICO",
        "vendor_name": "EQUIFAX",
        "version": "8"
      }'
    ```

    The response includes the system-generated `id`:

    ```json theme={"system"}
    {
      "id": "c387f46a-0a9e-44bc-82fa-aed68982e6a5",
      "customer_id": "4a666a01-d23a-47b1-8c20-2eb5a923da35",
      "score": 725,
      "score_requested_time": "2023-09-19T19:15:45.861687Z",
      "source_of_score": "ACCOUNT_OPENING",
      "type": "FICO",
      "vendor_name": "EQUIFAX",
      "version": "8",
      "creation_time": "2023-09-19T15:48:24.10184Z",
      "last_updated_time": "2023-09-19T20:14:45.861687Z"
    }
    ```
  </Step>

  <Step title="Link the score to the application">
    Associate the score with the applicant on the Line of Credit application using [PATCH /v2/applications/\{APPLICATION\_ID}](/v2/reference/patchapplication). Add all relevant score IDs to `credit_score_ids`:

    ```shell theme={"system"}
    curl \
      -X PATCH \
      -H "Authorization: Bearer $apikey" \
      -H 'Content-Type: application/json' \
      https://api.synctera.com/v2/applications/{APPLICATION_ID} \
      --data-binary '
      {
        "applicants": [
          {
            "is_primary": true,
            "customer_id": "4a666a01-d23a-47b1-8c20-2eb5a923da35",
            "credit_score_ids": ["c387f46a-0a9e-44bc-82fa-aed68982e6a5"]
          }
        ]
      }'
    ```

    ```json theme={"system"}
    {
      "id": "ebda67f0-e0a7-41e2-98ed-0617a1e815a6",
      "account_type": "LINE_OF_CREDIT",
      "type": "CREDIT",
      "purpose": "ACCOUNT_OPENING",
      "status": "SUBMITTED",
      "applicants": [
        {
          "is_primary": true,
          "customer_id": "4a666a01-d23a-47b1-8c20-2eb5a923da35",
          "credit_score_ids": ["c387f46a-0a9e-44bc-82fa-aed68982e6a5"]
        }
      ],
      "creation_time": "2023-09-19T19:14:45.861687Z",
      "last_updated_time": "2023-09-20T00:31:10.255042Z"
    }
    ```
  </Step>
</Steps>

## Best practices

<Warning>
  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.
</Warning>

* **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](/v2/docs/adverse-actions-guide).

## Related guides

<CardGroup cols={2}>
  <Card title="Adverse Actions" href="/v2/docs/adverse-actions-guide" icon="ban" horizontal>
    Record the reasons behind an adverse credit decision.
  </Card>

  <Card title="Credit Applications" href="/v2/docs/credit-applications-guide" icon="file-lines" horizontal>
    Link credit scores to the applications they inform.
  </Card>

  <Card title="Line of Credit Accounts" href="/v2/docs/line-of-credit-accounts-guide" icon="building-columns" horizontal>
    The credit accounts these decisions open.
  </Card>
</CardGroup>

## API reference

* [Create a credit score](/v2/reference/createcreditscores)
* [List credit scores](/v2/reference/listcreditscores)
* [Get a credit score](/v2/reference/getcreditscore)
* [Update an application](/v2/reference/patchapplication)