Integrating with Journeys

Getting Started

Your Alloy Implementations team will configure your desired Journey in the Alloy Dashboard. Once it is set up, you can interact with it via API. We may configure a shell test journey for you so that you can finish integrating before your workflows are entirely finished.

The Sandbox URL: https://sandbox.alloy.co

The Production URL: https://api.alloy.co

You’ll want to make sure that you have configured your webhook in the Alloy dashboard to send out all Journey-related events to your endpoints since the Journey's webhook handles the applicant's state management. To configure the webhook:

  • Navigate to Settings > Webhooks and click "+ Webhook"
  • Under trigger action, select "Notify on live Journey status application change"
  • Fill in the name, endpoint URL, and authentication settings
  • Test the Webhook by clicking the "Test Webhook" button in the bottom left corner
  • When finished, click "Create" to exit and save your changes

Running A Journey Synchronously

Journeys are able to be run synchronously, meaning, rather than waiting for a webhook to pass individual events as they happen, you can get a real-time response to display the application status back to the customer. When you add the sync header to the request body, the application waits for a synchronous response, holding the connection open for up to twenty seconds. Rendering views on the front-end is made easier with synced responses, which can then be the target of a webhook to a listener on the backend, which make updates to your core.

We strongly recommend that you do not drive business rules off of this response, and instead consistently wait for the completed_application webhook event. Waiting for the webhook will allow you to consistently handle manual reviews and real time decisions without additional development.

To enable this functionality, in the header, set alloy-journey-application-sync : true, as demonstrated below.

curl -X POST https://sandbox.alloy.co/v1/journeys/:journey_token/applications \
  -H "Content-Type: application/json" \
  -H “alloy-journey-application-sync: true” \
  -u workflow_token:workflow_secret \
  -d ${
    "entities": [{
        "phone_number": "18042562188",
        "name_first": "John",
        "name_last": "Doe",
        "email_address": "[email protected]",
        "birth_date": "1985-01-23",
        "address_line_1": "1717 E Test St",
        "address_city": "Richmond",
        "address_state": "VA",
        "document_ssn": "123456789",
        "address_postal_code": "23220",
        "address_country_code": "US",
        "iovation_blackbox": "dsif20sJDFSIef89204j - dsfSDIFiwefj083463902t6j",
        "neuro_user_id": "23489 sdf - a942tj8ef - asofwe",
        "site_id": "28 dfa9342",
        "meta": {
            "income": 100000
        }
    }]
}'

Integrating with Journeys

  1. Create and Run an Application Through the Journey

    Make sure that a webhook for notification of journey events has been configured with your desired URL (you can do this in Settings > Webhooks, by selecting the trigger action: notify on journey application status change. Here’s a doc on webhooks.). Expect to receive webhooks in the form of a request to the url you have specified in the webhook configuration. Webhooks are sent for every application event.

    POST to `/journeys/:journey_token/applications`

Authorization is handled by using a workflow_token:workflow_secret pair as HTTP Basic Auth, similar to creating an evaluation. Any valid pair workflow_token and workflow_secret will be considered valid for any Journey in your account.

Find your workflow_token and workflow_secret by navigating to the “Workflow” tab in your Alloy dashboard. Select the relevant workflow, and the keys should be displayed on the left side of the screen.

To make a POST request, you’ll require the :journey_token , the workflow_token and workflow_secret .

The :journey_token can be found on the Journeys page in the Alloy Dashboard (https://app.alloy.co/v3/dashboard/journeys). See below.

10401040

The token can be copied by hovering over it and clicking the clipboard icon.

Streaming" Requests

If you have incomplete information, streaming requests allow you to submit the information you have, and additional information later. (For example, say you are onboarding a business and its beneficial owners through one Journey Application. If you only have one of the two owners’ information, you can add the one you have, and the other at a later time.)

Set do_await_additional_entities to true; this will put the Journey into a state where the application will not enter reconciliation conditions until the stream is over. (e.g. "do_await_additional_entities": false is passed, allowing a stream of multiple entities to be passed through the Journey until the stream ends.

  1. Create a Request to Retrieve Data and Response

    To receive the full evaluation results for an application, make a GET to /journeys/:journeyToken/applications/:journeyApplicationToken , or a POST /journeys/:journey_token/applications, if you are setting the journey to respond synchronously. Include both the Journey application_token and the journey_token in the request.

    Note, if you are using an Underwriting Workflow within your Journey, the final result in the application may include “Top-Level Keys” which are populated from individual evaluation output attributes or matrix models. These keys are set by Alloy to populate important keys near the top of the response body. The pre-defined keys are as follows:

    annual_interest_ratecredit_limitmonthly_payment_amount
    loan_amountline_of_credit_amountamortization_period
    term_length_monthsterm_length_years
  1. Update a Journey

    There can be cases where a later workflow will require more data than an earlier workflow. In this event, send a data_request_evaluation webhook to pause the Evaluation (and Application) until more information is received.

    The webhook notification for the data request event will include several pieces of information to handle the event, including the data._embedded.node.workflow_token which identifies which workflow the data request is from.

    Additionally, data._links.evaluation will refer to the full response from the data request. If you make a GET request to that URL, it will display the precise information needed to advance the application.

    Once you have the new data, you can resume the application by PUTing to the data._links.journey_application path from the webhook response (e.g. /v1/journeys/:journey_token/applications/:application_token) with a new payload.

    This will immediately replace the Evaluation payload with this new incoming payload, and attempt to continue the Application. Note that to use this feature, you must include identifiers.external_entity_id in both requests.