# Surveywall API

Eligible Placement & AdSlot Combinations

The table below shows all Placement & AdSlot Type combinations that allow you to utilize the Surveywall API integration.

| Placement Type | AdSlot Type    | Eligible Integration Type |
| -------------- | -------------- | ------------------------- |
| Android App    | Surveywall API | Surveywall API            |
| iOS App        | Surveywall API | Surveywall API            |
| Website        | Surveywall API | Surveywall API            |

{% hint style="danger" %}
If you integrate the Surveywall API while using a different Placement & AdSlot combination in the ayeT-Studios dashboard, you won't be able to make correct API requests.
{% endhint %}

## Getting Started

Before you start with the integration, make sure you:

* [x] Created an Account
* [x] Added a Placement
* [x] Added an AdSlot

You will find more details here:

{% content-ref url="/pages/W7CE6bNya8L7RoaXXY21" %}
[Dashboard Setup](/v/product-docs/dashboard-setup.md)
{% endcontent-ref %}

## Technical Surveywall API Documentation <a href="#technical-offerwall-api-documentation" id="technical-offerwall-api-documentation"></a>

For API Calls, all surveys matching the parameters provided will be returned and can be displayed to the user.

The Surveywall API supports both server and client-side calls.

Follow the link below to get to the detailed technical documentation.

{% embed url="<https://www.ayetstudios.com/openapi/publisher-doc#tag/Surveywall-API>" %}

### Passing Profiling Information via the Surveywall API

If you already collect profiling data from your users, you can optionally pass this information to us through the Surveywall API call. While not required, providing profiling details can improve targeting and survey performance.

To enable this feature, open the **Edit Adslot** modal for your Surveywall API adslot in the dashboard and generate a **Profiling Data Validation Hash**.

#### Available Questions and Answers

You can find the complete list of supported profiling questions and acceptable answer formats here:\
👉 [Profiling Questions & Answers](https://docs.google.com/spreadsheets/d/1sO598lcKXQG4wlKJk5ex2hXYnQ2gopea_bp8HhH8RZA/edit?usp=sharing)\
Please check this document regularly for updates.

#### How to Pass Profiling Information

To include profiling data in your API call, append the appropriate question and answer parameters to the request URL. You'll also need to generate a cryptographic hash to validate the data.

For example, to pass the following information:

* **Gender**: Male
* **ZIP Code**: 20500
* **Birthdate**: 1995-05-31

The API call would look like this:

```
https://www.ayetstudios.com/surveys/surveywall_api/{adslotId}?external_identifier={YOUR_USER_IDENTIFIER}&q5=1995-05-31&q6=20500&q7=8&hash=88cd2108b5347d973cf39cdf9053d7dd42704876d8c9a9bd8e2d168259d3ddf7
```

#### Hash Generation

The `hash` parameter is calculated as a SHA256 HMAC, using the **Profiling Data Validation Hash** as the secret key. The input string is a URL-encoded query string of all parameters **except** the `hash` itself, sorted by key.

Here’s a PHP example:

```php
function generateHash($requestParams, $profilingDataValidationHash) {
    // Remove the 'hash' parameter
    unset($requestParams['hash']);

    // Sort parameters by key
    ksort($requestParams);

    // Build query string
    $queryString = http_build_query($requestParams);

    // Calculate HMAC-SHA256 hash
    $expectedHash = hash_hmac('sha256', $queryString, $profilingDataValidationHash);

    return $expectedHash;
}

// Input data
$profilingDataValidationHash = "your-key";
$requestParams = [
    "external_identifier" => "testuser1234",
    "q5" => "1995-05-31",
    "q6" => "20500",
    "q7" => "8"
];

echo "https://www.ayetstudios.com/surveys/surveywall_api/1234?external_identifier=testuser1234&q5=1995-05-31&q6=20500&q7=8&hash=" . generateHash($requestParams, $profilingDataValidationHash);
```

## Conversion Callbacks & Currency Handling <a href="#conversion-callbacks-and-currency-handling" id="conversion-callbacks-and-currency-handling"></a>

Learn about:

* Setting up callbacks
* IP Whitelists
* Securing callbacks using HMAC Security Hash
* Testing callbacks

Click on the link below:

{% content-ref url="/pages/5sxVWIW1fto5Mmv1JxeJ" %}
[Callbacks & Testing](/v/product-docs/callbacks-and-testing.md)
{% endcontent-ref %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.ayetstudios.com/v/product-docs/surveywall/api-integrations/surveywall-api.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.