Education Scenarios

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 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 first.

Create a scenario [Server-side]

The SSN digits and dates of birth of Truv’s built-in education scenarios 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:

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.

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

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`.

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`.

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.
`terms`	array	Certified terms.

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

{
  "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.

{
  "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.

{
  "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 do.

{
  "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.

{
  "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.

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

Next steps

Education Testing

Truv’s built-in education scenarios and how an order selects one

Create an order

The request that carries the applicant’s SSN and date of birth

Data refresh

See an active enrollment advance toward graduation

Sandbox API reference

Full request and response schemas for every sandbox endpoint

Get Started

Start Building

Implementation

Bridge SDK

Testing & Launch

Dashboard & Configuration

Coverage

Education Scenarios

Create a scenario [Server-side]

Use it in an order

Matching fields

Behavior

How enrollments are served

Payload reference

Examples

Graduate with no current enrollment

Half-time student at a community college

Match on date of birth

Unconfirmed match

No record found

Limits

Next steps

Education Testing

Create an order

Data refresh

Sandbox API reference

​Create a scenario [Server-side]

​Use it in an order

​Matching fields

​Behavior

​How enrollments are served

​Payload reference

​Examples

​Graduate with no current enrollment

​Half-time student at a community college

​Match on date of birth

​Unconfirmed match

​No record found

​Limits

​Next steps

Education Testing

Create an order

Data refresh

Sandbox API reference

Create a scenario [Server-side]

Use it in an order

Matching fields

Behavior

How enrollments are served

Payload reference

Examples

Graduate with no current enrollment

Half-time student at a community college

Match on date of birth

Unconfirmed match

No record found

Limits

Next steps