# Universal data connector API

{% hint style="info" %}
Public API credentials This API allows you to send your own segmentation data directly in AB Tasty for its usage in our platform. If you are a partner and want to build a program with AB Tasty, please contact us at <product@abtasty.com>
{% endhint %}

### Introduction

Using our Universal Data Connector API, you will be able to send AB Tasty segmentation data. This data can come from a DMP, a CDP, a CRM, a datawarehouse, a database or a one time file extract. This data can be used to create a custom segment using our targeting engine. This allows the AB Tasty tag to trigger the custom personalization campaigns you have created.

The sent data will be stored for 30 days in our system once received by default.

### Quick Start

Here are the steps:

* get an access with the dedicated role from our Public API (contact the administrator of your AB Tasty account)
* setup the recurring call to our API with the appropriate file format as described below
* that's all, everything else is already in AB Tasty!

### Authentication

Create a user for the public API in your AB Tasty account with at least the "Send and get third party segments" role.

<figure><img src="/files/nMLn5EIrdPv65EZRVxfJ" alt=""><figcaption></figcaption></figure>

This will give you your credentials. Use these credentials each time you want to [authentify to the Public API](/client-side/data-apis/public-api.md#authentication) to get a token.

### Upload segments information

To upload the file containing all segmentation information, use this route:

`POST https://api-data-connector.abtasty.com/accounts/{account_identifier}/segments/{partner_name}`

Curl template:

```bash
curl -v -X POST --data-binary "{file_location}" \
  -H 'Authorization: Bearer {public_api_oauth_token}' \
  -H 'Content-Type: {content_type}' \
  "https://api-data-connector.abtasty.com/accounts/{account_identifier}/segments/{partner_name}"
```

**Requirements**

| Name                      | Requirements | Type   | Description                       | Accepted Values                |
| ------------------------- | ------------ | ------ | --------------------------------- | ------------------------------ |
| file\_location            | \s+          | string | Name of the file to be posted     |                                |
| account\_identifier       | \s+          | string | Identifier of the account         |                                |
| public\_api\_oauth\_token | \s+          | string | Valid public API Oauth token      |                                |
| content\_type             | \s+          | string | Content-type of the uploaded file | text/csv, application/json     |
| partner\_name             | \s+          | string | ID of the account                 | best3rdparty, awesomeTool, ... |

{% hint style="info" %}
The "parter name" can also be your own brand name if you're not getting the segments from a third party. This field is customizable and only serve the purpose of identify a data source for your segments.
{% endhint %}

**File format**

| Name        | Required | Validation Regex                                                           | Type      | Description                                                                                                                              |
| ----------- | -------- | -------------------------------------------------------------------------- | --------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| visitor\_id | true     | (?i)^\[a-z0-9-]{1,32}$                                                     | string    | Visitor ID, as provided by the client                                                                                                    |
| value       | false    | (?i)^(\[\[:alnum:]]\|\[$€£\\\[\\]{}&(§!)\\-\_%=+:/.?<>@#]\|\[À-ÿ]){1,100}$ | string    | Segment value                                                                                                                            |
| segment     | true     | (?i)^(\[\[:alnum:]]\|\[$€£\\\[\\]{}&(§!)\\-\_%=+:/.?<>@#]\|\[À-ÿ]){1,100}$ | string    | Segment name                                                                                                                             |
| expiration  | false    | \d+                                                                        | timestamp | Time at which this segment information will be deleted by ABTasty, default and maximum is 30days. The `-1` value will delete the record. |

Example request:

<pre><code><strong>curl -v -X POST --data-binary "@segments.csv" \
</strong>  -H 'Authorization: Bearer 0MWQ4MjRlMNzY5ODFjODYwNTU2YTBkMThiMjk2NzNlYzNiOAMTJkOTEyZjNhYzQzTE0YzRkM2UyNDk4NWE1MTY' \
  -H 'Content-Type: text/csv' \
  "https://api-data-connector.abtasty.com/accounts/83cb13aabbfc8e879084f3a0bcdcb4f3/segments/partnerName"
</code></pre>

Example segments.csv file content

```
visitor_id;value;segment;expiration
19102009415591439;SEGMENT_1_VALUE_1;SEGMENT_1;1609136172230
j73xvgwb5yz9re9f;SEGMENT_1_VALUE_2;SEGMENT_1;1609136172230
19051217151193693;SEGMENT_2_VALUE_1;SEGMENT_2;1609136172230
```

{% hint style="info" %}
You can also send the content directly in the body of your request.
{% endhint %}

The request will return a 200 json response if successful with a link to a Public API route to check the upload state

Example response

```json
{
    "success":true,
    "state_link":"https//api.abtasty.com/v1/accounts/83cb13aabbfc8e879084f3a0bcdcb4f3/dmp-files/42"
}
```

calling the "state link" requires a valid Public API Oauth token

**Status Codes**

| Status code | Description                                                                                    |
| ----------- | ---------------------------------------------------------------------------------------------- |
| `202`       | Returned when the upload was succesful                                                         |
| `400`       | Returned when the file is empty or invalid                                                     |
| `403`       | Returned when the token is either invalid or doesn't have the proper permissions               |
| `404`       | Returned when the route was malformed (missing required parameter)                             |
| `413`       | Returned when the request is too large, file should be maximum 20 \* 1024 \* 1024 Bytes        |
| `415`       | Returned when the content type is wrong, only application/json and text/csv files are accepted |

### Get a visitor's segment list from the web

To get a specific visitor's segment in JavaScript, you can call the following URL:

```title="calling
https://api-data-connector.abtasty.com/accounts/{identifier}/segments/{visitor_id}
```

It is much more convenient and faster to use.

### Limits

#### Maximum rows of a file

You can send up to 100,000 rows at once, or 20 MB. The same limit applies if you send the data directly in the payload of the request instead of in a file.

#### Maximum concurrent files

You can send as many files as you need, they will be queued up and processed in their order of arrival. This is the best way to work with the 100k rows limit.

#### Time to process a file

A large file, close to the limits, will take minutes to be processed. A smaller file will be processed almost instantly. If your data doesn't show up within 10 minutes, we advise you check your request before trying again.

### Use case with JavaScript

You can build up the connection using native features of AB Tasty: the account JavaScript and a code targeting in each campaign. You will only need two snippets templates:

* the first one, in the [AB Tasty account global code](https://app2.abtasty.com/settings/global-code), makes the call to the API,
* the second, in the campaign code targeting, checks the answer of the API to decide whether the tag should play the campaign or not.

#### Doing the API call

A custom script set in the account global code will be executed at the very beggining of the tag execution as soon as there is at least one live campaign.

We are going to leverage this opportunity to connect to the API (example of code in AB Tasty global code):

```javascript
const url = `https://api-data-connector.abtasty.com/accounts/${window.ABTasty.accountData.accountSettings.identifier}/segments/${localStorage.getItem('ABTastyUDC')}`;

fetch(url, { method: 'GET', mode: 'cors', headers: { Origin: document.location.origin } })
  .then((data) => data.json())
  .then((data) => sessionStorage.setItem('ABTastyUDC', JSON.stringify(data)))
  .catch(() => console.log('Unable to fetch UDC'));
```

This snippet asks the API to match the visitorId sent as parameter to its corresponding segment value. For this example, we assume the visitorId is stored in the localStorage in the `ABTastyUDC` entry.

Adjust this snippet to your needs.

#### Targeting on a segment

For each campaign, you can create a JS code trigger. Create a new trigger or go for a custom one and select "Code". In the scripting area, you can put your targeting code.

Example of code in an AB Tasty campaign's code targeting:

```javascript
return !!sessionStorage.getItem('ABTastyUDC') && JSON.parse(sessionStorage.getItem('ABTastyUDC'))[0].segment === "SEGMENT_1";
```

This snippet looks for the value stored in the sessionStorage that was filled by the previous API call. If the value is equal to `SEGMENT_1`, then the script returns `true` and the campaign will launch.

Adjust this snippet to your needs.


---

# 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.abtasty.com/client-side/data-apis/universal-data-connector.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.