How to use the Foreplay API Endpoints with N8N

This article is to highlight the most commonly used endpoints in the Foreplay API for full endpoint documentation go here: https://public.api.foreplay.co/docs

Written By Zach Murray

Last updated 5 months ago

ℹ️ You are currently on the platform knowledge base.
For full technical documentation go here 👉 API Technical Docs 🔗

To chat with the the API technical docs 👉 Docs GPT 🔗

How to search Foreplay with the API

  1. Set up your environment

    • Start with any automation platform of your choice.

    • Prepare to make HTTP requests.

 2. Add the Server URL

  • Refer to the documentation to find the server URL.

  • Add the server URL into your automation platform.

3. Add the Endpoint

  • Scroll down to find the 'search and filter ads' endpoint in the documentation.

  • Insert this endpoint into your request.

4. Add Authentication

  • Set up authentication by adding a header.

  • Copy the authorization key from Full Play and paste it into the header value.

5. Add Query Parameters

  • Add query parameters for your search.

6. Test the request

  • Send the request to the API

7. Review the Results

  • Check the response for the ads returned.

  • Confirm the details required for your automation

How to get boards

Step 1: Access the API

  • Identify the need to retrieve board names and ideas for ads.

  • Understand that this process is for boards related to different products, brands, or niches.

Step 2: Set up the API Request

  • Add the endpoint: /API/boards.

Step 3: Configure Authentication

  • Send headers for authorization. 

Step 4: Add API Key

  • Copy your API key from Foreplay.

  • Paste the API key into the appropriate field for authorization. 

Step 5: Test the Request

  • Test the request to see if it works.

  • Confirm that the response is successful and displays the desired information

How to get ads from a board

Step 1: Set up the API call

  • Use the endpoint: board/ads

Step 2: Add parameters to filter ads

  • Board ID (Required)

  • Platform (e.g., platform=Facebook)

  • Status (e.g., live=true for active ads)

  • Language (e.g., languages=English)

Step 2: Test the API Call

  • Execute the API call to retrieve ads.

  • Check the response for required details

How to get brands from a board

Step 1: Request the Board ID

  • Don’t have a board ID? Watch how to get boards

Step 2: Set up the API request

  • Change the limit parameter to 1 to retrieve only one brand.

  • Ensure to include the required query parameter for the board ID in your API request. 

Step 3: Test the API Request

  • Test the API request to see if it retrieves the brands correctly.

Step 4: Review Retrieved Brands

  • Check the response to see the brands returned from the board.

How to get brands from Spyder

Step 1: Set Up Your Automation Platform

  • Open n8n or your preferred AI automation platform.

Step 2: Configure the API Endpoint

  • Change the API endpoint to: /api/spider/brands 

Step 3: Authentication Setup

  • Ensure you have the header authentication in place:

    • Include your authorization value with the API key.

Step 4: Test the API Call

  • Test the API call to test if it works correctly.

Step 6: Review Retrieved Data

  • Check the response to see the brands being tracked.

How to get specific brands from Spyder

Step 1: Access Your AI Automation Platform

  • Open your AI automation platform.

  • Prepare to input the brand ID you want to track. 

Step 2: Modify the Brand ID

  • Add the specific brand ID you want to track

Step 3: Test the automation step

  • Execute the step to test if it works correctly.

Step 4: Verify the Output

  • Check the output to confirm it shows the expected brand

  • Review additional data returned, such as text and niches.

How to get ads from Spyder

Step 1: Access Your AI Automation Platform

  • Open your AI automation platform.

  • Prepare to specify the brand you want to track.

Step 2: Specify the Brand and Ad Type

  • Enter the brand name you want to track.

  • Specify that you want to track ads.

 Step 3: Set Filters for Your Search

  • Add a limit to the number of ads (e.g., limit to 1).

  • Apply additional filters, such as:

    • Name: display_format

    • Value: video

    • This will return video ads

Step 4: Test your request

  • Execute the test to see if the step 

Step 5: Review the data

  • Examine the details of the ad retrieved:

    • Description

    • Brand ID

    • Categories

    • Creative targeting

    • Languages

    • Market

    • Niche

    • Avatar

    • Call to Action (CTA)

    • AI emotional analysis of emotions provoked

    • Media file URL (Image or video asset)

How to get a specific ad

Step 1: Access Your Automation Platform

  • Open your automation platform.

  • Prepare to modify the endpoint for retrieving ads.

Step 2: Change the Endpoint

  • Locate the endpoint in the docs

  • Add to URL

Step 3: Add the Ad ID as a Query Parameter

  • Obtain the specific ad ID you want to retrieve.

  • Add the ad ID as a query parameter in the request. 

Step 4: Test the step

  • Execute the request to test if the specific ad is retrieved successfully.

  • Confirm that the ad data is coming through in the output

Step 5: Review the Retrieved Ad Data

  • Check the details of the retrieved ad, including:

    • Description

    • Categories

    • Creative target

    • Languages

    • Market (e.g., D2C)

    • Accessories

    • Avatar

    • Call to Action (CTA)

    • Display format (e.g., video, images)

    • Emotions driven by the ad

    • Link URL for the landing page

    • Active status (e.g., live)

    • Persona information

    • Platforms the ad was launched on

    • Start date of the ad

    • Thumbnail for the video

    • Video file

    • Run duration and video duration.

Step 6: Utilize the Retrieved Ad Data

  • Use the retrieved ad data in your automation as needed.

  • Ensure you have access to all relevant information for future steps.

How to get ads from a specific brand

1. Add the API Endpoint

2. Send Query Parameters

  • Check the documentation for required parameters:

    • Use the field domain to input the brand's domain (e.g., nike.com).

    • Test the endpoint to retrieve the brand ID. 

3. Getting Ads by Brand ID

  • Change the endpoint to get ads by brand ID:

    • Use the retrieved brand ID from the previous step.

    • Set a limit for the number of ads to retrieve (e.g., limit to 1 ad). 

4. Verify output

  • Review the data returned from the API:

    • Ad ID, name, brand ID, description

    • Categories, creative targeting, languages, target market

    • Product category, call to action (CTA), display format (e.g., video)

    • Emotional analysis of the ad

    • Link URL, active status, persona, publisher platform

    • Ad launch date, thumbnail, video format, video URL, running duration, video duration.

How to get brand analytics

1. Retrieve the Server URL and Endpoint

  • Copy the server URL from the documentation.

  • Find the appropriate endpoint for brand analytics.

2. Get the Brand ID

  • Input the endpoint into the platform.

  • Set authentication to 'none'.

  • Enter the domain (e.g., Nike.com).

3. Add Authorization Header

  • Locate your API key from Full Play.

  • Add the API key in the headers for authorization.

4. Execute the Step to Retrieve Brand ID

  • Execute the step to obtain the brand ID. 

6. Access Brand Analytics

  • Add the brand analytics endpoint

  • Add ID query parameter and brand ID

7. Input Required Parameters

  • Ensure you have the correct brand ID and any necessary IDs.

  • Execute the step.

8. Troubleshoot Invalid IDs

  • If you encounter an error, check the brand ID or page ID.

  • Go back to the previous step to verify the ID.

10. Confirm Successful Retrieval of Brand ID

  • Ensure the correct brand ID is displayed.

11. Review Brand Analytics Data

  • Analyze the returned data, including active/inactive ad counts and formats.