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

# Education Scenarios

> Pair an applicant identity with the degrees and enrollments the National Student Clearinghouse should return for it

Set the student record a sandbox education verification returns. An `education` scenario pairs the last four digits of an applicant's SSN, or their date of birth, with the degrees and enrollments you want back, and serves them when you order education verification for that applicant.

Use it when the built-in [education scenarios](https://docs.truv.com/developers/testing/education.md) don't cover the case you need: a student who graduates on a date you choose, two enrollments at different schools, a half-time term, or a National Student Clearinghouse (NSC) outcome other than a confirmed hit. For the shared concepts, read [Custom Sandbox Data](https://docs.truv.com/developers/testing/custom-sandbox-data.md) first.

***

## Create a scenario \[Server-side]

> [!WARNING]
>
> The SSN digits and dates of birth of Truv's built-in [education scenarios](https://docs.truv.com/developers/testing/education.md) are reserved, and the API refuses either one with `reserved_credential`. Pick four digits and a date from outside those tables.

This request creates a scenario for a current full-time student who graduates four months after the first verification:

```bash theme={null}
curl --request POST \
     --url https://prod.truv.com/v1/sandbox/scenarios/ \
     --header 'X-Access-Client-Id: YOUR_TRUV_CLIENT_ID' \
     --header 'X-Access-Secret: YOUR_TRUV_SANDBOX_SECRET' \
     --header 'Content-Type: application/json' \
     --data '{
  "data_source": "education",
  "label": "Truv College — senior, graduating soon",
  "ssn_last4": "4321",
  "payload": {
    "result": { "transaction_status": "CNF", "nsc_hit": true, "status_code": 0, "status_message": "Successful" },
    "enrollments": [
      {
        "official_school_name": "Truv College",
        "school_code": "001234",
        "branch_code": "00",
        "school_type": "4",
        "current_enrollment_status": "CC",
        "ended_enrollment_status": "CN",
        "is_active": true,
        "terms": [
          { "enrollment_status": "F", "term_begin_date": "2026-05-22", "duration_days": 120 }
        ]
      }
    ]
  }
}'
```

The response is the stored scenario with every field filled in; the matching fields of other data sources stay empty.

> [!NOTE]
>
> Send `"data_source": "education"` explicitly. Truv can't infer the data source from `ssn_last4` alone and refuses the request with `data_source_required`. Only `date_of_birth` fits education alone, so a scenario that sets it can leave `data_source` out.

### Use it in an order

[Create an education order](https://docs.truv.com/developers/testing/education.md#quick-start) for an applicant whose SSN ends in `4321`, for example `666-09-4321`, through the API or the Dashboard. Open the `share_url`, pick a school, and the task completes with your record instead of Truv's built-in scenarios. Read the result from the [task webhooks](https://docs.truv.com/api-reference/webhooks/object.md) and the education report on the order.

The student's name and date of birth in the report always come from the applicant. The scenario supplies the Clearinghouse outcome, the schools, the degrees, and the enrollment history.

***

## Matching fields

| Field | Type | Description |
| - | - | - |
| `ssn_last4` | string | The last four digits of the SSN on the order. The first five digits are never compared. |
| `date_of_birth` | date | The date of birth on the order, `YYYY-MM-DD`. |
| `is_refresh` | boolean | `true` matches data refreshes only, `false` initial verifications only. `null` (the default) matches both. |

A scenario that sets both fields matches only an applicant with both. One that sets either field alone matches on it whatever the other value is. Your scenarios are checked before Truv's built-in ones, so an applicant who matches nothing of yours still gets the built-in record for their SSN, then the built-in record for their date of birth, or, failing both, no data.

`products` can only be `education`, so leave it empty.

### Behavior

Education verification is a single request to the Clearinghouse with no login step, so a scenario can only end the way that request ends. `behavior_status` accepts `done`, `no_data`, `unavailable`, `config_error`, `login_error`, and `error`; `behavior_mfa` is refused. `behavior_duration_seconds` holds the task the same way as on other data sources. See [Behavior](https://docs.truv.com/developers/testing/custom-sandbox-data.md#behavior) for the fields.

***

## How enrollments are served

Degrees and past enrollments are served with the dates you author. A current enrollment is different: set `is_active: true` and give its term a `duration_days`, and Truv keeps it current for you.

* The anticipated graduation date is `duration_days` after the first verification of that connection. Refreshes keep using that same first verification date.
* Until then, every run serves `currentEnrollmentStatus` as `current_enrollment_status` (`CC` by default) and slides the term's end date to today, so the student always reads as enrolled right now.
* Once the anticipated graduation passes, runs serve `ended_enrollment_status` (`CN` by default) and the term ends on the anticipated date, so a [data refresh](https://docs.truv.com/developers/integration/embedded-orders/data-refresh.md) sees the student graduate.
* An active enrollment whose terms carry no `duration_days` never ends.
* On an active term with `duration_days`, Truv replaces `term_end_date` and `anticipated_graduation_date` with the derived dates. Every other term serves the `term_end_date` and `anticipated_graduation_date` you author, active or not.
* `certified_on_date` is always served as authored. Without it, the term's `term_begin_date` is used.

***

## Payload reference

The `payload` object contains an optional `result` block and the `degrees` and `enrollments` arrays. Every field is optional: send only what your test needs, and leave the rest out.

> [accordion] result
>
> The Clearinghouse transaction-level outcome. Omit it for a confirmed hit.
>
> | Field | Type | Description |
> | - | - | - |
> | `transaction_status` | string | `CNF` confirmed, `UCF` unconfirmed. `UCF` ends the task with `no_data`. Default `CNF`. |
> | `nsc_hit` | boolean | Whether a record was found. `false` ends the task with `no_data`. Default `true`. |
> | `status_code` | integer | `0` is success; any other value ends the task with `unavailable`, with `status_message` as the error message. Default `0`. |
> | `status_message` | string | Default `Successful`. |

> [accordion] degrees\[]
>
> | Field | Type | Description |
> | - | - | - |
> | `degree_title` | string | e.g. `Bachelor of Science`. |
> | `degree_status` | string | `CD` is a confirmed degree. Default `CD`. |
> | `official_school_name` | string | |
> | `school_code` | string | Department of Education six-digit school id. |
> | `branch_code` | string | Two digits. |
> | `school_type` | string | `4` four-year, `2` two-year, `1` less than two-year. |
> | `graduated` | boolean | Default `true`. |
> | `award_date` | date | |
> | `award_date_range` | string | Clearinghouse bucketed months-since-award range. |
> | `academic_honors` | string | e.g. `Cum Laude`. |

> [accordion] enrollments\[]
>
> | Field | Type | Description |
> | - | - | - |
> | `official_school_name` | string | |
> | `school_code` | string | Six digits. |
> | `branch_code` | string | Two digits. |
> | `school_type` | string | `4` four-year, `2` two-year, `L` or `1` less than two-year. |
> | `current_enrollment_status` | string | Served while the enrollment is current. `CC` currently enrolled, `CN` not currently enrolled. Default `CC`. |
> | `ended_enrollment_status` | string | Served once an active enrollment passes its anticipated graduation. Default `CN`. |
> | `student_class_credential` | string | Two characters, carried on each term. |
> | `student_address` | object | `address1`, `address2`, `city`, `state`, `zip_code`, `province`, `postal_code`, `country`. |
> | `is_active` | boolean | Default `false`. See [How enrollments are served](#how-enrollments-are-served). |
> | `terms` | array | Certified terms. |

> [accordion] enrollments\[].terms\[]
>
> | Field | Type | Description |
> | - | - | - |
> | `enrollment_status` | string | `F` full-time, `Q` three-quarter time, `H` half-time, `L` less than half-time, `Y` status withheld by the school. |
> | `term_begin_date` | date | |
> | `term_end_date` | date | Replaced by the derived end on an active term with `duration_days`. |
> | `certified_on_date` | date | Always served. Defaults to `term_begin_date`. |
> | `anticipated_graduation_date` | date | Replaced by the derived date on an active term with `duration_days`. |
> | `duration_days` | integer | `0`–`3660`. Read only when `is_active` is `true`. |

***

## Examples

Each example is a request body for `POST /v1/sandbox/scenarios/` and creates a new scenario. Send it with the same `curl` command as [the first scenario](#create-a-scenario-server-side). Each one uses its own SSN digits, so they coexist.

### Graduate with no current enrollment

A former student. The Clearinghouse confirms the degree and reports a past enrollment with fixed dates.

```json theme={null}
{
  "data_source": "education",
  "label": "Truv College — graduated 2021",
  "ssn_last4": "4322",
  "payload": {
    "degrees": [
      {
        "degree_title": "Bachelor of Science",
        "degree_status": "CD",
        "official_school_name": "Truv College",
        "school_code": "001234",
        "school_type": "4",
        "graduated": true,
        "award_date": "2021-05-15",
        "academic_honors": "Cum Laude"
      }
    ],
    "enrollments": [
      {
        "official_school_name": "Truv College",
        "school_code": "001234",
        "school_type": "4",
        "current_enrollment_status": "CN",
        "is_active": false,
        "terms": [
          {
            "enrollment_status": "F",
            "term_begin_date": "2021-01-19",
            "term_end_date": "2021-05-14",
            "certified_on_date": "2021-02-01",
            "anticipated_graduation_date": "2021-05-15"
          }
        ]
      }
    ]
  }
}
```

### Half-time student at a community college

A current enrollment below full time. `enrollment_status: "H"` is what a certification reads as half-time.

```json theme={null}
{
  "data_source": "education",
  "label": "Truv Community College — half-time",
  "ssn_last4": "4323",
  "payload": {
    "enrollments": [
      {
        "official_school_name": "Truv Community College",
        "school_code": "005678",
        "school_type": "2",
        "is_active": true,
        "terms": [
          { "enrollment_status": "H", "term_begin_date": "2026-08-24", "duration_days": 300 }
        ]
      }
    ]
  }
}
```

### Match on date of birth

Set `date_of_birth` instead of, or as well as, `ssn_last4`. This scenario answers any applicant born on this date. A scenario that matches the same applicant on `ssn_last4` alone is equally specific, so the older of the two wins; set both fields on one scenario to make it win outright.

```json theme={null}
{
  "data_source": "education",
  "label": "Born 1990-01-02 — enrolled, no degree yet",
  "date_of_birth": "1990-01-02",
  "payload": {
    "enrollments": [
      {
        "official_school_name": "Truv College",
        "school_code": "001234",
        "school_type": "4",
        "is_active": true,
        "terms": [
          { "enrollment_status": "F", "term_begin_date": "2026-08-24", "duration_days": 600 }
        ]
      }
    ]
  }
}
```

### Unconfirmed match

The Clearinghouse found something but could not confirm it is this student. The task ends with `no_data`, as Truv's own [unconfirmed test records](https://docs.truv.com/developers/testing/education.md#empty-and-unconfirmed-records) do.

```json theme={null}
{
  "data_source": "education",
  "label": "Unconfirmed match",
  "ssn_last4": "4324",
  "payload": {
    "result": { "transaction_status": "UCF", "nsc_hit": true, "status_code": 0, "status_message": "Successful" }
  }
}
```

### No record found

A failure status needs no payload. `no_data` is how a student with no Clearinghouse record ends.

```json theme={null}
{
  "data_source": "education",
  "label": "No education record",
  "ssn_last4": "4325",
  "behavior_status": "no_data",
  "behavior_error_message": "No education records were found for the student."
}
```

***

## Limits

These are the default limits for education payloads. The account-wide limits are listed on [Custom Sandbox Data](https://docs.truv.com/developers/testing/custom-sandbox-data.md#limits).

| Limit | Default |
| - | - |
| Degrees per scenario | 10 |
| Enrollments per scenario | 10 |
| Terms per enrollment | 20 |

***

## Next steps

> [card] [Education Testing](https://docs.truv.com/developers/testing/education.md)
>
> Truv's built-in education scenarios and how an order selects one

> [card] [Create an order](https://docs.truv.com/api-reference/orders/orders_create.md)
>
> The request that carries the applicant's SSN and date of birth

> [card] [Data refresh](https://docs.truv.com/developers/integration/embedded-orders/data-refresh.md)
>
> See an active enrollment advance toward graduation

> [card] [Sandbox API reference](https://docs.truv.com/api-reference/sandbox/object.md)
>
> Full request and response schemas for every sandbox endpoint


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.