Transaction Response Attachments

For most services, fulfilling a service order request usually involves responding with a file attachment that gets uploaded to the source loan file for the lender to view. For example, processing a flood zone determination, in addition to providing certain loan data, usually involves generating a flood report document, that needs to make it back to the lender.

The Encompass application suite natively supports two different types of loan attachments:

eFolder attachments

These attachments are organized in document folders and are accessible from the eFolder in Encompass desktop, or the Documents section in the Web Version of Encompass. The eFolder supports a limited number of human readable file formats, including .pdf, .jpg, .docx, and .txt.

Loan Folder attachments

File formats that are not supported by the eFolder can be attached to the loan as a Loan Folder attachment. Examples include .json and .xml documents. These files are not viewable in Encompass (web and desktop versions) - but Lenders can easily access these attachments either via the partner applications user-interface (by utilizing the JavaScript API's application.open and application.openModal methods), or via the Developer Connect APIs.

When a Partner sends a file attachment with its transaction response, EPC will attach it to the loan as an eFolder attachment, if the file type is supported by the eFolder. If the file type is not supported by the eFolder, EPC will attach it to the loan as a loan folder attachment. Attaching files to a transaction response is a three step process.

Step 1: Create a streaming URL for each file you plan to attach:

To create a streaming URL, make a POST call to the https://api.elliemae.com/partner/v2/transactions/{{transaction_id}}/response/resources endpoint. In the body of the call, specify the name and MIME type of each file as below.

[
    {
        "name": "TestPDF.pdf",
        "mimeType": "application/pdf"
    }
]

You will receive a 201 Created response if the request is successful:

[
    {
        "id": "{{string}}",
        "name": "TestPDF.pdf",
        "mimeType": "application/pdf",
        "url": "{{streaming_url}}",
        "authorizationHeader": "{{streaming_auth_header}}"
    }
]

Step 2: Upload each file by making a PUT call to the the generated streaming URL:

PUT the file as binary content to the URL generated for the resource above, passing the returned authorizationHeader in the Authorization request header

📘

The Content-Type header should supply a MIME type that matches the file extension, as well as the mimeType provided when generating the streaming URL in Step 1, for the file to be viewable inside an Encompass application without any issues.

PUT {{streaming_url}} 
Content-Type: application/pdf
Authorization: {{authorizationHeader}}
 
<--binary file contents-->

❗️

File Size Limit

The maximum file size that can be streamed to the EPC platform is limited to 200 MB. If you're application requires sending back file attachments larger than this size, please reach out to the EPC Support Team.

If the call is successful, you will receive a 204 No Content response code.

Step 3: Attach the newly-created resource to a transaction response

To associate the file attachment you just uploaded to a transaction response, you need to reference the file in your transaction responses $.resources array when making a PATCH call to the https://api.elliemae.com/partner/v2/transactions/:id/response endpoint, upon fulfilling a transaction request.

📘

If you don't attach a file that has you've uploaded to the EPC platform to a transaction response, that file will become orphaned and will not be attached to any loan.

{
    "status": "completed",
    ...
    "resources": [
      {
        "id": "{{string}}",
        "name": "TestPDF.pdf",
        "mimeType": "application/pdf"
      }
    ]
}

If the call is successful, you will receive a 200 Ok response.

🚧

File Access Time Period

Files uploaded to the EPC platform and attached to a transaction response will be accessible to Partners and Lenders for 7 years, before they are archived.

If all goes well, and the response attachments you sent as part of your response are successfully updated to the source loans eFolder/Loan Folder, you will receive a success callback event from the EPC platform, indicating that your response has been successfully processed:

First, a webhook is delivered to your application, indicating there is a new transaction event that has occurred for the subject transaction:

{
  "eventTime" : "2020-05-02T11:08:52Z",
  "eventType" : "created",
  "ingressTime" : "2020-05-02T11:08:53.258Z",
  "meta" : {
    "resourceType" : "urn:elli:epc:transaction:event",
    "resourceId" : "{{TRANSACTION_EVENT_ID}}",
    "instanceId" : "{{PRODUCT_NAME}}",
    "resourceRef" : "https://api.elliemae.com/partner/v2/transactions/{{TRANSACTION_ID}}/events/{{TRANSACTION_EVENT_ID}}"
  }
}

Second, when you callback into the transaction event URL and retrieve the transaction event, you should see urn:elli:epc:transaction:response:processed as the event type, indicating successful processing of your transaction responses data and file attachments:

{
    "text": "Transaction response successfully processed",
    "type": "urn:elli:epc:transaction:response:processed",
    "from": "System",
    "comments": "Transaction response successfully processed"
}

Common Error Scenarios:

Step 1: While Creating a Streaming URL

File name does not exist in payload or it is empty

{
  "errors": [
    {
      "code": "EPC-1329",
      "description": "Resource name required",
      "type": "system",
      "resourceId": "TRANSACTION"
    }
  ]
}

MIME type does not exist in payload or it is empty

{
  "errors": [
    {
      "code": "EPC-1331",
      "description": "Mime type is either missing or invalid",
      "type": "system",
      "resourceId": "TRANSACTION"
    }
  ]
}

Invalid MIME type provided in the request payload

{
  "errors": [
    {
      "code": "EPC-1999",
      "description": "Invalid data for parameter(s) 'mimeType' 
      (value must be one of [text/plain, application/xml, application/json, image/jpeg, 
       image/png, image/bmp, image/gif, application/msword, 
       application/vnd.openxmlformats-officedocument.wordprocessingml.document, 
       text/html, application/vnd.ms-xpsdocument, application/emf, application/zip, 
       application/pdf, text/csv]).",
    "type": "system",
    "resourceId": "TRANSACTION"
    }
	]
}

File extension does not match the MIME type provided

{
  "errors": [
    {
      "code": "EPC-1040",
      "description": "Resource name does not end with correct extension",
      "type": "system",
      "resourceId": "TRANSACTION"
    }
  ]
}

File name does not have file extension

{
  "errors": [
    {
      "code": "EPC-1041",
      "description": "Invalid resource name",
      "type": "system",
      "resourceId": "TRANSACTION"
    }
  ]
}

Step 2: While Uploading to Streaming URL

No file/binary content passed

{
    "code": "SKYDRIVESTREAM-1009",
    "summary": "Bad Request",
    "details": "Invalid data for parameter(s) 'stream' (stream is empty)"
}

Multiple uploads to the same streaming URL

{
    "code": "SKYDRIVESTREAM-3002",
    "summary": "Conflict",
    "details": "Object '17cd75dc-91c1-4067-bbda-7ce88e08b807' is already uploaded"
}

Content-Type provided in header does not match the MIME type provided when creating the resource in Step 1, or Content-Type does not match the file content type provided as binary content in the request body

{
    "code": "SKYDRIVESTREAM-1022",
    "summary": "Unsupported Media Type",
    "details": "Entity 'File' only supports requests of content type 'application/pdf'."
}

Step 3: While Sending Attachment In Transaction Response

Resource ID does not exist or it is empty

{
  "errors": [
    {
      "code": "EPC-1039",
      "description": "Resource id required",
      "type": "system",
      "fieldId": "resources",
      "resourceId": "TRANSACTION"
    }
  ]
}

Name does not exist or it is empty

{
  "errors": [
    {
      "code": "EPC-1329",
      "description": "Resource name required",
      "type": "system",
      "fieldId": "resources",
      "resourceId": "TRANSACTION"
    }
  ]
}

MIME Type does not exist or it is empty

{
  "errors": [
    {
      "code": "EPC-1331",
      "description": "Mime type is either missing or invalid",
      "type": "system",
      "fieldId": "resources",
      "resourceId": "TRANSACTION"
    }
  ]
}

Invalid MIME type provided in the request payload

{
  "errors": [
    {
      "code": "EPC-1999",
      "description": "Invalid data for parameter(s) 'mimeType' 
      (value must be one of [text/plain, application/xml, application/json,
       mage/jpeg, image/png, image/bmp,image/gif, application/msword, 
       application/vnd.openxmlformats-officedocument.wordprocessingml.document, 
       text/html, application/vnd.ms-xpsdocument, application/emf, application/zip, 
       application/pdf, text/csv]).",
    "type": "system",
    "resourceId": "TRANSACTION"
    }
  ] 
}

File extension does not match the MIME type provided

{
  "errors": [
    {
      "code": "EPC-1040",
      "description": "Resource name does not end with correct extension",
      "type": "system",
      "fieldId": "resources",
      "resourceId": "TRANSACTION"
    }
  ]
}

The same resource already exists in the transaction response

{
  "errors": [
    {
      "code": "EPC-1044",
      "description": "Resource id <id passed in payload> already exists on the transaction",
      "type": "system",
      "resourceId": "TRANSACTION"
    }
  ]
}

Resource MIME type provided in Step 3 doesn't match the MIME type provided in Step 1

{
  "errors": [
    {
      "code": "EPC-1040",
      "description": "Resource name does not end with correct extension",
      "type": "system",
      "fieldId": "resources",
      "resourceId": "TRANSACTION"
    }
  ]
}

Resource name provided in Step 3 does not match the resource name provided in Step 1

{
  "errors": [
    {
      "code": "EPC-1040",
      "description": "Resource name does not end with correct extension",
      "type": "system",
      "fieldId": "resources",
      "resourceId": "TRANSACTION"
    }
  ]
}

Incorrect resource ID provided and is different than what was generated in Step 1

{
  "errors": [
    {
      "code": "EPC-1333",
      "description": "Resource id <id passed in payload> does not exist on SkyDrive",
      "type": "system",
      "resourceId": "TRANSACTION"
    }
  ]
}