Superwall

This documentation for the Superwall integration describes the technical capabilities of this integration, including authorization, scopes/permissions, and utilized endpoints. For more information on how to integrate Superwall, visit our connection instructions.

Version

This integration utilizes the Superwall Superwall API.

Base URL

The base URL used for all Superwall API endpoints:

https://api.superwall.com

---

Authentication & Authorization

The DataGrail Superwall integration connects using token authentication which requires an Organization API Key and Application ID.

Sensitive Credentials

Publicly exposing your API credentials can allow unauthorized access to Superwall API endpoints by a third party. DataGrail stores your API credentials encrypted and protected.

Scopes

The Superwall integration requires specific scopes that must be granted in order to function for a given capability.

Scope	Base	Access	Deletion
Users Read	✅	✅	✅
Users Write			✅

Base Scopes

All base scopes must be granted in order to connect the integration with DataGrail. The remaining scopes are only required if enabling those capabilities

Endpoints Utilized

DataGrail uses the following endpoints to authorize and test the connection:

Method	Endpoint	Purpose	Docs
GET	/v2/users/filter-properties	Validate the connection is successful and, if Email Properties are configured, that each property exists.

---

Limits

Limits in Superwall are calculated using the leaky bucket algorithm. All requests that are made after rate limits have been exceeded are throttled and an HTTP 429 Too Many Requests error is returned. Requests succeed again after enough requests have emptied out of the bucket.

• DataGrail supports requests throttling to stay within 70-80% of specified service rate limits.
• DataGrail processes API responses with HTTP 429 status to interrupt requests, waiting and retrying (using an exponential backoff strategy).

---

Capabilities

Access

DataGrail's Superwall integration provides Synchronous Access capabilities for the following supported identifier categories: Email and Service ID.

Data Interactions

For Access requests, DataGrail will take the following actions:

1. Query for users whose App User ID matches a Service ID in the request, or whose email properties match an Email in the request. All identifiers are matched in a single query.
2. Return the matching users and their synced attributes.

Multiple Identifiers

The Superwall API matches users whose App User ID matches any provided Service ID, or whose email properties match any provided Email. DataGrail sends all identifiers in a single query.

Email Properties

DataGrail searches the user properties listed in the Email Properties field of the integration, which accepts comma-separated property keys. If the field is empty, DataGrail only searches the email property.

Endpoints Utilized

Method	Endpoint	Purpose	Docs
POST	/v2/users/query	Search for users whose App User ID or configured email properties match the identifiers provided in the request.

---

Deletion

DataGrail's Superwall integration provides Synchronous Deletion capabilities for the following supported identifier categories: Email and Service ID.

Data Interactions

Superwall has no endpoint to erase a user. For Deletion requests, DataGrail will take the following actions:

1. List the attributes set on each user identified during access.
2. Set the value of every attribute to empty, which clears the user's data. The user's App User ID remains in Superwall.

No User Erasure Endpoint

The Superwall API does not offer an endpoint to erase a user. Access requests return the user's synced attributes, and Deletion requests clear those attributes.

Endpoints Utilized

Method	Endpoint	Purpose	Docs
GET	/v3/users/APP_USER_ID/attributes	List the attributes set on the user.
POST	/v3/users/APP_USER_ID/attributes	Clear the user's attributes.

---