×

api-documentation

Welcome to the PerfectLO developer documentation!

From this starting point, you can navigate to the information and instructions you’ll need to complete the integration of your services with the PerfectLO Document Aggregation Service (DAS). We continue to improve our documentation and would like to hear from you about how to make it better. Once you let us know you’re interested, we’ll engage with you directly, so we can answer your questions quickly and offer additional guidance.

PerfectLO exposes a REST API to our partners. We’ve tried to stay true to the principles of REST and most of our resources have a direct correspondence to the objects that users will see in the UI of your application. These resources include things like documents (PDF, Word, text), document sources (Bank of America, Verizon), and document source “connections” which represent the persistent association between a user and their account on a website. Our API documentation describes each of these resources in detail.

There are two other points of integration between your service and ours: our change notification and document delivery services. In contrast to our API, where you call us, these two services make calls back to your service via webhook endpoints that you expose to us.

We suggest you proceed from here to our discussion of Tools that are useful for your development work, and then move on to the PerfectLO API documentation. When you’ve gotten a sense of how our API is structured, return here and we will explain how to set up your partner account.

The PerfectLO Partner Console

A good way to become familiar with how your service connects to and communicates with the PerfectLO service, is to install our Partner Console application. The console is used to configure connections and to monitor logs during the operation of the system. It’s particularly valuable for correlating what you see in your logs with what you see in the console logs. The console is a desktop application and runs on Mac, Windows and Linux platforms. Once you’ve used it to set up your account you can explore how things like document deliveries work. The rest of this section will walk you through this.

First, contact us to obtain your partner account credentials. Then proceed the following instructions:

Change your temporary partner admin account credentials

  1. Log into the PerfectLO web client using the partner credentials we gave you.
  2. Click the little gray down arrow next to the “Hello” text in the upper-left corner of the window.
  3. From the pulldown menu that appears, choose the Profile item.
  4. In the dialog panel that appears, enter your actual email address and click the “OK” button.
  5. Click the little gray down arrow again and select the Security item
    Enter your old and new passwords and click the OK button to confirm.

Download and install the partner console

  1. Download a copy of the console installer.
  2. Launch the installer application
  3. In the dialog that appears, note that the publisher is “Unknown” and there are warnings about the application having unrestricted access. You can safely ignore these. They appear because we have used a self-signed cert to sign this application’s code.
  4. Click the Install button on this dialog.
  5. On the next dialog, choose an installation directory, or accept the default, and click the Continue button.
  6. When the installer completes and quits, the console application will be launched automatically.

Log into the console

  1. After launching the console application, choose the Production item from the Server popup menu in the login dialog.
  2. Enter your partner admin credentials in the username and password fields and then click the “Log In” button.
  3. If the Partner tab is not selected, select it.
  4. Observe that various settings have been pre-set for you. We will describe each of these in more detail later.
User Interactions

One PerfectLO subsystem that will require some work on your part is the service which manages the security questions that user websites pose as our fetching services visit their account websites to look for documents. These user interactions must propagate back to your system (via our change notification system) for your user to answer them in your application. The answers submitted by your users must then be returned to us (via a call to the PerfectLO API). When we receive the user’s answers, our fetchers can proceed with their work.

Some examples of user-interactions:

  • A site asks the user to answer a security question, like “What was the name of your first pet?”
  • A site asks the user to enter a one-time authorization code sent to their mobile phone.
  • Informing the user that they need to go to the website themselves to say they want to “go paperless”.

When PerfectLO needs to alert end-users to some condition, or when it needs to ask them a question, as sometimes arises during when fetching documents, it creates a user-interaction request. As a PerfectLO content delivery partner, or a client app writer, you are responsible for responding to these requests by posing the information or questions to users in your own user interface, obtaining their answer and returning their response to us so that we can complete the operation. An interaction may happen more-or-less synchronously, or may be completed over a period of hours, or even days. The two typical cases are:

  1. The user creates a new connection to an account site, is prompted to enter his credentials and then must answer an initial challenge question. (eg. “What is your mother’s maiden name?”). Since the user is sitting at his computer when these interaction requests are made and responded to, this is a synchronous exchange that is completed in a short period of time.
  2. The PerfectLO fetch servers run automatically (every couple of days, or so) and when we connect to the user’s account site to check for new documents, another challenge question is posed by the site. Since the user is unlikely to still be sitting at his computer, this question is recorded and will remain pending until the user returns to answer it. Clearly, we need to prompt the user to do so. Standard PerfectLO clients are sent an email notification from our service. PerfectLO content delivery partners may want to provide their own end-user notifications. In any case, the user interaction is completed over a longer period of time.

Regardless of how long it takes to complete the user interaction, PerfectLO uses the same mechanisms to store pending requests, notify clients and partners that they need to be responded to, and completes the pending actions (i.e. fetch documents) once the responses are received.

When PerfectLO sends you a user-interaction request, it is not necessary to attach any meaning to what is being asked for or to write any special code to present requests to users. Instead, an interaction request is a self-contained description of what to present to the user and what responses are required. Given the interaction request, which is packaged as JSON, you just need to create and pose a UI form, let users enter information, and return their responses to us in another JSON record.

To illustrate how this works and to serve as a tutorial for writing your own implementation of the user-interaction workflow, we’ve written a sample application as a web app. Open this now to have a look. There are instructions in the client itself, but as a quick overview, here are descriptions of the purpose of each tab panel:

User Interactions Tab

This panel is a functioning implementation of the client side of the user-interaction workflow. It uses canned request data and does not interact with our API, but it parses sample request data, generates a live UI from it, accepts input from a user, and generates the response data that would be sent back when the user clicks the “OK” button in the form.

The variety of request samples will both give you an idea of the kinds of requests you’ll typically see from our servers and provides a range of different UI elements that you’ll be expected to render.

Source Code Tab

This panel shows copies of the actual JavaScript source code used by the previous panel. These are three code snippets that are central to making things work. Your implementation may not be in JavaScript, but you can use these as pseudocode for yours, knowing that they are complete and functional.

The first file, Request Parser, is generic JavaScript with no external dependencies. Given a user-interaction request, it will parse it and invoke abstract methods on a given “generator” instance. This parser is used in two contexts, each with different instances of concrete generator classes. The first use is to generate the GUI. The second is to extract the user-entered values from the GUI and generate the response data.

The second file, Form Generator, is an implementation of the abstract generator used by the request parser. The form generator creates GUI widgets. This generator is written to use the same Sencha ExtJS HTML 5 framework that the fake client itself is written for. It is therefore dependent on that framework’s classes. As pseudocode, though, you ought to be able to make sense of it and be able to map it to whatever UI kit you’re using.

The third file, Response Generator, is another implementation of the abstract generator. When a user clicks the “OK” button on the form, the fake client re-parses the request data using the parser instance but uses a response generator instead of a form generator instance. The response generator, which is also written to work with the ExtJS framework, knows how to extract user-entered values from the GUI widgets and it uses this to generate the required response JSON. Again, you can use this file as pseudocode to guide your own implementation using your UI framework.

JSON Schemas Tab

This panel shows the JSON Schema specifications for our user-interaction request and response data. Once your eyes adjust to the syntax, you can use this as a reference to understand what to expect.