Facebook Custom Audiences - Meta Marketing API

Create and manage Facebook Custom Audiences via Meta Marketing API. Add/remove users with auto-hashing, create lookalike audiences, share across ad accounts, get audience insights. Direct integration with Facebook Ads.

Features

Audience Management

• create_audience - Create a new custom audience
• get_audience - Get details of a specific audience
• list_audiences - List all custom audiences in an ad account
• update_audience - Update audience name/description
• delete_audience - Delete a custom audience

User Management

• add_users - Add users to audience (auto-hashes PII)
• remove_users - Remove users from audience
• get_audience_users - Get estimated audience size and demographics

Advanced Features

• create_lookalike - Create lookalike audience from source audience
• share_audience - Share audience with another ad account
• get_audience_insights - Get demographic/interest insights

Quick Start

{
  "input": "your input here"
}

Demo Mode

Set demoMode: true to test with sample data (no charges). When you're ready for real results, set demoMode: false or omit it.

{
  "demoMode": true,
  ...
}

Input Parameters

Parameter	Type	Required	Description
See input schema

Output Format

Audience Object

{
  "id": "123456789",
  "name": "High Value Customers",
  "description": "Customers with LTV > $500",
  "approximate_count": 15000,
  "data_source": {
    "type": "CUSTOM",
    "sub_type": "CUSTOM"
  },
  "delivery_status": {
    "code": 200,
    "description": "Ready"
  },
  "operation_status": {
    "code": 200,
    "description": "Normal"
  }
}

Add Users Response

{
  "audience_id": "123456789",
  "num_received": 1000,
  "num_invalid_entries": 5,
  "invalid_entry_samples": ["invalid@", "123"]
}

Pricing

This actor uses pay-per-event billing: $0.01 per query (all tasks)

Use Cases

Build Retargeting Audience

1. Export customer emails from CRM
2. Use add_users to upload to Facebook
3. Create ad campaigns targeting the audience

Create Lookalike Audience

1. Create source audience of best customers
2. Use create_lookalike with 1-10% ratio
3. Reach new people similar to your customers

Sync Across Accounts

1. Create audience in main ad account
2. Use share_audience to share with agency accounts
3. All accounts can target the same audience

---

Common Problems & Solutions

"Invalid API key" error

Cause: Your API key is wrong, expired, or doesn't have the right permissions. Fix: Double-check your API key. Make sure you copied it exactly without extra spaces.

"Rate limit exceeded" error

Cause: You've hit the API's rate limits. Fix: Wait a few minutes, then try again. Consider reducing the number of concurrent requests.

Empty or incomplete results

Cause: The target may have anti-scraping protection or the data doesn't exist. Fix:

• Check if the URL/search query is correct
• Try with different parameters
• Some sites may block automated access

Demo data showing instead of real results

Cause: demoMode is still set to true. Fix: Set demoMode: false and provide your API key(s).

---

Built by John Rippy | Actor Arsenal