Activity Lookup

Contents

  1. Overview
  2. Getting started
  3. Best practices
  4. Authentication
  5. Query activity data

Overview

Traverse Activity Lookup allows marketers to lookup when hashes were last active on our network.

Getting started

To get started with Traverse Activity Lookups:

  1. Review the best practices.
  2. Get credentials.
  3. Query activity data.

Authentication

All API calls are authorized via OAuth 2.0 bearer tokens.

Please contact us for a token.

Call our HTTPS endpoint and provide this token through the authorization header with the value: bearer AUTH_TOKEN.

Note: The token can also be provided through the a URL GET prameter named, authToken. This is strongly discouraged, please use the authentication header if possible.

Best Practices

While we make every attempt to maintain the availability of our system, unexpected errors may occur:

  1. Always check whether the HTTP status code is 2xx (success) before proceeding, and abort if not.
  2. If the status code is 4xx (client error), your request is likely invalid. Review the documentation before retrying.
  3. If the status code is 5xx (server error), there is likely a problem on our end. Please retry after 60 seconds.
  4. Otherwise, treat any unexpected response, status code, timeout or exception as a 5xx.
  5. Log your requests and replies, and monitor for and review any failures.

Query activity data

Parameters

Parameter Description Required
clientId Your provided 36-character client ID (includes hyphens) Yes
authToken Your provided authentication token Yes
emailMd5Lower An MD5 hash of a lowercased email address No*
emailSha1Lower A SHA-1 hash of a lowercased email address No*
start ISO-8601 format timestamp. How far back is the oldest that we should look? 3 Months is default No

*Note: One of emailMd5Lower or emailSha1Lower are required so we can look it up. If both are provided, we return the timestamp of the first one that we saw.

API Request

Create a HTTP GET request of our activity endpoint with parameters supplied through url parameters. Example request:

curl -H "authorization: bearer $authToken" "https://api.traversedlp.com/activity/v1/lookup?clientId=$clientId&emailMd5Lower=f3ada405ce890b6f8204094deb12d8a8"

API Response

The response will be in a JSON list of objects containing timestamps. If the list is empty, we did not find the timestamp. If the list has one object, that is the most recent ISO-8601 timestamp that we found.

Example response if we found activity:

[{"timestamp": "2017-05-17T17:23:44.682Z"}]

Example response if we found no activity:

[]