Custom Audiences from Offline Conversions

Group people who visited your store, made calls to your customer service, or took action offline and target them with Facebook ads. For example, to target people who spent more than USD1000 in the past 90 days:

curl \
-F 'name=90d High Value' \
-F 'rule={"inclusions":{"operator":"or","rules":[{"retention_seconds":7776000,"event_sources":[{"id":"<OFFLINE_EVENT_SET_ID>","type":"offline_events"}],"filter":{"operator":"and","filters":[{"operator":"=","field":"event","value":"Purchase"}]},"aggregation":{"type":"sum","field":"value","operator":">","value":"1000"}}]}}' \
-F 'access_token=<ACCESS_TOKEN>' \
https://graph.facebook.com/<VERSION>/act_<AD_ACCOUNT_ID>/customaudiences"

Custom Audiences from Offline Conversions are based on conversion events uploaded to an Offline Event Set. See Offline Conversions API documentation.

Create an Audience

To create a Custom Audience from your offline event set, the account needs to have already accepted the Terms of Service for Custom Audiences, in Ads Manager:

curl \
  -F 'name=My New Offline Event Set' \
  -F 'rule={"inclusions":{"operator":"or","rules":[{"retention_seconds":2592000,"event_sources":[{"id":"<OFFLINE_EVENT_SET_ID>","type":"offline_events"}],"filter":{"operator":"and","filters":[{"operator":"=","field":"event","value":"purchase"},{"operator":">","field":"value","value":"50+Sheet1!A2+Sheet1!A2+Sheet1!A2+"}]}}]}}'
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/<VERSION>/act_<AD_ACCOUNT_ID>/customaudiences

These parameters are most relevant for custom audiences from your website:

Name Description Type Required

name

The name for the cluster.

String

Yes

rule

Audience rules to be applied on the referrer URL.

String

Yes

description

Description of your custom audience.

String

No

Audience Rules

Rules determine whether a person should be added to this audience. They apply to Offline Events sent through the Offline Conversions API or uploaded manually with Offline Event Manager. Rules are applied on specific events or the custom_data field.

Key components of Audience Rule are:

For for full examples of these components in action, see Example Custom Audience Rules.

For full details of the Audience Rules Syntax, see Audience Rules, Audience Rules Syntax.

Audience Rule Syntax

To define an audience rule, the following structure must be followed:

rule: {
   "inclusions": <RULE_SET>,
   "exclusions": <RULE_SET>,}
Name Description Type Required

inclusions

Rule Set JSON string that defines the inclusion

String

Yes

exclusions

Rule set JSON string that defines the inclusion

String

No

A custom audience for Website Custom Audiences must contain an audience rule. Each rule must be provided as a JSON-encoded string.

Inclusion/Exclusion Rule Syntax

{
  "event_sources" : <EVENT_SOURCE_DEFINITION>, 
  "retention_seconds" : <SECONDS>,
  "filter" : <FILTER>,
  "aggregation" : <AGGREGATION>, 
}

The aggregation and retention_seconds are editable fields. However, editing aggregation and retention_seconds does not flush the audience. People who only match the old rule/aggregation continue to be in the audience until they expire.

Name Description Type Required

event_source

JSON object containing the id (Pixel ID) and type (pixel)

String

Yes

retention_seconds

Integer (in seconds) for the retention window of the audience. Max=15552000 (180 days)

Integer

Yes

filter

JSON string of the filter rules; see Filters

String

No

aggregation

JSON string of the aggregation functions; see Aggregate Functions

Integer

No

Filters

Filtration follows this general format:

"filter" : {"operator": <BOOLEAN_OPERATOR>,"filters": <FILTER_SET>,}

Filter Rules

{
    "field": <FIELD>,
    "operator": <COMPARISON_OPERATOR>,
    "value": <VALUE>,
}
Name Description Type Required

field

Use "event" if the filter is to specify an event. Parameters that match events sent by pixel (for example, 'ViewContent', 'Purchase')

String

Yes

comparison operator

"="("eq"), "!="("neq"), ">="("gte"), ">"("gt"), "<="("lte"), "<"("lt"), "i_contains", "i_not_contains", "contains", "not_contains", "is_any", "is_not_any", "i_is_any", "i_is_not_any", "i_starts_with", "starts_with", "regex_match"[INFO]. If "field" is set to "event", must use "="

String

Yes

value

If the field attribute is set to "event", the value must be set to an event name. Use the App Event API to see app events and parameters reported by the app.

String

Yes

Audience Rules, deprecated

Use this content for audience rules prior to v3.0.

Rules determine whether a person should be added to this audience. They apply to Offline Events sent through the Offline Conversions API or uploaded manually with Offline Event Manager.

For example, build an audience with people who purchased in the past 30 days:

curl \
-F 'name=30d Purchasers' \
-F 'subtype=OFFLINE_CONVERSION' \
-F 'retention_days=30' \
-F 'rule={"event":{"eq":"Purchase"}}' \
-F 'dataset_id=&lt;OFFLINE_EVENT_SET_ID>' \
-F 'access_token=&lt;ACCESS_TOKEN>' \
"https://graph.facebook.com/&lt;API_VERSION>/act_&lt;AD_ACCOUNT_ID>/customaudiences"

Rules can use Offline Event attributes in custom_data field called 'category'. This targets people who purchased a product from the footwear category in the past 60 days:

curl \
-F 'name=60d Footwear Purchasers' \
-F 'subtype=OFFLINE_CONVERSION' \
-F 'retention_days=60' \
-F 'rule={"and": [{"event":{"eq":"Purchase"}},{"custom_data.category":{"i_contains":"FOOTWEAR"}}]}' \
-F 'dataset_id=&lt;OFFLINE_EVENT_SET_ID>' \
-F 'access_token=&lt;ACCESS_TOKEN>' \
"https://graph.facebook.com/&lt;API_VERSION>/act_&lt;AD_ACCOUNT_ID>/customaudiences"

Rules are based on these operators and data types:

Name Description

operator

  • i_contains - Contains substring, case insensitive
  • i_not_contains - Does not contain substring, case insensitive
  • contains - Contains substring, case sensitive
  • not_contains - Does not contain substring, case sensitive
  • eq - Equal to, case sensitive
  • neq - Not equal to, case sensitive
  • lt - Less than, numeric fields only
  • lte - Less than or equal to, numeric fields only
  • gt - Greater than, numeric fields only
  • gte - Greater than or equal to, numeric fields only
  • regex_match -
    Matches a regular expression, such as ".*shoes". Full PCRE grammar supported

data

  • event - Offline Event name. Examples: 'Purchase', 'Lead', 'Other'
  • value - Offline Event value
  • custom_data - Any attribute added to custom_data for an Offline Event. Examples: custom_data.category, custom_data.color.

Aggregate Functions

Use this content for aggregate functions prior to v3.0.

Create custom audiences based upon the frequency and intensity of behavior using the aggregation in the audience rule field. With this, you define an aggregate function; for example:

"aggregation" : {"type":"count","operator":">","value":1}
Name Description Type Required

type

The aggregation function type: “count” “sum” “avg” “min” “max” "time_spent" "last_event_time_field"

String

Yes

method

"absolute", meaning add people that logged events in specified range, or "percentile", meaning add people from a specified percentile range. If you select percentile, the operator should only be in_range and not_in_range.

String

No

field

The parameter on which the aggregation function is applied.

String

No, if type is count; otherwise, yes.

comparison operator

=, !=, >=, >, <=, <, in_range, not_in_range

String

Yes

value

Expected value of the parameter

String

Yes

Comparison Operators

Operator Description

">" or "gt"

True if event's parameter value greater than specified value.

">=" or "gte"

True if event's parameter value greater than or equal to specified value.

"<" or "lt"

True if event's parameter value less than specified value.

"<=" or "lte"

True if event's parameter value less than or equal to specified value.

"=" or "eq"

True if event's parameter value equal to specified value. Note: This is equivalent to not specifying an operator at all; that is, "'x' : { 'eq' : 'y' }" is the same as "'x' : 'y' }.

"!=" or "neq"

True if event's parameter value not equal to specified value.

"contains"

True if event's parameter value, as string, contains specified string. Value of "shoe12345" fulfills 'contains' if specified value is 'shoe'.

"not_contains"

True if event's parameter value, as string, does not contain specified string. Value "shoe12345" fulfills 'not_contains' if specified value is 'purse'.

"i_contains"

Contains, case-insensitive

"i_not_contains"

Not contains, case-insensitive

"is_any"

True if event's parameter value matches any strings in given array.

"is_not_any"

True if event's parameter value matches no strings in specified array.

"i_is_any"

'is_any', case-insensitive.

"i_is_not_any"

'is_not_any', case-insensitive

"starts_with"

True if the event's parameter value starts with the given string.

"i_starts_with"

"starts_with", case-insensitive.

"regex_match"

Matches a regular expression, such as \"example\.com.*purchase$\". The full PCRE grammar is supported.

Example Rules

Match all referring `favorite_food` containing the string `'pizza'` in the last 30 days:

{
    "inclusions": {
        "operator": "or",
        "rules": [
            {
                "event_sources": [
                    {
                        "type": "offline_events",
                        "id": "<OFFLINE_EVENT_SET_ID>",
                    }
                ],
                "retention_seconds": 2592000,
                "filter": {
                    "operator": "and",
                    "filters": [
                        {
                            "field": "custom_data.favorite_food",
                            "operator": "i_contains",
                            "value": "pizza"
                        }
                    ]
                },
            }
        ]
    }
}

Match Purchase events where cost is greater than or equal to USD100 in the last 30 days. Consider using this rule for the following event:

{
    "inclusions": {
        "operator": "or",
        "rules": [
            {
                "event_sources": [
                    {
                        "type": "offline_events",
                        "id": "<OFFLINE_EVENT_SET_ID>"
                    }
                ],
                "retention_seconds": 2592000,
                "filter": {
                    "operator": "and",
                    "filters": [
                        {
                            "field": "event",
                            "operator": "eq",
                            "value": "Purchase"
                        },
                        {
                            "operator": "or",
                            "filters": [
                                {
                                    "field": "value",
                                    "operator": ">=",
                                    "value": "100"
                                }
                            ]
                        }
                    ]
                }
            }
        ]
    }
}

Match Purchase events where the product's color is blue defined by offline event attributes in the custom_data field called 'color' in the last 30 days. Consider using this rule for the following event:

{
    "inclusions": {
        "operator": "or",
        "rules": [
            {
                "event_sources": [
                    {
                        "type": "offline_events",
                        "id": "<OFFLINE_EVENT_SET_ID>"
                    }
                ],
                "retention_seconds": 2592000,
                "filter": {
                    "operator": "and",
                    "filters": [
                        {
                            "field": "event",
                            "operator": "eq",
                            "value": "Purchase"
                        },
                        {
                            "operator": "or",
                            "filters": [
                                {
                                    "field": "custom_data.color",
                                    "operator": "eq",
                                    "value": "blue"
                                }
                            ]
                        }
                    ]
                }
            }
        ]
    }
}

~~~~

Aggregate Functions, deprecated

Create custom audiences based upon the frequency and intensity of a person's behavior through a rule_aggregation field. Provide functions with these fields:

Name Description

type

Type of function: count, sum, avg, max, min

config

Required by certain aggregation functions. See below

operator

  • =
  • >
  • >=
  • <
  • <=
  • !=
  • @> - Time between delivery and when the Offline Event took place is longer than the value, or now - pass-in-time > value
  • @< - Time between delivery when the Offline Event took place is shorter than the value, or now - pass-in-time < value

value

Integer. rule_aggregation value

The available functions are:

NameRequired ConfigDescription

count

Number of Offline Events satisfying the rule

sum

{“field”: “field_name”}

Accumulate values of given Offline Event's field

avg

{“field”: “field_name”}

Average of values in specified Offline Event's field

max

{“field”: “field_name”}

Maximum value for a Offline Event's field

min

{“field”: “field_name”}

Minimum value in a Offline Event's field

To target people who purchased more than 5 times in the past 110 days:

curl \
-F 'name=110d Returning Customers' \
-F 'subtype=OFFLINE_CONVERSION' \
-F 'retention_days=110' \
-F 'rule={"event":{"eq":"Purchase"}}' \
-F 'rule_aggregation={"type":"count", "operator":">", "value": "5"} ' \
-F 'dataset_id=&lt;OFFLINE_EVENT_SET_ID>' \
-F 'access_token=&lt;ACCESS_TOKEN>' \
"https://graph.facebook.com/&lt;API_VERSION>/act_&lt;AD_ACCOUNT_ID>/customaudiences"

Best Practices

  • Experiment with different audiences, for example, people who purchased frequently in the past that did not return recently or people who purchased only from one category
  • Create Lookalike audiences based on audiences that perform the best