Verifications

Order document-based income verifications.

#The verifications object

Attributes
  • #
    idstring (uuid)
    Unique ID of the verification.
  • #
    userstring (uuid)
    ID of the user associated with the verification.
  • #
    created_atstring (datetime)

    Timestamp (ISO 8601) when the verification was requested.

  • #
    updated_atstring (datetime)

    Timestamp (ISO 8601) when the verification object was last updated.

  • #
    sourcestring
    Origin of the verification order.
  • #
    statusobject
    Verification status information.
  • #
    statestring (enum)

    Verification state.

  • #
    codestring (enum)

    Verification status code.

  • #
    errorsarray of objects

    Error information.

    Error details, such as what caused a PAUSED state or prevented GSE eligibility for a COMPLETED verification.


  • #
    codestring (enum)

    Error code.

  • #
    codestring

    Error title.

  • #
    messagestring

    Error message.

  • #
    resourcesarray of objects

    Additional troubleshooting resources (e.g. the ID of an unmatched document).

  • #
    reportobject

    Report information.

  • #
    idstring (uuid)

    Unique ID of the report.

    Only available when verification state is COMPLETED

  • #
    typestring (enum)

    The type of report.

  • #
    file_urlstring

    Download link to the report PDF.
    — Requires Argyle authentication headers.

    Only available when verification state is COMPLETED

  • #
    json_urlstring

    Download link to the report in JSON.
    — Requires Argyle authentication headers.

    Only available when verification state is COMPLETED

  • #
    employmentsarray of objects

    List of employments for the user.

  • #
    employerstring

    Name of the employer.

  • #
    statusstring (enum)

    User's current employment status at this employer.

  • #
    hire_datestring (date)

    Employment start date in ISO 8601 format.

  • #
    termination_datestring (date)
    optional

    Employment end date in ISO 8601 format.

    null when employment status is active

  • #
    loanobject

    Optional loan details.

  • #
    numberstring

    Loan number or identifier.

  • #
    borrower_idstring

    Borrower identifier.

  • #
    application_idstring

    Application identifier.

  • #
    officer_emailstring
    optional

    Email of the loan officer requesting the verification.

  • #
    billingobject

    Optional billing details.

  • #
    cost_centerstring

    Cost center identifier.

Example
1{
2  "id": "43a2c6c3-1e63-91e5-88e3-f9ab2dcc489b",
3  "user": "018051aa-f7a9-a0db-2f38-6cfa325e9d69",
4  "created_at": "2023-03-09T16:22:06.081Z",
5  "updated_at": "2023-03-09T16:22:06.081Z",
6  "source": "api",
7  "status": {
8    "state": "PENDING",
9    "code": "pending",
10    "errors": []
11  },
12  "report": {
13    "id": null,
14    "type": "doc-voi-mortgage",
15    "file_url": null,
16    "json_url": null
17  },
18  "employments": [
19    {
20      "employer": "Starbucks",
21      "status": "active",
22      "hire_date": "2015-08-28",
23      "termination_date": null
24    }
25  ],
26  "loan": {
27    "number": "1234",
28    "borrower_id": "ABC789",
29    "application_id": "2121313",
30    "officer_email": "john.doe@mortgage.com"
31  },
32  "billing": {
33    "cost_center": "5"
34  }
35}

#Order a verification

post/v2/verifications

Orders a new verification.

Request body
  • #
    user_detailsobject
    required

    Personal information about the user.

  • #
    first_namestring
    required

    First name of the user.

  • #
    last_namestring
    required

    Last name of the user.

  • #
    ssnstring
    required

    Social Security number of the user.

  • #
    emailstring
    optional

    Email of the user.

  • #
    phone_numberstring
    optional

    Phone number of the user. E.164 international format.

  • #
    addressobject
    optional

    Address of the user.

  • #
    citystring
    optional
    Name of the city, town, district, or similar regional entity.
  • #
    line1string
    optional
    Address-Line 1, usually street address or P.O. Box information.
  • #
    line2string
    optional
    Address-Line 2, usually the apartment or unit number.
  • #
    statestring
    optional
    State, county, province, region, or equivalent.
  • #
    countrystring
    optional

    Two-letter country code (ISO 3166-1 alpha-2 format).

  • #
    postal_codestring
    optional
    Zip code, or equivalent.
  • #
    birth_dateobject
    optional
    Birth date of the user.
  • #
    yearinteger
    optional
    Birth year (1900 or later).
  • #
    monthinteger
    optional
    Birth month (between 1 and 12).
  • #
    dayinteger
    optional
    Birth day (between 1 and 31).
  • #
    employmentsarray of objects
    required

    List of employments for the user.

  • #
    employerstring
    required

    Name of the employer.

  • #
    statusstring (enum)
    required

    User's current employment status at this employer.

  • #
    hire_datestring (date)
    required

    Employment start date in ISO 8601 format.

  • #
    termination_datestring (date)
    optional

    Employment end date in ISO 8601 format.

    Required when employment status is previous

  • #
    reportobject
    required
  • #
    typestring
    required

    The type of report to generate.

  • #
    loanobject
    optional

    Optional loan details.

  • #
    numberstring
    optional

    Loan number or identifier.

  • #
    borrower_idstring
    optional

    Borrower identifier.

  • #
    application_idstring
    optional

    Application identifier.

  • #
    officer_emailstring
    optional

    Email of the loan officer requesting the verification.

  • #
    billingobject
    optional
  • #
    cost_centerstring
    optional

    Cost center identifier.

Example Request
1curl --request POST \
2     --url https://api.argyle.com/v2/verifications \
3     --header 'accept: application/json' \
4     --header 'content-type: application/json' \
5     --data '{
6        "user_details": {
7            "first_name": "Bob",
8            "last_name": "Jones",
9            "ssn": "123-45-6789",
10            "email": "bob@email.com",
11            "phone_number": "+12125555555",
12            "address": {
13                "city": "New York",
14                "line1": "759 Victoria Plaza",
15                "line2": null,
16                "state": "New York",
17                "country": "US",
18                "postal_code": "10014"
19            },
20            "birth_date": {
21                "year": 1990,
22                "month": 6,
23                "day": 15
24            }
25        },
26        "employments": [
27            {
28                "employer": "Starbucks",
29                "status": "active",
30                "hire_date": "2015-08-28",
31                "termination_date": null
32            }
33        ],
34        "report": {
35            "type": "doc-voi-mortgage"
36        },
37        "loan": {
38            "number": "1234",
39            "borrower_id": "ABC789",
40            "application_id": "2121313",
41            "officer_email": "john.doe@mortgage.com"
42        },
43        "billing": {
44            "cost_center": "5"
45        }
46     }'
Example Response
1{
2  "id": "43a2c6c3-1e63-91e5-88e3-f9ab2dcc489b",
3  "user": "018051aa-f7a9-a0db-2f38-6cfa325e9d69",
4  "created_at": "2023-03-09T16:22:06.081Z",
5  "updated_at": "2023-03-09T16:22:06.081Z",
6  "source": "api",
7  "status": {
8    "state": "PENDING",
9    "code": "pending",
10    "errors": []
11  },
12  "report": {
13    "id": null,
14    "type": "doc-voi-mortgage",
15    "file_url": null,
16    "json_url": null
17  },
18  "employments": [
19    {
20      "employer": "Starbucks",
21      "status": "active",
22      "hire_date": "2015-08-28",
23      "termination_date": null
24    }
25  ],
26  "loan": {
27    "number": "1234",
28    "borrower_id": "ABC789",
29    "application_id": "2121313",
30    "officer_email": "john.doe@mortgage.com"
31  },
32  "billing": {
33    "cost_center": "5"
34  }
35}

#Retrieve a verification

get/v2/verifications/{id}

Retrieves a verification.

Path parameters
  • #
    idstring (uuid)
    required
    ID of the verification to be retrieved.
Example Request
1curl --request GET \
2     --url https://api.argyle.com/v2/verifications/{id} \
3     --header 'accept: application/json' \
4     --header 'content-type: application/json'
Example Response
1{
2  "id": "43a2c6c3-1e63-91e5-88e3-f9ab2dcc489b",
3  "user": "018051aa-f7a9-a0db-2f38-6cfa325e9d69",
4  "created_at": "2023-03-09T16:22:06.081Z",
5  "updated_at": "2023-03-09T16:22:06.081Z",
6  "source": "api",
7  "status": {
8    "state": "PENDING",
9    "code": "pending",
10    "errors": []
11  },
12  "report": {
13    "id": null,
14    "type": "doc-voi-mortgage",
15    "file_url": null,
16    "json_url": null
17  },
18  "employments": [
19    {
20      "employer": "Starbucks",
21      "status": "active",
22      "hire_date": "2015-08-28",
23      "termination_date": null
24    }
25  ],
26  "loan": {
27    "number": "1234",
28    "borrower_id": "ABC789",
29    "application_id": "2121313",
30    "officer_email": "john.doe@mortgage.com"
31  },
32  "billing": {
33    "cost_center": "5"
34  }
35}

#Update a verification

patch/v2/verifications/{id}

Updates a verification.

After a verification is updated, it will re-enter the PROCESSING state.

Path parameters
  • #
    idstring (uuid)
    required
    ID of the verification to be updated.
Request body
  • #
    loanobject
    optional
  • #
    borrower_idstring
    optional

    Borrower identifier.

    Can be updated at any time, regardless of verification status.

  • #
    employmentsarray of objects
    optional

    Can only be updated when verification state is PAUSED

    Updating employments will act like a PUT request (the entire employments array will be replaced by the new employments array provided).

  • #
    employerstring
    required

    Name of the employer.

  • #
    statusstring (enum)
    required

    User's current employment status at this employer.

  • #
    hire_datestring (date)
    required

    Employment start date in ISO 8601 format.

  • #
    termination_datestring (date)
    optional

    Employment end date in ISO 8601 format.

    Required when employment status is previous

Example Request
1curl --request PATCH \
2     --url https://api.argyle.com/v2/verifications/{id} \
3     --header 'accept: application/json' \
4     --header 'content-type: application/json' \
5     --data '{
6        "loan": {
7          "borrower_id": "5678"
8        }
9        "employments": [
10          {
11              "employer": "Starbucks",
12              "status": "previous",
13              "hire_date": "2015-08-28",
14              "termination_date": "2023-05-01"
15          },
16          {
17              "employer": "Amazon",
18              "status": "active",
19              "hire_date": "2023-06-15",
20              "termination_date": null
21          }
22        ]
23     }'
Example Response
1{
2  "id": "43a2c6c3-1e63-91e5-88e3-f9ab2dcc489b",
3  "user": "018051aa-f7a9-a0db-2f38-6cfa325e9d69",
4  "created_at": "2023-03-09T16:22:06.081Z",
5  "updated_at": "2023-03-09T16:22:06.081Z",
6  "source": "api",
7  "status": {
8    "state": "PROCESSING",
9    "code": "documents_processing",
10    "errors": []
11  },
12  "report": {
13    "id": null,
14    "type": "doc-voi-mortgage",
15    "file_url": null,
16    "json_url": null
17  },
18  "employments": [
19    {
20      "employer": "Starbucks",
21      "status": "previous",
22      "hire_date": "2015-08-28",
23      "termination_date": "2023-05-01"
24    },
25    {
26      "employer": "Amazon",
27      "status": "active",
28      "hire_date": "2023-06-15",
29      "termination_date": null
30    }
31  ],
32  "loan": {
33    "number": "5678",
34    "borrower_id": "ABC789",
35    "application_id": "2121313",
36    "officer_email": "john.doe@mortgage.com"
37  },
38  "billing": {
39    "cost_center": "5"
40  }
41}

#Cancel a verification

post/v2/verifications/{id}/cancel

Cancels a verification order.

Only verifications in the PAUSED state can be cancelled.

Path parameters
  • #
    idstring (uuid)
    required
    ID of the verification to be cancelled.
Example Request
1curl --request POST \
2     --url https://api.argyle.com/v2/verifications/{id}/cancel \
3     --header 'accept: application/json' \
4     --header 'content-type: application/json'
Example Response
1{
2  "id": "43a2c6c3-1e63-91e5-88e3-f9ab2dcc489b",
3  "user": "018051aa-f7a9-a0db-2f38-6cfa325e9d69",
4  "created_at": "2023-03-09T16:22:06.081Z",
5  "updated_at": "2023-03-09T16:22:06.081Z",
6  "source": "api",
7  "status": {
8    "state": "CANCELLED",
9    "code": "cancelled_by_client",
10    "errors": []
11  },
12  "report": {
13    "id": null,
14    "type": "doc-voi-mortgage",
15    "file_url": null,
16    "json_url": null
17  },
18  "employments": [
19    {
20      "employer": "Starbucks",
21      "status": "active",
22      "hire_date": "2015-08-28",
23      "termination_date": null
24    }
25  ],
26  "loan": {
27    "number": "1234",
28    "borrower_id": "ABC789",
29    "application_id": "2121313",
30    "officer_email": "john.doe@mortgage.com"
31  },
32  "billing": {
33    "cost_center": "5"
34  }
35}

#List all verifications

get/v2/verifications

Returns an array of all verifications.

Query parameters
  • #
    userstring
    optional

    Filter by user ID.

  • #
    status_statestring
    optional

    Filter by verification status state

  • #
    status_codestring
    optional

    Filter by verification status code

  • #
    report_typestring
    optional

    Filter by report type

  • #
    loan_numberstring
    optional

    Filter by loan number

  • #
    limitinteger
    optional

    Number of verification objects returned per page. Default: 10. Maximum: 200.

Example Request
1curl --request GET \
2     --url https://api.argyle.com/v2/verifications?limit=2 \
3     --header 'accept: application/json' \
4     --header 'content-type: application/json'
Example Response
1[
2  {
3    "id": "43a2c6c3-1e63-91e5-88e3-f9ab2dcc489b",
4    "user": "018051aa-f7a9-a0db-2f38-6cfa325e9d69",
5    "created_at": "2023-03-09T16:22:06.081Z",
6    "updated_at": "2023-03-09T16:22:06.081Z",
7    "source": "api",
8    "status": {
9      "state": "COMPLETED",
10      "code": "completed",
11      "errors": []
12    },
13    "report": {
14      "id": "2a14ce6f-3aed-4c15-8ea2-92a17b6edb95",
15      "type": "doc-voi-mortgage",
16      "file_url": "https://api.argyle.com/v2/reports/12345678-e321-4a76-8d10-093cfdbb8cdd/pdf",
17      "json_url": "https://api.argyle.com/v2/reports/12345678-e321-4a76-8d10-093cfdbb8cdd/json"
18    },
19    "employments": [
20      {
21        "employer": "Starbucks",
22        "status": "active",
23        "hire_date": "2015-08-28",
24        "termination_date": null
25      }
26    ],
27    "loan": {
28      "number": "1234",
29      "borrower_id": "ABC789",
30      "application_id": "2121313",
31      "officer_email": "john.doe@mortgage.com"
32    },
33    "billing": {
34      "cost_center": "5"
35    }
36  },
37  {
38    "id": "43a2c6c3-1e63-91e5-88e3-f9ab2dcc3333",
39    "user": "018051aa-f7a9-a0db-2f38-6cfa325e9345",
40    "created_at": "2023-03-10T05:14:06.081Z",
41    "updated_at": "2023-03-10T13:03:06.081Z",
42    "source": "api",
43    "status": {
44      "state": "PROCESSING",
45      "code": "documents_processing",
46      "errors": []
47    },
48    "report": {
49      "id": null,
50      "type": "doc-voi-mortgage",
51      "file_url": null,
52      "json_url": null
53    },
54    "employments": [
55      {
56        "employer": "Starbucks",
57        "status": "active",
58        "hire_date": "2019-01-01",
59        "termination_date": null
60      }
61    ],
62    "loan": {
63      "number": "1234",
64      "borrower_id": "ABC789",
65      "application_id": "2121313",
66      "officer_email": "john.doe@mortgage.com"
67    },
68    "billing": {
69      "cost_center": "5"
70    }
71  }
72]
Updating Argyle status...
© 2025 Argyle Systems Inc.argyle.com