Retargeting Audience Files | Swaarm Help Center

Introduction

As a Mobile Measurement Partner (MMP), Swaarm provides this API for our clients to help their partners efficiently access audience data for retargeting campaigns.

Our API allows you to retrieve lists of device identifiers (advertising IDs), emails, or phone numbers for your approved offers (campaigns). These audience segments are specifically designed to optimize your retargeting efforts by targeting users who have already shown interest in the client's products or services.

At Swaarm, we understand the importance of both campaign performance and user privacy. That's why we provide various identifier types, including SHA-256 hashed options, to accommodate different privacy requirements while maintaining targeting effectiveness. This flexibility allows you to remain compliant with global privacy regulations while maximizing your retargeting campaign success.

API Overview

The Retargeting Audience Files API allows you to access user identifier files for advertising and retargeting purposes. It provides endpoints to list available files and to retrieve specific files by their ID.

Note: The actual domain for API requests will be provided to you by Swaarm. Replace `{domain}` in the endpoint URLs with the domain specific to your account

Authentication

All API requests require an `apiKey` parameter to be included in the URL. Please ask your advertiser for it.

Endpoints

List Available Files

Returns a list of all available retargeting files for a specific offer (campaign). You can get the offer id from your advertiser or from the partner platform.

Endpoint:

GET https://{domain}/retargeting/files

Parameters:

Parameter	Required	Description
apiKey	yes	Your API authentication key
offerId	yes	ID of the offer for which to retrieve files

Example Request:

GET https://feed.hector.swaarm-app.com/retargeting/files?apiKey=a96d7e9c-f65f-438d-b2dc-b31566db6a48&offerId=21

Response Format:


{
  "errorMessage": null,
  "files": [
    {
      "id": "2",
      "idType": "SHA_256_ADVERTISING_ID",
      "name": "Example Hashed Advertising Id File",
      "updatedAt": "2025-04-08T05:52:20.241706944",
      "url": "https://feed.hector.swaarm-app.com/retargeting/file/2"
    },
    {
      "id": "3",
      "idType": "ADVERTISING_ID",
      "name": "Example Advertising Id File",
      "updatedAt": "2025-04-08T05:52:20.519522942",
      "url": "https://feed.hector.swaarm-app.com/retargeting/file/3"
    }
  ]
}

Response Fields:

Field	Description
errorMessage	Error message if any, or null for successful requests
files	Array of file objects
files[].id	Unique identifier of the file
files[].idType	Type of identifiers contained in the file (see ID Types table below)
files[].name	Human-readable name of the file
files[].updatedAt	Timestamp when the file was last updated (ISO 8601 format)
files[].url	URL to download the specific file

Retrieve a Specific File

Retrieves a specific file by its ID.

Endpoint:

GET https://{domain}/retargeting/file/{fileId}

Parameters:

Parameter	Required	Description
fileId	yes	ID of the file to retrieve (path parameter)
apiKey	yes	Your API authentication key

Example Request:

GET https://feed.hector.swaarm-app.com/retargeting/file/2?apiKey=a96d7e9c-f65f-438d-b2dc-b31566db6a48

Response Format:

The response will be the file content in its original format.

ID Types

ID Type	Description
ADVERTISING_ID	Raw advertising IDs (e.g., IDFA, GAID)
SHA_256_ADVERTISING_ID	SHA-256 hashed advertising IDs
EMAIL	Raw email addresses
SHA_256_EMAIL	SHA-256 hashed email addresses
PHONE_NUMBER	Raw phone numbers
SHA_256_PHONE_NUMBER	SHA-256 hashed phone numbers

Error Handling

If an error occurs, the API will return an error message in the `errorMessage` field of the response. For successful requests, this field will be `null`.

The API may return the following error responses:

Error Message	HTTP Status Code	Description
Invalid API Key	401 UNAUTHORIZED	The provided API key is invalid or missing
Offer not found	404 NOT FOUND	The specified offer ID does not exist
Offer not approved for this partner	403 FORBIDDEN	Your account does not have permission to access the specified offer

Example Workflow

Call the `/retargeting/files` endpoint to get a list of available files for your offer.
Choose the file you need based on the `idType` and other metadata.
Use the URL from the file object or construct a request to the `/retargeting/file/{fileId}` endpoint to download the specific file.
Process the downloaded file to extract the audience identifiers.
If working with hashed identifiers, ensure your comparison data is also hashed using SHA-256.
Use the identifier list to create audience segments in your retargeting platform.

Best Practices

Store your API key securely and do not expose it in client-side code.
Cache file listings when appropriate to reduce API calls.
Check the `updatedAt` timestamp to determine if you need to download a new version of a file.
When processing hashed identifiers (SHA-256), ensure your own data is hashed using the same algorithm before matching.
Respect data privacy regulations when using these audience files for retargeting campaigns.
Consider implementing retry logic with backoff for temporary API failures.

Data Privacy Considerations

The API provides both raw and hashed identifiers. When available, use hashed identifiers (SHA-256) to enhance user privacy protection while still enabling effective retargeting. Always ensure your usage of these audience files complies with relevant data privacy regulations such as GDPR, CCPA, and platform-specific requirements from Apple and Google.

Retargeting Campaigns