The information and data accessible via this API contain Proofpoint proprietary, confidential, and/or trade secret information. Sharing or providing the information to another party without Proofpoint's express written consent is prohibited. Please review the updated Terms of Use for Proofpoint APIs. API Terms of Use can be found online at API Terms of Use | Proofpoint US.

Proofpoint provides advanced detection through its Intelligent Cloud Email Security (ICES) products to protect organizations from inbound threats and outbound data loss.

The Proofpoint API provides customers access to Proofpoint security event data and can be used to integrate into your SOC Workflows and other auditing and monitoring measures.

We offer RESTful API endpoints that return JSON objects containing the requested data.

The API enables you to ingest Proofpoint data into your own tools or datastores, where you can visualize and interact with the data.

The most common use cases for which data is consumed outside the Proofpoint Portal include:

• Triage of security events across your SOC workflow applications
• Correlation of important Proofpoint event data with other sources, such as device monitoring, password resets etc.
• Integration of Proofpoint events into internal security dashboards, SIEM/SOAR tooling for effective reporting and alerting
• Automation of security/compliance-wide statistics and presentations to track your team's success

The most common use case is to call the API on a recurring basis (e.g. once per hour or day) to retrieve all new or updated data, and send that data to your desired data tool.

The hostname of the API endpoint will be the same as for the URL of your Proofpoint Portal page:

• For our EU environment, that is https://your-subdomain.tessian-platform.com/...
• For our US environment, that is https://your-subdomain.tessian-app.com/...

The documentation for each endpoint provides an example code snippet showing how to call it, alongside the schemas for the request and response.

Generating an API Token

In order to authenticate and authorize the API request, you must provide a valid API Token.

ℹ️ Note

In order to generate an API Token, the user creating it must be assigned to a role with both "Integrations" and "Security Events" permissions.

A Proofpoint Portal user who has the correct permissions can generate an API Token by navigating to Integrations > Security Integrations > Proofpoint API in the Proofpoint Portal.

⚠️ Warning

The API Token will only ever be shown once; at the time it is generated.

Data Security Best Practice

• Never share your API Token with other people. When generating an API Token, we always recommend creating a separate Token for each use case. This way you can terminate access to specific Tokens at any point without disrupting your existing integrations.
• For permanent integrations, we recommend injecting your API Token into your code via an environment variable. This way, visibility of your Token is limited to applications running within this environment.
• We recommend that you regularly review any Tokens in use and delete any of unknown use. You can see on the Proofpoint Portal when a Token was last used to call the Proofpoint API. This is on the same page where you can generate and delete tokens: Integrations > Security Integrations > Proofpoint API.
• API Token creation and deletion are audited in the Proofpoint Portal's Audit Trail.

Permissions & Lifecycle

An API Token always has the same permissions as the user who created it. Changes to permissions of the the owning user are automatically reflected in the Token's permissions.

If the owning user is deleted, the API Token's access will be revoked automatically. Similarly, if an API Token is deleted from the Proofpoint API Portal page (Integrations > Security Integrations > Proofpoint API), it will no longer be valid and any subsequent API requests will be rejected.

If you prefer, you can create a separate Proofpoint Portal user as a "service" account for access to the API, rather than representing a human. This can then be used as an API-only account, e.g. for Managed Service Providers to access the Proofpoint API. As with any user account, the Tokens created while using that account will allow access to the API until the Token is deleted, the relevant endpoint permissions are revoked from the user's role, or the user is deleted.

Endpoint Permissions

Below are the required Portal Permissions for the given API endpoints:

Calling the API with a Token

On each request, you must send a valid API Token in the Authorization HTTP header, in the format Authorization: API-Token <your-api-token> (where <your-api-token> is the token that you generated via the steps outlined above).

Example: Raw HTTP

GET /api/v1/endpoint HTTP/1.1
Host: you.tessian-platform.com
Authorization: API-Token <your-api-token>

Example: cURL

curl -H "Authorization: API-Token $YOUR_API_TOKEN" https://you.tessian-platform.com/api/v1/endpoint

Example: Python

import requests

response = requests.get(
  "https://you.tessian-platform.com/api/v1/endpoint",
  headers={"Authorization": f"API-Token {api_token}"},
)

Paginated Endpoints

For any endpoint that returns paginated results, you will need to supply a checkpoint to fetch more than the first page of results.

• Paginated endpoints always return a boolean flag that indicates whether there are further pages of results.
  • This is under the additional_results key of the root object.
• Paginated endpoints always return a checkpoint that can be used to retrieve the next page of results.
  • This is under the checkpoint key of the root object.
• The first time a paginated endpoint is called, no checkpoint should be supplied. This will return the first page of results.
• Any subsequent calls must include the last supplied checkpoint as the after_checkpoint URL parameter.
• Once additional_results is false, there are no more results to fetch.

Example

ℹ️ Note

A robust implementation will require error handling and backoff logic in the case of rate limiting.

url = "https://you.tessian-platform.com/api/v1/endpoint"
headers = {"Authorization": f"API-Token {api_token}"}

results = []

# First request
response = requests.get(url, headers=headers).json()
results.extend(response["results"])
checkpoint = response["checkpoint"]
additional_results = response["additional_results"]

# Subsequent requests, if necessary
while additional_results:
    response = requests.get(url, headers=headers, params={"after_checkpoint": checkpoint}).json()
    # The above is broadly equivalent to appending "?after_checkpoint=checkpoint_value" to the URL
    results.extend(response["results"])
    checkpoint = response["checkpoint"]
    additional_results = response["additional_results"]

Timestamps

The timestamp (date & time) of the email follows the ISO 8601 format as Coordinated Universal Time (UTC), using (optional) microsecond precision and a zero-offset: YYYY-MM-DDTHH:MM:SSZ or YYYY-MM-DDTHH:MM:SS.mmmmmmZ. Note that this format uses 24 hour time.

Timestamp Example: 2022-09-07T23:34:28Z.

• For inbound emails, the timestamp describes the actual time that the email was sent.
• For outbound emails, the timestamp describes the time that the user (sender) attempted to send the email.

Return Values

All responses include a JSON object containing the requested data. The structure of the each return type is documented in our OpenAPI Specification. This file documents all requests that can be made to the various endpoints, as well as the expected return types.

Return types for specific requests are documented alongside the requests themselves throughout the endpoints section of this document.

Data Mutability

Data returned by the Proofpoint API is not immutable. Various external factors may cause changes, for example user and admin interactions with Security Events, or extra details being added by Proofpoint's algorithms as more information is available.

Consequently, some datapoints may be returned by the API multiple times as new information is added to them.

If a datapoint returned in a previous API call was updated with new information, the updated datapoint will be returned when calling the API using the most recent checkpoint.

When consuming Proofpoint API data, you should deduplicate returned data based on the id field, keeping only the latest returned version.

ℹ️ Tip

In Splunk, deduplication can be performed using the dedup command.

Old versions of updated datapoints will never be returned from the API, even if you reuse an old checkpoint (or use no checkpoint). At any given point in time, only the most recent version of any datapoint will be returned.

Pagination Limits

For paginated endpoints, you may receive fewer than limit items back (or even zero items), while still receiving additional_results equal to true. Do not rely on counting the number of rows returned in order to determine whether to call the API again; instead, always look at additional_results. Conversely, there may be times when additional_results is true, but then you make a subsequent call and receive back zero rows (and additional_results is false).

Rate Limits

Rate limiting is enforced for the Proofpoint API API. If you receive HTTP status code 429 "Too Many Requests", give the API a break and try again in a few seconds. You may inspect the response headers for details; these broadly follow this draft RFC. Exact rate limits are subject to change.

Future Changes

We reserve the right to make unannounced non-breaking changes to existing endpoints, such as:

• adding new optional request parameters
• adding additional attributes to responses
• adding new values to enum types

Any breaking changes will be communicated in advance. This may include (but is not limited to):

• changing required request parameters
• modifying response types in a backwards-incompatible manner
• deprecating and/or removing old endpoints

If you have any questions at any time we are here to support you. Please contact Proofpoint at: tessian-support@proofpoint.com.

Endpoints in this section provide granular access to security events across Proofpoint products.

Groups are named collections of email addresses; their members may be specified either by specific address, or by a wildcard including all addresses in an entire domain. You can retrieve information about the Groups Proofpoint, create, modify or delete them.

Endpoints in this section provide ways to monitor user deployment health and information. You will be able to monitor deployment statuses, and various aspects of Proofpoint's coverage within your organization.

Endpoints in this section detail anomalous user activity that has been detected by the system, where anomalous activity is defined as users sending unusual numbers of sensitive emails to unauthorized addresses compared to their normal behaviour.

Endpoints in this section allow you to remediate security events.

These endpoints provide access to audit information of usage and changes made to your Proofpoint products and settings.

Endpoints in this section provide aggregated risk drivers, which are the underlying components for the Proofpoint combined Risk Score.