Calling the Event API

The API allows adding events to the Darwinium engine and enrichment of a journey with data that is otherwise not scrapable using content extractions. Usecases include:

• Adding and risk assessing events when operating not on the Edge (Tags Deployment)
• Receiving the full data associated to a journey or event to make a real-time decision on
• Logins where additional identity data such as the user's first name and last name are not included in a form post
• Payments where beneficiary or sender details are missing or provided as IDs and we wish to perform subsequent risk assessment

The additional context provided as part of journey enrichment may be used by other steps in the journey through the use of import dependencies, and the decisions and additional attributes are available through forensics, if an event is recorded.

1.  In Darwinium Portal, create an API step in your journey

Calls to the Darwinium API are bound to a journey and a given step.
To create an API step, open your journey in Darwinium Portal, click the dropdown next to the "+" button on the journey step overview:

Then configure for the API step:

• Step Name
• Event Type
• (optional) Import dependencies: The data from dependencies will be inherited into the step and response. Used for import precomputed scores and signals.
• (optional) Workflows. Features, Rulesets and Models can be added just like any other step.

Make sure to commit and deploy the changes to the journey.

2. Calling API: To generate an event

Now the API can be called.

a. Authentication: a valid client certificate that has been configured with access to your node. See : Setting up certificates & Access

b. Headers: Input and output is JSON.
Note: If calling the API for enrichment with Darwinium event identifier, it must be specified in the from_identifier Header, not the Body.

• Content-Type = 'application/json'
• Accept = 'application/json'
• from_identifier = '<identifiervalue>'      (optional)

c. Host URL: The API is called using the POST method to your journey step.

<first>-<second>.node.darwinidentity.com/api/<journeyname>/<stepname>

• <first>-<second>: This is the two random words used for your node's subdomain. Can retrieve from Darwinium Portal.
• <journeyname>: This is the journey name specified in configuration of your .journey.yaml file. Note: This could be different to the name of the file.
• <stepname>: This is the step name you gave in 1. (eg. APICall)

d. Body: The post body consists of a JSON hierarchy of the attributes you wish to include. The Darwinium API Helper can assist with the format of this JSON for the attributes you wish to include.
Example:

{
  "identity": {
    "ACCOUNT": {
      "email": {
        "PERSONAL": {
          "email": "<insert value here>"
        }
      }
    }
  }
}

Using the Darwinium API Helper

As a convenience, the Darwinium journey editor provides a means of quickly assembling API calls in the required format. Simply click Help me construct an API call to this step on the Step Summary tab of an API step, and a new tab should appear with your steps details completed. You are then able to select which attribute(s) you wish to input as part of your API call. Boilerplate is then generated with mock values for each input which can then be used by your integration.

Side-by-side view of the API helper (right) and a corresponding API step in a journey (left) 

3. Calling API: With existing  journey_id or identifier

The journey_id or identifier is required if you wish to provide the enrichment or receive data back within context of a journey that was already initiated.

A useful approach is adding the Darwinium identifier and/or journey_id as a header on existing requests to your downstream service within a Darwinium step.

Inserting Darwinium event identifier as a header named dwnidentifier

Inserting Darwinium journey_id as a header named dwnjourneyid. Note the Journey dependency.

 

 Examples

 Example API Code