Update API

The Darwinium Update API allows you to update attributes or run workflows against events that have already been processed by Darwinium.

Example Use Cases

1. Run ruleset that can update the event_type after an action completes successfully
   • Example: Change from account_login to account_login_success after successful authentication
2. Enrich an event with additional data that becomes available after processing
   • Example: Update a signup attempt event with the customer token assigned after the account is successfully created
3. Apply labels or run workflows on historical events
   • Example: Add a "challenge_passed" label to device identifier + customer token combination after succeeding a one time passcode stepup

The diagram illustrates a typical use case for the Update API

In this flow, the Update API is called asynchronously after successful signup to:

1. Pass into status attribute success, which will lead to change in event_type in a .rules file. Ensuring features in subsequent events can calculate against successful signups only
2. Add the assigned customer identifier to the risk assessment event. That allows the customer's signup journey to be retrieved for future investigations and in feature computations.

Authentication

The Update API uses the same certificate-based authentication (Mutual TLS) as the Event API.

Creating a Darwinium Update API Step

You create and deploy the Update API Step from your Darwinium journey file.

Important: The Update API step must specify api_name: UPDATE in the journey configuration.

Journey Configuration Example

steps:
  - step_name: outcome
    event_type: misc_other
    api_event:
      trigger:
        api_name: UPDATE

Workflows on Update API Steps:

Rulesets can be attached to an Update API step to perform conditional operations:

• Set Attributes - Modify attribute values based on logic
• Add/Remove Labels - Apply or remove labels conditionally

Calling the Update API

URL Format

https://example-host.node.darwinidentity.com:9443/api/update/<journey>/<step>/<identifier>

URL Parameters:

• example-host: Your node's subdomain (retrieve from Darwinium Portal > Admin > Nodes)
• <journey>: The journey_name specified in your deployed .journey.yaml file
• <step>: The step_name of the Update API step you created in your .journey.yaml file
• <identifier>: Required - The Darwinium identifier from the original event you wish to update

Example URL:

https://random-words.node.darwinidentity.com:9443/api/update/authjourney/outcome/2cb7594d12ec4378ac03be04cad971f0

Headers

Content-Type: application/json
Accept: application/json

Request Body

The Update API accepts the same request body attributes as the Event API.

Important: Any attributes contained in the Update API request payload will replace the value on the event.

Example: Update signup event after successful account creation

Update a signup risk assessment event with the customer identifier (assigned only after successful signup) and change the event type:

{
    "identity": {
        "ACCOUNT":{
            "customer_token":{
                "customer_token": "customer_123456789"
            }
        }
    },
    "custom": {
        "general_purpose": {
            "update_status": "success"
        }
    }
}

Response Body

The response body returns the updated event data in the same format as the Event API response.

Error Responses

Missing identifier (400 Bad Request):

{
  "error": "missing_identifier"
}

Identifier not found (500 Internal Server Error):
Returned when the identifier does not refer to a prior Darwinium event.

Limitations

• Attributes in Update API request body will replace those in the original event
• Workflows are executed to set attributes or apply/remove labels, but not for risk assessments (no model scoring)
• event_type should be set in a .rules file**
• You cannot set event_type to NULL
• The identifier must refer to an existing Darwinium event
• Event data is only available for updates within the standard retention period

Best Practices

Asynchronous Processing

Since the Update API is typically used to update a prior event after additional processing has completed, it is usually called asynchronously from your main application flow. This means:

• Update API calls happen after the user interaction is complete
• Failures in Update API calls should not block your application's primary workflow
• Implement appropriate retry logic upon errors (network failures, timeouts, 5xx responses)
• Consider using a message queue or background job system for reliability

Proactive Success Approach

Assume events represent failed or incomplete attempts unless proactively updated with success.

This pattern provides several benefits:

• Risk assessments reflect worst-case scenarios by default
• If Update API calls fail, events retain their original "attempt" state
• More accurate reporting when systems experience issues
• Easier to identify incomplete workflows

Example:

• Initial Event API: event_type: account_login (status pending)
• Update API: Ruleset set upon success: event_type: account_login_success (status confirmed successful)

If the Update API call fails or never happens, the event remains as an "attempt" which is appropriate for risk analysis.

Full Schema

The full Darwinium API schema is available from:

GET https://example-host.node.darwinidentity.com:9443/api/schema