D1C reports guide

An updated version of this guide is now available.

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

`users.fully_synced`

The users.fully_synced webhook is publicly documented and can be viewed here. 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 -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:

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

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

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

D1C report — Request

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

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:

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

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:

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

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

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

<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 endpoint to check the SSN for a user in Argyle.

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

<Error>
    <message>Failed authenticating password</message>
</Error>

Status = “500” (storage service failed)

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

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

Generate via API

Generate a report using the /reports 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:

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

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

Overview

Workflows

POS & LOS Systems

Day 1 Certainty® and AIM

Document Processing

Console

Link

API

Overview

`users.fully_synced`

Example users.fully_synced response payload:

`reports.d1c_data_ready`

Example reports.d1c_data_ready response payload:

`reports.d1c_data_incomplete`

Example reports.d1c_data_incomplete response payload:

Endpoint — /v1/du-validation/generate

D1C report — Request

Example of body parameters in XML with values filled in:

D1C report — Response

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

Endpoint — Error codes

Validation errors

System errors

PDF reports

Generate via Console

Generate via API

Example voie-d1c report JSON payload:

Example voie-d1c report JSON payload with error:

Overview

Workflows

POS & LOS Systems

Day 1 Certainty® and AIM

Document Processing

Console

Link

API

​Overview

​Subscribe to webhooks

​users.fully_synced

​Example users.fully_synced response payload:

​reports.d1c_data_ready

​Example reports.d1c_data_ready response payload:

​reports.d1c_data_incomplete

​Example reports.d1c_data_incomplete response payload:

​Endpoint — /v1/du-validation/generate

​D1C report — Request

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

​D1C report — Response

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

​Endpoint — Error codes

​Validation errors

​System errors

​PDF reports

​Generate via Console

​Generate via API

​Example voie-d1c report JSON payload:

​Example voie-d1c report JSON payload with error:

Overview

Subscribe to webhooks

`users.fully_synced`

Example users.fully_synced response payload:

`reports.d1c_data_ready`

Example reports.d1c_data_ready response payload:

`reports.d1c_data_incomplete`

Example reports.d1c_data_incomplete response payload:

Endpoint — /v1/du-validation/generate

D1C report — Request

Example of body parameters in XML with values filled in:

D1C report — Response

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

Endpoint — Error codes

Validation errors

System errors

PDF reports

Generate via Console

Generate via API

Example voie-d1c report JSON payload:

Example voie-d1c report JSON payload with error: