Introduction

Welcome to the Found.ee API Reference! You can use our API to access Found.ee API endpoints.

We have language bindings in Shell (cURL)! You can view code examples in the dark area to the right.

Authentication

To make requests to the Found.ee API, create a Found.ee user account with email and password. After successful login API returns access and refresh tokens. An access token is required in the header of every Found.ee API request. Found.ee access token is a JSON Web Token (JWT). Any request requiring authenticated access must contain Authorization: Bearer ${accessToken} header, where ${accessToken} is a value returned by Login or Refresh Token APIs.

Logins a user with email and password and returns token and account information.

curl -X POST "https://api.found.ee/auth/login" \
  -H "Content-Type: application/json" \
  -d '{ "email": "user@mail.com", "password": "secret" }'

{
  "token": "eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJvbGVnQHRoZWZvdW5kZ3JvdXAuY29tIiwiaWQiOjI0ODkyLCJyb2xlIjoiUk9MRV9VU0VSIiwicGF5bWVudFR5cGUiOiJVU0VSX1BBWU1FTlRfUFJFX1BBSUQiLCJwZXJtaXNzaW9uIjoiT1dORVIiLCJ1c2VyRmVhdHVyZXMiOlt7Im5hbWUiOiJQVUJMSUNfTUVUUklDUyIsInByb3BzIjp7fX1dLCJleHAiOjE2MjE2MDMzNzB9.ZQMGBo-3g_qE3UtVPcMWUm3UJZrlfH6aYFmmSDyqT2iPw-a3gKp3paKaNHOZaV-gRh8uf8yco3f4CNcgdRQIOg",
  "expires": 3600,
  "refreshToken": "27fe32a2-bu1c-bae8-c0ce-0e51ebebd06f",
  "permission": "OWNER",
  "data": {
    "name": "John",
    "email": "user@mail.com",
    "role": "ROLE_USER",
    "paymentType": "USER_PAYMENT_PRE_PAID",
    "gdprAccepted": true
  },
  "status": 0,
  "message": "Ok"
}

HTTP Request

POST https://api.found.ee/auth/login

Request Body

Field	Optional	Default value	Description
email	false		Email of the registered user
password	false		User's password

Response Body

If success, Returns the Login response, otherwise, returns error code.

Refresh token

Returns new access token and new refresh token.

curl -X POST "https://api.found.ee/auth/refreshToken" \
  -H "Content-Type: application/json" \
  -d '{ "refreshToken": "your_refresh_token" }'

{
  "token": "eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJvbGVnQHRoZWZvdW5kZ3JvdXAuY29tIiwiaWQiOjI0ODkyLCJyb2xlIjoiUk9MRV9VU0VSIiwicGF5bWVudFR5cGUiOiJVU0VSX1BBWU1FTlRfUFJFX1BBSUQiLCJwZXJtaXNzaW9uIjoiT1dORVIiLCJ1c2VyRmVhdHVyZXMiOlt7Im5hbWUiOiJQVUJMSUNfTUVUUklDUyIsInByb3BzIjp7fX1dLCJleHAiOjE2MjE2MDMzNzB9.ZQMGBo-3g_qE3UtVPcMWUm3UJZrlfH6aYFmmSDyqT2iPw-a3gKp3paKaNHOZaV-gRh8uf8yco3f4CNcgdRQIOg",
  "expires": 3600,
  "refreshToken": "27fe32a2-bu1c-bae8-c0ce-0e51ebebd06f",
  "permission": "OWNER",
  "status": 0,
  "message": "Ok"
}

HTTP Request

POST https://api.found.ee/auth/refreshToken

Request Body

Field	Optional	Default value	Description
refreshToken	false		Refresh token

Response Body

If success, Returns the Login response, otherwise, returns error code.

Logs user into a desired Found.ee website's page in the browser. The URL should be used in the browser.

curl -X GET "https://found.ee/super/signin?keySwitch=onetimeaccesscode&next=/pages/123"

HTTP Request

GET https://found.ee/super/signin

Query parameters

Field	Optional	Default value	Description
keySwitch	false		Onetime access code. See Generate onetime access code on how to generate it.
next	true		An optional relative page URL in the Found.ee website. For example, if the user wants to be logged into https://found.ee/super/pages/123, then the relatvie path would be `/pages/123`.

Response

If success logs user into the specified next URL or dashboard otherwise. If error a page not found page is displayed.

Generate onetime access code

Generates a requested user's onetime access code which can be used to log a user by it via the Login by onetime access code.

curl -X POST "https://api.found.ee/auth/api/permissions/123/token" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <your_access_token>" \

{
  "token": "f8730f89-c508-4e16-9c7b-f6e8640bd2e7",
  "status": 0,
  "message": "Ok"
}

HTTP Request

POST https://api.found.ee/auth/api/permissions/{userId}/token

Path parameters

Field	Optional	Default value	Description
userId	false		ID of the user for which the onetime access code will be generated

Response Body

If success, returns the Onetime access code model, otherwise, returns error code.

Onetime access code response

Field	Type	Description
token	String	Generated access code

Login response object contains tokens that are used to authenticate a user in Found.ee requests and basic account information.

Field	Type	Description
token	String	Access token used for authenticating requests
expires	Long	Access token TTL in seconds
refreshToken	String	Refresh token used to obtain new access tokens. It is valid for 7 days
permission	String	Permission granted to access the account
data	Account information	Basic information about the authenticated user

Account information

Field	Type	Description
name	String	Name of the user
email	String	Emails of the user
role	String	User role
paymentType	String	Payment type
gdprAccepted	Boolean	Flag indicating whether user accepted Found.ee Privacy Policy or not.

Refresh token response

Refresh token response object contains tokens that are used to authenticate a user in Found.ee requests.

Field	Type	Description
token	String	Access token used for authenticating requests
expires	Long	Access token TTL in seconds
refreshToken	String	Refresh token used to obtain new access tokens. It is valid for 7 days
permission	String	Permission granted to access the account

User accounts management

Create user

Creates a new user without email confirmation.

curl -X POST "https://api.found.ee/auth/api/users/registerSimple" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <your_access_token>" \  
  -d '{ "name": "John", "email": "user@mail.com", "password": "secret" }'

{
  "data": {
    "id": 10,
    "name": "John",
    "email": "user@mail.com",
    "role": "ROLE_USER",
    "paymentType": "USER_PAYMENT_PRE_PAID",
    "regDate": "2021-05-24T19:05:17.859",
    "updateDate": "2021-05-24T19:05:17.859",
    "status": "ACTIVE",
    "gdprAccepted": true
  },
  "status": 0,
  "message": "Ok"
}

HTTP Request

POST https://api.found.ee/auth/api/users/registerSimple

Request Body

Field	Optional	Default value	Description
name	true		Name of the registered user
email	true		Email of the registered user
password	true		User's password
showPermission	true	true	Whether to show the created Admin permission to the created user or not

Response Body

If success, returns the User model, otherwise, returns error code.

Switch into user account

Switches into the specified user account which user has access to.

curl -X POST "https://api.found.ee/auth/api/permissions/switch" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <your_access_token>" \  
  -d '{ "userId": 123 }'

{
  "token": "eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJvbGVnQHRoZWZvdW5kZ3JvdXAuY29tIiwiaWQiOjI0ODkyLCJyb2xlIjoiUk9MRV9VU0VSIiwicGF5bWVudFR5cGUiOiJVU0VSX1BBWU1FTlRfUFJFX1BBSUQiLCJwZXJtaXNzaW9uIjoiT1dORVIiLCJ1c2VyRmVhdHVyZXMiOlt7Im5hbWUiOiJQVUJMSUNfTUVUUklDUyIsInByb3BzIjp7fX1dLCJleHAiOjE2MjE2MDMzNzB9.ZQMGBo-3g_qE3UtVPcMWUm3UJZrlfH6aYFmmSDyqT2iPw-a3gKp3paKaNHOZaV-gRh8uf8yco3f4CNcgdRQIOg",
  "expires": 3600,
  "refreshToken": "27fe32a2-bu1c-bae8-c0ce-0e51ebebd06f",
  "permission": "ADMIN",
  "data": {
    "name": "John",
    "email": "user@mail.com",
    "role": "ROLE_USER",
    "paymentType": "USER_PAYMENT_PRE_PAID",
    "gdprAccepted": true
  },
  "status": 0,
  "message": "Ok"
}

HTTP Request

POST https://api.found.ee/auth/api/permissions/switch

Request Body

Field	Optional	Default value	Description
userId	false		ID of the user

Response Body

If success, returns the Switch user model, otherwise, returns error code.

Switch user response

Switch user response object contains tokens that are used to authenticate a user in Found.ee requests and basic account information.

Field	Type	Description
token	String	Access token used for authenticating requests
expires	Long	Access token TTL in seconds
refreshToken	String	Refresh token used to obtain new access tokens. It is valid for 7 days
permission	String	Permission granted to access the account
data	Account information	Basic information about the authenticated user

Grant access to user's account

Grants specified access to the access token owner to the specified user account .

curl -X POST "https://api.found.ee/auth/api/permissions/create" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <your_access_token>" \  
  -d '{ "onUserId": 123, "toUserEmail": "userEmailWhoYouAreGoingToGrantAccessTo@mail.com", "type": "ADMIN", "show": true }'

{
  "data":
  {
    "id": 112233,
    "type": "ADMIN",
    "user":
    {
      "id": 321,
      "name": "Firstname Lastname",
      "email": "userEmailWhoYouAreGoingToGrantAccessTo@mail.com"
    }
  },
  "status": 0,
  "message": "Ok"
}

HTTP Request

POST https://api.found.ee/auth/api/permissions/create

Request Body

Field	Optional	Default value	Description
onUserId	true		ID of the user to which account's the access is being granted
toUserEmail	false		Email of the user to which the `onUserId` (or current user if no `onUserId` value is present) access is shared with
type	false		Type of granted permission
show	true	true	Flag indicating whether permission should be internal, as a result, hidden from showing to end-user

Response Body

If success, returns the Grant access to my account model, otherwise, returns error code.

Grant access to an account response

Field	Type	Description
data	Permission information	Permission information

Attach existing Found.ee user to a partner

Performs the "attaching" to the target user to the current user's partner.

curl -X POST "https://api.found.ee/auth/api/partner/attach" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <your_access_token>" \  
  -d '{ "userId": 123 }'

{
  "status": 0,
  "message": "Ok"
}

HTTP Request

POST https://api.found.ee/auth/api/partner/attach

Request Body

Field	Optional	Default value	Description
userId	false		ID of the user to attach to the partner of the current user.

Response Body

If success, returns the success reponse, otherwise returns error response.

Permission information

Field	Type	Description
id	Long	Name of the user
type	Permission type	Permission type
user	Permissions user information	User information

Permissions user information

Field	Type	Description
id	Long	Found.ee ID of the user
name	String	Name of the user
email	String	Email of the user

Permission type

Allowed values: READ, WRITE, ADMIN.

Account information

Field	Type	Description
name	String	Name of the user
email	String	Emails of the user
role	String	User role
paymentType	String	Payment type
gdprAccepted	Boolean	Flag indicating whether user accepted Found.ee Privacy Policy or not.

User information

Field	Type	Description
id	Long	Found.ee ID of the user
name	String	Name of the user
email	String	Emails of the user
role	String	User role
regDate	String	Registration date formatted according to ISO-8601 standard
updateDate	String	Last update date formatted according to ISO-8601 standard
paymentType	String	Payment type
status	User status	User status
gdprAccepted	Boolean	Flag indicating whether user accepted Found.ee Privacy Policy or not.

User status

Allowed values: ACTIVE, INACTIVE.

Attach an existing Found.ee user to a partner

Assign a partner and enable a pre-configured subscription of the access token owner to the specified user account.

curl -X POST "https://api.found.ee/auth/api/partner/attach" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <your_access_token>" \  
  -d '{ "userId": 123 }'

{
  "status": 0,
  "message": "Ok"
}

HTTP Request

POST https://api.found.ee/auth/api/partner/attach

Request Body

Field	Optional	Default value	Description
userId	false		ID of the user to which account's partner is assigned, and account's subscription is enabled.

Response Body

If success, Returns ok message, otherwise, returns error code.

Detach an existing Found.ee user from a partner

Detach a partner from requested user and disable a pre-configured subscription of the access token owner to the specified user account.

curl -X POST "https://api.found.ee/auth/api/partner/detach" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <your_access_token>" \  
  -d '{ "userId": 123 }'

{
  "status": 0,
  "message": "Ok"
}

HTTP Request

POST https://api.found.ee/auth/api/partner/detach

Request Body

Field	Optional	Default value	Description
userId	false		ID of the user from which a partner is removed and subscription is disabled.

Response Body

If successful, it returns 'ok' message. Otherwise, it returns an error code.

Fetch logged in user's full profile

Fetches the profile information of the currently logged in user.

curl -X POST "https://api.found.ee/auth/api/account/full" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <your_access_token>" \

{
  "data": {
    "id": 123456,
    "name": "John",
    "email": "user@mail.com",
    "role": "ROLE_USER",
    "paymentType": "USER_PAYMENT_PRE_PAID",
    "gdprAccepted": true
  },
  "status": 0,
  "message": "Ok"
}

HTTP Request

POST https://api.found.ee/auth/api/account/full

Response Body

If success, returns the Full account information model, otherwise, returns error code.

Full account information response

If success, returns the Full account information model, otherwise, returns error code.

Full account information response

Field	Type	Description
data	Full account information	Full account information

Full account information

Field	Type	Description
id	Int	ID of the user
name	String	Name of the user
email	String	Emails of the user
role	String	User role
paymentType	String	Payment type
gdprAccepted	Boolean	Flag indicating whether user accepted Found.ee Privacy Policy or not.

User subscriptions management

Subscriptions supported for management via API

List current user's subscriptions

Get the list of current subscriptions for the user.

curl -X POST "https://api.found.ee/feature/api/user/features" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <your_access_token>"

{
  "data":
  [
    {
      "name": "BASIC_PREMIUM",
      "startDate": "2023-06-12T03:43:11.369",
      "endDate": "2023-07-12T03:43:11.369",
      "canceled": false,
      "type": "SUBSCRIPTION_PLAN"
    }
  ],
  "status": 0,
  "message": "Ok"
}

HTTP Request

POST https://api.found.ee/feature/api/user/features

Response Body

Returns array of User subscription information objects, otherwise, returns error code.

Cancel existing user's subscription

Cancels existing subscription for the user. Only subscriptions available for management via Found.ee API can be canceled.

curl -X POST "https://api.found.ee/feature/api/user/features/disable" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <your_access_token>" \  
  -d '{ "featureId": 1 }'

{
  "status": 0,
  "message": "Ok"
}

HTTP Request

POST https://api.found.ee/feature/api/user/features/disable

Request Body

Field	Optional	Default value	Description
featureId	false		The Found.ee ID of the subscription to cancel

Response Body

If success, returns the standard response body with status and message fields, otherwise, returns error code.

User subscription information

Field	Type	Description
name	string	Subscription code in the Found.ee system.
startDate	datetime	Start date of the current paid period.
endDate	datetime	End date of the current paid period.
canceled	boolean	Whether current subscription has been canceled by the user until the end of the current paid period.
type	string	Subscription type. One of `SUBSCRIPTION_PLAN`/`OTHER`.

Page Service

Found.ee lets you create a page to promote your album/single release. There are three types of Pages available for creation:

Pages for the already released albums/singles.
Pre-save pages. The pages for the not released albums/singles. With the ability for your fans to pre-save the object on Spotify/Apple Music/Deezer/Amazon Music/TIDAL.
Timed release pages. The music is not released yet, ut you want to create your link ahead of time, so it’s ready on release date. On release date, the link converts to post release link and all marked retailers are scanned.

Supported retailers

NOTE: this list is a subject to changes.

AMAZON_API_DIGITAL is not supported anymore. Please use AMAZON_API_GEO_MUSIC or AMAZON_API_STORE instead.

Short code generation rules

If you want to update the short code of existing page, please use Page Update

How to pass multiple artists information for page generation APIs.

This applies to the following APIs:

Pages
Pre-save pages
Timed release pages

If the album/release is a collaboration of multiple artists, then it is possible to pass multiple artists to the API joined in 1 string. In all instances of use of artisName and albumName, it is recommended passing just one artist, as the prioritized artist sent to DSP's even if the album/release is a collaboration of multiple artists.

Also artist name field is used as a header of the page and is used as a part of the page URL. See Short Code Generation Rules for more details.

Create a regular Page

curl -X POST "https://api.found.ee/link/api/page"
  -H "Authorization: Bearer token"
  -H "Content-Type: application/json"
  -d '{"upc": "8713092815750", "artistName": "Ray Smith", "albumName": "Ga met me mee", "retailersToUse": ["SPOTIFY", "DEEZER_GEO", "PANDORA"]}'

{
"data": {
        "id": 54612,
        "domainId": 14,
        "domain": "found.ee",
        "shortCode": "raysmith_gametmemee-4",
        "shortFull": "https://found.ee/raysmith_gametmemee-4",
        "created": "2021-02-01T02:29:47.836",
        "clicks": 0,
        "uniqueClicks": 0,
        "parentId": null,
        "countryCode": null,
        "header": "Ray Smith",
        "desc": "Ga met me mee",
        "retailersInfo": [
            {
                "retailerId": 2,
                "retailerName": "Spotify",
                "defaultAction": "Listen",
                "dest": {
                    "shortenDestUrl": "https://found.ee/raysmith_gametmemee-4/ms-spotify-3",
                    "destinationUrl": "https://open.spotify.com/album/1ZZo88VHUb77T5fPOcW6a2",
                    "type": "URL"
                },
                "order": 3,
                "callToAction": null
            },
            {
                "retailerId": 9,
                "retailerName": "Deezer",
                "defaultAction": "Listen",
                "dest": {
                    "shortenDestUrl": "https://found.ee/raysmith_gametmemee-4/ms-deezer-4",
                    "destinationUrl": "https://deezer.com/us/album/152401732",
                    "type": "URL"
                },
                "order": 4,
                "callToAction": null
            },
            {
                "retailerId": 6,
                "retailerName": "Pandora",
                "defaultAction": "Listen",
                "dest": {
                    "shortenDestUrl": "https://found.ee/raysmith_gametmemee-4/ms-pandora-5",
                    "destinationUrl": "https://pandora.app.link/?$desktop_url=https%3A%2F%2Fwww.pandora.com%2Fartist%2Fray-smith%2Fga-met-me-mee-single%2FALtVw6Vpd9lz74c&$ios_deeplink_path=pandorav4%3A%2F%2Fbackstage%2Falbum%3Ftoken%3DAL%3A5717913&$android_deeplink_path=pandorav4%3A%2F%2Fbackstage%2Falbum%3Ftoken%3DAL%3A5717913&~channel=Partner%20Catalog%20Search%20API",
                    "type": "URL"
                },
                "order": 5,
                "callToAction": null
            }
        ],
        "socialMediasInfo": [],
        "background": {
            "name": "bb1c6d6a-44d1-4cce-bbcb-b1bc4b5a0f37",
            "url": "https://found.ee/user/11221/bb1c6d6a-44d1-4cce-bbcb-b1bc4b5a0f37",
            "blur": 10,
            "image": null,
            "type": "IMAGE",
            "newImage": false
        },
        "content": {
            "image": {
                "imageName": "24cfeee8-9f6c-498e-a22c-aeb8266081c1",
                "imageUrl": "https://found.ee/user/11221/24cfeee8-9f6c-498e-a22c-aeb8266081c1"
            },
            "musicPreviewUrl": "https://audio-ssl.itunes.apple.com/itunes-assets/AudioPreview113/v4/b2/90/43/b29043f0-5f61-3003-cfb9-9712603b4b74/mzaf_5722414421667241194.plus.aac.p.m4a",
            "type": "IMAGE_AND_PREVIEW_URL"
        },
        "tourWidget": null,
        "fontColor": "#ffffff",
        "rescanDataV2": null,
        "pageTemplateId": 2,
        "publicMetricsPageUrl": null,
        "tags": [],
        "iPageType": "MUSIC_PAGE",
        "ipageType": "MUSIC_PAGE",
        "type": "IPAGE"
    },
    "status": 0,
    "message": "Ok"
}

The endpoint is used to create a Page for the released music. On the backend found.ee scans the requested/supported retailers and retrieve all the necessary information about the released music.

HTTP Request

POST https://api.found.ee/link/api/page

Query Request Body

Field	Optional	Description
upc	false	The released music Universal Product Code (UPC)
artistName	true	Artist name. The field is used as a header of the page. If null, the artist name from the scan results is used
albumName	true	Album name. The field is used as a description of the page. If null, the album name from the scan results is used
coverUrl	true	Album cover link. If null, the cover url from scanned retailer is used
retailersToUse	true	List of retailers to scan. if `null`, all the supported values are used
releaseDate	true	Music release date and time in PST timezone
domain	true	Custom domain. If `null`, "found.ee" domain is used. See the Custom Domain Info
preview	true	Preview content. See the Preview Content Info

Custom Domain Info

Specify either domain ID or domain name (host). The id field has a higher priority than the domain field: if both are specified, then domain is resolved by ID. If none are specified, then the default "found.ee" domain will be used to create a page.

Field	Optional	Type	Description
id	true	Long	Custom domain ID. Default is 14 which corresponds to "found.ee" domain.
domain	true	String	Custom domain host. Default is "found.ee"

Preview Content Info

Widget or audio content to be used in a page banner area.

Field	Optional	Type	Description
widget	true	WidgetContent	Main widget, e.g. an embedded musical video from YouTube.
musicPreviewUrl	true	String	A link to a music preview file.

Response Body

If success, returns the Page object, otherwise, returns error code.

Create a Pre-save page

curl -X POST "https://api.found.ee/link/api/page/pre-save" \
  -H "Authorization: Bearer token" \
  -H "Content-Type: application/json" \
    -d '{"upc": "8713092815750", "artistName": "Ray Smith", "albumName": "Ga met me mee", "retailersToUse": ["APPLE", "SPOTIFY", "DEEZER_GEO", "PANDORA"], "coverUrl": "https://static.found.ee/user/1111/correct-image-url.jpg", "releaseDate": "2101-01-01T00:00:00"}'

{
    "data": {
        "id": 54604,
        "domainId": 14,
        "domain": "found.ee",
        "shortCode": "raysmith_gametmemee-2",
        "shortFull": "https://found.ee/raysmith_gametmemee-2",
        "created": "2101-01-01T00:00:00.632",
        "clicks": 0,
        "uniqueClicks": 0,
        "parentId": null,
        "countryCode": null,
        "header": "Ray Smith",
        "desc": "Ga met me mee",
        "retailersInfo": [
            {
                "retailerId": 34,
                "retailerName": "Spotify Pre-Save",
                "defaultAction": "Pre-Save",
                "dest": {
                    "shortenDestUrl": "https://found.ee/raysmith_gametmemee-2/ms-spotifypre-1",
                    "spotifyPreSaveInfo": {
                        "id": 423,
                        "spotifyResourceURI": null,
                        "dateTime": "2022-01-02T00:00:00",
                        "spotifyArtistURI": null,
                        "spotifyPlaylistURL": null,
                        "releases": [
                            {
                                "id": 84,
                                "artistName": "Ray Smith",
                                "albumName": "Ga met me mee",
                                "trackName": null,
                                "dateTime": "2101-01-02T00:00:00"
                            }
                        ],
                        "transitionToStreamButton": true,
                        "preReleaseCTA": "Pre-Save",
                        "postReleaseCTA": "Listen",
                        "createdAt": "2021-02-01T02:28:19.84"
                    },
                    "type": "SPOTIFY_PRE_SAVE"
                },
                "order": 1,
                "callToAction": "Pre-Save"
            },
            {
                "retailerId": 33,
                "retailerName": "Apple Music Pre-Add",
                "defaultAction": "Pre-Add",
                "dest": {
                    "shortenDestUrl": "https://found.ee/raysmith_gametmemee-2/ms-applepre-2",
                    "applePreAddData": {
                        "id": 66,
                        "url": null,
                        "objectId": null,
                        "objectType": null,
                        "upc": "8713092815750",
                        "artistName": "Ray Smith",
                        "title": "Ga met me mee",
                        "releaseDate": "2101-01-01T00:00:00",
                        "preReleaseCta": "Pre-Add",
                        "postReleaseCta": "Listen",
                        "artistUrl": null,
                        "playlistUrl": null
                    },
                    "type": "APPLE_PRE_ADD"
                },
                "order": 2,
                "callToAction": null
            },
            {
                "retailerId": 147,
                "retailerName": "Deezer Pre-Save",
                "defaultAction": "Pre-Save",
                "dest": {
                    "shortenDestUrl": "https://found.ee/raysmith_gametmemee-2/ms-deezerpre-3",
                    "deezerPreSaveInfo": {
                        "id": 10,
                        "upc": "8713092815750",
                        "artistName": "Ray Smith",
                        "albumName": "Ga met me mee",
                        "trackName": null,
                        "releaseDate": "2101-01-01T00:00:00",
                        "postReleaseCTA": "Listen",
                        "preReleaseCTA": "Presave",
                        "deezerReleasedUrl": null,
                        "releasedUrl": null,
                        "artistUrl": null,
                        "playlistUrl": null
                    },
                    "type": "DEEZER_PRE_SAVE"
                },
                "order": 3,
                "callToAction": null
            }
        ],
        "socialMediasInfo": [],
        "background": {
            "type": "DEFAULT"
        },
        "content": {
            "image": {
                "imageName": "a374b627-f6e0-4380-8376-450254f17a66",
                "imageUrl": "https://static.found.ee/user/11221/a374b627-f6e0-4380-8376-450254f17a66"
            },
            "type": "IMAGE"
        },
        "tourWidget": null,
        "fontColor": "#ffffff",
        "rescanDataV2": {
            "upc": "8713092815750",
            "artistName": "fdsafasdf",
            "albumName": "Ga met me mee",
            "releaseDate": "2022-01-01T00:00:00",
            "attempts": 0,
            "retailersToPopulate": [
                {
                    "retailerId": 4,
                    "postReleaseCta": null,
                    "order": 0,
                    "processingResult": "IN_PROGRESS"
                },
                {
                    "retailerId": 5,
                    "postReleaseCta": null,
                    "order": 1,
                    "processingResult": "IN_PROGRESS"
                },
                {
                    "retailerId": 130,
                    "postReleaseCta": null,
                    "order": 2,
                    "processingResult": "IN_PROGRESS"
                },
                {
                    "retailerId": 3,
                    "postReleaseCta": null,
                    "order": 3,
                    "processingResult": "IN_PROGRESS"
                },
                {
                    "retailerId": 9,
                    "postReleaseCta": null,
                    "order": 4,
                    "processingResult": "IN_PROGRESS"
                },
                {
                    "retailerId": 1,
                    "postReleaseCta": null,
                    "order": 5,
                    "processingResult": "IN_PROGRESS"
                },
                {
                    "retailerId": 6,
                    "postReleaseCta": null,
                    "order": 6,
                    "processingResult": "IN_PROGRESS"
                },
                {
                    "retailerId": 2,
                    "postReleaseCta": null,
                    "order": 7,
                    "processingResult": "IN_PROGRESS"
                },
                {
                    "retailerId": 8,
                    "postReleaseCta": null,
                    "order": 8,
                    "processingResult": "IN_PROGRESS"
                },
                {
                    "retailerId": 32,
                    "postReleaseCta": null,
                    "order": 9,
                    "processingResult": "IN_PROGRESS"
                }
            ]
        },
        "pageTemplateId": 2,
        "publicMetricsPageUrl": null,
        "tags": [],
        "ipageType": "PRESAVE_PAGE",
        "iPageType": "PRESAVE_PAGE",
        "type": "IPAGE"
    },
    "status": 0,
    "message": "Ok"
}

The endpoint creates a new pre-save release. If the music is not released, but you want to share it as a Pre-Order or Pre-Save (Spotify / Deezer / Apple Music / Amazon Music / TIDAL) until release day. Along with the pre-save retailers, the other requested retailers will be scheduled for scanning on the release date and time. Once the music is released and publicly available the pre-save buttons are replaced with regular links to the released music.

HTTP Request

POST https://api.found.ee/link/api/page/pre-save

Query Request Body

Field	Optional	Description
upc	false	The released music Universal Product Code (UPC)
artistName	true	Artist name. The field is used as a header of the page. If null, the artist name from the scan results is used
albumName	true	Album name. The field is used as a description of the page. If null, the album name from the scan results is used
coverUrl	true	Album cover link. If null, the cover url from scanned retailer is used
retailersToUse	true	List of retailers to scan. if `null`, all the supported values are used
releaseDate	false	Music release date and time in PST timezone
additionalInfo	true	Pre-save object additional request info. See the Pre-Add Additional Info
domain	true	Custom domain. If `null`, "found.ee" domain is used. See the Custom Domain Info
preview	true	Preview content. See the Preview Content Info

For example, if you want to create a page with a Pre-Save button for Spotify, you can specify json "retailersToUse": ["SPOTIFY"]

If you want to create a page with a Pre-Add button for Apple Music, you can specify json "retailersToUse": ["APPLE"]

If you want to create a page with a Pre-Save button for Deezer, you can specify json "retailersToUse": ["DEEZER_GEO"]

If you want to create a page with a Pre-Save button for Amazon Music, you can specify json "retailersToUse": ["AMAZON_API_GEO_MUSIC"]

If you want to create a page with a Pre-Save button for TIDAL, you can specify json "retailersToUse": ["TIDAL"]

Pre-Add Additional Info

Field	Optional	Type	Description
appleInfo	true	Apple Pre-Add Additional Info	Apple Pre-Add additional info, such as URL (if known)
spotifyInfo	true	Spotify Pre-Save Additional Info	Spotify Pre-Save additional info, such as artist ID or playlist URL

Spotify Pre-Save additional info

Field	Optional	Type	Description
artistId	true	String	Spotify artist URI of the form `spotify:artist:4m2880jivSbbyEGAKfITCa`.
playlistUrl	true	String	Spotify playlist URL to follow upon pre-save, e.g. `https://open.spotify.com/playlist/54JhvNo0uawxTu0CSnJ9qV`.

Apple Pre-Add additional info

Field	Optional	Type	Description
url	false	String	Apple Music URL of the album, e.g. `https://music.apple.com/us/album/skin/1572670680`

Custom Domain Info (Pre-Save)

Field	Optional	Type	Description
id	true	Long	Custom domain ID. Default is 14 which corresponds to "found.ee" domain.
domain	true	String	Custom domain host. Default is "found.ee"

Preview Content Info (Pre-Save)

Widget or audio content to be used in a page banner area.

Field	Optional	Type	Description
widget	true	WidgetContent	Main widget, e.g. an embedded musical video from YouTube.
musicPreviewUrl	true	String	A link to a music preview file.

Restrictions:

"upc": cannot be a blank string

either both "albumName" and "artistName" should be passed with valid values or both should be empty

"coverUrl": should be a valid full URL link

"releaseDate": should be a date time in future of a format 'YYYY-MM-DDThh:mm:ss'. This date must be sooner than 1 year from now.

"retailersToUse": an optional array of supported retailers.

"domain.id": should be a positive integer.

"domain.domain": max length: 253.

"preview.musicPreviewUrl": should be a valid full URL link. Found.ee doesn't enforce media type restrictions, but you should use one of the supported HTML audio formats in order to get a properly working page: MP3, WAV, OGG.

"additionalInfo.appleInfo.url": should be a valid full URL link.

"additionalInfo.spotifyInfo.playlistUrl": should be a valid full URL link.

Response Body

If success, Returns the Page object, otherwise, returns error code.

Example

Find the examples on the right panel.

curl -X POST "https://api.found.ee/link/api/page/pre-save" \
  -H "Authorization: Bearer token" \
  -H "Content-Type: application/json" \
    -d '{
      "domain": { "domain": "link.music.co" },
      "upc": "8713092815750",
      "artistName": "Warner Bros. Pictures",
      "albumName": "The Matrix Resurrections",
      "retailersToUse": ["APPLE", "SPOTIFY", "DEEZER_GEO", "PANDORA"],
      "preview": { "widget": { "code": "<iframe width=\"560\" height=\"315\" src=\"https://www.youtube.com/embed/9ix7TUGVYIo\" title=\"YouTube video player\" frameborder=\"0\" allow=\"accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture\" allowfullscreen></iframe>" } },
      "releaseDate": "2021-12-22T00:00:00"
    }'

Create a Timed-release page

curl -X POST "https://api.found.ee/link/api/page/timed-release"
  -H "Authorization: Bearer token"
  -H "Content-Type: application/json"
  -d '{ "upc": "1111111", "artistName": "fdsafasdf", "albumName": "Ga met ffdsfd", "releaseDate": "2022-01-01T00:00:00"}'

{
    "data": {
        "id": 54603,
        "domainId": 14,
        "domain": "found.ee",
        "shortCode": "fdsafasdf_gametffds-1",
        "shortFull": "https://found.ee/fdsafasdf_gametffds-1",
        "created": "2021-02-01T02:27:43.237",
        "clicks": 0,
        "uniqueClicks": 0,
        "parentId": null,
        "countryCode": null,
        "header": "fdsafasdf",
        "desc": "Ga met ffds",
        "retailersInfo": [],
        "socialMediasInfo": [],
        "background": {
            "type": "DEFAULT"
        },
        "content": {
            "image": {
                "imageName": "9706887f-f71e-41f9-97c4-0c4e9642a368",
                "imageUrl": "https://static.found.ee/user/11221/9706887f-f71e-41f9-97c4-0c4e9642a368"
            },
            "type": "IMAGE"
        },
        "tourWidget": null,
        "fontColor": "#ffffff",
        "rescanDataV2": {
            "upc": "111111",
            "artistName": "fdsafasdf",
            "albumName": "Ga met ffds",
            "releaseDate": "2022-01-01T00:00:00",
            "attempts": 0,
            "retailersToPopulate": [
                {
                    "retailerId": 4,
                    "postReleaseCta": null,
                    "order": 0,
                    "processingResult": "IN_PROGRESS"
                },
                {
                    "retailerId": 5,
                    "postReleaseCta": null,
                    "order": 1,
                    "processingResult": "IN_PROGRESS"
                },
                {
                    "retailerId": 130,
                    "postReleaseCta": null,
                    "order": 2,
                    "processingResult": "IN_PROGRESS"
                },
                {
                    "retailerId": 3,
                    "postReleaseCta": null,
                    "order": 3,
                    "processingResult": "IN_PROGRESS"
                },
                {
                    "retailerId": 9,
                    "postReleaseCta": null,
                    "order": 4,
                    "processingResult": "IN_PROGRESS"
                },
                {
                    "retailerId": 1,
                    "postReleaseCta": null,
                    "order": 5,
                    "processingResult": "IN_PROGRESS"
                },
                {
                    "retailerId": 6,
                    "postReleaseCta": null,
                    "order": 6,
                    "processingResult": "IN_PROGRESS"
                },
                {
                    "retailerId": 2,
                    "postReleaseCta": null,
                    "order": 7,
                    "processingResult": "IN_PROGRESS"
                },
                {
                    "retailerId": 8,
                    "postReleaseCta": null,
                    "order": 8,
                    "processingResult": "IN_PROGRESS"
                },
                {
                    "retailerId": 32,
                    "postReleaseCta": null,
                    "order": 9,
                    "processingResult": "IN_PROGRESS"
                }
            ]
        },
        "pageTemplateId": 2,
        "publicMetricsPageUrl": null,
        "tags": [],
        "ipageType": "TIMED_RELEASE",
        "iPageType": "TIMED_RELEASE",
        "type": "IPAGE"
    },
    "status": 0,
    "message": "Ok"
}

Creates a new future release Page. If your music is not released yet, but you want to create your link ahead of time, so it’s ready on release date. On release date, the retailer links are scanned and converted to post release links.

HTTP Request

POST https://api.found.ee/link/api/page/timed-release

Query Request Body

Field	Optional	Description
upc	false	The released music Universal Product Code (UPC)
artistName	false	Artist name. The field is used as a header of the page. If null, the artist name from the scan results is used
albumName	false	Album name. The field is used as a description of the page. If null, the album name from the scan results is used
coverUrl	true	Album cover link. If null, the cover url from scanned retailer is used
retailersToUse	true	List of retailers to scan. if `null`, all the supported values are used
releaseDate	false	Music release date and time in PST timezone
domain	true	Custom domain. If `null`, "found.ee" domain is used. See the Custom Domain Info
preview	true	Preview content. See the Preview Content Info

Custom Domain Info (Timed Release)

Field	Optional	Type	Description
id	true	Long	Custom domain ID. Default is 14 which corresponds to "found.ee" domain.
domain	true	String	Custom domain host. Default is "found.ee"

Preview Content Info (Timed Release)

Widget or audio content to be used in a page banner area.

Field	Optional	Type	Description
widget	true	WidgetContent	Main widget, e.g. an embedded musical video from YouTube.
musicPreviewUrl	true	String	A link to a music preview file.

Restrictions:

"upc": cannot be a blank string

"artistName": cannot be a blank string

"albumName": cannot be a blank string

either both "albumName" and "artistName" should be passed with valid values or both should be empty

"coverUrl": should be a valid full URL link

"releaseDate": should be a date time in future of a format 'YYYY-MM-DDThh:mm:ss'. This date must be sooner than 1 year from now.

"retailersToUse": an optional array of supported retailers.

"domain.id": should be a positive integer.

"domain.domain": max length: 253.

Response Body

If success, Returns the Page object, otherwise, returns error code.

Get page by ID

curl -X POST 'https://api.found.ee/link/api/interstitialPages/{id}' \
  -H 'authorization: Bearer <your_access_token>' \
  -H 'content-type: application/json'

{
  "data": {
    "id": 203353,
    "domainId": 14,
    "domain": "found.ee",
    "shortCode": "qdJcK",
    "shortFull": "https://found.ee/qdJcK",
    "created": "2021-05-27T08:05:31.38",
    "clicks": 5,
    "uniqueClicks": 3,
    "parentId": null,
    "countryCode": null,
    "header": "any title",
    "desc": "new page description",
    "retailersInfo": [
      {
        "retailerId": 48,
        "retailerName": "Email Capture",
        "defaultAction": "Subscribe",
        "dest": {
          "customForm": "subscribe",
          "shortenDestUrl": null,
          "type": "CUSTOM_FORM"
        },
        "order": 0,
        "callToAction": "Subscribe",
        "type": "CUSTOM_FORM"
      },
      {
        "retailerId": 158,
        "retailerName": "Custom",
        "defaultAction": "Listen",
        "dest": {
          "shortenDestUrl": "https://found.ee/qdJcK/ms-custom-1",
          "destinationUrl": "https://open.spotify.com/genre/focus-home-shelf",
          "type": "URL"
        },
        "order": 1,
        "callToAction": "Listen",
        "type": "CUSTOM"
      }
    ],
    "socialMediasInfo": [],
    "background": {
      "type": "DEFAULT"
    },
    "content": {
      "image": {
        "imageName": "img_631991.1425233119.png",
        "imageUrl": "https://static.found.ee/user/11243/img_631991.1425233119.png"
      },
      "type": "IMAGE"
    },
    "tourWidget": null,
    "fontColor": "#ffffff",
    "rescanDataV2": null,
    "iPageType": "MUSIC_PAGE",
    "pageTemplateId": 2,
    "publicMetricsPageUrl": null,
    "tags": [],
    "ipageType": "MUSIC_PAGE",
    "type": "IPAGE"
  },
  "status": 0,
  "message": "Ok"
}

The endpoint fetches the existing page. You can query any type of page, a regular page, a Pre-Save page, a Timed-release page.

HTTP Request

POST https://api.found.ee/link/api/interstitialPages/{id}

Path parameters

Field	Optional	Default value	Description
id	false		Found.ee ID of page that needs to be updated

Response Body

If success, Returns the Page object, otherwise, returns error code.

Update a page

curl -X POST 'https://api.found.ee/link/api/interstitialPages/{id}/update' \
  -H 'authorization: Bearer <your_access_token>' \
  -H 'content-type: application/json' \
  -d '{"background":{"type":"DEFAULT"},"desc":"new page description","domainId":14,"fontColor":"#ffffff","header":"any title","shortCode":"qdJcK","pageTemplateId":2,"id":203353,"retailersData":[{"callToAction":"Subscribe","order":0,"retailerId":48,"dest":{"type":"CUSTOM_FORM","customForm":"subscribe"}},{"callToAction":"Listen","order":1,"retailerId":158,"dest":{"type":"URL","destinationUrl":"https://open.spotify.com/genre/focus-home-shelf"}}]}'

{
  "data": {
    "id": 203353,
    "domainId": 14,
    "domain": "found.ee",
    "shortCode": "qdJcK",
    "shortFull": "https://found.ee/qdJcK",
    "created": "2021-05-27T08:05:31.38",
    "clicks": 5,
    "uniqueClicks": 3,
    "parentId": null,
    "countryCode": null,
    "header": "any title",
    "desc": "new page description",
    "retailersInfo": [
      {
        "retailerId": 48,
        "retailerName": "Email Capture",
        "defaultAction": "Subscribe",
        "dest": {
          "customForm": "subscribe",
          "shortenDestUrl": null,
          "type": "CUSTOM_FORM"
        },
        "order": 0,
        "callToAction": "Subscribe",
        "type": "CUSTOM_FORM"
      },
      {
        "retailerId": 158,
        "retailerName": "Custom",
        "defaultAction": "Listen",
        "dest": {
          "shortenDestUrl": "https://found.ee/qdJcK/ms-custom-1",
          "destinationUrl": "https://open.spotify.com/genre/focus-home-shelf",
          "type": "URL"
        },
        "order": 1,
        "callToAction": "Listen",
        "type": "CUSTOM"
      }
    ],
    "socialMediasInfo": [],
    "background": {
      "type": "DEFAULT"
    },
    "content": {
      "image": {
        "imageName": "img_631991.1425233119.png",
        "imageUrl": "https://static.found.ee/user/11243/img_631991.1425233119.png"
      },
      "type": "IMAGE"
    },
    "tourWidget": null,
    "fontColor": "#ffffff",
    "rescanDataV2": null,
    "iPageType": "MUSIC_PAGE",
    "pageTemplateId": 2,
    "publicMetricsPageUrl": null,
    "tags": [],
    "ipageType": "MUSIC_PAGE",
    "type": "IPAGE"
  },
  "status": 0,
  "message": "Ok"
}

The endpoint updates an existing page. You can update any type of page, a regular page, a Pre-Save page, a Timed-release page.

Take into account the following limitations:

Page ID (id) can’t be changed
Page type (type and iPageType) can’t be changed
Page creation date (created) can’t be changed
Page statistics (clicks and uniqueClicks) can’t be changed
Page public metrics URL (publicMetricsPageUrl) can’t be changed
geo-page info (parentId and countryCode) can’t be changed
domain name (domain) can’t be changed directly, it depends on domainId
full short link URL (shortFull) can’t be changed directly, because it depends on domainId and shortCode
Spotify Pre-Save, Deezer Pre-Save, Amazon Music Pre-Save, TIDAL Pre-Save, and Apple Pre-Add details can't be changed using Page Update request. Contact our team for details on how to get more control over pre-saves.

HTTP Request

POST https://api.found.ee/link/api/interstitialPages/{id}/update

Path parameters

Field	Optional	Default value	Description
id	false		Found.ee ID of page that needs to be updated

Query Request Body

See Page object description.

Response Body

If success, Returns the Page object, otherwise, returns error code.

Examples

Allowed modifications in update operation:

any page content changes (See ContentInfo):
- content type content.type
- banner image content.image
- banner widget content.widget
bottom widget tourWidget.code
text content:
- header or title header
- description desc
- font color fontColor
page background background. See BackgroundInfo
(only for PRE-SAVE and TIMED RELEASE pages) a list of auto-rescannable retailers and their search criteria rescanDataV2. See Auto-Rescan Configuration
a list of retailers retailersData. this list can contain regular, pre-save, social unlock, custom form retailers
a list of social media icons socialMedias. See SocialMediaInfo
page layout:
- for 1-column page use pageTemplateId: 2
- for 2-column page use pageTemplateId: 1
short code change (shortCode)
domain change (use domainId)

Short code change

Here is an example of how to update a pre-save page without changing retailers list (buttons) and page content.

In order to do this, in request body...

specify a new short code, e.g. "shortCode": "fantastic-release-page";
don't specify content;
keep other page object values unchanged, send the retailers list in retailersData field. With that in mind, you might want to first get the current page content using Get Page by ID request.

curl -X POST 'https://api.found.ee/link/api/interstitialPages/{id}/update' \
  -H 'authorization: Bearer <your_access_token>' \
  -H 'content-type: application/json' \
  -d '{
        "background":{"type":"DEFAULT"},
        "desc":"using the same page description",
        "domainId":14,
        "fontColor":"#ffffff",
        "header":"using the same page title",
        "shortCode":"fantastic-release-page",
        "pageTemplateId":2,
        "id":203353,
      "retailersData": [
        {
          "callToAction":"Subscribe",
          "order":0,
          "retailerId":48,
          "dest": {
            "type":"CUSTOM_FORM",
            "customForm":"subscribe"
          }
        },
        {
          "callToAction":"Listen",
          "order":1,
          "retailerId":158,
          "dest":{
            "type":"URL",
            "destinationUrl":"https://open.spotify.com/genre/focus-home-shelf"
          }
        }
        {
          "callToAction":"Pre-Add",
          "order":2,
          "retailerId":113,
          "dest": {
            "type":"APPLE_PRE_ADD",
            "id":2501
          }
        },
        {
          "callToAction":"Pre-Save",
          "order":3,
          "retailerId":4649,
          "dest": {
            "type":"DEEZER_PRE_SAVE",
            "id":1807
          }
        },
        {
          "callToAction":"Pre-Save",
          "order":4,
          "retailerId":296,
          "dest":{
            "type":"SPOTIFY_PRE_SAVE",
            "id":2686
          }
        }
      ]}'

In this example the page has 5 retailers and we send them unchanged:

"Subscribe To Emails" button ("type":"CUSTOM_FORM")
a regular button ("type":"URL")
an Apple Music Pre-Add button ("type":"APPLE_PRE_ADD")
a Deezer Pre-Save button ("type":"DEEZER_PRE_SAVE")
a Spotify Pre-Save button ("type":"SPOTIFY_PRE_SAVE")

The retailersData field is not required in update request, but if we send a request without retailersData, all existing retailers will be deleted from the page. Other fields, such as domainId, desc, header, are required in update request, so they can't be omitted.

Delete a page

Delete a page and its associated content.

curl -X POST "https://api.found.ee/link/api/interstitialPages/{id}/delete" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <your_access_token>" \

{
  "status": 0,
  "message": "Ok"
}

HTTP Request

POST https://api.found.ee/link/api/interstitialPages/{id}/delete

Path parameters

Field	Optional	Default value	Description
id	false		Found.ee page ID to delete

Response Body

If success, returns the OK response, otherwise, returns error code.

Get a public metrics HTML page for a page

Returns HTML page with metrics data for the given page. Please note that this API does not require authentication. The absolute public metrics page URL can be obtained from the Page APIs responses as a part of the Page Object, the publicMetricsPageUrl field.

curl -X GET "https://found.ee/public/metrics/512d961b-ca33-41b3-de9c-1e1ag5ba1732"

HTTP Request

GET https://found.ee/public/metrics/{token}

Path parameters

Field	Optional	Default value	Description
token	false		A unique token generated when page is created and is associated with that only page.

Response Body

If success, returns the HTML page with metrics data, otherwise, returns error code.

Page object

Page object contains a link to the created page, and detailed information about the generated page, including information about retailers.

Field	Type	Description
id	Long	The created Page identifier
domainId	Long	The created Page domain identifier. By default it is found.ee domain id
domain	String	The created page domain name. By default it is found.ee.
shortCode	String	The created page short code.
shortFull	String	Link to the created page. For usage in responses only.
created	DateTime	Creation date and time in PST timezone.
clicks	Int	Number of page clicks (metrics)
uniqueClicks	Int	Number of page unique clicks (metrics)
type	String	Short link type. For the Page object = IPAGE
header	String	Page header. In case of page generation equals to Artist Name.
desc	String	Page description. In case of page generation equals to Album Name
fontColor	String	Font color (HEX code). Example value: `#4a4a4a`.
content	ContentInfo	Page content
background	BackgroundInfo	Page background information
tourWidget	WidgetContent	Page bottom widget, e.g. an embedded tour dates & tickets reservation
socialMediasInfo	Collection<SocialMediaInfo>	A list of page social media icons
retailersInfo	Collection<RetailerInfo>	A list of page retailers including Pre-Saves
rescanDataV2	Auto-Rescan Configuration	Auto-Rescan configuration object. It's used in requests and responses with pages of type `"iPageType": "PRESAVE_PAGE"` and `"iPageType": "TIMED_RELEASE"`.
publicMetricsPageUrl	String	Link to the publicly accessible metrics (contact our team for details)
pageTemplateId	Long	Identifier of a template that is used to render the page. Existing templates: 2-column and 1-column page.

Background Info

Page background object contains information about the background used.

Page background could be of different types. Depending on the background type, the response object contains different fields. Supported background types: * a solid color * a custom image with an optional blur effect

Default page background (type DEFAULT) is a solid light grey color. In a generated page, a relevant auto-discovered image (if any) is blurred and used as the page background.

Field	Type	Description
type	String	Page background type. One of `DEFAULT`/`IMAGE`/`COLOR`
color	String	Page background color HEX code (e.g. #4a4a4a). Present only if type is `COLOR`.
blur	Int	Page background image blur (in %). Present only if type is `IMAGE`.
name	String	Page background image name. Present only if type is `IMAGE`. Example value: `"picture.jpg"`.
url	String	Page background image URL. Present in responses only if type is `IMAGE`.

Retailer Info

Field	Type	Description
retailerId	Long	The created retailer identifier
retailerName	String	The created retailer name
order	Int	Order in the list on the page. Retailer buttons are ordered in ascending order when rendered. Min: 0.
callToAction	String	Button Call-to-Action string
defaultAction	String	Default Call-to-Action
dest	RetailerDestination	The retailer destination object
type	String	The retailer type

Retailer destination object

Field	Type	Description
type	String	The retailer destination type
id	Long	Identifier of a pre-save or pre-add instance (if applicable)
destinationUrl	String	The destination URL (if applicable)

URL destination example

"dest": {
  "type": "URL",
  "destinationUrl": "https://music.apple.com/us/artist/demo-artist/id12345678"
}

"dest": {
  "shortenDestUrl": "https://found.ee/cB4z/ms-apple-0",
  "destinationUrl": "https://music.apple.com/us/artist/demo-artist/id12345678",
  "type": "URL"
}

Apple Music Pre-Add destination example

"dest": {
    "type":"APPLE_PRE_ADD",
    "id":111
}

"dest": {
  "shortenDestUrl": "https://found.ee/cB4z/ms-applepre-0",
  "applePreAddInfo": {
    "id": 111,
    "upc": "1110110870000",
    "artistName": "such artist",
    "title": "such album",
    "releaseDate": "2021-06-10T12:10:00",
    "postReleaseCTA": "Listen",
    "preReleaseCTA": "Pre-Add",
    "url": null,
    "artistUrl": null,
    "playlistUrl": null
  },
  "type": "APPLE_PRE_ADD",
  "id": 111
}

Deezer Pre-Save destination example

"dest": {
    "type":"DEEZER_PRE_SAVE",
    "id":453
}

"dest": {
  "shortenDestUrl": "https://found.ee/cB4z/ms-deezerpre-1",
  "deezerPreSaveInfo": {
    "id": 453,
    "upc": "1110110870000",
    "artistName": "such artist",
    "albumName": "such album",
    "trackName": null,
    "releaseDate": "2021-06-10T12:10:00",
    "postReleaseCTA": "Listen",
    "preReleaseCTA": "Pre-Save",
    "deezerReleasedUrl": null,
    "releasedUrl": null,
    "artistUrl": null,
    "playlistUrl": null
  },
  "type": "DEEZER_PRE_SAVE",
  "id": 453
}

Spotify Pre-Save destination example

"dest": {
  "type":"SPOTIFY_PRE_SAVE",
  "id": 1188
}

"dest": {
  "shortenDestUrl": "https://found.ee/cB4z/ms-spotifypre-2",
  "spotifyPreSaveInfo": {
    "upc": "1110110870000",
    "id": 1188,
    "spotifyResourceURI": null,
    "dateTime": "2021-06-10T12:10:00",
    "spotifyArtistURI": null,
    "artistName": "such artist",
    "albumName": "such album",
    "spotifyPlaylistURL": null,
    "releases":[],
    "transitionToStreamButton": true,
    "preReleaseCTA": "Pre-Save",
    "postReleaseCTA": "Listen",
    "createdAt": "2021-06-09T01:48:41.53"
  },
  "type":"SPOTIFY_PRE_SAVE",
  "id": 1188
}

Amazon Music Pre-Save destination example

"dest": {
  "type":"AMAZON_MUSIC_PRE_SAVE",
  "id": 115
}

"dest": {
  "shortenDestUrl": "https://found.ee/cB4z/ms-amazonmusicpre-2",
  "amazonMusicPreSaveInfo": {
    "id": 115,
    "upc": "8713092815750",
    "artistName": "such artist",
    "albumName": "such album",
    "trackName": null,
    "releaseDate": "2023-01-01T00:00:00",
    "scheduledScanDate": "2023-01-01T00:00:00",
    "postReleaseCTA": "Listen",
    "preReleaseCTA": "Pre-Save",
    "releasedUrl": null,
    "artistUrl": null,
    "playlistUrl": null
  },
  "type":"AMAZON_MUSIC_PRE_SAVE",
}

TIDAL Pre-Save destination example

"dest": {
  "type":"TIDAL_PRE_SAVE",
  "id": 3
}

"dest": {
  "shortenDestUrl": "https://found.ee/cB4z/ms-tidalpre-2",
  "tidalPreSaveInfo": {
    "id": 3,
    "upc": "8713092815750",
    "artistName": "such artist",
    "albumName": "such album",
    "trackName": null,
    "releaseDate": "2023-01-01T00:00:00",
    "scheduledScanDate": "2023-01-01T00:00:00",
    "postReleaseCTA": "Listen",
    "preReleaseCTA": "Pre-Save",
    "releasedUrl": null,
    "artistUrl": null,
    "playlistUrl": null
  },
  "type":"TIDAL_PRE_SAVE",
}

Social media object contains information about a social media icon. For usage in responses.

Field	Type	Description
retailerId	Long	The created retailer identifier
retailerName	String	The created retailer name
order	Int	Order in the list on the page. Social Media icons are ordered in ascending order when rendered. Min: 0.
callToAction	String	Button Call-to-Action string. (not used)
defaultAction	String	Default Call-to-Action text. (not used)
dest	String	The retailer destination link (a valid URL, not null)

Auto Rescan Configuration

Auto-Rescan configuration object contains data related to auto-rescan, such as search criteria, release date, and retailers to populate when found.

Field	Type	Description
upc	String	UPC
artistName	String	Artist name
albumName	String	Album name
releaseDate	String	Music release date and time in PST timezone
retailersToPopulate	Collection<AutoRescanRetailer>	A list of retailers scheduled for scanning on release date
attempts	Int	A number of attempts taken by the background job to find the object. For usage in responses.

Auto Rescan Retailer

Field	Type	Description
retailerId	Long	The retailer identifier to be rescanned
postReleaseCta	String	Button Call-to-Action text after release
order	Int	Retailer order in the list. Retailer buttons are ordered in ascending order when rendered. Min: 0.
processingResult	String	Processing status. Possible values: `IN_PROGRESS`, `SUCCESS`, `ATTEMPTS_EXCEEDED` (for usage in responses).

Page Content Info

Page content info holds information about the page banner, widget and audio preview. Depending on page content type the response object contains different fields.

Field	Type	Description
type	String	Page content type. See the notice above
image	ImageContent	Banner image, e.g. an album art (used with the `type` that supports image)
widget	WidgetContent	Main widget, e.g. an embedded musical video (used with the `type` that supports widget)
musicPreviewUrl	String	Link to a music preview file (.mp3) (used with the `type` that supports audio preview)

Image Content Object

Field	Type	Description
imageName	String	Image name, e.g. `"album-art.jpg"`. Long filenames will be truncated.
imageUrl	String	Image full URL

Field	Type	Description
code	String	HTML code of an embeddable widget. Like `<iframe ... </iframe>`

Page object (Update)

Page object should contain detailed information about the generated page, including information about retailers.

This a payload for Page Update request.

Field	Type	Optional	Description
domainId	Long	false	The updated Page domain identifier. By default it is found.ee domain id
shortCode	String	true	The updated page short code. Leave `null` if not changed.
header	String	false	Page header.
desc	String	false	Page description.
fontColor	String	false	Font color (HEX code). Example value: `#4a4a4a`.
content	ContentInfo	true	The Updated Page content. Leave `null` if not changed.
background	BackgroundInfo	false	Page background information
tourWidget	WidgetContent	true	Page bottom widget, e.g. an embedded tour dates & tickets reservation
socialMedias	Collection<SocialMediaInfo>	true	A list of page social media icons
retailersData	Collection<RetailerInfo>	true	A list of page retailers including Pre-Saves. Leave `null` to detach all existing retailers from page.
rescanDataV2	Auto-Rescan Configuration	true	Auto-Rescan configuration object. It's used in requests and responses with pages of type `"iPageType": "PRESAVE_PAGE"` and `"iPageType": "TIMED_RELEASE"`.
pageTemplateId	Long	false	Identifier of a template that is used to render the page. Existing templates: 2-column and 1-column page.

Background Info (Update)

Page background object contains information about the background used.

Page background could be of different types. Depending on the background type, the request object may contain different fields. Supported background types: * a solid color * a custom image with an optional blur effect

Default page background (type DEFAULT) is a solid light grey color. In a generated page, a relevant auto-discovered image (if any) is blurred and used as the page background.

Field	Type	Description
type	String	Page background type. One of `DEFAULT`/`IMAGE`/`COLOR`
color	String	Page background color HEX code (e.g. #4a4a4a). Required only if type is `COLOR`.
blur	Int	Page background image blur (in %). Required only if type is `IMAGE`. Minimum value: `0`. 100% = 10px. Use `0` to disable blur.
name	String	Page background image name. Required only if type is `IMAGE`. Example value: `"picture.jpg"`.
image	String	Page background image content (Base64). For usage in requests if type is `IMAGE`. If not specified, defaults to `null`. In update request context, `image: null` means "keep using the same background image". In create request context, `image: null` with `type: "IMAGE"` throws error.

Retailer Info (Update)

Field	Type	Optional	Default	Description
retailerId	Long	false		The updated retailer identifier
order	Int	true	0	Order in the list on the page. Retailer buttons are ordered in ascending order when rendered. Min: 0.
callToAction	String	true		Button Call-to-Action string
dest	RetailerDestination	The retailer destination object

Social media object contains information about a social media icon. For usage in requests.

Field	Type	Description
retailerId	Long	A retailer identifier (Required)
dest	String	The retailer destination link (Required)
order	Int	Icon order in the list. Social Media icons are ordered in ascending order when rendered. Min: 0. (Required)
callToAction	String	(not used)

Auto Rescan Configuration (Update)

Auto-Rescan configuration object contains data related to auto-rescan, such as search criteria, release date, and retailers to populate when found.

Update request requires at least one of the following:

upc
artistName + albumName

Field	Type	Description
retryRescan	Boolean	Retry Auto-Rescan for failed retailers? It has effect only in UPDATE requests and only if auto-rescan background job failed to find some auto-rescan retailers.
upc	String	UPC (search criteria)
artistName	String	Artist name (search criteria)
albumName	String	Album name (search criteria)
releaseDate	String	Music release date and time in PST timezone (required)
retailersToPopulate	Collection<AutoRescanRetailer>	A list of retailers scheduled for scanning on release date

Auto Rescan Retailer (Update)

Field	Type	Description
retailerId	Long	The retailer identifier to be rescanned
postReleaseCta	String	Button Call-to-Action text after release
order	Int	Retailer order in the list. Retailer buttons are ordered in ascending order when rendered. Min: 0.

Page Content Info (Update)

Page content info holds information about the page banner, widget and audio preview. Depending on page content type the request object contains different fields.

Field	Type	Optional	Description
type	String	false	Page content type. See the notice above
image	ImageContent	true	Banner image, e.g. an album art (used with the `type` that supports image). Leave `null` if not changed.
widget	WidgetContent	true	Main widget, e.g. an embedded musical video (used with the `type` that supports widget). Leave `null` if not changed.
musicPreviewUrl	String	true	Link to a music preview file (.mp3) (used with the `type` that supports audio preview). Leave `null` if not changed.

Image Content Object (Update)

Field	Type	Description
imageBase64	String	Image content encoded in Base64.
imageName	String	Image name, e.g. `"album-art.jpg"`. Long filenames will be truncated.
imageUrl	String	Image full URL

Field	Type	Description
code	String	HTML code of an embeddable widget. Like `<iframe> ... </iframe>`

Manage your Affiliate Ids

Affiliate Ids allow you to earn commission from your affiliates by sharing your links. Found.ee allows you to automatically attach Apple/Amazon affiliate Id to all your Apple/Amazon links respectively. Additionally, you can set different Affiliate Ids for different countries. Found.ee system considers Affiliate Id as a user setting. To Create/Update/Get setting, the user should use a predefined setting key.

Supported Affiliates

Add/Update Affiliate Id

curl -X POST "https://api.found.ee/auth/api/user-settings"
  -H "Authorization: Bearer token"
  -H "Content-Type: application/json"
  -d '[{"settingKey": "APPLE_AFFILIATE_ID", "settingVaule": "aff1", country: "US"}]'

{
  "data":[
    {"settingKey":"AMAZON_AFFILIATE_ID","settingValue":"fdsafsadfasd","country":null},
    {"settingKey":"AMAZON_AFFILIATE_ID","settingValue":"1223","country":"CY"},
    {"settingKey":"APPLE_AFFILIATE_ID","settingValue":"dsfdas","country":"BZ"},
    {"settingKey":"APPLE_AFFILIATE_ID","settingValue":"appl-1","country":null}
  ],
  "status":0,
  "message":"Ok"
}

The endpoint is used to create or update the User settings.

HTTP Request

POST https://api.found.ee/auth/api/user-settings

Query Request Body

An array of settings to update/create

Field	Optional	Description
settingKey	false	Setting key to create/update. One of: AMAZON_AFFILIATE_ID/APPLE_AFFILIATE_ID
settingValue	false	Value to set for the setting key
country	true	Country code. Use a Country code API to get a list of country codes

Response Body

If success, returns a List of settings.

Delete a user setting

curl -X DELETE "https://api.found.ee/auth/api/user-settings?name=AMAZON_AFFILIATE_ID&country=US" \
  -H "Authorization: Bearer token" \
  -H "Content-Type: application/json"

{
    "status": 0,
    "message": "Ok"
}

The endpoint removes the setting by name and country code.

HTTP Request

DELETE https://api.found.ee/auth/api/user-settings

Query Request Parameters

Parameter name	Optional	Default value	Description
name	false		Setting key to delete. One of: AMAZON_AFFILIATE_ID/APPLE_AFFILIATE_ID
country	true		Country code to remove the setting for.

Response Body

If success, Returns ok message, otherwise, returns error code.

Get a list of settings

curl -X GET "https://api.found.ee/auth/api/user-settings?name=AMAZON_AFFILIATE_ID&country=US
  -H "Authorization: Bearer token"
  -H "Content-Type: application/json"

{
  "data":[
    {"settingKey":"AMAZON_AFFILIATE_ID","settingValue":"1223","country":"US"}
  ],
  "status":0,
  "message":"Ok"
}

Returns a list of user settings with filter by setting name and country code. If parameters are not set returns all user settings.

HTTP Request

GET https://api.found.ee/auth/api/user-settings?name=AMAZON_AFFILIATE_ID&country=US

Query Request Parameters

Parameter name	Optional	Default value	Description
name	true		Setting key to get. One of: AMAZON_AFFILIATE_ID/APPLE_AFFILIATE_ID
country	true		Country code to get the setting for.

Response Body

If success, returns a List of settings.

Setting info

Field	Type	Description
settingKey	String	Setting key
settingValue	String	Setting value
country	Country code

Get a list of country codes

curl -X POST "https://api.found.ee/link/api/shortLinks/list/country
  -H "Authorization: Bearer token"
  -H "Content-Type: application/json"

{
  "data":[
    {"code":"AF","name":"Afghanistan"}, 
    {"code":"AX","name":"Åland Islands"}, 
    {"code":"AL","name":"Albania"}, 
    {"code":"DZ","name":"Algeria"}, 
    {"code":"AS","name":"American Samoa"}, 
    {"code":"AD","name":"Andorra"}, 
    {"code":"AO","name":"Angola"}, 
    {"code":"AI","name":"Anguilla"}, 
    {"code":"BS","name":"Bahamas"}
  ],
  "status":0,
  "message":"Ok"
}

Returns a list of available country codes.

HTTP Request

POST https://api.found.ee/link/api/shortLinks/list/country

Response Body

If success, returns a List of country codes.

Country code info

Field	Type	Description
code	String	country code to use in requests
name	String	Full country name

Html5 Ads Builder

The Html5 Ads Builder service is used to create HTML5 Ads banners for further use in advertising campaign.

To create an HTML5 Ad you need to be an authorized advertiser user. After authorization, you can get access to the HTML5 Ads builder API.

The main concept of the Html5 Ads Builder is that each instance is associated with an HTML5 Ad template. The end-user should select some template to build an Html5 Ad (instance). Each Html5 Ad Template comes with a list of fields (mandatory or optional) that should be populated in the create template instance request. Once created the Html5 Ad instance can be previewed, downloaded as a zip archive, used as a creative for Ad Campaign.

Get All Templates

curl -X POST "https://api.found.ee/html5ad/api/html5ad/template"
  -H "Authorization: Bearer token"
  -H "Content-Type: application/json"
  -d '{"page": 0, "size": 10}'

{
    "meta": {
        "totalRows": 1,
        "totalPages": 1
    },
    "data": [
        {
            "id": 1,
            "name": "Simple Template Banner",
            "description": "Html5 Advertising template banner with a widget in the center",
            "fields": [
                {
                    "fieldName": "size",
                    "fieldDescription": "Advertising banner size. Available values: [Size300x250, Size160x600, Size120x600, Size728x90, Size300x600]. Format: Size{height}x{width}",
                    "optional": false
                },
                {
                    "fieldName": "widget",
                    "fieldDescription": "Widget, that should be placed in the center of the banner. Widget could be an Apple Streaming Player, Youtube Video Streaming player etc.",
                    "optional": true
                },
                {
                    "fieldName": "backgroundImage",
                    "fieldDescription": "SVG or any other type of image content, that should be used as a banner background.",
                    "optional": false
                },
                {
                    "fieldName": "payload",
                    "fieldDescription": "Image template payload.",
                    "optional": true
                },
                {
                    "fieldName": "widgetProperties",
                    "fieldType": "WidgetProperties",
                    "fieldDescription": "Widget offset from the top/left edge in pixels. Widget size. Fields: offsetTop, offsetLeft, width, height",
                    "optional": true
                }
            ]
        }
    ],
    "status": 0,
    "message": "Ok"
}

This endpoint retrieves a list of Html5 Ad templates available for the user.

HTTP Request

POST https://api.found.ee/html5ad/api/html5ad/template

Query Request Body

Field	Optional	Default value	Description
page	true	0	Page number.
size	false		Page size.

Get a Specific Template by ID

curl "https://api.found.ee/html5ad/api/html5ad/template/1"
  -H "Authorization: Bearer token"

{
    "data": {
        "id": 1,
        "name": "Simple Template Banner",
        "description": "Html5 Advertising template banner with a widget in the center",
        "fields": [
            {
                "fieldName": "size",
                "fieldDescription": "Advertising banner size. Available values: [Size300x250, Size160x600, Size120x600, Size728x90, Size300x600]. Format: Size{height}x{width}",
                "optional": false
            },
            {
                "fieldName": "widget",
                "fieldDescription": "Widget, that should be placed in the center of the banner. Widget could be an Apple Streaming Player, Youtube Video Streaming player etc.",
                "optional": false
            },
            {
                "fieldName": "backgroundImage",
                "fieldDescription": "SVG or any other type of image content, that should be used as a banner background.",
                "optional": false
            },
            {
                "fieldName": "payload",
                "fieldDescription": "Image template payload.",
                "optional": true
            },
            {
                "fieldName": "widgetProperties",
                "fieldType": "WidgetProperties",
                "fieldDescription": "Widget offset from the top/left edge in pixels. Widget size. Fields: offsetTop, offsetLeft, width, height",
                "optional": true
            }
        ]
    },
    "status": 0,
    "message": "Ok"
}

This endpoint retrieves a specific Html5 Ad template by identifier.

HTTP Request

GET https://api.found.ee/html5ad/api/html5ad/template/<ID>

URL Parameters

Parameter	Description
ID	The ID of the Template to retrieve

Get a Specific Template body

curl "https://api.found.ee/html5ad/api/html5ad/template/1/body"
  -H "Authorization: Bearer {{token}}"

{
    "data": "<!DOCTYPE html><html><head><meta name=\"ad.size\" content=\"width={{size.width}},height={{size.height}}\"></head><body></body></html>",
    "status": 0,
    "message": "Ok"
}

This endpoint retrieves a template parsed into html document. The template fields are populated with mock values.

The API can be used to preview template object before while it is being created. The mock values can be replaced by some real values.

Mock values to be replaced are marked with {{}}. For example: width={{size.width}}

HTTP Request

GET https://api.found.ee/html5ad/api/html5ad/template/<ID>/body

URL Parameters

Parameter	Description
ID	The ID of of the Template to parse and retrieve

Get a List of available Sizes

curl "https://api.found.ee/html5ad/api/html5ad/template/sizes"
  -H "Authorization: Bearer {{token}}"

{
    "data": [
        "Size300x250",
        "Size160x600",
        "Size120x600",
        "Size728x90",
        "Size300x600"
    ],
    "status": 0,
    "message": "Ok"
}

This endpoint retrieves a list of available Ads banner sizes. The API can be used in a Html5 Ad banner size select field.

Size value format: Size{height}x{width}

HTTP Request

GET https://api.found.ee/html5ad/api/html5ad/template/sizes

Create Template Instance

curl -X POST "https://api.found.ee/html5ad/api/html5ad/instance/create"
  -H "Authorization: Bearer {{token}}"
  -H "Content-Type: application/json"
  -d '{"name": "my html5 ad", "advertiserId": 1, "templateId": 1, "fields": { "size": "Size300x250", "widget": ""}}'

{
    "data": {
        "id": 4,
        "name": "Charlotte's Ad",
        "advertiserId": 2715,
        "fields": {
            "size": "Size300x250",
            "widget": "<iframe src=\"https://video-ssl.itunes.apple.com/itunes-assets/Video113/v4/75/15/be/7515be6d-97fd-d250-a195-8fb8a694be84/mzvf_17738180372251070029.640x346.h264lc.U.p.m4v\"></iframe>",
            "backgroundImage": "user/11200/Charlotte's Ad-1575657232826.svg",
            "payload": ""
        },
        "templateId": 1,
        "createDate": "2019-12-06T10:29:31.887"
    },
    "status": 0,
    "message": "Ok"
}

Create an Html5 Ad Template instance. The user (advertiser) should set an Html5 Ad Template id that is used to create an instance. The Html5 Ad Template controls what fields the instance has to have. The Html5 Ad Templates description can be found in Appendix 1

HTTP Request

POST https://api.found.ee/html5ad/api/html5ad/instance/create

Query Request Body

Field	Optional	Description
advertiserId	false	Current advertiser.
templateId	false	Html5 Ad Template Id to use for current instances.
name	false	Template instance name.
fields	false	A map of to populate the template instance. Fields are described in the template and can vary from one template to another.

Get Template Instances List

curl -X POST "https://api.found.ee/html5ad/api/html5ad/instance"
  -H "Authorization: Bearer {{token}}"
  -H "Content-Type: application/json"
  -d '{"page": 0, "size": 10, "advertiserId": 2715}'

{
    "meta": {
        "totalRows": 12,
        "totalPages": 2
    },
    "data": [
        {
            "id": 5,
            "name": "Charlotte's Ad 1",
            "advertiserId": 2715,
            "fields": {},
            "templateId": 1,
            "createDate": "2019-12-06T10:29:31.998"
        },
        {
            "id": 4,
            "name": "Charlotte's Ad 2",
            "advertiserId": 2715,
            "fields": {},
            "templateId": 1,
            "createDate": "2019-12-06T10:29:31.887"
        }
    ],
    "status": 0,
    "message": "Ok"
}

This endpoint retrieves a list of template instances for the current user (advertiser).

HTTP Request

POST https://api.found.ee/html5ad/api/html5ad/instance

Query Request Body

Field	Optional	Default value	Description
page	true	0	Page number.
size	false		Page size.
advertiserId	false		Advertiser created the instances.
templateId	true		Html5 Ad Template Id to filter instances.
name	true		Template instance name to filter instances.
dateFrom	true		Field to filter instances by create date. Show instances created after the date.
dateTo	true		Field to filter instances by create date. Show instances created before the date.
sortBy	true	createDate	Field to sort by (one of: "name"; "createDate").
sortDirection	true	DESC	Sorting direction (one of: "DESC"; "ASC").

Get Template Instance by identifier

curl "https://api.found.ee/html5ad/api/html5ad/instance/1"
  -H "Authorization: Bearer token"

{
    "data": {
        "id": 4,
        "name": "Charlotte's Ad",
        "advertiserId": 2715,
        "fields": {
            "size": "Size300x250",
            "widget": "<iframe src=\"https://video-ssl.itunes.apple.com/itunes-assets/Video113/v4/75/15/be/7515be6d-97fd-d250-a195-8fb8a694be84/mzvf_17738180372251070029.640x346.h264lc.U.p.m4v\"></iframe>",
            "backgroundImage": "user/11200/Charlotte's Ad-1575657232826.svg",
            "payload": ""
        },
        "templateId": 1,
        "createDate": "2019-12-06T10:29:31.887"
    },
    "status": 0,
    "message": "Ok"
}

This endpoint retrieves a specific Html5 Ad template instance by identifier.

HTTP Request

GET https://api.found.ee/html5ad/api/html5ad/instance/<ID>

URL Parameters

Parameter	Description
ID	The ID of the Template instance to retrieve

Get Template Instance body by identifier

curl "https://api.found.ee/html5ad/api/html5ad/instance/1/body"
  -H "Authorization: Bearer token"

{
    "data": "<!DOCTYPE html>
            <html>
               <head>
                <meta name=\"ad.size\" content=\"width=300,height=250\">  
                <style></style>
                <script type=\"text/javascript\">
                    var foundeeProps = {ad: '4'};
                </script>
                </head>
            <body onclick=\"sendFoundeeEvent('ad_click', window.foundeeProps); window.open(APPNEXUS.getClickTag(), '_blank');\">
            <a>
            <div style=\"
                position: relative;
                background-repeat: no-repeat;
                background-image: url('user/11200/Charlotte's Ad-1575657232826.svg');
                background-size: contain;
                      width: 300px;
                      height: 250px;
            \">
            <div id=\"widget\"></div>
            </div>
            </a>
            <script type=\"text/javascript\">
            </script>
          </body>
          </html>
    ",
    "status": 0,
    "message": "Ok"
}

This endpoint retrieves a specific Html5 Ad template instance body. The endpoint can be used to preview the instance banner body.

HTTP Request

GET https://api.found.ee/html5ad/api/html5ad/instance/<ID>/body

URL Parameters

Parameter	Description
ID	The ID of the Template instance to retrieve

Update Template Instance

curl -X POST "https://api.found.ee/html5ad/api/html5ad/instance/4/update"
  -H "Authorization: Bearer {{token}}"
  -H "Content-Type: application/json"
  -d '{"name": "my html5 ad", "advertiserId": 1, "templateId": 1, "fields": { "size": "Size300x250", "widget": ""}}'

{
    "data": {
        "id": 4,
        "name": "Charlotte's Ad",
        "advertiserId": 2715,
        "fields": {
            "size": "Size300x250",
            "widget": "<iframe src=\"https://video-ssl.itunes.apple.com/itunes-assets/Video113/v4/75/15/be/7515be6d-97fd-d250-a195-8fb8a694be84/mzvf_17738180372251070029.640x346.h264lc.U.p.m4v\"></iframe>",
            "backgroundImage": "user/11200/Charlotte's Ad-1575657232826.svg",
            "payload": ""
        },
        "templateId": 1,
        "createDate": "2019-12-06T10:29:31.887"
    },
    "status": 0,
    "message": "Ok"
}

Update an Html5 Ad Template instance. The Html5 Ad Template controls what fields the instance has to have. The Html5 Ad Templates description can be found in Appendix 1

HTTP Request

POST https://api.found.ee/html5ad/api/html5ad/instance/<ID>/update

URL Parameters

Parameter	Description
ID	The ID of the Template instance to update

Query Request Body

Field	Optional	Description
advertiserId	false	Current advertiser.
templateId	false	Html5 Ad Template Id to use for current instances.
name	false	Template instance name.
fields	false	A map of to populate the template instance. Fields are described in the template and can vary from one template to another.

Delete Template Instance

curl -X POST "https://api.found.ee/html5ad/api/html5ad/instance/4/delete"
  -H "Authorization: Bearer {{token}}"

Delete Html5 Ad Instance by Identifier. The instance cannot be deleted if it is used as active creative in any Advertising Campaign.

HTTP Request

POST https://api.found.ee/html5ad/api/html5ad/instance/<ID>/delete

URL Parameters

Parameter	Description
ID	The ID of the Template instance to delete

Download Html5 Ad Instance as zip Archive

curl -X POST "https://api.found.ee/html5ad/api/html5ad/instance/4/download"
  -H "Authorization: Bearer {{token}}"

Download Html5 Ad Banner archive file by Identifier. The Archive includes all the files that are part of the Html5 Ad Instance.

HTTP Request

POST https://api.found.ee/html5ad/api/html5ad/instance/<ID>/download

URL Parameters

Parameter	Description
ID	The ID of the Template instance to download

curl -X POST "https://api.found.ee/html5ad/api/html5ad/instance/4/shared/link"
  -H "Authorization: Bearer {{token}}"
  -H "Content-Type: application/json"
  -d '{"advertiserId": 1}'

Returns a link to the Html5 Ad banner preview page. The page can be accessed without authorization.

HTTP Request

POST "https://api.found.ee/html5ad/api/html5ad/instance/<ID>/shared/link

URL Parameters

Parameter	Description
ID	The ID of the Template instance to share

Query Request Body

Field	Optional	Default value	Description
advertiserId	false		Current advertiser.

Advertising Campaign Service

The Subsystem is used to create and fire Advertising Campaign that targets some audiences.

Each campaign should include at least Creative (media/digital asset) attached to it. Types of Creatives:

Banner Image file
Audio/Video file
HTML5 zip archive

List operating systems

The endpoint returns a list of operating system objects supported for ad targeting.

curl -X POST "https://api.found.ee/ad/api/1.0/os/get"
  -H "Authorization: Bearer token"
  -H "Content-Type: application/json"
  -d '{"page": 0, "size": 10}'

{
  "data":
  [
    {
      "id": 1,
      "name": "Windows"
    },
    {
      "id": 2,
      "name": "Android"
    },
    {
      "id": 3,
      "name": "iOS"
    }
  ],
  "meta":
  {
    "totalRows": 3,
    "totalPages": 1
  },
  "message": "Ok",
  "status": 0
}

HTTP Request

POST https://api.found.ee/ad/api/1.0/os/get

Query Request Body

Field	Optional	Type	Default value	Description
page	true	integer	0	Zero-based page index.
size	true	integer	100	Size of the page to return.
sortBy	true	string		Field to sort result by. Can be one of `id`, `name`.
sortDirection	true	string	`ASC`	Direction of the sort. Can be one of `ASC` or `DESC`. If `sortBy` is not specified, `sortDirection` value is ignored.

Returns Operating system information object

List countries

The endpoint returns a list of country objects supported for ad targeting.

curl -X POST "https://api.found.ee/ad/api/1.0/country/get"
  -H "Authorization: Bearer token"
  -H "Content-Type: application/json"
  -d '{"page": 0, "size": 5}'

{
  "meta":
  {
    "totalRows": 246,
    "totalPages": 1
  },
  "data":
  [
    {
      "code": "AF",
      "country": "Afghanistan"
    },
    {
      "code": "AX",
      "country": "Aland Islands"
    },
    {
      "code": "AL",
      "country": "Albania"
    },
    {
      "code": "DZ",
      "country": "Algeria"
    },
    {
      "code": "AS",
      "country": "American Samoa"
    }
  ],
  "status": 0,
  "message": "Ok"
}

HTTP Request

POST https://api.found.ee/ad/api/1.0/country/get

Query Request Body

Field	Optional	Type	Default value	Description
page	true	integer	0	Zero-based page index.
size	true	integer	100	Size of the page to return.
sortBy	true	string		Field to sort result by. Can be one of `code`, `name`.
sortDirection	true	string	`ASC`	Direction of the sort. Can be one of `ASC` or `DESC`. If `sortBy` is not specified, `sortDirection` value is ignored.

Returns Country object

List countries by Found.ee IDs

The endpoint returns a list of country objects supported for ad targeting filtered by Found.ee IDs.

curl -X POST "https://api.found.ee/ad/api/1.0/country/get/by/ids"
  -H "Authorization: Bearer token"
  -H "Content-Type: application/json"
  -d '{"countryIds": ["AF", "AX", "AL", "DZ", "AS"], "page": 0, "size": 5}'

{
  "meta":
  {
    "totalRows": 246,
    "totalPages": 1
  },
  "data":
  [
    {
      "code": "AF",
      "country": "Afghanistan"
    },
    {
      "code": "AX",
      "country": "Aland Islands"
    },
    {
      "code": "AL",
      "country": "Albania"
    },
    {
      "code": "DZ",
      "country": "Algeria"
    },
    {
      "code": "AS",
      "country": "American Samoa"
    }
  ],
  "status": 0,
  "message": "Ok"
}

HTTP Request

POST https://api.found.ee/ad/api/1.0/country/get/by/ids

Query Request Body

Field	Optional	Type	Default value	Description
countryIds	false	array of string		Array of ISO 3166-1 alpha-2 code 2-letter country codes.
page	true	integer	0	Zero-based page index.
size	true	integer	100	Size of the page to return.
sortBy	true	string		Field to sort result by. Can be one of `code`, `name`.
sortDirection	true	string	`ASC`	Direction of the sort. Can be one of `ASC` or `DESC`. If `sortBy` is not specified, `sortDirection` value is ignored.

Returns Country object

List regions

The endpoint returns a list of region objects supported for ad targeting.

curl -X POST "https://api.found.ee/ad/api/1.0/region/get"
  -H "Authorization: Bearer token"
  -H "Content-Type: application/json"
  -d '{"countryCode": "NO", "page": 0, "size": 10}'

{
  "meta":
  {
    "totalRows": 3,
    "totalPages": 1
  },
  "data":
  [
    {
      "id": 2779,
      "name": "Akershus",
      "code": "02",
      "countryId": "NO"
    },
    {
      "id": 2780,
      "name": "Aust-Agder",
      "code": "09",
      "countryId": "NO"
    },
    {
      "id": 2781,
      "name": "Buskerud",
      "code": "06",
      "countryId": "NO"
    }
  ],
  "status": 0,
  "message": "Ok"
}

HTTP Request

POST https://api.found.ee/ad/api/1.0/region/get

Query Request Body

Field	Optional	Type	Default value	Description
countryCode	false	string		ISO 3166-1 alpha-2 code 2-letter country code.
page	true	integer	0	Zero-based page index.
size	true	integer	100	Size of the page to return.
sortBy	true	string		Field to sort result by. Can be one of `id`, `code`, `name`, `countryId`.
sortDirection	true	string	`ASC`	Direction of the sort. Can be one of `ASC` or `DESC`. If `sortBy` is not specified, `sortDirection` value is ignored.

Returns Region object

List regions by Found.ee IDs

The endpoint returns a list of region objects supported for ad targeting filtered by Found.ee IDs.

curl -X POST "https://api.found.ee/ad/api/1.0/region/get/by/ids"
  -H "Authorization: Bearer token"
  -H "Content-Type: application/json"
  -d '{"regionIds": [2779, 2780, 2781], "page": 0, "size": 10}'

{
  "meta":
  {
    "totalRows": 3,
    "totalPages": 1
  },
  "data":
  [
    {
      "id": 2779,
      "name": "Akershus",
      "code": "02",
      "countryId": "NO"
    },
    {
      "id": 2780,
      "name": "Aust-Agder",
      "code": "09",
      "countryId": "NO"
    },
    {
      "id": 2781,
      "name": "Buskerud",
      "code": "06",
      "countryId": "NO"
    }
  ],
  "status": 0,
  "message": "Ok"
}

HTTP Request

POST https://api.found.ee/ad/api/1.0/region/get/by/ids

Query Request Body

Field	Optional	Type	Default value	Description
regionIds	false	array of integer		Array of Found.ee region IDs.
page	true	integer	0	Zero-based page index.
size	true	integer	100	Size of the page to return.
sortBy	true	string		Field to sort result by. Can be one of `id`, `code`, `name`, `countryId`.
sortDirection	true	string	`ASC`	Direction of the sort. Can be one of `ASC` or `DESC`. If `sortBy` is not specified, `sortDirection` value is ignored.

Returns Region object

List cities

The endpoint returns a list of city objects supported for ad targeting.

curl -X POST "https://api.found.ee/ad/api/1.0/city/get/active"
  -H "Authorization: Bearer token"
  -H "Content-Type: application/json"
  -d '{"name": "Oslo", "countryCode": "NO", "regionIds": [2789],"page": 0, "size": 10}'

{
  "meta":
  {
    "totalRows": 1,
    "totalPages": 1
  },
  "data":
  [
    {
      "id": 145838,
      "name": "Oslo",
      "countryId": "NO",
      "regionId": 2789
    }
  ],
  "status": 0,
  "message": "Ok"
}

HTTP Request

POST https://api.found.ee/ad/api/1.0/city/get/active

Query Request Body

Field	Optional	Type	Default value	Description
name	true	string		City name.
countryCode	false	string		ISO 3166-1 alpha-2 code 2-letter country code.
regionIds	true	array of integer	empty array	Array of region Found.ee IDs.
page	true	integer	0	Zero-based page index.
size	true	integer	100	Size of the page to return.
sortBy	true	string		Field to sort result by. Can be one of `id`, `name`, `countryId`, `regionId`.
sortDirection	true	string	`ASC`	Direction of the sort. Can be one of `ASC` or `DESC`. If `sortBy` is not specified, `sortDirection` value is ignored.

Returns City object

List cities by Found.ee IDs

The endpoint returns a list of city objects supported for ad targeting filtered by Found.ee IDs.

curl -X POST "https://api.found.ee/ad/api/1.0/city/get/by/ids"
  -H "Authorization: Bearer token"
  -H "Content-Type: application/json"
  -d '{"cityIds": [145838],"page": 0, "size": 10}'

{
  "meta":
  {
    "totalRows": 1,
    "totalPages": 1
  },
  "data":
  [
    {
      "id": 145838,
      "name": "Oslo",
      "countryId": "NO",
      "regionId": 2789
    }
  ],
  "status": 0,
  "message": "Ok"
}

HTTP Request

POST https://api.found.ee/ad/api/1.0/city/get/by/ids

Query Request Body

Field	Optional	Type	Default value	Description
cityIds	false	array of integer		Array of city Found.ee IDs.
page	true	integer	0	Zero-based page index.
size	true	integer	100	Size of the page to return.
sortBy	true	string		Field to sort result by. Can be one of `id`, `name`, `countryId`, `regionId`.
sortDirection	true	string	`ASC`	Direction of the sort. Can be one of `ASC` or `DESC`. If `sortBy` is not specified, `sortDirection` value is ignored.

Returns City object

List DMAs

The endpoint returns a list of DMA objects supported for ad targeting.

curl -X POST "https://api.found.ee/ad/api/1.0/dma/get"
  -H "Authorization: Bearer token"
  -H "Content-Type: application/json"
  -d '{"countryCode": "NO", "page": 0, "size": 10}'

{
  "meta":
  {
    "totalRows": 1,
    "totalPages": 1
  },
  "data":
  [
    {
      "id": 2458,
      "name": "Oslo",
      "countryId": "NO",
      "code": "Oslo"
    }
  ],
  "status": 0,
  "message": "Ok"
}

HTTP Request

POST https://api.found.ee/ad/api/1.0/dma/get

Query Request Body

Field	Optional	Type	Default value	Description
countryCode	false	string		ISO 3166-1 alpha-2 code 2-letter country code.
page	true	integer	0	Zero-based page index.
size	true	integer	100	Size of the page to return.
sortBy	true	string		Field to sort result by. Can be one of `id`, `name`, `countryId`, `code`.
sortDirection	true	string	`ASC`	Direction of the sort. Can be one of `ASC` or `DESC`. If `sortBy` is not specified, `sortDirection` value is ignored.

Returns DMA object

List DMAs by Found.ee IDs

The endpoint returns a list of DMA objects supported for ad targeting filtered by Found.ee IDs.

curl -X POST "https://api.found.ee/ad/api/1.0/dma/get/by/ids"
  -H "Authorization: Bearer token"
  -H "Content-Type: application/json"
  -d '{"dmaIds": [2458],"page": 0, "size": 10}'

{
  "meta":
  {
    "totalRows": 1,
    "totalPages": 1
  },
  "data":
  [
    {
      "id": 2458,
      "name": "Oslo",
      "countryId": "NO",
      "code": "Oslo"
    }
  ],
  "status": 0,
  "message": "Ok"
}

HTTP Request

POST https://api.found.ee/ad/api/1.0/dma/get/by/ids

Query Request Body

Field	Optional	Type	Default value	Description
dmaIds	false	array of integer		Array of DMA Found.ee IDs.
page	true	integer	0	Zero-based page index.
size	true	integer	100	Size of the page to return.
sortBy	true	string		Field to sort result by. Can be one of `id`, `name`, `countryId`, `code`.
sortDirection	true	string	`ASC`	Direction of the sort. Can be one of `ASC` or `DESC`. If `sortBy` is not specified, `sortDirection` value is ignored.

Returns DMA object

List postal codes

The endpoint returns a list of postal code objects supported for ad targeting.

curl -X POST "https://api.found.ee/ad/api/1.0/postal_code/get"
  -H "Authorization: Bearer token"
  -H "Content-Type: application/json"
  -d '{"id": [195476],"page": 0, "size": 10}'

{
  "meta":
  {
    "totalRows": 1,
    "totalPages": 1
  },
  "data":
  [
    {
      "id": 195476,
      "code": "0661",
      "countryId": "NO"
    }
  ],
  "status": 0,
  "message": "Ok"
}

HTTP Request

POST https://api.found.ee/ad/api/1.0/postal_code/get

Query Request Body

Field	Optional	Type	Default value	Description
id	true	array of integer		Array of postal code Found.ee IDs.
codes	true	array of string		Array of postal codes.
countryCode	true	string		Country code.
page	true	integer	0	Zero-based page index.
size	true	integer	100	Size of the page to return.
sortBy	true	string		Field to sort result by. Can be one of `id`, `countryId`, `code`.
sortDirection	true	string	`ASC`	Direction of the sort. Can be one of `ASC` or `DESC`. If `sortBy` is not specified, `sortDirection` value is ignored.

Returns Postal code object

List inventory lists

The endpoint returns a list of inventory list objects with meta information supported for ad targeting.

curl -X POST "https://api.found.ee/ad/api/1.0/inventory_list/get/withMeta"
  -H "Authorization: Bearer token"
  -H "Content-Type: application/json"
  -d '{"page": 0, "size": 10}'

{
  "meta":
  {
    "totalRows": 3,
    "totalPages": 1
  },
  "data":
  [
    {
      "id": 11236,
      "name": "ALL MUSIC - MAX CLICKS",
      "urlType": "WHITELIST",
      "type": "DISCOVERY",
      "category": "MUSIC",
      "domainsCount": 511,
      "props":
      {
        "description": "AUTO-OPTIMIZED TO MAXIMIZE CLICKS AND LOWER CPCs ON ALL MUSIC MUSIC WEBSITES WITH ENHANCED MUSIC FAN TARGETING.",
        "cost": "AVG. CPC $0.06 - $0.30"
      }
    },
    {
      "id": 11251,
      "name": "ALL MUSIC - PREMIUM SITES",
      "urlType": "WHITELIST",
      "type": "PREMIUM",
      "category": "MUSIC",
      "domainsCount": 177,
      "props":
      {
        "description": "AUTO-OPTIMIZED FOR MAXIMUM IMPRESSIONS AND VIEWABILITY ON THE MOST INFLUENTIAL ALL MUSIC WEBSITES",
        "example": "PASTE, BILLBOARD, XLR8R.",
        "cost": "AVG. CPM < $5"
      }
    },
    {
      "id": 11311,
      "name": "AMERICANA - MAX CLICKS",
      "urlType": "WHITELIST",
      "type": "DISCOVERY",
      "category": "MUSIC",
      "domainsCount": 310,
      "props":
      {
        "description": "AUTO-OPTIMIZED TO MAXIMIZE CLICKS AND LOWER CPCs ON AMERICANA MUSIC WEBSITES WITH ENHANCED AMERICANA MUSIC FAN TARGETING.",
        "cost": "AVG. CPC $0.06 - $0.30"
      }
    }
  ],
  "status": 0,
  "message": "Ok"
}

HTTP Request

POST https://api.found.ee/ad/api/1.0/inventory_list/get/withMeta

Query Request Body

Field	Optional	Type	Default value	Description
page	true	integer	0	Zero-based page index.
size	true	integer	100	Size of the page to return.
sortBy	true	string		Field to sort result by. Can be one of `id`, `name`.
sortDirection	true	string	`ASC`	Direction of the sort. Can be one of `ASC` or `DESC`. If `sortBy` is not specified, `sortDirection` value is ignored.

Returns Inventory list object

Get inventory list by ID

The endpoint returns the inventory list object extended information by its Found.ee ID.

curl -X GET "https://api.found.ee/ad/api/1.0/inventory_list/get/11236"
  -H "Authorization: Bearer token"
  -H "Content-Type: application/json"

{
  "data":
  {
    "id": 11236,
    "name": "ALL MUSIC - MAX CLICKS",
    "urlType": "WHITELIST",
    "type": "DISCOVERY",
    "category": "MUSIC",
    "domainsCount": 511,
    "props":
    {
      "description": "AUTO-OPTIMIZED TO MAXIMIZE CLICKS AND LOWER CPCs ON ALL MUSIC MUSIC WEBSITES WITH ENHANCED MUSIC FAN TARGETING.",
      "cost": "AVG. CPC $0.06 - $0.30"
    }
  },
  "status": 0,
  "message": "Ok"
}

HTTP Request

GET https://api.found.ee/ad/api/1.0/inventory_list/get/{id}

Query parameters

Field	Optional	Type	Default value	Description
id	false	integer		Found.ee ID of the inventory list.

Returns Extended Inventory List object

List interest segments

The endpoint returns all interest segments information.

curl -X GET "https://api.found.ee/ad/api/1.0/segment/interests"
  -H "Authorization: Bearer token"
  -H "Content-Type: application/json"

{
  "meta":
  {
    "totalRows": 3,
    "totalPages": 1
  },
  "data":
  [
    {
      "id": 179,
      "name": "AARP",
      "type": "Behavioral",
      "size": 68943273
    },
    {
      "id": 180,
      "name": "Accounting And Tax Service",
      "type": "Interest",
      "size": 5052641
    },
    {
      "id": 181,
      "name": "Action/Adventure Movie",
      "type": "Behavioral",
      "size": 183488752
    }
  ],
  "status": 0,
  "message": "Ok"
}

HTTP Request

GET https://api.found.ee/ad/api/1.0/segment/interests

Returns Extended interest segment object

Get interest segment by IDs

The endpoint returns interest segments information by Found.ee IDs.

curl -X POST "https://api.found.ee/ad/api/1.0/segment/interests/ids"
  -H "Authorization: Bearer token"
  -H "Content-Type: application/json"
  -d '{"ids": [179, 180, 181]}'

{
  "meta":
  {
    "totalRows": 3,
    "totalPages": 1
  },
  "data":
  [
    {
      "id": 179,
      "name": "AARP",
      "type": "Behavioral",
      "size": 68943273
    },
    {
      "id": 180,
      "name": "Accounting And Tax Service",
      "type": "Interest",
      "size": 5052641
    },
    {
      "id": 181,
      "name": "Action/Adventure Movie",
      "type": "Behavioral",
      "size": 183488752
    }
  ],
  "status": 0,
  "message": "Ok"
}

HTTP Request

POST https://api.found.ee/ad/api/1.0/segment/interests/ids

Query Request Body

Field	Optional	Type	Default value	Description
ids	false	array of integer		Array of interest segment Found.ee IDs.

Returns Extended interest segment object

List deals

The endpoint returns a list of deal objects supported for ad targeting.

curl -X POST "https://api.found.ee/ad/api/1.0/deal/get"
  -H "Authorization: Bearer token"
  -H "Content-Type: application/json"
  -d '{"sellerName": "SPOTIFY", "page": 0, "size": 10}'

{
  "meta":
  {
    "totalRows": 3,
    "totalPages": 1
  },
  "data":
  [
    {
      "id": 514031,
      "name": "Spotify - Genre:  Classical"
    },
    {
      "id": 514048,
      "name": "Spotify - Playlists:  Party"
    },
    {
      "id": 514034,
      "name": "Spotify - Genre:  Funk"
    }
  ],
  "status": 0,
  "message": "Ok"
}

HTTP Request

POST https://api.found.ee/ad/api/1.0/deal/get

Query Request Body

Field	Optional	Type	Default value	Description
sellerName	false	Deal seller		Deal seller name.
id	true	array if integer	empty array	Array of deal Found.ee IDs.
page	true	integer	0	Zero-based page index.
size	true	integer	100	Size of the page to return.
sortBy	true	string		Field to sort result by. Can be one of `id`,`name`.
sortDirection	true	string	`ASC`	Direction of the sort. Can be one of `ASC` or `DESC`. If `sortBy` is not specified, `sortDirection` value is ignored.

Returns Deal object

List deals by Found.ee IDs

The endpoint returns a list of deal objects supported for ad targeting filtered by Found.ee IDs.

curl -X POST "https://api.found.ee/ad/api/1.0/deal/get/by/ids"
  -H "Authorization: Bearer token"
  -H "Content-Type: application/json"
  -d '{"id": [514031, 514048, 514034], "page": 0, "size": 10}'

{
  "meta":
  {
    "totalRows": 3,
    "totalPages": 1
  },
  "data":
  [
    {
      "id": 514031,
      "name": "Spotify - Genre:  Classical"
    },
    {
      "id": 514048,
      "name": "Spotify - Playlists:  Party"
    },
    {
      "id": 514034,
      "name": "Spotify - Genre:  Funk"
    }
  ],
  "status": 0,
  "message": "Ok"
}

HTTP Request

POST https://api.found.ee/ad/api/1.0/deal/get/by/ids

Query Request Body

Field	Optional	Type	Default value	Description
id	false	array of integer		Array of Found.ee deal IDs.
page	true	integer	0	Zero-based page index.
size	true	integer	100	Size of the page to return.
sortBy	true	string		Field to sort result by. Can be one of `id`, `name`.
sortDirection	true	string	`ASC`	Direction of the sort. Can be one of `ASC` or `DESC`. If `sortBy` is not specified, `sortDirection` value is ignored.

Returns Deal object

Create profile

The endpoint is used to create a targeting profile.

curl -X POST "https://api.found.ee/ad/api/1.0/profile/create"
  -H "Authorization: Bearer token"
  -H "Content-Type: application/json"
  -d '{"name": "my profile", "advertiserId": 10, "countryTargets": { "countries": ["US", "CA"], "action": "INCLUDE" }}'

{
  "data":
  {
    "advertiserId": 10,
    "countryTargets": {
      "action": "INCLUDE",
      "countries": [
        "US", "CA"
      ]
    },
    "createDate": "2020-01-15T16:29:43.565",
    "id": 111,
    "inventoryItemTarget": null,
    "maxDayImpressions": null,
    "maxHourImpressions": null,
    "maxLifetimeImpressions": null,
    "maxMonthImpressions": null,
    "maxWeekImpressions": null,
    "name": "my profile",
    "operatingSystemTargets": null,
    "updateDate": "2020-01-15T16:29:43.565",
    "urlList": null,
    "segmentGroupTarget": null,
    "dealTargets": null,
    "contentCategoryGroupTarget": null,
    "cityTarget": null,
    "genderTarget": null,
    "ageTarget": null,
    "interestsTarget": [],
    "regionTarget": null,
    "dmaTarget": null,
    "postalCodeTarget": null
  },
  "message": "Ok",
  "status": 0
}

HTTP Request

POST https://api.found.ee/ad/api/1.0/profile/create

Query Request Body

Field	Optional	Type	Default value	Description
name	false	string		Profile name.
advertiserId	false	integer		Found.ee ID of the advertiser
urlList	true	URLs list		Information about URLs list targeting
operatingSystemTarget	true	Operating system target		Information about operating system targeting
countryTargets	true	Country target		Information about country targeting
segmentGroupTarget	true	Segment group target		Information about segment group targeting
dealTargets	true	array of integer		List of Found.ee IDs of deals.
cityTarget	true	City target		Information about city targeting
regionTarget	true	Region target		Information about region targeting
dmaTarget	true	DMA target		Information about DMA targeting
postalCodeTarget	true	array of integer		List of Found.ee IDs of postal codes.
inventoryItemTarget	true	integer		Found.ee ID of inventory item.
genderTarget	true	Gender target		Information about gender targeting
ageTarget	true	Age target		Information about age targeting
interestsTarget	true	Array of Interest target	empty array	Information about interest targeting
maxLifetimeImpressions	true	integer		The maximum number of impressions per person. If set, this value must be between 0 and 255.
maxDayImpressions	true	integer		The maximum number of impressions per person per day. If set, this value must be between 0 and 255.
maxHourImpressions	true	integer		The maximum number of impressions per person per hour. If set, this value must be between 0 and 255.
maxWeekImpressions	true	integer		The maximum number of impressions per person per week. If set, this value must be between 0 and 255.
maxMonthImpressions	true	integer		The maximum number of impressions per person per month. If set, this value must be between 0 and 255.

Returns Profile information object

Update profile

The endpoint is used to update an existing targeting profile.

curl -X POST "https://api.found.ee/ad/api/1.0/profile/update"
  -H "Authorization: Bearer token"
  -H "Content-Type: application/json"
  -d '{"id": 111, "name": "my profile", "advertiserId": 10, "countryTargets": { "countries": ["US", "CA"], "action": "INCLUDE" }}'

{
  "data":
  {
    "advertiserId": 10,
    "countryTargets":
    {
      "action": "INCLUDE",
      "countries":
      [
        "US", "CA"
      ]
    },
    "inventoryItemTarget": null,
    "maxDayImpressions": null,
    "maxHourImpressions": null,
    "maxLifetimeImpressions": null,
    "maxMonthImpressions": null,
    "maxWeekImpressions": null,
    "name": "my profile",
    "operatingSystemTargets": null,
    "updateDate": "2020-01-15T16:29:43.565",
    "urlList": null,
    "segmentGroupTarget": null,
    "dealTargets": null,
    "contentCategoryGroupTarget": null,
    "cityTarget": null,
    "genderTarget": null,
    "ageTarget": null,
    "interestsTarget": [],
    "regionTarget": null,
    "dmaTarget": null,
    "postalCodeTarget": null
  },
  "message": "Ok",
  "status": 0
}

HTTP Request

POST https://api.found.ee/ad/api/1.0/profile/update

Query Request Body

Field	Optional	Type	Default value	Description
id	false	integer		Found.ee ID of the profile.
name	false	string		Profile name.
advertiserId	false	integer		Found.ee ID of the advertiser. This ID can't be changed in update
urlList	true	URLs list		Information about URLs list targeting
operatingSystemTarget	true	Operating system target		Information about operating system targeting
countryTargets	true	Country target		Information about country targeting
segmentGroupTarget	true	Segment group target		Information about segment group targeting
dealTargets	true	array of integer		List of Found.ee IDs of deals.
cityTarget	true	City target		Information about city targeting
regionTarget	true	Region target		Information about region targeting
dmaTarget	true	DMA target		Information about DMA targeting
postalCodeTarget	true	array of integer		List of Found.ee IDs of postal codes.
inventoryItemTarget	true	integer		Found.ee ID of inventory item.
genderTarget	true	Gender target		Information about gender targeting
ageTarget	true	Age target		Information about age targeting
interestsTarget	true	Array of Interest target	empty array	Information about interest targeting
maxLifetimeImpressions	true	integer		The maximum number of impressions per person. If set, this value must be between 0 and 255.
maxDayImpressions	true	integer		The maximum number of impressions per person per day. If set, this value must be between 0 and 255.
maxHourImpressions	true	integer		The maximum number of impressions per person per hour. If set, this value must be between 0 and 255.
maxWeekImpressions	true	integer		The maximum number of impressions per person per week. If set, this value must be between 0 and 255.
maxMonthImpressions	true	integer		The maximum number of impressions per person per month. If set, this value must be between 0 and 255.

Returns Profile information object

Get profiles

The endpoint is used to lookup existing profiles by their Found.ee IDs.

curl -X POST "https://api.found.ee/ad/api/1.0/profile/get"
  -H "Authorization: Bearer token"
  -H "Content-Type: application/json"
  -d '{"id": [111], "page": 0, "size": 10, "sortBy": "createDate", "sortDirection": "DESC"}'

{
  "data":
  [
    {
      "advertiserId": 10,
      "ageTarget":
      {
        "ageRange":
        [
          "Range_18_24"
        ],
        "allowUnknown": true
      },
      "cityTarget":
      {
        "action": "INCLUDE",
        "ids":
        [
          11,
          12
        ]
      },
      "contentCategoryGroupTarget":
      {
        "allowUnknown": true,
        "contentCategories":
        [
          {
            "action": "INCLUDE",
            "id": 20
          }
        ]
      },
      "countryTargets":
      {
        "action": "INCLUDE",
        "countries":
        [
          "US",
          "CA"
        ]
      },
      "createDate": "2020-01-15T16:29:43.565",
      "dealTargets":
      [
        30
      ],
      "dmaTarget":
      {
        "action": "INCLUDE",
        "ids":
        [
          40
        ]
      },
      "genderTarget":
      {
        "allowUnknown": true,
        "gender": "MALE"
      },
      "id": 111,
      "interestsTarget":
      [
        {
          "id": 17,
          "name": "Health",
          "size": 1234,
          "type": "health"
        }
      ],
      "inventoryItemTarget": null,
      "maxDayImpressions": 10,
      "maxHourImpressions": 10,
      "maxLifetimeImpressions": 10,
      "maxMonthImpressions": 10,
      "maxWeekImpressions": 10,
      "name": "my profile",
      "operatingSystemTargets":
      {
        "action": "INCLUDE",
        "ids":
        [
          22,
          23
        ]
      },
      "postalCodeTarget":
      [
        11,
        12
      ],
      "regionTarget":
      {
        "action": "INCLUDE",
        "ids":
        [
          44,
          45
        ]
      },
      "segmentGroupTarget":
      {
        "segmentBooleanOperator": "AND",
        "segmentGroups":
        [
          {
            "booleanOperator": "AND",
            "segments":
            [
              {
                "action": "INCLUDE",
                "id": 56
              }
            ]
          }
        ]
      },
      "updateDate": "2020-01-15T16:29:43.565",
      "urlList":
      {
        "type": "WHITELIST",
        "urls":
        [
          "cnn.com"
        ]
      }
    }
  ],
  "meta":
  {
    "totalRows": 1,
    "totalPages": 1
  },
  "message": "Ok",
  "status": 0
}

HTTP Request

POST https://api.found.ee/ad/api/1.0/profile/get

Query Request Body

Field	Optional	Type	Default value	Description
id	false	array of integer		Found.ee IDs of profiles to lookup.
page	true	integer	0	Zero-based page index.
size	true	integer	100	Size of the page to return.
sortBy	true	string		Field to sort result by. Can be one of `id`, `createDate`, `updateDate`.
sortDirection	true	string	`ASC`	Direction of the sort. Can be one of `ASC` or `DESC`. If `sortBy` is not specified, `sortDirection` value is ignored.

Returns Profile information object

Upload media file

curl -X POST "https://api.found.ee/ad/api/1.0/creative/upload?duration=0" \
  -H "Authorization: Bearer token" \
  -H "Content-Type: multipart/form-data" \
  -F "file=@filename.jpg;type=image/jpeg"

{
  "data": {
    "duration": 0,
    "fileName": "filename.jpg",
    "mediaAssetId": 111,
    "mediaAssetUrl": null
  },
  "message": "string",
  "status": 0
}

The endpoint uploads media file to Found.ee storage.

HTTP Request

POST https://api.found.ee/ad/api/1.0/creative/upload

Query parameters

Field	Optional	Type	Default value	Description
duration	false	integer		Duration in milliseconds for audio file type. Pass 0 if file is not an audio file.

Returns the Media asset object information.

Create creative

curl -X POST "https://api.found.ee/ad/api/1.0/creative/create"
  -H "Authorization: Bearer token"
  -H "Content-Type: application/json"
  -d '{
    "name": "test_creative",
    "advertiserId": 1,
    "type": "IMAGE",
    "width": 640,
    "height": 480,
    "content": "",
    "fileName": "",
    "clickUrl": "http://test.org",
    "mediaUrl": "http://www.t-e-s-t.org/wp-content/uploads/Marina-w3.jpg"
  }'

{
  "data": {
    "id": 2177,
    "name": "test img creative",
    "advertiserId": 1,
    "width": 640,
    "height": 480,
    "clickUrl": "http://test.org",
    "auditState": "PENDING",
    "state": "ACTIVE",
    "allowAudit": true,
    "campaigns": [],
    "mediaUrl": "https://api.staging.found.ee/ad/media/get/2177/red_dot.jpg",
    "mediaAssetInfo": null,
    "type": "IMAGE",
    "audioType": null,
    "createDate": "2021-06-28T20:36:07.186",
    "updateDate": "2021-06-28T20:36:07.186",
    "auditFeedback": null,
    "payed": false,
    "properties": {}
  },
  "status": 0,
  "message": "Ok"
}

curl -X POST "https://api.found.ee/ad/api/1.0/creative/create" \
  -H "Authorization: Bearer token" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "test img creative",
    "advertiserId": 1,
    "type": "IMAGE",
    "width": 640,
    "height": 480,
    "content": "iVBORw0KGgoAAAANSUhEUgAAAAUAAAAFCAYAAACNbyblAAAAHElEQVQI12P4//8/w38GIAXDIBKE0DHxgljNBAAO9TXL0Y4OHwAAAABJRU5ErkJggg==",
    "fileName": "red_dot.jpg",
    "clickUrl": "http://test.org"
  }'

{
  "data": {
    "id": 2175,
    "name": "test_creative",
    "advertiserId": 1,
    "width": 640,
    "height": 480,
    "clickUrl": "http://test.org",
    "auditState": "PENDING",
    "state": "ACTIVE",
    "allowAudit": true,
    "campaigns": [],
    "mediaUrl": "http://www.t-e-s-t.org/wp-content/uploads/Marina-w3.jpg",
    "mediaAssetInfo": null,
    "type": "IMAGE",
    "audioType": null,
    "createDate": "2021-06-27T16:45:09.337",
    "updateDate": "2021-06-27T16:45:09.337",
    "auditFeedback": null,
    "payed": false,
    "properties": {}
  },
  "status": 0,
  "message": "Ok"
}

curl -X POST "https://api.found.ee/ad/api/1.0/creative/create" \
  -H "Authorization: Bearer token" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "test_creative",
    "advertiserId": 1,
    "type": "AUDIO",
    "audioType":"IHEART",
    "width": 640,
    "height": 480,
    "content": "iVBORw0KGgoAAAANSUhEUgAAAEAAAABACAYAAACqaXHeAAAAAXNSR0IArs4c6QAAAAlwSFlzAAAuIwAALiMBeKU/dgAAAVlpVFh0WE1MOmNvbS5hZG9iZS54bXAAAAAAADx4OnhtcG1ldGEgeG1sbnM6eD0iYWRvYmU6bnM6bWV0YS8iIHg6eG1wdGs9IlhNUCBDb3JlIDUuNC4wIj4KICAgPHJkZjpSREYgeG1sbnM6cmRmPSJodHRwOi8vd3d3LnczLm9yZy8xOTk5LzAyLzIyLXJkZi1zeW50YXgtbnMjIj4KICAgICAgPHJkZjpEZXNjcmlwdGlvbiByZGY6YWJvdXQ9IiIKICAgICAgICAgICAgeG1sbnM6dGlmZj0iaHR0cDovL25zLmFkb2JlLmNvbS90aWZmLzEuMC8iPgogICAgICAgICA8dGlmZjpPcmllbnRhdGlvbj4xPC90aWZmOk9yaWVudGF0aW9uPgogICAgICA8L3JkZjpEZXNjcmlwdGlvbj4KICAgPC9yZGY6UkRGPgo8L3g6eG1wbWV0YT4KTMInWQAABkhJREFUeAHtVl1oXEUUvjNzd5PYpiiGVDc/G7AVagpVVywWhSoK2uLPkw/ig4oQ9cGXgoLoq4pVKAg+SJ8UoagIovRBQYPiQ4SoUCP6YEz2JzWFgumPu5u9d8bvm72zudnc3VbxSWfY2Zl75nxnznznzLk3CHzzDHgGPAOeAc+AZ8Az4BnwDHgGPAOeAc+AZ8Az4BnwDHgGPAOeAc+AZ+D/woDocVAJea81QjS64SSjEUd8r9YP6zBZ+18Kl4Vx9txIn2mnb1N9VzcWswjKkm0gNmb99Prt34vYfvY2ds2YdQO5gd61a9dAvV4/oFQ7kkIEJo6FjYCUOmeM+qlSqaxAl3iXCXY+MTFRCIJ4rxAi1lrEqT0NsbDzc61Wq3ZhnZrdv1AoXIG9bzdGFqU0Tdj5vlqtnkqUrI4DuHF8fHw37Be1li3IBHAg0sANodFa8Hm7UqY5MnLN1/Pz81YHeiZ0BjCS+XhkZGR4fb1+IgzlIQA7yzLhXsowiCL9LBbeRKfUHdLOjYnvU0odJ9ZhnBFitY6ex/NrXViq2P1xkFtB+FvoJaVo0gTG6MbExNjrlUrtJQjoFBc4knR2LYQ5AvszbTFQNiyIHEYplR3j2DyHw38B/U6jITbrfKlUyg0NDR6DTR7+AuQRF2FEG2MuYnY+ju1565Sjuei3n/DPbHFiYJrojaTXE0L/7ChvTBiIeOfOnaM4yLs4eAmYOvb6Lo51RUo5CFJfBAlHEggP3d0u0L7W5jyw6T0iyJrw6YVqdeVoAmoziwdHgD0I0iyPw74N8V5jxM04zGfYmIeaE0LtRzbtxx43AvdRYmgjRRIBUz8JzDngDufzUZH2wlDvQYruAf5ENxbE2wPl8+pO4K8nycA+hYiXWq0YZOiTCXn3JlhGwR3C+oDovwH/SkLIm+D7IawvtTMoOI7n68rl2isJlpnW8dtdARIgVldXEeVgLlEMxsfHzirFNBLnKpXygpMnI522xKXlIBBnYCYY/JvG2lpc37ZNqigKxejo6Er6/qVxnANnI0cDiOLhYnHsbLMZfxuGA480Go0dVEGnz8zM9N5ieXn5NGTsAWrIaSlFg3bwK1cq1RrEJIx4m8IYbXMZwAdrkNcAcysHOE8xnKGMG4vp6WnIOuxj2t2MhD6vzXYQ99XQ0MAa7v0S6kHtzJnVl1PadMY2kGKdkjL/OXAfI+UDZN7D2ObTMFS/tlrNd8JQ7FtZWSkDwMPTvzQBnMupqalBjLjz8ir4rmCLfgxRhrbl8BSmCeBzkDjjUsRtwtGyvrCwwArq1gnp1YjhwZLO1NjkdBpHe+HS0lID0XpI6/gxXINvkPrnkcbDIOEBpPYnqAGOQNruEJgY0sDbmpXLrXcyBFngfM3C2KimHfkX5gIVmb6Zi7jKDyIbTuXzervWeRlF0e+pDeiQawRExWLhAGoEuvgtDMO7ce8LKIK3oT8BIu6CzjOTk5PHy+XyIubuKjgb3aMjyI3d6/Z5SwZs1hKo/qBaXFbELdRFGbgYRS/Kowqur8sYpNSR1teOjY1dDcX04YODB+0rMIhjeYNS4VHUnQ9xbWZ4UBTm92DzZOJXiMxgLQhc4UzkWwbuTyFIdBmwRYcCVwQzF+Fnrh3NgDXgshqiF+LFwXYlbtiXcdwyLKQ4EL9KaM99Q9j3PhVnZ9uEgKwPWq31GUT7FmTOMaT846D/HFT2JX78gI+oH4lxdYPzrAbS8sSgt73JUoLsEhnAyNuC1pfFtG1cOfjeDjD2V3AgZIeOJRPrA2n9ZM5oqcXFxTWk+6OI8ixtgIh96HfAzg7I5lBUn4Ye7/emV1lio3uATftK2pRt3UpZGdABIHlebbX0+4hCNQXsrKdknFqSkAH4djD3w1k4EKeIE8DpXBgaG0Gnn7JhSUCl/wWyeyYnCwdBxm6uwxZqQm6WRRKPDBp1s5qVK7XjjyhqPgnfR6DkPqHpdy/fs2z9I1nfgpOy2E+vX8r2W3Pms2xnyax+z4XEWoj3vsSrj5G0rxi3S59RAhMODg5atvEBI9Jz2KKdVGZkWpIocmp4eN6gPgSJD4xur8hvMVIqBblGY1pgv7+F22LICzwDngHPgGfAM+AZ8Ax4BjwDngHPgGfAM+AZ8Ax4BjwDngHPgGfAM+AZ+M8w8Bfq0JtZInECgQAAAABJRU5ErkJggg==",
    "fileName": "banner_image.jpg",
    "clickUrl": "https://test.org/click/destination",
    "allowAudit": false,
    "mediaUrl": null,
    "mediaAssetId": 14
}'

{
  "data": {
    "id": 2172,
    "name": "example_track.ogg",
    "advertiserId": 1,
    "width": 640,
    "height": 480,
    "clickUrl": "https://test.org/click/destination",
    "auditState": "NO_AUDIT",
    "state": "ACTIVE",
    "allowAudit": false,
    "campaigns": [],
    "mediaUrl": "https://api.found.ee/ad/media/get/2172/banner_image.jpg",
    "mediaAssetInfo": {
      "mediaAssetId": 14,
      "mediaAssetUrl": "https://api.found.ee/ad/media/get/mediaAssetFile/2172",
      "fileName": "Audio Ad So Soon.mp3",
      "duration": 30000
    },
    "type": "AUDIO",
    "audioType": "IHEART",
    "createDate": "2021-06-27T14:36:54.910",
    "updateDate": "2021-06-27T14:36:54.910",
    "auditFeedback": null,
    "payed": false,
    "properties": {}
  },
  "status": 0,
  "message": "Ok"
}

curl -X POST "https://api.found.ee/ad/api/1.0/creative/create"
  -H "Authorization: Bearer token"
  -H "Content-Type: application/json"
  -d '{
    "name": "test_creative",
    "advertiserId": 1,
    "type": "AUDIO",
    "audioType":"IHEART",
    "width": 640,
    "height": 480,
    "content": "",
    "clickUrl": "https://www.iheart.com/podcast/",
    "allowAudit": false,
    "mediaUrl": "https://api.found.ee/ad/media/get/2172/banner_image.jpg",
    "mediaAssetId": 14
}'

{
  "data": {
    "id": 2173,
    "name": "test_creative",
    "advertiserId": 1,
    "width": 640,
    "height": 480,
    "clickUrl": "https://www.iheart.com/podcast/",
    "auditState": "NO_AUDIT",
    "state": "ACTIVE",
    "allowAudit": false,
    "campaigns": [],
    "mediaUrl": "https://api.found.ee/ad/media/get/2172/banner_image.jpg",
    "mediaAssetInfo": {
      "mediaAssetId": 14,
      "mediaAssetUrl": "https://api.staging.found.ee/ad/media/get/mediaAssetFile/2173",
      "fileName": "Audio Ad So Soon.mp3",
      "duration": 30000
    },
    "type": "AUDIO",
    "audioType": "IHEART",
    "createDate": "2021-06-28T14:43:46.582",
    "updateDate": "2021-06-28T14:43:46.582",
    "auditFeedback": null,
    "payed": false,
    "properties": {}
  },
  "status": 0,
  "message": "Ok"
}

The endpoint creates banner or audio Advertising Creatives.

HTTP Request

POST https://api.found.ee/ad/api/1.0/creative/create

Query Request Body

Field	Optional	Type	Default value	Description
name	false	string		Creative name.
advertiserId	false	integer		Found.ee ID of the current advertiser.
type	false	Creative type	Creative type
audioType	true	Creative audio type	Creative audio type
width	false	integer		Banner width in pixels
height	false	integer		Banner height in pixels
content	false	string		Optional Base64 image representation. Pass an empty string if `mediaUrl` is used.
fileName	true	string		Name of the uploaded banner file if `content` field is used.
clickUrl	false	string		Creative's click destination URL.
mediaUrl	true	string		Media file HTTPS URL. Can be used instead of `content` and `fileName`.
mediaAssetId	true	integer		Found.ee ID of the uploaded audio file. Used for audio creatives.
state	false	Creative state	`ACTIVE`	Creative state.
allowAudit	false	boolean	true	Flag indicating whether creative can be submitted for audit or not.
campaigns	true	array of integer		Array of Found.ee campaign IDs this creative should be associated with.

Returns the Creative object information.

Update creative

curl -X POST "https://api.found.ee/ad/api/1.0/creative/update" \
  -H "Authorization: Bearer token" \
  -H "Content-Type: application/json" \
  -d '{
    "id": 2173,
    "width": 640,
    "height": 480,
    "clickUrl": "https://www.iheart.com/podcast/",
    "allowAudit": true,
    "state": "ACTIVE",
    "campaigns": [2318],
    "name": "test_creative"
  }'

{
  "data": {
    "id": 2173,
    "name": "test_creative",
    "advertiserId": 1,
    "width": 640,
    "height": 480,
    "clickUrl": "https://www.iheart.com/podcast/",
    "auditState": "PENDING",
    "state": "ACTIVE",
    "allowAudit": true,
    "campaigns": [2318],
    "mediaUrl": "https://api.found.ee/ad/media/get/2172/banner_image.jpg",
    "mediaAssetInfo": {
      "mediaAssetId": 14,
      "mediaAssetUrl": "https://api.staging.found.ee/ad/media/get/mediaAssetFile/2173",
      "fileName": "Audio Ad So Soon.mp3",
      "duration": 30000
    },
    "type": "AUDIO",
    "audioType": "IHEART",
    "createDate": "2021-06-28T14:43:46.582",
    "updateDate": "2021-06-28T14:43:46.582",
    "auditFeedback": null,
    "payed": true,
    "properties": {}
  },
  "status": 0,
  "message": "Ok"
}

The endpoint updates banner or audio Advertising Creatives.

HTTP Request

POST https://api.found.ee/ad/api/1.0/creative/update

Query Request Body

Field	Optional	Type	Default value	Description
id	false	integer		Creative ID.
name	false	string		Creative name.
width	false	integer		Banner width in pixels.
height	false	integer		Banner height in pixels.
clickUrl	false	string		Creative's click destination URL.
state	false	Creative state	`ACTIVE`	Creative state.
allowAudit	false	boolean	true	Flag indicating whether creative can be submitted for audit or not.
campaigns	true	array of integer		Array of Found.ee campaign IDs this creative should be associated with. Overwrites the previous value.

Returns the Creative object information.

Get Creatives

Returns array of creatives.

curl -X POST "https://api.found.ee/ad/api/1.0/creative/get" \
  -H "Authorization: Bearer token" \
  -H "Content-Type: application/json" \
  -d '{}'

{
  "meta": {
    "totalRows": 2,
    "totalPages": 1
  },
  "data": [
    {
      "id": 2165,
      "name": "1200x627.jpg",
      "advertiserId": 123,
      "width": 1,
      "height": 1,
      "clickUrl": "https://www.iheart.com/podcast/",
      "auditState": "PENDING",
      "state": "ACTIVE",
      "allowAudit": true,
      "campaigns": [
        2303,
        2304,
        2305
      ],
      "mediaUrl": "https://api.staging.found.ee/ad/media/get/2165/null",
      "mediaAssetInfo": null,
      "type": "LIVE_INTENT",
      "audioType": null,
      "createDate": "2021-06-04T19:28:52.024",
      "updateDate": "2021-06-28T14:20:41.597",
      "auditFeedback": null,
      "payed": true,
      "properties": {
        "title": "25",
        "sponsor": "25",
        "description": "90",
        "cta": "15",
        "mainImageAssetId": "955",
        "iconImageAssetId": "956"
      }
    },
    {
      "id": 2172,
      "name": "demo creative",
      "advertiserId": 123,
      "width": 640,
      "height": 480,
      "clickUrl": "https://test.org/click/destination",
      "auditState": "NO_AUDIT",
      "state": "ACTIVE",
      "allowAudit": false,
      "campaigns": [],
      "mediaUrl": "https://api.staging.found.ee/ad/media/get/2172/banner_image.jpg",
      "mediaAssetInfo": {
        "mediaAssetId": 14,
        "mediaAssetUrl": "https://api.staging.found.ee/ad/media/get/mediaAssetFile/2172",
        "fileName": "Audio Ad So Soon.mp3",
        "duration": 30000
      },
      "type": "AUDIO",
      "audioType": "IHEART",
      "createDate": "2021-06-28T14:36:54.910",
      "updateDate": "2021-06-28T14:36:54.910",
      "auditFeedback": null,
      "payed": false,
      "properties": {}
    }
  ],
  "status": 0,
  "message": "Ok"
}

HTTP Request

POST https://api.found.ee/ad/api/1.0/creative/get

Query Request Body

Field	Optional	Type	Default value	Description
name	true	string		Creative name filter.
auditState	true	Creative audit state		Creative audit state filter.
state	true	Array of Creative state	array of all supported creative states	Creative state filter.
audioType	true	Creative audio type		Creative audio type filter.
id	true	array of integer		Creative IDs filter.
page	true	integer	0	Zero-based page index.
size	true	integer	100	Size of the page to return.
sortBy	true	string		Field to sort result by. Can be one of `NAME`,`STATE`, `CREATE_DATE`, `AUDIT_STATE`.
sortDirection	true	string	`ASC`	Direction of the sort. Can be one of `ASC` or `DESC`. If `sortBy` is not specified, `sortDirection` value is ignored.

Returns the Creative object information.

Obtain creative base audit price

curl -X POST "https://api.found.ee/ad/api/1.0/creative/audit/price" \
  -H "Authorization: Bearer token" \
  -H "Content-Type: application/json"

{
  "data": 1.0,
  "status": 0,
  "message": "Ok"
}

The endpoint returns the base audit price for creatives.

HTTP Request

GET https://api.found.ee/ad/api/1.0/creative/audit/price

Returns the base audit price for creatives.

Get Ad Campaigns

Returns array of advertising campaigns.

curl -X POST "https://api.found.ee/ad/api/1.0/campaign/get" \
  -H "Authorization: Bearer token" \
  -H "Content-Type: application/json" \
  -d '{}'

{
  "meta": {
    "totalRows": 2,
    "totalPages": 1
  },
  "data": [
    {
      "id": 2318,
      "name": "test ad campaign",
      "advertiserId": 123,
      "profile": 2715,
      "creatives": [
        2171
      ],
      "lifetimeBudget": 111,
      "dailyBudget": 4.07000000,
      "currentTotalSpent": 0,
      "currentDailySpent": 0,
      "startDate": 1624975200,
      "endDate": 1627333200,
      "state": "ACTIVE",
      "cost": 16,
      "cpcGoalValue": 1.50000000,
      "goalType": "CPM",
      "campaignType": "IHEART",
      "createDate": "2021-06-28T09:11:20.678",
      "updateDate": "2021-06-28T09:12:22.531",
      "draft": false
    },
    {
      "id": 2315,
      "name": "test draft campaign",
      "advertiserId": 123,
      "profile": 2712,
      "creatives": [],
      "lifetimeBudget": 111,
      "dailyBudget": 4.07000000,
      "currentTotalSpent": 0,
      "currentDailySpent": 0,
      "startDate": 1624975200,
      "endDate": 1627333200,
      "state": "INACTIVE",
      "cost": 16,
      "cpcGoalValue": 1.50000000,
      "goalType": "CPM",
      "campaignType": "IHEART",
      "createDate": "2021-06-28T08:54:43.751",
      "updateDate": "2021-06-29T12:15:19.596",
      "draft": true
    }
  ],
  "status": 0,
  "message": "Ok"
}

HTTP Request

POST https://api.found.ee/ad/api/1.0/campaign/get

Query Request Body

Field	Optional	Type	Default value	Description
name	true	string		Filter by campaign name.
campaignType	true	Campaign Type	a list of all supported campaign types	Filter by campaign type.
id	true	array of integer		Campaign IDs filter.
page	true	integer	0	Zero-based page index.
size	true	integer	100	Size of the page to return.
sortBy	true	string		Field to sort result by. Can be one of `NAME`,`STATE`, `START_DATE`, `CREATE_DATE`.
sortDirection	true	string	`ASC`	Direction of the sort. Can be one of `ASC` or `DESC`. If `sortBy` is not specified, `sortDirection` value is ignored.

Returns the Ad Campaign object information.

Create Ad Campaign

curl -X POST "https://api.found.ee/ad/api/1.0/campaign/create" \
  -H "Authorization: Bearer token" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "first",
    "advertiserId": 16,
    "profile": 14,
    "lifetimeBudget": 999,
    "dailyBudget": 4.5,
    "cost": 22,
    "creatives": [ 11, 12 ],
    "startDate": 1625749200,
    "endDate": 1635336000,
    "campaignType": "PROSPECTING",
    "goalType": "CPM"
  }'

{
  "data": {
    "id": 2321,
    "name": "first",
    "advertiserId": 16,
    "profile": 14,
    "creatives": [ 11, 12 ],
    "lifetimeBudget": 999,
    "dailyBudget": 4.5,
    "currentTotalSpent": 0,
    "currentDailySpent": 0,
    "startDate": 1625749200,
    "endDate": 1635336000,
    "state": "INACTIVE",
    "cost": 22,
    "cpcGoalValue": 0,
    "goalType": "CPM",
    "campaignType": "PROSPECTING",
    "createDate": "2021-06-30T06:48:48.929",
    "updateDate": "2021-06-30T06:48:48.929",
    "draft": true
  },
  "status": 0,
  "message": "Ok"
}

The endpoint creates an Advertising Campaign.

HTTP Request

POST https://api.found.ee/ad/api/1.0/campaign/create

Query Request Body

Field	Optional	Type	Default value	Description
name	false	string		Ad campaign name.
advertiserId	false	integer		Found.ee ID of the current advertiser.
campaignType	false	Campaign Type		Selected campaign type.
state	true	Campaign state	`INACTIVE`	Campaign state.
goalType	false	Goal Type		Campaign goal.
startDate	false	integer		Start date (launch) formatted according to Unix Epoch Timestamp standard. In PST timezone.
endDate	false	integer		End date formatted according to Unix Epoch Timestamp standard. In PST timezone.
profile	false	integer		Found.ee ID of an advertising profile.
lifetimeBudget	false	number		Lifetime budget in USD.
dailyBudget	true	number		Daily budget in USD.
cost	true	number	0.00	Campaign cost per mille (CPM) in USD.
cpcGoalValue	true	number	0.00	CPC goal value in USD.
creatives	false	array of integer		Array of Found.ee creative IDs this campaign is associated with.

Returns the Campaign object information.

Update Ad Campaign

curl -X POST "https://api.found.ee/ad/api/1.0/campaign/update" \
  -H "Authorization: Bearer token" \
  -H "Content-Type: application/json" \
  -d '{
    "id": 2321,
    "name": "first",
    "profile": 14,
    "lifetimeBudget": 999,
    "dailyBudget": 4.5,
    "cost": 22,
    "creatives": [ 11, 12 ],
    "startDate": 1625749200,
    "endDate": 1635336000,
    "state": "INACTIVE",
    "goalType": "CPM"
  }'

{
  "data": {
    "id": 2321,
    "name": "first",
    "advertiserId": 16,
    "profile": 14,
    "creatives": [ 11, 12 ],
    "lifetimeBudget": 999,
    "dailyBudget": 4.5,
    "currentTotalSpent": 0,
    "currentDailySpent": 0,
    "startDate": 1625749200,
    "endDate": 1635336000,
    "state": "INACTIVE",
    "cost": 22,
    "cpcGoalValue": 0,
    "goalType": "CPM",
    "campaignType": "PROSPECTING",
    "createDate": "2021-06-30T06:48:48.929",
    "updateDate": "2021-06-30T06:48:48.929",
    "draft": true
  },
  "status": 0,
  "message": "Ok"
}

The endpoint updates an Advertising Campaign.

HTTP Request

POST https://api.found.ee/ad/api/1.0/campaign/update

Query Request Body

Field	Optional	Type	Default value	Description
id	false	integer		Ad campaign ID.
name	false	string		Ad campaign name.
state	false	Campaign state	`INACTIVE`	Campaign state.
goalType	false	Goal Type		Campaign goal.
startDate	false	integer		Start date (launch) formatted according to Unix Epoch Timestamp standard. In PST timezone.
endDate	false	integer		End date formatted according to Unix Epoch Timestamp standard. In PST timezone.
profile	false	integer		Found.ee ID of an advertising profile.
lifetimeBudget	false	number		Lifetime budget in USD.
dailyBudget	true	number		Daily budget in USD.
cost	true	number	0.00	Campaign cost per mille (CPM) in USD.
cpcGoalValue	true	number	0.00	CPC goal value in USD.
creatives	false	array of integer		Array of Found.ee creative IDs this campaign is associated with.

Returns the updated Campaign object information.

Create An HTML5 Creative

curl -X POST "https://api.found.ee/ad/api/1.0/creative/html5ad/create"
  -H "Authorization: Bearer token"
  -H "Content-Type: application/json"
  -d '{"name": "some name", "advertiserId": 10, "templateInstanceId": 2, "destinationUrl": "https://google.com"}'

{
  "data": {
    "id": 1522,
    "name": "Pink Roses",
    "advertiserId": 2715,
    "width": 300,
    "height": 250,
    "clickUrl": "https://google.com",
    "auditState": "PENDING",
    "state": "ACTIVE",
    "allowAudit": true,
    "campaigns": [
      1427,
      1428
    ],
    "mediaUrl": "",
    "mediaAssetInfo": {
      "mediaAssetId": 466,
      "mediaAssetUrl": "http://api.staging.found.ee/ad/media/get/mediaAssetFile/1522",
      "fileName": "Pink Roses-9.zip",
      "duration": 0
    },
    "type": "HTML5",
    "audioType": null,
    "createDate": "2020-01-15T16:29:43.565",
    "updateDate": "2020-01-16T07:31:25.075",
    "auditFeedback": null,
    "payed": true,
    "properties": {
      "html5adInstanceId": "9"
    }
  },
  "status": 0,
  "message": "Ok"
}

The endpoint is used to create an Advertising Creative from an existing HTML5 Ad Instance.

HTTP Request

POST https://api.found.ee/ad/api/1.0/creative/html5ad/create

Query Request Body

Field	Optional	Description
name	false	HTML5 creative name.
advertiserId	false	Current advertiser.
templateInstanceId	false	HTML5 Ad Instance to create a Creative from.
destinationUrl	false	Target URL for the HTML5 Ad banner.

Get an HTML5 Ad Creative by HTML5 Ad Instance Id

curl -X POST "https://api.found.ee/ad/api/1.0/creative/html5ad/get"
  -H "Authorization: Bearer token"
  -H "Content-Type: application/json"
    -d '{"advertiserId": 10, "templateInstanceId": 2}'

{
  "data": {
    "id": 1522,
    "name": "Pink Roses",
    "advertiserId": 2715,
    "width": 300,
    "height": 250,
    "clickUrl": "https://google.com",
    "auditState": "PENDING",
    "state": "ACTIVE",
    "allowAudit": true,
    "campaigns": [
      1427,
      1428
    ],
    "mediaUrl": "",
    "mediaAssetInfo": {
      "mediaAssetId": 466,
      "mediaAssetUrl": "http://api.staging.found.ee/ad/media/get/mediaAssetFile/1522",
      "fileName": "Pink Roses-9.zip",
      "duration": 0
    },
    "type": "HTML5",
    "audioType": null,
    "createDate": "2020-01-15T16:29:43.565",
    "updateDate": "2020-01-16T07:31:25.075",
    "auditFeedback": null,
    "payed": true,
    "properties": {
      "html5adInstanceId": "9"
    }
  },
  "status": 0,
  "message": "Ok"
}

This endpoint retrieves an HTML5 Creative by HTML5 Ad instance identifier.

HTTP Request

POST https://api.found.ee/ad/api/1.0/creative/html5ad/get

Query Request Body

Field	Optional	Default value	Description
advertiserId	false		Current advertiser.
templateInstanceId	false		HTML5 Ad Instance Id.

Copy an HTML5 Ad Creative

curl -X POST "https://api.found.ee/ad/api/1.0/creative/html5ad/1/copy"
  -H "Authorization: Bearer token"
  -H "Content-Type: application/json"
    -d '{"advertiserId": 10, ""clientDate": "2020-03-05T13:47:51.797Z", "destinationUrl": "https://google.com"}'

{
  "data": {
    "id": 1522,
    "name": "Pink Roses",
    "advertiserId": 2715,
    "width": 300,
    "height": 250,
    "clickUrl": "https://google.com",
    "auditState": "PENDING",
    "state": "ACTIVE",
    "allowAudit": true,
    "campaigns": [
      1427,
      1428
    ],
    "mediaUrl": "",
    "mediaAssetInfo": {
      "mediaAssetId": 466,
      "mediaAssetUrl": "http://api.staging.found.ee/ad/media/get/mediaAssetFile/1522",
      "fileName": "Pink Roses-9.zip",
      "duration": 0
    },
    "type": "HTML5",
    "audioType": null,
    "createDate": "2020-01-15T16:29:43.565",
    "updateDate": "2020-01-16T07:31:25.075",
    "auditFeedback": null,
    "payed": true,
    "properties": {
      "html5adInstanceId": "9"
    }
  },
  "status": 0,
  "message": "Ok"
}

This endpoint creates a copy of the existing HTML5 Creative. The API should be used if an end user wants to create a campaign using a HTML5 ad banner that has already been used in some other campaign. Found.ee doesn't allow the end user to have one HTML5 ad banner for multiple campaigns. As a result of the API call, new HTML5 Ad banner instance and Creative are created.

HTTP Request

POST https://api.found.ee/ad/api/1.0/creative/html5ad/<ID>/copy

Query Request Body

Field	Optional	Description
advertiserId	false	Current advertiser.
destinationUrl	false	Destination URL for the banner Creative.
clientDate	false	A user client date. It is used to generate HTML5 instance name.

URLs list

Field	Optional	Type	Default value	Description
urls	false		array of string	List of domains to target. Domain should not include protocol, slashes, query parameters, e.g. `mydomain.com`.
type	false	Targeting list type		Type of the URLs list.

Operating system target

Field	Optional	Type	Default value	Description
ids	false	array of integers		List of Found.ee IDs of operating systems.
action	false	Action Type		Action type

Country target

Field	Optional	Type	Default value	Description
countries	false	array of strings		List of ISO 3166-1 alpha-2 code 2-letter country codes.
action	false	Action Type		Action type

Segment group target

Field	Optional	Type	Default value	Description
segmentBooleanOperator	false	Segment group boolean operator		Segment group boolean operator.
segmentGroups	false	array of Segment groups objects		Segment groups

Segment group

Field	Optional	Type	Default value	Description
booleanOperator	false	Segment boolean operator		Segments boolean operator.
segments	false	array of Segment target		Segment targets

Segment target

Field	Optional	Type	Default value	Description
id	false	integer		Found.ee ID of the segment.
action	false	Action Type		Action type

Segment boolean operator

Boolean operator used to join between multiple segment groups or individual segments. Can be one of AND, OR.

City target

Field	Optional	Type	Default value	Description
ids	false	array of integers		List of Found.ee IDs of cities.
action	false	Action Type		Action type

Region target

Field	Optional	Type	Default value	Description
ids	false	array of integers		List of Found.ee IDs of regions.
action	false	Action Type		Action type

DMA target

Field	Optional	Type	Default value	Description
ids	false	array of integers		List of Found.ee IDs of DMAs.
action	false	Action Type		Action type

Gender target

Field	Optional	Type	Default value	Description
allowUnknown	false	boolean		If true, apple where the gender of the user is not available.
gender	true	Gender info		Gender info

Age target

Field	Optional	Type	Default value	Description
allowUnknown	false	boolean		If true, apple where the age of the user is not available.
ageRange	true	Age range info	empty array	Age range info, e.g. `"Range_25_34"`.

Age range info

Age information. Combined into ranges. Supported age ranges:

"Range_18_24"
"Range_25_34"
"Range_35_44"
"Range_45_54"
"Range_55_64"
"Range_65_100"

Interest target

Field	Optional	Type	Default value	Description
id	false	integer		Found.ee ID of the interest target.

Action type

Type of action to perform with the targeting parameter. Can be one of INCLUDE, EXCLUDE.

Targeting list type

Type of the targeting list. Can be one of WHITELIST, BLACKLIST.

Gender info

Gender information. Can be one of MALE, FEMALE.

Targeting profile information

Targeting profile object contains information about targeting options associated with the running ad campaign.

Field	Type	Description
id	integer	The Profile identifier
name	string	The Profile name
advertiserId	integer	Found.ee ID of the advertiser that this profile belongs to
urlList	URLs list	Information about URLs list targeting
operatingSystemTarget	Operating system target	Information about operating system targeting
countryTargets	Country target	Information about country targeting
segmentGroupTarget	Segment group target	Information about segment group targeting
dealTargets	array of integer	List of Found.ee IDs of deals.
cityTarget	City target	Information about city targeting
regionTarget	Region target	Information about region targeting
dmaTarget	DMA target	Information about DMA targeting
postalCodeTarget	array of integer	List of Found.ee IDs of postal codes.
inventoryItemTarget	integer	Found.ee ID of inventory item.
genderTarget	Gender target	Information about gender targeting
ageTarget	Age target	Information about age targeting
interestsTarget	Array of Interest target	Information about interest targeting
maxLifetimeImpressions	integer	The maximum number of impressions per person.
maxDayImpressions	integer	The maximum number of impressions per person per day.
maxHourImpressions	integer	The maximum number of impressions per person per hour.
maxWeekImpressions	integer	The maximum number of impressions per person per week.
maxMonthImpressions	integer	The maximum number of impressions per person per month.

Operating system information

Field	Type	Description
id	integer	Found.ee ID of the operating system object.
name	string	Name of the operating system object.

Country information

Field	Type	Description
code	string	ISO 3166-1 alpha-2 code 2-letter country code.
country	string	Country name.

Region information

Field	Type	Description
id	integer	Found.ee ID of the region.
name	string	Region name.
countryId	string	ISO 3166-1 alpha-2 code 2-letter country code.
code	string	Region code.

City information

Field	Type	Description
id	integer	Found.ee ID of the city.
name	string	City name.
countryId	string	ISO 3166-1 alpha-2 code 2-letter country code.
regionId	integer	Found.ee ID of the region.
dmaId	integer	Found.ee ID of the DMA.

DMA information

Field	Type	Description
id	integer	Found.ee ID of the DMA.
name	string	DMA name.
countryId	string	ISO 3166-1 alpha-2 code 2-letter country code.
code	string	DMA code.

Postal code information

Field	Type	Description
id	integer	Found.ee ID of the postal code.
countryId	string	ISO 3166-1 alpha-2 code 2-letter country code.
code	string	Postal code.

Inventory list information

Field	Type	Description
id	integer	Found.ee ID of the inventory list.
name	string	Inventory list name.
urlType	Targeting list type	Targeting type of the list.
type	Inventory list type	Targeting type of the list.
category	string	Inventory list category.
domainsCount	integer	Number of domains inside the inventory list.
props	object	A key-value object that contains different properties of the inventory list.

Extended inventory list information

Field	Type	Description
id	integer	Found.ee ID of the inventory list.
name	string	Inventory list name.
urlType	Targeting list type	Targeting type of the list.
type	Inventory list type	Targeting type of the list.
category	string	Inventory list category.
domains	array of string	Domains list of the inventory list.

Inventory list type

Type of the inventory list. Can be one of DISCOVERY, PREMIUM, OTHER.

Extended interest segment object

Field	Type	Description
id	integer	Found.ee ID of the interest segment.
name	string	Interest segment name.
type	string	Interest segment type.
size	integer	Interest segment audience's size.

Deal information

Field	Type	Description
id	integer	Found.ee ID of the interest segment.
name	string	Interest segment name.

Deal seller

Supported deal sellers. Can be one of SPOTIFY, IHEART, LIVE_INTENT, OTHER.

Creative type

Supported creative types. Can be one of IMAGE, HTML5, LIVE_INTENT, AUDIO.

Creative audio type

Supported creative audio types. Can be one of IHEART, SPOTIFY.

Creative state

Supported creative states. Can be one of ACTIVE, INACTIVE.

Creative information

Field	Type	Description
id	integer	Found.ee ID of the creative.
name	string	Creative name.
advertiserId	integer	Found.ee advertiser ID this creative belongs to.
width	integer	Banner width in pixels.
height	integer	Banner height in pixels.
clickUrl	string	Creative's click destination URL.
auditState	Creative audit state	Creative's audit state.
auditFeedback	string	Description of the audit result.
state	Creative state	Creative's state.
allowAudit	boolean	Flag indicating whether creative can be submitted for audit or not.
campaigns	array of integer	Array of Found.ee campaign IDs this creative is associated with.
mediaUrl	string	Uploaded banner's URL.
mediaAssetInfo	Media asset information	Media asset information.
type	Creative type	Creative type.
audioType	Creative audio type	Creative audio type.
createDate	string	Create date formatted according to ISO-8601 standard. In PST timezone.
updateDate	string	Update date formatted according to ISO-8601 standard. In PST timezone.
payed	boolean	Flag indicating whether creative has been paid or not.
properties	object	Object with custom properties.

Creative audit state

Supported creative audit states. Can be one of NO_AUDIT, PENDING, REJECTED, AUDITED.

Media asset information

Field	Type	Description
mediaAssetId	integer	Found.ee ID of the uploaded media file.
mediaAssetUrl	string	URL of the uploaded media file.
fileName	string	Name of the uploaded media file.
duration	integer	Duration (in milliseconds) of the uploaded media file.

Campaign Type

Supported campaign types. Can be one of PROSPECTING, REMARKETING, IHEART, SPOTIFY, LIVE_INTENT.

Goal Type

Supported campaign goal types. Can be one of CPM, CPC.

Ad Campaign information

Field	Type	Description
id	integer	Found.ee ID of the campaign.
name	string	Ad campaign name.
advertiserId	integer	Found.ee advertiser ID this campaign belongs to.
campaignType	Campaign Type	Campaign type.
state	Campaign State	Campaign state.
goalType	Goal Type	Campaign goal.
startDate	integer	Start date (launch) formatted according to Unix Epoch Timestamp standard. In PST timezone.
endDate	integer	End date formatted according to Unix Epoch Timestamp standard. In PST timezone.
createDate	string	Create date formatted according to ISO-8601 standard. In PST timezone.
updateDate	string	Update date formatted according to ISO-8601 standard. In PST timezone.
profile	integer	Found.ee ID of an advertising profile.
lifetimeBudget	number	Lifetime budget in USD.
dailyBudget	number	Daily budget in USD.
currentTotalSpent	number	Total spent budget in USD.
currentDailySpent	number	Daily spent budget in USD.
cost	number	Campaign cost in USD.
cpcGoalValue	number	CPC goal value in USD.
draft	boolean	Is campaign draft?
creatives	array of integer	Array of Found.ee creative IDs this campaign is associated with.

Errors

Found.ee API HTTP error codes

Error Code	Meaning
400	Bad Request -- Your request is invalid.
401	Unauthorized -- Your API key is wrong.
403	Forbidden -- The requested is hidden for administrators only.
404	Not Found -- The specified resource could not be found.
405	Method Not Allowed -- You tried to access with an invalid HTTP method.
500	Internal Server Error -- We had a problem with our server. Try again later.
503	Service Unavailable -- We're temporarily offline for maintenance. Please try again later.

If you get a response like "status":401, "error":"Unauthorized", it means that you need to check your API key. Read about authentication: https://dev.found.ee/docs/api/#authentication

Found.ee API response status codes

Response	Meaning
0	OK -- Success.
1	Body is not valid -- The request body is not valid.
2	Argument is not valid -- The request body validation failed
3	Not Found -- The specified object could not be found.
4	Token has been expired -- The token is not acceptable, please authorize again.
5	Request is not allowed -- The request is not allowed.
6	Internal Server Error -- We had a problem with our server. Try again later or contact administrator.

Appendix 1

Html5 Ad Templates

Found.ee Html5 Ad templates is a predefined list of templates that can be used to create an Html5 Ad Banner. Template can be found and referenced by its id Each template has a list of fields that are used to build an advertising banner.

A simple template banner with a widget in its center.

Parameter Name	Value
id	1
name	Simple Template Banner
description	Html5 Advertising template banner with a widget in the center
fields	A list of simple template banner fields

Field Name	Optional	Description	Validation Rules
size	false	Advertising banner size	One of the sizes
widget	false	Widget, that should be placed in the center of the banner	Should be a valid html `iframe`. Possible sources for the `iframe` are restricted to the List of widget sources
backgroundImage	false	SVG or any other type of image content, that should be used as a banner background	Should be of Image object model type
payload	true	Image template payload. The field is for internal usage
widgetProperties	true	Widget offset from the top/left edge in pixels. Widget size	Should be of WidgetProperties

Image object model

Query Request model

Field	Optional	Type	Description
fileName	false	String	Background image file name
content	false	Base64	Base64 encoded background image content

Query Response model

Response contains a string with relative path to the background image in Found.ee internal storage

WidgetProperties object model

Field	Optional	Type	Description
offsetTop	false	Integer	Offset from the top edge in pixels
offsetLeft	false	Integer	Offset from the left edge in pixels
width	false	Integer	Widget width in pixels
height	false	Integer	Widget height in pixels

List of widget sources that are supported and can be used in Html5 Advertising banner:

Spotify Streaming Player
Spotify Follow Button
Apple Streaming Player
YouTube Video Streaming Player
SoundCloud Streaming Player
MailChimp Email Capture
Show.co player
Bandcamp embedded player
Deezer embed