Businesses need to
Ads Campaign Structure
Each client should attach the Facebook account to the WABA before the partner can work with data from META. See Meta's Official Documentation about Ads Campaign Structure.
Configuring Tracking Keywords
To effectively use this API, it is essential to configure the appropriate keywords that will be tracked.
See Trackable Events (Keywords) .
Best Practices
Here are some Best Practices that you can follow to configure keywords for the Signals API:
Define your campaign objectives: Before you begin configuring keywords, it is essential to have a clear understanding of your campaign objectives. This will help you determine the types of keywords that you should track.
Identify relevant keywords: Once you have defined your campaign objectives, you can start identifying relevant keywords. These are the words and phrases that users are likely to search for when looking for products or services related to your campaign. Try to configure "unique" keywords to track - it will help avoid false-positive results
Configure the Signals API: After identifying keywords, you can configure the Signals API to track the performance of each group of keywords.
Monitor performance : Once you have configured the Signals API to track your keywords, it is important to monitor performance regularly. This will help you identify areas where you need to make changes to optimize your campaigns.
Analyzing Results
The Signals API provides the capability to read data at various levels, offering flexibility and granularity in the data you can access. Depending on your use case, you can choose to read data at the campaign, ad group, ad, or keyword level.
Ad Overview: This provides an overview of your ad campaign's performance, including metrics such as impressions, clicks, and spend. This information is updated on a daily basis, allowing you to stay up-to-date with your campaign's progress.
Ad Daily Insights : Detailed day-by-day information is available to help you compare campaign results over time. This allows you to identify trends and patterns in your campaign's performance and make informed decisions about how to optimize your advertising efforts. This information is updated on a daily basis.
Conversion Insights : The API provides summary statistics per conversion, allowing you to track how well your keywords are performing. This information is updated on a daily basis, giving you insights into your campaign's conversion rates.
Events List : For granular information about each conversion event, the API provides an events list that is updated instantly. This feature allows you to track individual events and analyze their impact on your campaign's overall performance.
Signals Endpoints
Base-URL
Retrieve Client's Facebook Accounts IDs
To retrieve the client_id of clients - check Get List of Clients .
Retrieve list of attached Facebook accounts of the client
GET https://api.signals.360dialog.io/v1/clients/{client_id}/apps/{app_id}/facebook-accounts/
Send a GET request and pick one Facebook account. In case of empty list - ask client to attach Facebook account first .
200: OK
Example
Copy [
{
"id": "2311334042249923",
"email": "advertiser@gmail.com"
}
] Retrieve list of Ad accounts related to the client's Facebook account
GET https://api.signals.360dialog.io/v1/clients/{client_id}/apps/{app_id}/facebook-accounts/{facebook_account_id}
Send a GET request and pick the Ad account.
200: OK
Copy [
{
"id": "1011872785512566",
"name": "Advertiser Company Name"
}
] For assistance with Signals endpoints, please contact our Support Team .
Meta Ads
Get Ads
GET [signals-base-url]/v1/clients/{client_id}/apps/{app_id}/ads/account/{ad_account_id}
Return paginated ad list for given app_id and fb ad_account_id
Request Example
curl --request GET
--url [base-url] /v1/clients/client_id/apps/app_id/ads/account/ad_account_id
--header 'Accept: application/json'
--header 'Authorization: Bearer'
Path Parameters
Query Parameters
>= 1 <= 100
Default: 20
Example: 20
>= 0
Default: 0
Example: 0
200: OK
Copy {
"data" : [
{
"id" : "23851172049950328" ,
"ad_account_id" : "174816537731874" ,
"ad_account" : {
"name" : "360dialog.com - Ad-Account" ,
"currency" : "EUR"
} ,
"ad_set" : {
"name" : "Spot ad set" ,
"status" : "ACTIVE"
} ,
"name" : "Spot image" ,
"status" : "ACTIVE" ,
"created_time" : "2022-11-01T10:05:08+01:00" ,
"updated_time" : "2022-11-30T14:05:08+01:00" ,
"campaign" : {
"id" : "23851172049950328" ,
"ad_account_id" : "174816537731874" ,
"ad_account" : {
"name" : "360dialog.com - Ad-Account" ,
"currency" : "EUR"
} ,
"name" : "Spot image" ,
"status" : "ACTIVE" ,
"start_time" : "2022-11-01T10:05:08+01:00" ,
"stop_time" : "2022-11-30T14:05:08+01:00" ,
"page" : {
"id" : "460293477343848"
} ,
"insight" : {
"campaign_id" : "23851172049950328" ,
"date" : "2023-02-28T08:01:15.667000" ,
"clicks" : 1234 ,
"cpc" : 0.3 ,
"cpm" : 3.4 ,
"ctr" : 1.4 ,
"impressions" : 6789 ,
"spend" : 123.45 ,
"currency" : "EUR" ,
"sessions" : 6789 ,
"cost_per_session" : 0.45 ,
"cvr_clicks_to_sessions" : 0.45 ,
"unique_users" : 5999 ,
"cost_per_unique_user" : 0.45 ,
"cvr_clicks_to_unique_users" : 0.45 ,
"engaged" : 5999 ,
"cost_per_engagement" : 0.45 ,
"cvr_unique_users_to_engaged" : 0.45 ,
"converted" : 5999 ,
"cost_per_conversions" : 0.45 ,
"cvr_unique_users_to_converted" : 0.45 ,
"events" : {
"conversation" : 2 ,
"keyword" : 0
} ,
"keywords" : [
{
"keyword" : "Product ordered" ,
"events" : 7 ,
"cvr" : 1.23
}
]
} ,
"sale_insight" : {
"ad_id" : "23851172049950328" ,
"date" : "2022-10-23T18:54:35" ,
"revenue" : 500 ,
"count" : 1 ,
"roas" : 3 ,
"cvr" : 2.04 ,
"cvr_cost" : 1
}
} ,
"page" : {
"id" : "460293477343848"
} ,
"insight" : {
"ad_id" : "23851172049950328" ,
"date" : "2023-02-28T08:01:15.667000" ,
"clicks" : 1234 ,
"cpc" : 0.3 ,
"cpm" : 3.4 ,
"ctr" : 1.4 ,
"impressions" : 6789 ,
"spend" : 123.45 ,
"currency" : "EUR" ,
"sessions" : 6789 ,
"cost_per_session" : 0.45 ,
"cvr_clicks_to_sessions" : 0.45 ,
"unique_users" : 5999 ,
"cost_per_unique_user" : 0.45 ,
"cvr_clicks_to_unique_users" : 0.45 ,
"engaged" : 5999 ,
"cost_per_engagement" : 0.45 ,
"cvr_unique_users_to_engaged" : 0.45 ,
"converted" : 5999 ,
"cost_per_conversions" : 0.45 ,
"cvr_unique_users_to_converted" : 0.45 ,
"events" : {
"conversation" : 2 ,
"keyword" : 0
} ,
"keywords" : [
{
"keyword" : "Product ordered" ,
"events" : 7 ,
"cvr" : 1.23
}
]
} ,
"sale_insight" : {
"ad_id" : "23851172049950328" ,
"date" : "2022-10-23T18:54:35" ,
"revenue" : 500 ,
"count" : 1 ,
"roas" : 3 ,
"cvr" : 2.04 ,
"cvr_cost" : 1
} ,
"active_event_groups_count" : 0
}
] ,
"total_count" : 0 ,
"offset" : 0 ,
"limit" : 0
} Get Ad
GET [signals-base-url]/v1/clients/{client_id}/apps/{app_id}/ads/{ad_id}
Return ad by id and app_id
Request Example
curl --request GET
--url [base-url]/v1/clients/client_id/apps/app_id/ads/ad_id
--header 'Accept: application/json'
--header 'Authorization: Bearer'
Path Parameters
200: OK 422: Unprocessable Entity
Copy {
"id" : "23851172049950328" ,
"ad_account_id" : "174816537731874" ,
"ad_account" : {} ,
"ad_set" : {} ,
"name" : "Spot image" ,
"status" : "ACTIVE" ,
"created_time" : "2022-11-01T10:05:08+01:00" ,
"updated_time" : "2022-11-30T14:05:08+01:00" ,
"campaign" : {
"id" : "23851172049950328" ,
"ad_account_id" : "174816537731874" ,
"ad_account" : {
"name" : "360dialog.com - Ad-Account" ,
"currency" : "EUR"
} ,
"name" : "Spot image" ,
"status" : "ACTIVE" ,
"start_time" : "2022-11-01T10:05:08+01:00" ,
"stop_time" : "2022-11-30T14:05:08+01:00" ,
"page" : {
"id" : "460293477343848"
} ,
"insight" : {
"campaign_id" : "23851172049950328" ,
"date" : "2023-02-28T08:01:15.667000" ,
"clicks" : 1234 ,
"cpc" : 0.3 ,
"cpm" : 3.4 ,
"ctr" : 1.4 ,
"impressions" : 6789 ,
"spend" : 123.45 ,
"currency" : "EUR" ,
"sessions" : 6789 ,
"cost_per_session" : 0.45 ,
"cvr_clicks_to_sessions" : 0.45 ,
"unique_users" : 5999 ,
"cost_per_unique_user" : 0.45 ,
"cvr_clicks_to_unique_users" : 0.45 ,
"engaged" : 5999 ,
"cost_per_engagement" : 0.45 ,
"cvr_unique_users_to_engaged" : 0.45 ,
"converted" : 5999 ,
"cost_per_conversions" : 0.45 ,
"cvr_unique_users_to_converted" : 0.45 ,
"events" : {
"conversation" : 2 ,
"keyword" : 0
} ,
"keywords" : [
{
"keyword" : "Product ordered" ,
"events" : 7 ,
"cvr" : 1.23
}
]
} ,
"sale_insight" : {
"ad_id" : "23851172049950328" ,
"date" : "2022-10-23T18:54:35" ,
"revenue" : 500 ,
"count" : 1 ,
"roas" : 3 ,
"cvr" : 2.04 ,
"cvr_cost" : 1
}
} ,
"page" : {} ,
"insight" : {
"ad_id" : "23851172049950328" ,
"date" : "2023-02-28T08:01:15.667000" ,
"clicks" : 1234 ,
"cpc" : 0.3 ,
"cpm" : 3.4 ,
"ctr" : 1.4 ,
"impressions" : 6789 ,
"spend" : 123.45 ,
"currency" : "EUR" ,
"sessions" : 6789 ,
"cost_per_session" : 0.45 ,
"cvr_clicks_to_sessions" : 0.45 ,
"unique_users" : 5999 ,
"cost_per_unique_user" : 0.45 ,
"cvr_clicks_to_unique_users" : 0.45 ,
"engaged" : 5999 ,
"cost_per_engagement" : 0.45 ,
"cvr_unique_users_to_engaged" : 0.45 ,
"converted" : 5999 ,
"cost_per_conversions" : 0.45 ,
"cvr_unique_users_to_converted" : 0.45 ,
"events" : {
"conversation" : 2 ,
"keyword" : 0
} ,
"keywords" : [
{
"keyword" : "Product ordered" ,
"events" : 7 ,
"cvr" : 1.23
}
]
} ,
"sale_insight" : {
"ad_id" : "23851172049950328" ,
"date" : "2022-10-23T18:54:35" ,
"revenue" : 500 ,
"count" : 1 ,
"roas" : 3 ,
"cvr" : 2.04 ,
"cvr_cost" : 1
}
}
Copy {
"detail" : [
{
"loc" : [
"string"
] ,
"msg" : "string" ,
"type" : "string"
}
]
}
Get Ads Insights
GET [signals-base-url]/v1/clients/{client_id}/apps/{app_id}/ads/{ad_id}/insights
Return Multiple Ad Insights from Meta for given app_id, ad_id and date intervals
Request Example
curl --request GET
--url [base-url]/v1/clients/client_id/apps/app_id/ads/ad_id/insights
--header 'Accept: application/json'
--header 'Authorization: Bearer'
Path Parameters
200: OK 422: Unprocessable Entity
Copy [
{
"ad_id" : "23851172049950328" ,
"date" : "2023-02-28T08:01:15.667000" ,
"clicks" : 1234 ,
"cpc" : 0.3 ,
"cpm" : 3.4 ,
"ctr" : 1.4 ,
"impressions" : 6789 ,
"spend" : 123.45 ,
"currency" : "EUR" ,
"sessions" : 6789 ,
"cost_per_session" : 0.45 ,
"cvr_clicks_to_sessions" : 0.45 ,
"unique_users" : 5999 ,
"cost_per_unique_user" : 0.45 ,
"cvr_clicks_to_unique_users" : 0.45 ,
"engaged" : 5999 ,
"cost_per_engagement" : 0.45 ,
"cvr_unique_users_to_engaged" : 0.45 ,
"converted" : 5999 ,
"cost_per_conversions" : 0.45 ,
"cvr_unique_users_to_converted" : 0.45 ,
"events" : {
"conversation" : 2 ,
"keyword" : 0
} ,
"keywords" : [
{
"keyword" : "Product ordered" ,
"events" : 7 ,
"cvr" : 1.23
}
]
}
]
Copy {
"detail" : [
{
"loc" : [
"string"
] ,
"msg" : "string" ,
"type" : "string"
}
]
}
Refresh Ads Insights
POST [signals-base-url]/v1/clients/{client_id}/apps/{app_id}/ads/account/{ad_account_id}/refresh
Refresh Ad Insights for given ad account
Request Example
curl --request POST
--url [base-url]/v1/clients/{client_id}/apps/{app_id}/ads/account/{ad_account_id}/refresh
--header 'Accept: application/json'
--header 'Authorization: Bearer'
Path Parameters
Refresh Ad Insights
POST [signals-base-url]/v1/clients/{client_id}/apps/{app_id}/ads/{ad_id}/refresh
Refresh Ad insights for given ad
Request Example
curl --request POST
--url [base-url]/v1/clients/client_id/apps/app_id/ads/ad_id/refresh
--header 'Accept: application/json'
--header 'Authorization: Bearer'
Path Parameters
Meta Campaigns
Get Campaigns
GET [signals-base-url]/v1/clients/{client_id}/apps/{app_id}/campaigns/account/{ad_account_id}
Return paginated Campaign list for given app_id and ad_account_id
Request Example
curl --request POST
--url [base-url]/v1/clients/client_id/apps/app_id/campaigns/account/ad_account_id
--header 'Accept: application/json'
--header 'Authorization: Bearer'
Path Parameters
200: OK
Copy {
"data" : [
{
"id" : "23851172049950328" ,
"ad_account_id" : "174816537731874" ,
"ad_account" : {
"name" : "360dialog.com - Ad-Account" ,
"currency" : "EUR"
} ,
"name" : "Spot image" ,
"status" : "ACTIVE" ,
"start_time" : "2022-11-01T10:05:08+01:00" ,
"stop_time" : "2022-11-30T14:05:08+01:00" ,
"page" : {
"id" : "460293477343848"
} ,
"insight" : {
"campaign_id" : "23851172049950328" ,
"date" : "2023-02-28T08:01:15.667000" ,
"clicks" : 1234 ,
"cpc" : 0.3 ,
"cpm" : 3.4 ,
"ctr" : 1.4 ,
"impressions" : 6789 ,
"spend" : 123.45 ,
"currency" : "EUR" ,
"sessions" : 6789 ,
"cost_per_session" : 0.45 ,
"cvr_clicks_to_sessions" : 0.45 ,
"unique_users" : 5999 ,
"cost_per_unique_user" : 0.45 ,
"cvr_clicks_to_unique_users" : 0.45 ,
"engaged" : 5999 ,
"cost_per_engagement" : 0.45 ,
