Service Ordering via Encompass Developer Connect

EPC Service Ordering via Developer Connect is an administrator-driven service setup. Encompass LO Connect administrators will need to create a service setup in LO Connect Admin Settings, authorize the API user, and designate credentials to the user for the integration.

EPC 2.0 Product Definition

Step 1: Encompass Developer Connect needs to be added as a supported application in the product configuration. See below for a sample payload:
POST /partner/v2/products/:id

{
  "id": "{{uuid}}",
  "name": "test-product",
  "listingName": "Test Product",
  .....
  "tags": {
    "applications": [
       "urn:elli:application:loconnect",
       "urn:elli:application:encompass",
       "urn:elli:application:developerconnect"
    ],
    ....
  }
  ....
}

Step 2: Use the Services Management admin setting in Encompass LO Connect to configure a service order template.

Services Management setting (Encompass LO Connect)Services Management setting (Encompass LO Connect)

Services Management setting (Encompass LO Connect)

See the table below for service order-related endpoints:

Action

URL

Purpose

POST

/encompass/v3/loans/:id/serviceOrders

Create a service order

GET

/encompass/v3/loans/:id/serviceOrders/:id

Retrieve status of an existing service order

GET

/encompass/v3/loans/:id/serviceOrders

Retrieve status of all service orders on a loan

PATCH

/encompass/v3/loans/:id/serviceOrders/:id/request

Update an existing service order request (if still possible)

GET

/encompass/v3/loans/:id/serviceOrders/:id/response/resources

Get downloadable URLs (as authorized) for the response attachments

POST

/encompass/v3/loans/:id/serviceOrderResources

Stage new service order request file attachment

Webhook Support

Service order events support emitting webhook events for the events listed in the table below.
Webhook service event endpoint: /platform/v1/events/serviceorders

Service Order History Event Type

Webhook Event Type

Scenario

urn:elli:encompass:services:order:placed

placed

Notify lender when order delivered to partner

urn:elli:encompass:services:order:acknowledgement_received

acknowledged

Notify lender when order acknowledged by partner

urn:elli:encompass:services:order:fulfilled

fulfilled

Notify lender when order completed, and response successfully ingested into Encompass

urn:elli:encompass:services:order:preparing:process_failure

processFailure

Notify lender when a process exception (biz rule/authorization/access) occurred while attempting to prepare the order request

urn:elli:encompass:services:order:processing_response:process_failure

processFailure

Notify lender when a process exception (biz rule/authorization/access) occurred while attempting to ingest order response into Encompass

urn:elli:encompass:services:order:fulfillment_failed/failed (need to confirm)

Notify lender when partner communicates a failed response - due to an exception in the partners system

urn:elli:encompass:services:order:retry_requested

Notify lender when request egress has entered retry (extended periodic retries - loan lock, not API retries)

urn:elli:encompass:services:order:retry_processing_response

Notify lender when response ingress has entered retry (extended periodic retries - loan lock, not API retries)

urn:elli:encompass:services:order:abandoned

Notify lender when partner communicates a canceled response

Service Order Life Cycle

Service orders typically go through the following life cycle:

  1. ORDER_REQUESTED
  2. ORDER_PLACED
  3. ORDER_ACKNOWLEDGEMENT_RECEIVED
  4. ORDER_RESPONSE_RECEIVED
  5. ORDER_FULFILLED

📘

NOTE

In the case of any failures in request/response processing - or Partner response cancelations/failures - the status and reason code will be updated accordingly, and the state of the service order will remain as populated up to the failure.

Endpoints and Sample Payloads

POST /encompass/v3/loans/:id/serviceOrders

{
  "serviceSetupId": "{{service_setup_id}}",
  "scope": "application:{{current_application_id}}",
  "reason": "Manual REQUESTED",
  "request": {
    "type": "Verification of Assets",
    "options": {
      "test": "test"
    },
    "resources": [
      {
        "sourceEntity": {
          "id": "{{efolder_attachment_id}}",       
          "type": "urn:elli:encompass:attachment"
        }
      }
    ]
  }
}
{
  "serviceSetupId": "{{service_setup_id}}"
  "scope": "application:{{current_application_id}}" // Only if you want to restrict execution for all relevant entities (all applications/borrowers) for non loan-level evaluation scope
}

GET /encompass/v3/loans/:id/serviceOrders/:id

{
  "id": "{{uuid}}",
  "environment": "TEST",                // Encompass instance type
  "category": "VERIF",
  "origin": "urn:elli:application:developerconnect",
  "serviceSetupId": "{{uuid}}",
  "created": "2020-05-27T00:58:22.686Z",
  "createdBy": "urn:elli:encompass:DEBE11170913:user:aa01",
  "updated": "2020-05-27T01:20:05.482Z",
  "updatedBy": "urn:elli:encompass:DEBE11170913:user:aa01",
  "status": "{{status_from_event_urn}}",
  "entityRef": {
    "entityId": "urn:elli:encompass:{{encompass_instance_id}}:loan:{{loan_guid}}",
    "entityType": "urn:elli:encompass:loan"
  },
  "scope": "application:{{current_application_id}}"
}
{
  "id": "{{uuid}}",
  "environment": "TEST",            // Encompass instance type
  "category": "VERIF",
  "origin": "urn:elli:application:developerconnect",
  "serviceSetup": {
      "id": "{{uuid}}",
      "category": "VERIF",
      "product": {
        "id": "{{uuid}}",
        "listingName": "{{listing_name}}"
      },
      "request": {                      // This would only apply for pre-configured requests - 1-click/ASO
        "type": "Verification of Assets",
        "options": {
          "test": "test"
        }
      }
    },
  "transactionId": "fc3c72aa-3b7d-4067-adf2-957c62ce9137",
  "trackingDocumentId": "{{efolder_document_id}}",
  "created": "2020-05-27T00:58:22.686Z",
  "createdBy": "urn:elli:encompass:DEBE11170913:user:aa01",
  "updated": "2020-05-27T01:20:05.482Z",
  "updatedBy": "urn:elli:encompass:DEBE11170913:user:aa01",
  "status": "{{status_from_event_urn}}",
  "entityRef": {
    "entityId": "urn:elli:encompass:{{encompass_instance_id}}:loan:{{loan_guid}}",
    "entityType": "urn:elli:encompass:loan"
  },
  "scope": "application:{{current_application_id}}",
  "request": {
    "type": "Verification of Assets",
    "requestingParty": {
      "name": "AMG Mortgage",
      "address": "4140 Dublin Blvd. #301",
      "city": "Santa Maria",
      "state": "CA",
      "postalCode": "93458",
      "pointOfContact": {
        "name": "Donald Duck",
        "role": "Loan Officer",
        "email": "[email protected]",
        "phone": "666-666-6666"
      }
    },
    "options": {
      "test": "test"
    },
    "resources": [
      {
        "id": "<id of the resource in the repository>",
        "name": "<name from eFolder attachment>",
        "type": "urn:elli:serviceorder:resource",
        "mimeType": "<mimeType>",
        "sourceEntity": {
          "id": "123",
          "type": "urn:elli:encompass:attachment"
        }
      }
    ]
  },
  "response": {
    "status": "completed",
    "partnerStatus": "Asset Verification Report Delivered",
    "referenceNumber": "CX123TY67",
    "respondingParty": {
      "name": "AAA Verification",
      "address": "3232 Loan Ave",
      "city": "Pleasanton",
      "state": "CA",
      "postalCode": "94588",
      "pointOfContact": {
        "name": "Scott Cooper",
        "role": "Co-ordinator",
        "email": "[email protected]",
        "phone": "343-222-1954"
      }
    },
    "resources": [
      {
        "id": "492b22f9-f037-4e96-825c-fabf2e88f446",
        "name": "testUpload.xml",
        "mimeType": "application/xml",
        "uploadedEntity": {
          "id": "testUpload.xml",
          "type": "urn:elli:encompass:attachment"
        }
      },
      {
        "id": "492b22f9-f037-4e96-825c-fabf2e88f446",
        "name": "testUpload.pdf",
        "mimeType": "application/pdf",
        "uploadedEntity": {
          "id": "testUpload.pdf",
          "type": "urn:elli:media:loans"
        }
      }
    ]
  }
}

📘

NOTE

view is an optional string query param, default view does not include expanded serviceSetup and request/response objects. Complete view expand the default view and include serviceSetup, response, and response objects.

GET /encompass/v3/loans/:id/serviceOrders/:id/response/resources

[
  {
    "id": "<id of the resource in the repository>",
    "name": "<name from eFolder attachment>", // Inherited from eFolder export
    "type": "urn:elli:skydrive",
    "mimeType": "<mimeType>", // Inherited from eFolder export type
    "url": "...clientId/objectId?signature=<signature>&expires=<epoch>",
    "authorizationHeader": "authorizationHeader",
    "uploadedEntity": {
      "id": "{{efolder_attachment_id}}",
      "type": "urn:elli:encompass:attachment"
    }
  },
  {
    "id": "<id of the resource in the repository>",
    "name": "<name from eFolder document>", // Inherited from eFolder export
    "type": "urn:elli:skydrive",
    "mimeType": "<mimeType>", // Inherited from eFolder export type
    "url": "...clientId/objectId?signature=<signature>&expires=<epoch>",
    "authorizationHeader": "authorizationHeader",
    "uploadedEntity": {
      "id": "{{efolder_document_id}}",
      "type": "urn:elli:encompass:document"
    }
  }
]

GET /encompass/v3/loans/:id/serviceOrders

[
  {
    "id": "{{uuid}}",
    "environment": "TEST",              // Encompass instance type
    "category": "VERIF",
    "origin": "urn:elli:application:developerconnect",
    "serviceSetupId": "{{uuid}}",  
    "transactionId": "fc3c72aa-3b7d-4067-adf2-957c62ce9137",
    "trackingDocumentId": "{{efolder_document_id}}",
    "created": "2020-05-27T00:58:22.686Z",
    "createdBy": "urn:elli:encompass:DEBE11170913:user:aa01",
    "updated": "2020-05-27T01:20:05.482Z",
    "updatedBy": "urn:elli:encompass:DEBE11170913:user:aa01",
    "status": "{{status_from_event_urn}}",
    "entityRef": {
      "entityId": "urn:elli:encompass:{{encompass_instance_id}}:loan:{{loan_guid}}",
      "entityType": "urn:elli:encompass:loan"
    },
    "scope": "application:{{current_application_id}}"
  }
]

📘

NOTE

view is an optional query parameter, complete view includes request and response resources no resource URL generation supported though. environment is an optional query parameter, TES, PROD or INTERNAL for lower environments. category is an optional, one of enumerated category list.

PATCH /encompass/v3/loans/:id/serviceOrders/:id/request

options are any data the integration wants to send to partners on behalf of lenders. It is key value pairs. resources will be appended. These are the only editable properties of a completed response status from the partner, which blocks the request from further updates.

{
  "options": {
    "test": "test"
  },
  "resources": [
    {
      "sourceEntity": {
        "id": "{{efolder_attachment_id}}",      // Allow Lenders to skip upload step for eFolder/eSigned package resources - orchestrate this for them?
        "type": "urn:elli:encompass:attachment"
      }
    }
  ]
}

POST /encompass/v3/loans/:id/serviceOrderResources

[
  {
    "name": "<name of the attachment>", // only needed for local uploads
    "mimeType": "<mimeType>" // only needed for local uploads
  },
  {
    "sourceEntity": {
      "id": "{{efolder_attachment_id}}", // efolder attachment
      "type": "urn:elli:encompass:attachment"
    }
  },
  {
    "sourceEntity": {
      "id": "{{efolder_document_id}}",  // efolder document
      "type": "urn:elli:encompass:document"
    }
  },
  {
    "sourceEntity": {
      "id": "{{esigned_package_id}}", // esigned package
      "type": "urn:elli:edelivery:package"
    }
  },
  {
    "sourceEntity": {
      "id": "{{stacking_template_package_id}}", // eFolder documents exported and organized into a stacking template
      "type": "urn:elli:encompass:stackingtemplate"
    }
  }
]

📘

NOTE

name optional, required for local uploads. mimeType optional, required for local uploads sourceEntity. entityId -- optional, required for eFolder docs attachments and eSigned packages sourceEntity.entityType -- optional, required for eFolder docs/attachments and eSigned packages, must be one of "urn:elli:encompass:document", "urn:elli:encompass:attachment", "urn:elli:edelivery:package"


Did this page help you?