---
updatedAt: 2026-03-16T10:13:22.000Z
---

# Retrieving Customer Entered Info

# Overview

1. End user creates an event using the widget's "Order" button.
2. Partner will use GET `/v1/collateral-widgets/events/{widgetId}` on timed intervals to find all open collateral widgets.
3. With the event information use GET `/v1/portfolio-loans/{id}` and `/v1/collaterals/{id}` to gather relevant information on the loan and collateral.
4. Once event, loan and collateral information is gathered, the event may be completed using PATCH `/v1/events/{id}/complete`
5. Make updates using PATCH `/v1/collaterals/{id}` and POST `/v1/documents`. At this point the Widget status should be updated to Complete or another status letting the end user know the order is complete.

# User creates an order

Once the widget is created, it will appear on all collateral for that customer. When ready the customer fills out the fields and clicks "order". The status of that widget will update to \[WidgetName] ordered on \[date]\[time] and an event will be generated

[block:image]
{
  "images": [
    {
      "image": [
        "https://files.readme.io/e6f11ab-image.png",
        null,
        ""
      ],
      "align": "center",
      "border": true
    }
  ]
}
[/block]

[block:image]
{
  "images": [
    {
      "image": [
        "https://files.readme.io/99960ce-image.png",
        null,
        ""
      ],
      "align": "center",
      "border": true
    }
  ]
}
[/block]

# Get open events

At this point an event will be created. You may use GET `/v1/collateral-widgets/events/{widgetId}` to view open events for the specified widget ID. *Note: It is important to use this endpoint to make sure only events created by your widget are retrieved.*

```Text Response
{
  "items": [
    {
     "id": 1717177,
      "eventTime": "2024-01-22T15:55:42.8795028-05:00",
      "eventType": "collateralWidgetEvent",
      "eventContent": {
        "collateralWidgetID": "4",
        "proposedLoanId": null,
        "loanId": "70517124",
        "collateralId": "53055892",
        "customerIds": "[85477283]"
      },
      "isComplete": false
    }
  ]
}
```
```Text Request
curl -X GET "https://api.sageworks.com/v1/events?eventType=collateralWidgetEvent" -H "accept: application/json" -H "authorization: Bearer [token]"
```

# Get widget information

Use GET `/v1/collateral-widgets/values/{id}/{collateralId}` to obtain all of the values entered by the end user.

```Text Response
{
  "fieldValues": {
    "Property Address": "1820 Preston Park Blvd",
    "Property City": "Plano",
    "Property County": "North Carolina",
    "Property State": "Texas",
    "Property Tax ID": "11111",
    "Property Zip": "75093",
    "Collateral Description": "1020",
    "BorrowerName": "New, User"
  },
  "customerId": 85477283
}
```
```Text Request
curl -X GET "https://api.sageworks.com/v1/collateral-widgets/values/4/53055892" -H "accept: application/json" -H "authorization: Bearer {token}"
```

## Get loan information

If necessary Use GET `/v1/portfolio-loans/{id}` or GET`/v1/proposed-loans` to get the related loan information.

```Text Response
{
  "id": 57649030,
  "loanNumber": "10",
  "name": "New Loan",
  "customerId": 85477283,
  "currentBalance": 10000,
  "unamortizedPremium": 0,
  "bookBalance": 0,
  "riskRating": 2,
  "paymentAmount": 0,
  "paymentFrequency": "monthly",
  "paymentType": "fixedPayment",
  "loanOfficerId": null,
  "interestRate": 0,
  "floorRate": 0,
  "ceilingRate": 0,
  "indexRateDescription": null,
  "spread": 0,
  "indexRate": 0,
  "callCode": "",
  "collateralCode": "",
  "loanTypeCode": "",
  "productCode": "",
  "purposeCode": "",
  "industryCode": "",
  "nonAccrual": false,
  "nonAccrualDate": null,
  "troubledDebtRestructure": false,
  "troubledDebtRestructureDate": null,
  "defaultStartDate": null,
  "adjustableInterestRate": false,
  "timesPastDue3060": 0,
  "timesPastDue6090": 0,
  "timesPastDue90Plus": 0,
  "daysCurrentlyPastDue": 0,
  "chargedOffAmount": 0,
  "amountPastDue": 0,
  "prepaymentPenalty": false,
  "remainingTermInMonths": 0,
  "dayCountConvention": null,
  "amortizedOver": null,
  "currentAvailableCredit": 0,
  "maturityDate": null,
  "netDeferredFeesOrCosts": 0,
  "totalFees": 0,
  "expectedUtilizationRate": 0,
  "upfrontFee": 0,
  "annualFee": 0,
  "unusedCommitmentFee": 0,
  "originationExpenses": 0,
  "overheadExpenses": 0,
  "servicingExpenses": 0,
  "accruedInterest": 0,
  "originalLoanAmount": 0,
  "originationDate": null,
  "originalTermInMonths": 0,
  "renewalDate": null,
  "governmentGuaranteed": false,
  "governmentGuaranteedPercent": 0,
  "governmentGuaranteedBalance": 0,
  "watchList": false,
  "points": 0,
  "refinance": false,
  "latestPaymentDate": null,
  "loanToValueRatio": 0.6944444,
  "isDeleted": false,
  "isGuidanceLineOfCredit": false,
  "bankCodeBranch": "",
  "accountType": null,
  "parentLoansId": null,
  "withheldAmount": null,
  "userDefinedString1": "",
  "userDefinedString2": "",
  "userDefinedString3": "",
  "userDefinedString4": "",
  "userDefinedString5": "",
  "userDefinedString6": "",
  "userDefinedString7": "",
  "userDefinedString8": "",
  "userDefinedString9": "",
  "userDefinedString10": "",
  "userDefinedString11": "",
  "userDefinedString12": "",
  "userDefinedString13": "",
  "userDefinedString14": "",
  "userDefinedString15": "",
  "userDefinedString16": "",
  "userDefinedString17": "",
  "userDefinedString18": "",
  "userDefinedString19": "",
  "userDefinedString20": "",
  "userDefinedNumber1": 0,
  "userDefinedNumber2": 0,
  "userDefinedNumber3": 0,
  "userDefinedNumber4": 0,
  "userDefinedNumber5": 0,
  "userDefinedNumber6": 0,
  "userDefinedNumber7": 0,
  "userDefinedNumber8": 0,
  "userDefinedNumber9": 0,
  "userDefinedNumber10": 0,
  "userDefinedNumber11": 0,
  "userDefinedNumber12": 0,
  "userDefinedNumber13": 0,
  "userDefinedNumber14": 0,
  "userDefinedNumber15": 0,
  "userDefinedNumber16": 0,
  "userDefinedNumber17": 0,
  "userDefinedNumber18": 0,
  "userDefinedNumber19": 0,
  "userDefinedNumber20": 0,
  "userDefinedDate1": null,
  "userDefinedDate2": null,
  "userDefinedDate3": null,
  "userDefinedDate4": null,
  "userDefinedDate5": null,
  "userDefinedDate6": null,
  "userDefinedDate7": null,
  "userDefinedDate8": null,
  "userDefinedDate9": null,
  "userDefinedDate10": null,
  "userDefinedFields": null
}
```
```Text Request
curl -X GET "https://api.sageworks.com/v1/portfolio-loans/[loanId]?includeUserDefinedFields=true" -H "accept: application/json" -H "authorization: Bearer [token]"
```

## Get collateral information

If other collateral information is needed, use GET `/v1/collaterals/{id}` to find the related collateral information.

```Text Response
{
  "id": 57532606,
  "description": "2222",
  "currentValue": 0,
  "mostRecentAppraisalValue": 0,
  "mostRecentAppraisalDate": null,
  "collateralCode": "",
  "collateralType": "",
  "customerId": 85477283,
  "originalValue": 0,
  "discountRate": 0,
  "isDeleted": false,
  "propertyAddress": null,
  "propertyCity": null,
  "propertyState": null,
  "propertyZip": null,
  "propertyCounty": null,
  "propertyTaxID": null,
  "make": null,
  "vin": null,
  "model": null,
  "year": null,
  "bodyStyle": null,
  "serialNumber": null,
  "manufacturer": null,
  "aircraftNumber": null,
  "vesselName": null,
  "vesselNumber": null,
  "possessoryType": null,
  "accountLOCNumber": null,
  "issuedBy": null,
  "issuer": null,
  "shares": null,
  "cusip": null,
  "heldBy": null,
  "beneficiary": null,
  "letterOfCreditDate": null,
  "govtContractNumber": null,
  "govtContractDate": null,
  "titledType": "unknown",
  "floodDeterminationDate": null,
  "specialFloodHazardArea": null,
  "capitalizationRate": 0,
  "isLOMC": null,
  "collateralBreakout": null,
  "cbraAndOPADesignationDate": null,
  "dwelling": null,
  "vesselLength": null,
  "floodZone": null,
  "floodZoneCode": null,
  "floodProgramType": null,
  "isLandImprovements": null,
  "lomcCaseNumber": null,
  "lomcDate": null,
  "nfipMapNumber": null,
  "nfipMapPanelDate": null,
  "nfipCommunityName": null,
  "nfipCommunityNumber": null,
  "nfipPropertyDescription": null,
  "constructionMethod": null,
  "manufacturedHomeType": null,
  "manufacturedHomeLandPropertyInterest": null,
  "totalUnits": null,
  "multiFamilyAffordableUnits": null,
  "occupancyType": null,
  "isForAgriculturalPurpose": null,
  "isOwnerOccupied": null,
  "isSecondHome": null,
  "isProtectedArea": null,
  "stateCode": null,
  "countyCode": null,
  "tractCode": null,
  "latitude": null,
  "longitude": null,
  "metropolitanStatisticalArea": null,
  "medianHouseholdIncome": null,
  "metropolitanDivision": null,
  "metropolitanDivisionCode": null,
  "userDefinedFields": {
    "8314": null,
    "Manual Flood Determination": null,
    "Widget21 Status": null,
    "Widget22 Status": null,
    "AaronTest Status": null,
    "Test": null,
    "8314 test two": null,
    "string Status": null,
    "Aircraft Widget 4 Status": "Aircraft Widget 4 ordered on June 15 2023 at 2:15 PM EST"
  },
  "dateAppraisalRequested": null,
  "isReadyForAppraisal": null,
  "collateralMetadataType": "existing",
  "collateralIdentifier": "",
  "legalDescription": null
}
```
```Text Request
curl -X GET "https://api.sageworks.com/v1/collaterals/[collateralId]?includeUserDefinedFields=true" -H "accept: application/json" -H "authorization: Bearer [token]"
```

# Complete the event

Once event, loan and collateral information is gathered, the event may be completed using PATCH `/v1/events/{id}/complete`. This will make it so that specific event does not appear on the list of events anymore

```Text Response
{
  "id": 8854,
  "eventTime": "2023-07-06T15:57:21.8276005-04:00",
  "eventType": "collateralWidgetEvent",
  "eventContent": {
    "collateralWidgetID": "4",
    "proposedLoanId": null,
    "loanId": "70517124",
    "collateralId": "53055892"
  },
  "isComplete": true
}
```
```Text Request
curl -X PATCH "https://api.sageworks.com/v1/events/125464545/complete" -H "accept: application/json" -H "authorization: Bearer [token]"
```

# Update Widget status

Once all relevant information is pulled from the event/loan/collateral the status of the widget may be updated using PATCH `/v1/collateral-widgets/status/{widgetId}/{collateralId}` (Ex: In process). This is displayed on the widget itself to the customer and may be used as communicate for what status the order is in.

*Note: You may link a url (such as for the order page on your website) within the status to allow a more fluid navigation for the end user. It muse be in the format of[Order link here](https://www.google.com/). This would result in the end user seeing "Order link here" as a hyperlink and it would redirect them to google.*

```Text Response
{
  "status": "Order is processing at {date/time}. Go to [Site|Url] to view details."
}
```
```Text Body
curl -X PATCH "https://stagingapi.sageworks.com/v1/collateral-widgets/status/[widgetId]/[collateralId]" -H "accept: application/json" -H "authorization: Bearer [token]" -H "Content-Type: application/json-patch+json" -d "{ \"status\": \"This order is processing\"}"
```

# Post new information

## Post collateral information

Once the order is completed, information can then be passed along  using the PATCH  `/v1/collaterals/{id}`.

```Text Response
{
  "id": 57532606,
  "description": "2222",
  "currentValue": 0,
  "mostRecentAppraisalValue": 0,
  "mostRecentAppraisalDate": null,
  "collateralCode": "",
  "collateralType": "",
  "customerId": 85477283,
  "originalValue": 0,
  "discountRate": 0,
  "isDeleted": false,
  "propertyAddress": null,
  "propertyCity": null,
  "propertyState": null,
  "propertyZip": null,
  "propertyCounty": null,
  "propertyTaxID": null,
  "make": null,
  "vin": null,
  "model": null,
  "year": null,
  "bodyStyle": null,
  "serialNumber": null,
  "manufacturer": null,
  "aircraftNumber": null,
  "vesselName": null,
  "vesselNumber": null,
  "possessoryType": null,
  "accountLOCNumber": null,
  "issuedBy": null,
  "issuer": null,
  "shares": null,
  "cusip": null,
  "heldBy": null,
  "beneficiary": null,
  "letterOfCreditDate": null,
  "govtContractNumber": null,
  "govtContractDate": null,
  "titledType": "unknown",
  "floodDeterminationDate": null,
  "specialFloodHazardArea": null,
  "capitalizationRate": 0,
  "isLOMC": null,
  "collateralBreakout": null,
  "cbraAndOPADesignationDate": null,
  "dwelling": null,
  "vesselLength": null,
  "floodZone": null,
  "floodZoneCode": null,
  "floodProgramType": null,
  "isLandImprovements": null,
  "lomcCaseNumber": null,
  "lomcDate": null,
  "nfipMapNumber": null,
  "nfipMapPanelDate": null,
  "nfipCommunityName": null,
  "nfipCommunityNumber": null,
  "nfipPropertyDescription": null,
  "constructionMethod": null,
  "manufacturedHomeType": null,
  "manufacturedHomeLandPropertyInterest": null,
  "totalUnits": null,
  "multiFamilyAffordableUnits": null,
  "occupancyType": null,
  "isForAgriculturalPurpose": null,
  "isOwnerOccupied": null,
  "isSecondHome": null,
  "isProtectedArea": null,
  "stateCode": null,
  "countyCode": null,
  "tractCode": null,
  "latitude": null,
  "longitude": null,
  "metropolitanStatisticalArea": null,
  "medianHouseholdIncome": null,
  "metropolitanDivision": null,
  "metropolitanDivisionCode": null,
  "userDefinedFields": {
    "8314": null,
    "Manual Flood Determination": null,
    "Widget21 Status": null,
    "Widget22 Status": null,
    "AaronTest Status": null,
    "Test": null,
    "8314 test two": null,
    "string Status": null,
    "Aircraft Widget 4 Status": "Aircraft Widget 4 ordered on June 15 2023 at 2:15 PM EST"
  },
  "dateAppraisalRequested": null,
  "isReadyForAppraisal": null,
  "collateralMetadataType": "existing",
  "collateralIdentifier": "",
  "legalDescription": null
}
```
```Text Body
curl -X PATCH "https://api.sageworks.com/v1/collaterals/[collateralId]" -H "accept: application/json" -H "authorization: Bearer [token]" -H "Content-Type: application/json-patch+json" -d "{ \"id\": 57532606, \"description\": \"2222\", \"currentValue\": 0, \"mostRecentAppraisalValue\": 0, \"mostRecentAppraisalDate\": null, \"collateralCode\": \"\", \"collateralType\": \"\", \"customerId\": 85477283, \"originalValue\": 0, \"discountRate\": 0, \"isDeleted\": false, \"propertyAddress\": null, \"propertyCity\": null, \"propertyState\": null, \"propertyZip\": null, \"propertyCounty\": null, \"propertyTaxID\": null, \"make\": null, \"vin\": null, \"model\": null, \"year\": null, \"bodyStyle\": null, \"serialNumber\": null, \"manufacturer\": null, \"aircraftNumber\": null, \"vesselName\": null, \"vesselNumber\": null, \"possessoryType\": null, \"accountLOCNumber\": null, \"issuedBy\": null, \"issuer\": null, \"shares\": null, \"cusip\": null, \"heldBy\": null, \"beneficiary\": null, \"letterOfCreditDate\": null, \"govtContractNumber\": null, \"govtContractDate\": null, \"titledType\": \"unknown\", \"floodDeterminationDate\": null, \"specialFloodHazardArea\": null, \"capitalizationRate\": 0, \"isLOMC\": null, \"collateralBreakout\": null, \"cbraAndOPADesignationDate\": null, \"dwelling\": null, \"vesselLength\": null, \"floodZone\": null, \"floodZoneCode\": null, \"floodProgramType\": null, \"isLandImprovements\": null, \"lomcCaseNumber\": null, \"lomcDate\": null, \"nfipMapNumber\": null, \"nfipMapPanelDate\": null, \"nfipCommunityName\": null, \"nfipCommunityNumber\": null, \"nfipPropertyDescription\": null, \"constructionMethod\": null, \"manufacturedHomeType\": null, \"manufacturedHomeLandPropertyInterest\": null, \"totalUnits\": null, \"multiFamilyAffordableUnits\": null, \"occupancyType\": null, \"isForAgriculturalPurpose\": null, \"isOwnerOccupied\": null, \"isSecondHome\": null, \"isProtectedArea\": null, \"stateCode\": null, \"countyCode\": null, \"tractCode\": null, \"latitude\": null, \"longitude\": null, \"metropolitanStatisticalArea\": null, \"medianHouseholdIncome\": null, \"metropolitanDivision\": null, \"metropolitanDivisionCode\": null, \"userDefinedFields\": { \"8314\": null, \"Manual Flood Determination\": null, \"Widget21 Status\": null, \"Widget22 Status\": null, \"AaronTest Status\": null, \"Test\": null, \"8314 test two\": null, \"string Status\": null, \"Aircraft Widget 4 Status\": \"Aircraft Widget 4 ordered on June 15 2023 at 2:15 PM EST\" }, \"dateAppraisalRequested\": null, \"isReadyForAppraisal\": null, \"collateralMetadataType\": \"existing\", \"collateralIdentifier\": \"\", \"legalDescription\": null}"
```

## Post Document information

Once ready to send documents, the correct document folder must be selected to send the document to Sageworks.  found when pulling the loan information.

### Get Document Folders

Use GET `/v1/document-folders` get all the customers' document folders if the `documentFolderId` is not known.

```Text Response
{
  "items": [
    {
      "id": 69526,
      "type": "customer",
      "name": "Loan Documents",
      "parentDocumentFolderId": null,
      "isDeleted": false
    },
    {
      "id": 69527,
      "type": "customer",
      "name": "Financial Documents",
      "parentDocumentFolderId": null,
      "isDeleted": false
    },
    {
      "id": 69528,
      "type": "customer",
      "name": "Collateral Documents",
      "parentDocumentFolderId": null,
      "isDeleted": false
    },
    {
      "id": 69529,
      "type": "customer",
      "name": "Tickler Documents",
      "parentDocumentFolderId": null,
      "isDeleted": false
    },
    {
      "id": 69530,
      "type": "customer",
      "name": "Workflow Documents",
      "parentDocumentFolderId": null,
      "isDeleted": false
    },
    {
      "id": 72323,
      "type": "customer",
      "name": "Flood Reports",
      "parentDocumentFolderId": 69528,
      "isDeleted": false
    },
    {
      "id": 79163,
      "type": "customer",
      "name": "Esignature Template Audit Trails",
      "parentDocumentFolderId": null,
      "isDeleted": false
    },
    {
      "id": 83133,
      "type": "customer",
      "name": "OCR Tax Documents",
      "parentDocumentFolderId": 69527,
      "isDeleted": false
    }
  ]
}
```
```Text Request
curl -X GET "https://stagingapi.sageworks.com/v1/document-folders" -H "accept: application/json" -H "authorization: Bearer
```

### Post Documents

Documents may be sent to Sageworks using POST `/v1/documents`. The `associationCustomerId` is the same value as `customerId` found in the get loan or get collateral steps. *Note: `documentContent` must be in base64 format.*

```Text Body
{
  "associationCustomerId": 85477283,
  "document": {
    "description": "Test File",
    "documentDated": "2017-12-31",
    "documentFolderId": 69526,
    "uniqueIdentifier": "Test Document 123",
    "name": "Test File",
    "fileName": "TestFileName.txt"
  },
  "documentContent": {
    "content": "Z2FyYmFnZSBmYWtl"
  }
}
```
```Text Response
{
  "id": 26278763,
  "customerId": 85477283,
  "documentFolderId": 69526,
  "uniqueIdentifier": "Test Document 123",
  "name": "Test File",
  "customerFacingName": null,
  "fileName": "TestFileName.txt",
  "sizeInBytes": 12,
  "isImage": false,
  "isDeleted": false,
  "documentDated": "2017-12-31",
  "description": "Test File",
  "dateUploaded": "2023-06-15"
}
```

### Post document associations

Use POST `/v1/document-associations` to associate the document with other objects in Sageworks.

```Text Body
{
  "id": 50929059,
  "documentId": 26865232,
  "objectType": "PortfolioLoan",
  "objectId": 57649024
}
```
```Text Response
{
  "id": 50929059,
  "documentId": 26865232,
  "objectType": "PortfolioLoan",
  "objectId": 57649024
}
```

# Update Widget status

Once all relevant information is pulled from the event/loan/collateral the status of the widget may be updated using `/v1/collateral-widgets/status/{widgetId}/{collateralId}` (Ex: Completed).

*Note: You may link a URL (such as for the order page on your website) within the status to allow a more fluid navigation for the end user). It must be in the format of [Order link here](https://www.google.com/). This would result in the end user seeing "Order link here" as a hyperlink and it would redirect them to google.*

```Text Response
{
  "status": "Order completed go to [Site|url] to view details."
}
```
```Text Request
curl -X PATCH "https://stagingapi.sageworks.com/v1/collateral-widgets/status/[widgetId]/[collateralId]" -H "accept: application/json" -H "authorization: Bearer [token]" -H "Content-Type: application/json-patch+json" -d "{ \"status\": \"This order is processing\"}"
```