getAdAccounts Documentation

Overview

This node is a component designed for the powerful Vantage analytics and data platform. It serves to retrieve advertising account information from a marketing integration (specifically, Meta Marketing). This function allows users to specify parameters to customize the data retrieval, ensuring the right data is fetched based on their needs.

Purpose

The primary purpose of the node is to facilitate access to essential advertising account information by integrating with Meta's advertising API. This includes details such as account status, currency, timezone, and business name, which are vital for businesses utilizing digital marketing strategies.

Settings

This node accepts various settings that control its behavior and output. Below are the exhaustive details for each setting used in the component:

1. fields

• Input Type: String
• Purpose: Specifies which fields to retrieve from the advertising accounts. By default, it requests important identifiers and attributes of the accounts.
• Effect of Changing: Altering this value allows the user to fetch specific attributes, which can reduce unnecessary data retrieval. For instance, users can limit the fields to only those strictly needed for their analysis.
• Default Value: The default string value is 'id,name,account_id,account_status,currency,timezone_name,business_name'.

2. limit

• Input Type: Numeric
• Purpose: Determines the maximum number of advertising accounts to be retrieved in a single API call.
• Effect of Changing: This value can optimize performance and limit data blown by restricting the amount of data fetched at once. Setting a low limit can be beneficial for testing or when searching for specific data points without overwhelming the system.
• Default Value: The default numeric value is 50.

How It Works

1. Input Handling: The function receives input parameters through the inputs object. If specific inputs are not provided, it defaults to configuration values or pre-defined settings.
2. Build Connection: It initializes the connection with the specified marketing integration using a secure connection, passing context information that may include authentication tokens and user-specific data.
3. Data Retrieval: Once the connection is established, the function calls getAdAccounts on the integration object with the defined fields and limit.
4. Output: It structures the output in a manner that includes both the retrieved data and any pagination information for large data sets. In case of an error during API calls, a structured error message is returned.

Expected Data

The function expects the following data structures:

1. Inputs Object:

   • fields: A string indicating the data fields requested.
   • limit: A numeric value for the number of accounts to fetch.

2. Integration Response:

   • data: An array of objects containing advertising account details.
   • paging: Optional pagination information for navigation through large data sets.

Error Handling

The component has robust error handling; if an error is thrown during integration (e.g., API downtime or bad requests), it provides a clear internal error message that includes the original error message from the Meta Marketing API.

Use Cases & Examples

Use Cases

1. Marketing Performance Analysis: A digital marketing agency may use getAdAccounts to pull in account data to evaluate the performance of various advertising accounts across different clients.

2. Data Reporting: A business could utilize this function as part of a regular reporting mechanism to summarize advertising account activities, such as account status or budget allocation.

3. Compliance Checking: Companies may need to regularly check account statuses and ensure they are compliant with advertising policies. This function can pull necessary account information needed for audits.

Example Configuration

Use Case: A marketing manager wants to obtain account details from several advertising accounts for quarterly performance analysis.

Sample Configuration:

{
  "inputs": {
    "fields": "id,name,account_status,currency",
    "limit": 100
  },
  "config": {
    "fields": "id,name,account_id,account_status,currency",
    "limit": 50
  },
  "context": {
    "auth_token": "example_token_12345"
  }
}

In this context, the marketing manager configures the fields to include only the necessary attributes for analysis and sets the limit to 100 to retrieve a broader dataset for comprehensive analysis. The context would include authentication credentials necessary for the API call.