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

# D1C reports guide

> Learn how to monitor and generate D1C reports.

<Note>
  An [updated version](/integrations/d1c-aim/verifications) of this guide is now available.
</Note>

Argyle is working together with Fannie Mae to become a designated vendor for supporting Day-1 Certainty (D1C) applications for mortgage underwriting.

With data from its consumer-permissioned platform, Argyle can populate and format D1C reports to work seamlessly with Fannie Mae's automated DU Validation Services (DUVS) system.

## Overview

Argyle is able to generate D1C reports when the required data is available from a user's connected payroll accounts. This guide shows you how to monitor whether a D1C report can be generated for a user and, if so, how to generate a D1C report.

Our [webhooks](/api-guide/webhooks) can be used together to determine if a D1C report is ready to be generated through Argyle:

* Subscribe to the `users.fully_synced` webhook to be notified when data retrieval has completed for all accounts connected by a user. Use this webhook to determine if there are any payroll platforms or employer accounts missing that may contain data required to generate a D1C report.
* Subscribe to the `reports.d1c_data_ready` webhook to be notified when a D1C report can be generated from the available data for a user.
* Subscribe to the `reports.d1c_data_incomplete` webhook to be notified if a D1C report cannot be generated from the available data for a user.

Once you receive the `reports.d1c_data_ready` webhook, you can generate a D1C report by making a POST request to the `/v1/du-validation/generate` endpoint. See this section below for further details on retrieving a D1C report via this endpoint.

## Subscribe to webhooks

<div className="argyle-divider" />

### `users.fully_synced`

The `users.fully_synced` webhook is publicly documented and can be viewed [here](/api-reference/users-webhooks/fully-synced).

Use this webhook to determine if there are any payroll platforms or employer accounts missing that may contain data required to generate a D1C report.

To subscribe, send a POST request in this form:

```curl theme={}
curl -X POST https://api.argyle.com/v1/webhooks \
  -u api_key_id:api_key_secret \
  -H "Content-Type: application/json" \
  -d '{"events": ["users.fully_synced"],
       "secret": "<secret for signature verification>",
         "name": "<name for your webhook>",
          "url": "https://webhook.site/url"}'
```

The payload of this webhook will contain the ID of the user and a list of payroll platforms and employers they have connected.

#### Example users.fully\_synced response payload:

```json theme={}
{
    "name": "<name for your webhook>",
    "event": "users.fully_synced",
    "data": {
        "user": "01838ad1-b6bd-22f8-22f1-d3f5b3953484",
        "resource": {
            "id": "01838ad1-b6bd-22f8-22f1-d3f5b3953484",
            "data_providers_connected": [
                "mypayroll_platform"
            ],
            "employers_connected": [
                "Whole Goods",
                "SprintCar"
            ],
            "external_metadata": {
                "key": "value"
            },
            "created_at": "2022-09-29T19:55:43.166Z"
        }
    }
}
```

### `reports.d1c_data_ready`

Subscribe to the `reports.d1c_data_ready` webhook to be notified when a D1C report can be generated from the available data for a user.

To subscribe, send a POST request in this form:

```curl theme={}
curl -X POST https://api.argyle.com/v1/webhooks \
  -u api_key_id:api_key_secret \
  -H "Content-Type: application/json" \
  -d '{"events": ["reports.d1c_data_ready"],
       "secret": "<secret for signature verification>",
         "name": "<name for your webhook>",
          "url": "https://webhook.site/url"}'
```

#### Example reports.d1c\_data\_ready response payload:

```json theme={}
{
    "name": "<name for your webhook>",
    "event": "reports.d1c_data_ready",
    "data": {
        "user": {
            "id": "01838ad1-b6bd-22f8-22f1-d3f5b3953484",
            "data_providers_connected": [
                "mypayroll_platform"
            ],
            "employers_connected": [
                "Whole Goods",
                "SprintCar"
            ],
            "external_metadata": {},
            "created_at": "2022-09-29T20:24:43.166Z"
        }
    }
}
```

### `reports.d1c_data_incomplete`

Subscribe to the `reports.d1c_data_incomplete` webhook to be notified if a D1C report cannot be generated from the available data for a user.

To subscribe, send a POST request in this form:

```curl theme={}
curl -X POST https://api.argyle.com/v1/webhooks \
  -u api_key_id:api_key_secret \
  -H "Content-Type: application/json" \
  -d '{"events": ["reports.d1c_data_incomplete"],
       "secret": "<secret for signature verification>",
         "name": "<name for your webhook>",
          "url": "https://webhook.site/url"}'
```

#### Example reports.d1c\_data\_incomplete response payload:

```json theme={}
{
    "name": "<name for your webhook>",
    "event": "reports.d1c_data_incomplete",
    "data": {
        "user": {
            "id": "01838ad1-b6bd-22f8-22f1-d3f5b3953484",
            "data_providers_connected": [
                "mypayroll_platform"
            ],
            "employers_connected": [
                "Whole Goods",
                "SprintCar"
            ],
            "external_metadata": {},
            "created_at": "2022-09-29T20:11:43.166Z"
        }
    }
}
```

## Endpoint — /v1/du-validation/generate

Once you receive the `reports.d1c_data_ready` webhook, you can generate a D1C report by making a POST request to the `/v1/du-validation/generate` endpoint.

For authentication, use your production `api_key_id` and `api_key_secret` found [in Console](https://console.argyle.com/api-keys).

### D1C report — Request

To retrieve a D1C report, send a POST request in this form:

```curl theme={}
curl -X POST https://api.argyle.com/v1/du-validation/generate \
  -u api_key_id:api_key_secret \
  -H "Content-Type: application/xml" \
  -d '<GenerateReportRequest>
            <UserId>"integer user Id"</UserId>
            <Identity>"ssn in XXX-XX-XXXX format"</Identity>
            <TrackingKey>"tracking key goes here"</TrackingKey>
            </GenerateReportRequest>'
```

Note that XML is used in requests to the `/v1/du-validation/generate` endpoint.

**Required** body parameters:

`<UserId>` - the unique ID of the user

`<Identity>` - the user's social security number, which can be partially masked xxx-xx-1234 or unmasked 123-45-6789.

`<TrackingKey>` - a pass through field containing random uuid metadata that can be used for your internal tracking needs.

#### Example of body parameters in XML with values filled in:

```xml theme={}
<GenerateReportRequest>
    <UserId>012491d2-54ce-22cd-32fe-a806141235c0</UserId>
    <Identity>XXX-XX-1191</Identity>
    <TrackingKey>8d652475-cb19-429b-b2b0-9648f71f2690</TrackingKey>
</GenerateReportRequest>
```

### D1C report — Response

After requesting a D1C report using the /v1/du-validation/generate endpoint, an XML response will be returned in the format prescribed by Fannie Mae, outlined formally in the below documents.

* [ReissueResponse-v1.15.4.xsd](https://res.cloudinary.com/argyle-media/raw/upload/v1666111507/docs-2022/Unlisted%20Pages/D1C%20reports%20guide/ReissueResponse-v1.15.4.xsd)
* [ReissueResponse-v1.15.4.xlsx](https://res.cloudinary.com/argyle-media/raw/upload/v1665783782/docs-2022/Unlisted%20Pages/D1C%20reports%20guide/VOE_Response_1.15.4.xlsx)

The response contains:

`<GenerateReportResponse>` - the outermost wrapper, which includes:

* `<IsValid>` - boolean value indicating whether `<ReissueResponse>` contains the necessary data to conform to the D1C report requirements prescribed by Fannie Mae.
* `<Status>` - value indicating whether `<ReissueResponse>` can be generated. Possible values are valid, processing, or incomplete.
* `<Error>` - included when `<IsValid>` is false. Contains error details.
* `<ReissueResponse>` - the D1C report itself. It will contain the following items in the opening tag:
* **Identity** - social security number of the user
* **ReportID** - report code that can be used in future communication with Fannie Mae
* **Product** - report type (VOE indicates Verification of Employment)
* **TrackingKey** - contains the uuid that you included in the body parameters of the request
* **ServiceProviderCode** - designated partner providing the D1C report
* **OriginalTransactionDate** - date the report was generated
* **Status** - error field. “0” indicates success. See the error codes section below for more information.

#### Example /v1/du-validation/generate response payload:

```xml theme={}
<GenerateReportResponse>
    <IsValid>true</IsValid>
    <Status>valid</Status>
    <ReissueResponse Identity="xxx-xx-9007" ReportID="0183a4e7-5925-c6de-6af3-bf3514ce14c0" Product="VOE" TrackingKey="120d0c26-b23e-481e-976b-6444f3153d02" ServiceProviderCode="Argyle" OriginalTransactionDate="2022-10-04" Status="0" Message="Success">
        <VerificationResponse>
            <VOE_VOI>
                <VOEHEADER>
                    <TransactionId>01837123-09e7-fa5f-c4c3-310f965be93f</TransactionId>
                    <TransactionDate>2022-10-04T21:29:30</TransactionDate>
                </VOEHEADER>
                <VOEBODY>
                    <VOE>
                        <EMPLOYER>
                            <NAME>Happy Company</NAME>
                            <ADDRESS>
                                <ADDR1>Some street</ADDR1>
                                <ADDR2/>
                                <CITY>New York</CITY>
                                <STATE>NY</STATE>
                                <POSTALCODE>1234</POSTALCODE>
                                <ISOCOUNTRYCODE>US</ISOCOUNTRYCODE>
                            </ADDRESS>
                        </EMPLOYER>
                        <EMPLOYEE>
                            <SSN>xxxxx9007</SSN>
                            <FULLNAME>
                                <FIRST_NAME>Bob</FIRST_NAME>
                                <MIDDLE_NAME/>
                                <LAST_NAME>Jones</LAST_NAME>
                            </FULLNAME>
                            <POSITION_TITLE>PT Preload Supervisor</POSITION_TITLE>
                            <EMPLOYEESTATUS>
                                <CODE>1</CODE>
                                <MESSAGE>Active</MESSAGE>
                            </EMPLOYEESTATUS>
                            <DTINFO>2022-09-24T00:00:00</DTINFO>
                            <DTMOSTRECENTHIRE>2006-01-11</DTMOSTRECENTHIRE>
                            <DTORIGINALHIRE>2006-01-11</DTORIGINALHIRE>
                        </EMPLOYEE>
                        <COMPLETENESS>INCOME</COMPLETENESS>
                        <BASECOMP>
                            <PAYFREQUENCY>
                                <CODE>9</CODE>
                                <MESSAGE>Hourly</MESSAGE>
                            </PAYFREQUENCY>
                            <RATEOFPAY>26.16</RATEOFPAY>
                            <ISOCurrencyCode>USD</ISOCurrencyCode>
                        </BASECOMP>
                        <ANNUALCOMPS>
                            <ANNUALCOMP>
                                <YEAR>2022</YEAR>
                                <BASE>29211.69</BASE>
                                <OVERTIME>118.82</OVERTIME>
                                <COMMISSION>0.0</COMMISSION>
                                <BONUS>0.0</BONUS>
                                <OTHER>1644.39</OTHER>
                                <TOTAL>30974.9</TOTAL>
                            </ANNUALCOMP>
                            <ANNUALCOMP>
                                <YEAR>2021</YEAR>
                                <BASE>42807.3</BASE>
                                <OVERTIME>2463.18</OVERTIME>
                                <COMMISSION>0.0</COMMISSION>
                                <BONUS>0.0</BONUS>
                                <OTHER>3565.17</OTHER>
                                <TOTAL>48835.65</TOTAL>
                            </ANNUALCOMP>
                            <ANNUALCOMP>
                                <YEAR>2020</YEAR>
                                <BASE>39877.9</BASE>
                                <OVERTIME>1344.91</OVERTIME>
                                <COMMISSION>0.0</COMMISSION>
                                <BONUS>0.0</BONUS>
                                <OTHER>1541.76</OTHER>
                                <TOTAL>42764.57</TOTAL>
                            </ANNUALCOMP>
                        </ANNUALCOMPS>
                        <VERIFICATIONTYPE>INSTANT</VERIFICATIONTYPE>
                    </VOE>
                </VOEBODY>
            </VOE_VOI>
        </VerificationResponse>
    </ReissueResponse>
</GenerateReportResponse>
```

## Endpoint — Error codes

Error codes can be found in the “Status” field in the `<ReissueResponse>` layer that is returned by the `/v1/du-validation/generate` endpoint. A “Status” value of “0” indicates a successful response has been generated.

### Validation errors

* **Status = “17357” (Argyle data validation)**

A D1C report cannot be generated with currently available data in Argyle for the user.

```xml theme={}
<GenerateReportResponse>
  <IsValid>false</IsValid>
  <Status>incomplete</Status>
  <Error>
    <message>User 0183e3fb-1eea-a7e2-350f-4f680c4782ca report is missing information for all 1 accounts</message>
    <details>
      <detail>Account 0183e3fb-98eb-6599-e64c-dbcec5ed296a: employment.base_pay is missing</detail>
      <detail>Account 0183e3fb-98eb-6599-e64c-dbcec5ed296a: employment.base_pay.amount is missing</detail>
      <detail>Account 0183e3fb-98eb-6599-e64c-dbcec5ed296a: employment.base_pay.period is missing</detail>
    </details>
  </Error>
  <ReissueResponse
     Identity="123-45-6789"
     ReportID="0183e7d1-0d61-2c56-8c64-839decf29c82"
     Product="VOE" TrackingKey="2248a6f1-cf15-437a-87af-a7c0bcb302e3"
     ServiceProviderCode="Argyle"
     OriginalTransactionDate="2022-10-17"
     Status="17357"
     Message="Unable to match reference data">
    ...
  </ReissueResponse>
</GenerateReportResponse>
```

* **Status = "202" (report generation)**

The D1C report is still processing and cannot currently be generated.

```xml theme={}
<GenerateReportResponse>
  <IsValid>false</IsValid>
  <Status>processing</Status>
</GenerateReportResponse>
```

* **Status = “400” (request payload validation)**

The request to `/v1/du-validation/generate` does not match the expected format.

```xml theme={}
<Error>
    <message>Invalid request</message>
</Error>
```

* **Status = “422” (identity validation)**

The SSN in the request to `/v1/du-validation/generate` does not match the SSN for the user in Argyle. Use the [`/profiles`](/legacy/api-reference/profiles) endpoint to check the SSN for a user in Argyle.

```xml theme={}
<Error>
    <message>Request SSN doesn't match user SSN.</message>
</Error>
```

### System errors

* **Status = “401” (auth failed)**

Authorization failed when calling the `/v1/du-validation/generate` endpoint.

```xml theme={}
<Error>
    <message>Failed authenticating password</message>
</Error>
```

* **Status = “500” (storage service failed)**

The generated D1C report could not be saved by the storage service.

```xml theme={}
<Error>
    <message>Failed to save report</message>
</Error>
```

## PDF reports

When you generate a Verification of Income and Employment (VOIE) report using Console or the API, Argyle will automatically attempt to generate a D1C report from the user's available data.

### Generate via Console

Generate a VOIE report through Console from within an individual user's profile.

If a D1C report was successfully generated from the user's available data, a **DU reference ID** will be included in the upper-right of the VOIE report. This ID can be passed to Fannie Mae's DUVS system.

* [Sample VOIE report (D1C available)](https://res.cloudinary.com/argyle-media/image/upload/v1672682813/docs-2022/Unlisted%20Pages/D1C%20reports%20guide/VOIE_report_with_DU_id.png)
* [Sample VOIE report (D1C not available)](https://res.cloudinary.com/argyle-media/image/upload/v1672682817/docs-2022/Unlisted%20Pages/D1C%20reports%20guide/VOIE_report_DU_id_not_available.png)

### Generate via API

Generate a report using the [`/reports`](/legacy/api-reference/reports#generate) endpoint with a type value of `voie-d1c`.

* The response payload will include a `d1c_report` object within metadata.
* If a D1C report was successfully generated from the user's available data, the `id` field within the `d1c_report` object will contain a **DU reference ID** that can be passed to Fannie Mae's DUVS system.

#### Example voie-d1c report JSON payload:

```json theme={}
{
    "id":"9f82994c-774d-11eb-b1c7-13e87316bacb",
    "reference_id":"9f82994c-774d-11eb-b1c7-13e87316bacb",
    "generated_at":"2020-11-29T08:33:41.525Z",
    "type":"voie",
    "user":"8a5f613a-673a-4434-aeee-1a38b960b936",
    "status":"generated",
    "file_url":"www.company.com/voie_report.pdf",
    "metadata":{
        "d1c_report":{
            "id": "0183a4e7-5925-c6de-6af3-bf3514ce14c0",
            "error":null,
        }
    }
}
```

There are two possible errors:

* `data_incomplete` — There is not sufficient data available for the user in order to generate a D1C report.

* `processing` — D1C report generation is still in progress.

#### Example voie-d1c report JSON payload with error:

```json theme={}
{
    "id":"9f82994c-774d-11eb-b1c7-13e87316bacb",
    "reference_id":"9f82994c-774d-11eb-b1c7-13e87316bacb",
    "generated_at":"2020-11-29T08:33:41.525Z",
    "type":"voie",
    "user":"8a5f613a-673a-4434-aeee-1a38b960b936",
    "status":"generated",
    "file_url":"www.company.com/voie_report.pdf",
    "metadata":{
        "d1c_report":{
            "id": null,
            "error":"data_incomplete"
        }
    }
}
```