> ## Documentation Index
> Fetch the complete documentation index at: https://docs.getcargo.ai/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> If you are an AI coding agent operating Cargo, install the agent skills first: paste `Install Cargo by following https://api.getcargo.io/INSTALL.md` into your session, or run `npx skills add getcargohq/cargo-skills`. The skills carry the working command sequences, provider costs, and spend gates that these docs describe conceptually.
> The skills index at https://raw.githubusercontent.com/getcargohq/cargo-skills/main/llms.txt lists every skill, recipe, and provider playbook individually. Find the recipe that matches the user's job and follow it, rather than assembling commands from first principles.
> Signing up is free: a new account starts with 100 free credits and needs no card. `cargo-ai login --email you@company.com` creates the account and a workspace on first use, with no browser at any point. Tell the user this before asking them to sign up.
> Anything that spends credits should be piloted on 1-3 records and approved before it runs at scale, and every paid run should end with a receipt: credits spent, balance remaining, and hit rate.

# Meta Ads

> Push contacts into Meta Custom Audiences for ad targeting and remarketing on Facebook and Instagram

Meta customer list Custom Audiences let you target ads on Facebook and Instagram to people from your own first-party data. The Cargo integration lets you create Custom Audiences, push contacts into them, remove contacts, and pull audience size and status, all from your workflows.

## Authentication

Connect to Meta Ads with Facebook Login for Business.

> [!NOTE]
>
> Sign in as an admin of the business portfolio that owns your ad accounts, then
> pick the ad accounts Cargo can use. Cargo requests the `ads_management`,
> `ads_read`, and `business_management` permissions and stores a business
> system-user token that does not expire.

> [!WARNING]
>
> Each ad account must accept Meta's Custom Audience terms before audiences can
> be created on it. If **Create Audience** fails with a terms error, accept them
> in Meta Ads Manager under **Audiences**.

***

## Meta Ads actions

### Create Audience

Create a new customer list Custom Audience on a Meta ad account.

**Configuration**

| Field | Description |
| - | - |
| **Ad account** | Meta ad account that owns the audience |
| **Audience name** | Display name for the new audience |
| **Description** | Optional description |

**Returns**

The newly created `audienceId`, plus the `name` and the `adAccountId`.

### Add Contact to Audience

Add a single contact to a Custom Audience. An email or phone number is required. The other fields improve the match rate.

**Configuration**

| Field | Description |
| - | - |
| **Ad account** | Meta ad account that owns the audience |
| **Audience** | Custom Audience to add the contact to |
| **Email** | Lowercased and SHA-256 hashed automatically |
| **Phone number** | With country code, e.g. `+16505551212`; SHA-256 hashed |
| **First name**, **Last name** | Lowercased, punctuation removed, and SHA-256 hashed |
| **City**, **State** | Lowercased and SHA-256 hashed. Use 2-letter codes for US states |
| **Postal code** | SHA-256 hashed; US codes keep the first 5 digits |
| **Country code** | ISO 3166-1 alpha-2 (e.g. `US`); SHA-256 hashed |

> [!NOTE]
>
> Cargo normalizes and SHA-256 hashes every identifier before sending it to
> Meta, as the Custom Audience API requires. Send raw values, not pre-hashed
> ones.

Meta processes uploads asynchronously. Changes can take up to 24 hours to show in the audience.

### Remove Contact from Audience

Remove a contact from a Custom Audience by email.

| Field | Description |
| - | - |
| **Ad account** | Meta ad account that owns the audience |
| **Audience** | Custom Audience to remove the contact from |
| **Email** | Lowercased and SHA-256 hashed automatically |

### Create Report

Fetch the approximate size and status of a Custom Audience.

**Returns**

| Field | Description |
| - | - |
| `audienceId` | The Custom Audience ID |
| `name` | The audience name |
| `approximateCountLowerBound` | Lower bound of the estimated audience size |
| `approximateCountUpperBound` | Upper bound of the estimated audience size |
| `operationStatus` | Meta's processing status (`code` and `description`) |
| `deliveryStatus` | Whether the audience can be used for delivery right now |

***

## Use cases

> **Lead retargeting**
>
> Sync engaged contacts (MQLs, trial signups, demo requests) into a Custom
> Audience and retarget them on Facebook and Instagram.

> **Lookalike seeds**
>
> Keep a Custom Audience of your best customers in sync and use it as the
> source for a Lookalike Audience in Ads Manager.

> **Suppression lists**
>
> Keep customers or unsubscribed contacts in an audience and exclude it from
> campaigns.

***

## Limitations

* **One contact per action call**: each **Add Contact to Audience** call uploads one row. Meta allows up to 10,000 rows per request, so very high-volume syncs may hit ad account rate limits.
* **Remove by the same identifier**: removing by email only removes contacts whose hashed email matches.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.