Developer Guides

Service Ordering via Encompass Developer Connect

Suggest Edits

EPC Service Ordering via Developer Connect is an administrator-driven service setup. Web Version of Encompass (previously known as Encompass LO Connect) administrators will need to create a service setup in Encompass Web 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": [
       "LO Connect",
       "Encompass Smart Client",
       "urn:elli:application:developerconnect"
    ],
    ....
  }
  ....
}

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

1154

Services Management setting (Web Version of Encompass)

See the table below for service order-related endpoints:

ActionURLPurpose
POST/encompass/v3/loans/:id/serviceOrdersCreate a service order
GET/encompass/v3/loans/:id/serviceOrders/:idRetrieve status of an existing service order
GET/encompass/v3/loans/:id/serviceOrdersRetrieve status of all service orders on a loan
PATCH/encompass/v3/loans/:id/serviceOrders/:id/requestUpdate an existing service order request (if still possible)
GET/encompass/v3/loans/:id/serviceOrders/:id/response/resourcesGet downloadable URLs (as authorized) for the response attachments
POST/encompass/v3/loans/:id/serviceOrderResourcesStage 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 TypeWebhook Event TypeScenario
urn:elli:encompass:services:order:placedplacedNotify lender when order delivered to partner
urn:elli:encompass:services:order:acknowledgement_receivedacknowledgedNotify lender when order acknowledged by partner
urn:elli:encompass:services:order:fulfilledfulfilledNotify lender when order completed, and response successfully ingested into Encompass
urn:elli:encompass:services:order:preparing:process_failureprocessFailureNotify 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_failureprocessFailureNotify 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_requestedNotify lender when request egress has entered retry (extended periodic retries - loan lock, not API retries)
urn:elli:encompass:services:order:retry_processing_responseNotify lender when response ingress has entered retry (extended periodic retries - loan lock, not API retries)
urn:elli:encompass:services:order:abandonedNotify 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"

Updated over 1 year ago