> For the complete documentation index, see [llms.txt](https://docs.ayetstudios.com/v/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.ayetstudios.com/v/product-docs/surveywall/api-integrations/surveywall-api.md).

# 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 %}