Introduction
Welcome to the Marin Social API!
We have language bindings in Curl! You can view code examples in the dark area to the right.
The request
Each request sent to the API can contain data determining the Response content.
Each service is summarized with main data.
First, an URL (Http request) identify the service you want to use.
The URI parameters section indicates what data you have to place in the URL placeholders, strings with brackets.
The Query Parameters section indicates GET parameters you can put after a '?' in your request.
The response
All responses content are in the JSON format.
Status code
| Status Code | Description |
|---|---|
| 200 | Success |
| 201 | Resource created |
| 202 | Expected result was already active (e.g. play an ad which is already in play status) |
| 400 | Form validation failed |
| 403 | Access denied |
| 404 | Resource not found |
| 500 | Internal error |
When response's status code is 4xx, response body contains an array with a message key. It explains why server returned that.
How to call services
Host
The API is hosted under the following domain :
https://api.mysocialpixel.com
Methods
| Methods | Description |
|---|---|
| GET | Fetch data on the platform and send it in a paginate response |
| POST | Create a new resource on the platform |
| PUT | Update a resource on the platform, not submitted fields are ignored (like a common PATCH) |
| DELETE | Delete a resource on the platform |
| PATCH | Perform a particular action on a resource |
Inpout/Output
Form inputs are expected to be in x-www-form-url-encoded. Concerned methods are POST, PUT and DELETE. You have to add the header in your requests :
Content-type: application/x-www-form-url-encoded
PATCH can be processed like forms or not. As a consequence, body requests for PATCH should be x-www-form-url-encoded string or JSON. The details are in each service documentation. Output is always a JSON encoded object.
Forms
For POST and PUT requests, we process parameters the same way as a form would be submitted. As a result, if we find some validation errors, the JSON response describes the form and the errors.
Pagination
Every GET request return a paginate result. The result resources are under data key, and the pagination informations are under range key.
Authentication
Make sure to replace
{{AGENCY_TOKEN}}with your API key.
A token is associated to your agency, allowing you to call services from the API. You have to add it in a key GET parameters in all your requests to the API.
https://api.mysocialpixel.com/resources/123456/subs?key={{AGENCY_TOKEN}}
Accounts
Get all Accounts
curl -X GET \
'https://api.mysocialpixel.com/accounts?key={{AGENCY_TOKEN}}' \
-H 'cache-control: no-cache'
The above command returns JSON structured like this:
{
"data": [
{
"id": "1",
"network_id": "123456789101111212",
"name": "Account 1",
"currency": "EUR",
"timezone": "Europe/Paris",
"country": "FR",
"active": true,
"src": "fb"
},
{
"id": "2",
"network_id": "a1b2c3d45e",
"name": "Account 2",
"timezone": "Europe/Paris",
"funding_instruments": [
"a1b2c3"
],
"active": true,
"src": "tw"
},
[...]
],
"range": {
"total": 1000,
"limit": 100,
"nb_pages": 10,
"page": 1,
"results": 100,
"next": "https://api.mysocialpixel.com/accounts?limit=100&key={{AGENCY_TOKEN}}&page=2"
}
}
This endpoint retrieves all accounts.
The response is returned with pagination. The result resources are under data key, and the pagination informations are under range key.
HTTP Request
GET https://api.mysocialpixel.com/accounts
Query Parameters
| Parameter | Optional | Default | Description |
|---|---|---|---|
| limit | yes | 100 | The maximum number of resource by page (Max 300) |
| page | yes | 1 | The requested page |
Get a specific Account
curl -X GET \
'https://api.mysocialpixel.com/accounts/{{ACCOUNT_ID}}?key={{AGENCY_TOKEN}}' \
-H 'cache-control: no-cache'
The above command returns JSON structured like this:
{
"data": {
"id": "1",
"network_id": "123456789101111212",
"name": "Account 1",
"currency": "EUR",
"timezone": "Europe/Paris",
"country": "FR",
"active": true,
"src": "fb"
}
}
This endpoint retrieves a specific account.
HTTP Request
GET https://api.mysocialpixel.com/accounts/{{ACCOUNT_ID}}
URI Parameters
| Parameter | Description |
|---|---|
| ACCOUNT_ID | The ID of the account to retrieve |
Get the Publisher Objects
curl -X GET \
'https://api.mysocialpixel.com/accounts/{{ACCOUNT_ID}}/objects?key={{AGENCY_TOKEN}}' \
-H 'cache-control: no-cache'
The above command returns JSON structured like this:
{
"data": [
{
"id": "1",
"name": "Object 1",
"network_id": "12345678911",
"picture": "https://scontent.xx.fbcdn.net/v/t39.2081-6/c0.0.76.76/p75x75/my_picture.png",
"url": "https://www.facebook.com/games/?app_id=123456789",
"type": "application"
},
{
"id": "2",
"name": "Object 2",
"network_id": "12345678912",
"picture": "https://scontent.xx.fbcdn.net/v/t1.0-1/p50x50/my_picture.png",
"url": "https://www.facebook.com/PageOne/",
"type": "page"
},
[...]
],
"range": {
"total": 10000,
"limit": 100,
"nb_pages": 10,
"page": 1,
"results": 100,
"next": "https://api.mysocialpixel.com/accounts/{{ACCOUNT_ID}}/objects?limit=100&key={{AGENCY_TOKEN}}&page=2"
}
}
This endpoint retrieves the publisher objects from a specific account.
The response is returned with pagination. The result resources are under data key, and the pagination informations are under range key.
HTTP Request
GET https://api.mysocialpixel.com/accounts/{{ACCOUNT_ID}}/objects
URI Parameters
| Parameter | Description |
|---|---|
| ACCOUNT_ID | The ID of the account to retrieve |
Query Parameters
| Parameter | Optional | Default | Description |
|---|---|---|---|
| limit | yes | 100 | The maximum number of resource by page (Max 300) |
| page | yes | 1 | The requested page |
Get the Funding Instruments
curl -X GET \
'https://api.mysocialpixel.com/accounts/{{ACCOUNT_ID}}/funding-instruments?key={{AGENCY_TOKEN}}' \
-H 'cache-control: no-cache'
The above command returns JSON structured like this:
{
"data": [
{
"id": "1",
"start_date": "2018-01-01T08:00:00+0000",
"end_date": "2019-01-01T06:59:59+0000",
"description": "funding instruments 1",
"currency": "USD"
},
{
"id": "2",
"start_date": "2018-01-01T08:00:00+0000",
"end_date": "2019-01-01T06:59:59+0000",
"description": "funding instruments 2",
"currency": "USD"
},
[...]
],
"range": {
"total": 1000,
"limit": 100,
"nb_pages": 10,
"page": 1,
"results": 100,
"next": "https://api.mysocialpixel.com/accounts/{{ACCOUNT_ID}}/funding-instruments?limit=100&key={{AGENCY_TOKEN}}&page=2"
}
}
This endpoint retrieves the funding instruments from a specific Twitter account.
The response is returned with pagination. The result resources are under data key, and the pagination informations are under range key.
HTTP Request
GET https://api.mysocialpixel.com/accounts/{{ACCOUNT_ID}}/funding-instruments
URI Parameters
| Parameter | Description |
|---|---|
| ACCOUNT_ID | The ID of the account to retrieve |
Query Parameters
| Parameter | Optional | Default | Description |
|---|---|---|---|
| limit | yes | 100 | The maximum number of resource by page (Max 300) |
| page | yes | 1 | The requested page |
Add a new Account
curl -X POST \
'https://api.mysocialpixel.com/accounts/fb\
?key={{AGENCY_TOKEN}}&access_token={{FACEBOOK_ACCESS_TOKEN}}'\
network_id={{FACEBOOK_ACCOUNT_ID}}&name={{FACEBOOK_ACCOUNT_NAME}}\
-H 'cache-control: no-cache'
The above command returns JSON structured like this:
{
"data": {
"id": "1",
"network_id": "123456789101111212",
"name": "Account 1",
"currency": "EUR",
"timezone": "Europe/Paris",
"country": "FR",
"active": true,
"src": "fb"
}
}
This endpoint add a specific Facebook account.
HTTP Request
POST https://api.mysocialpixel.com/accounts/fb
Query Parameters
| Parameter | Optional | Description |
|---|---|---|
| name | no | The name of the account to add |
| network_id | no | The Facebook ID of the account to add |
| access_token | no | Facebook access token |
Refresh a specific Account
curl -X PUT \
'https://api.mysocialpixel.com/accounts/{{ACCOUNT_ID}}\
?key={{AGENCY_TOKEN}}&access_token={{FACEBOOK_ACCESS_TOKEN}}' \
-H 'cache-control: no-cache'
The above command returns JSON structured like this:
{
"data": {
"id": "1",
"network_id": "123456789101111212",
"name": "Account 1",
"currency": "EUR",
"timezone": "Europe/Paris",
"country": "FR",
"active": true,
"src": "fb"
}
}
This endpoint refresh a specific account from Facebook.
HTTP Request
PUT https://api.mysocialpixel.com/accounts/{{ACCOUNT_ID}}
URI Parameters
| Parameter | Description |
|---|---|
| ACCOUNT_ID | The ID of the account to refresh |
Query Parameters
| Parameter | Optional | Description |
|---|---|---|
| access_token | no | Facebook access token |
Delete a specific Account
curl -X DELETE \
'https://api.mysocialpixel.com/accounts/{{ACCOUNT_ID}}?key={{AGENCY_TOKEN}}' \
-H 'cache-control: no-cache'
The above command returns JSON structured like this:
{
"data": {
"id": "1",
"network_id": "123456789101111212",
"name": "Account 1",
"currency": "EUR",
"timezone": "Europe/Paris",
"country": "FR",
"active": false,
"src": "fb"
}
}
This endpoint deletes a specific account.
HTTP Request
DELETE https://api.mysocialpixel.com/accounts/{{ACCOUNT_ID}}
URI Parameters
| Parameter | Description |
|---|---|
| ACCOUNT_ID | The ID of the account to delete |
Get all lead forms
curl -X GET \
'https://api.mysocialpixel.com/accounts/{{ACCOUNT_ID}}/lead-forms?key={{AGENCY_TOKEN}}' \
-H 'cache-control: no-cache'
The above command returns JSON structured like this:
{
"data": [
{
"id": "12345",
"name": "My first lead form",
"network_id": "1234567890123456",
"csv_url": "https://www.facebook.com/ads/lead_gen/export_csv/?id=1234567890123456&type=form&source_type=graph_api",
"locale": "en_US"
},
{
"id": "105",
"name": "My second lead form",
"network_id": "1234567890654321",
"csv_url": "https://www.facebook.com/ads/lead_gen/export_csv/?id=1234567890654321&type=form&source_type=graph_api",
"locale": "en_US"
},
[...]
],
"range": {
"total": 1000,
"limit": 100,
"nb_pages": 10,
"page": 1,
"results": 100,
"next": "https://api.mysocialpixel.com/accounts/{{ACCOUNT_ID}}/lead-forms?key={{AGENCY_TOKEN}}&page=2"
}
}
This endpoint return a paginate list of all lead lead forms of an account.
The response is returned with pagination. The result resources are under data key, and the pagination informations are under range key.
HTTP Request
GET https://api.mysocialpixel.com/accounts/{{ACCOUNT_ID}}/lead-forms
URI Parameters
| Parameter | Description |
|---|---|
| ACCOUNT_ID | The ID of the account to retrieve |
Query Parameters
| Parameter | Optional | Default | Description |
|---|---|---|---|
| limit | yes | 100 | The maximum number of resource by page (Max 300) |
| page | yes | 1 | The requested page |
Search locations and interests
curl -X GET \
'https://api.mysocialpixel.com/accounts/{{ACCOUNT_ID}}/target_search?key={{AGENCY_TOKEN}}&q={{QUERY}}&type={{SEARCH_TYPE}}' \
-H 'cache-control: no-cache'
The above command returns JSON structured like this:
{
"data": [
{
"key": "6003221189867",
"name": "Swimming pool",
"category": "interests",
"type": "interests"
},
{
"key": "141750626068",
"name": "USA Swimming",
"category": "demographic",
"type": "work_employer"
},
{
"key": "359129637615491",
"name": "Swimming Instructor",
"category": "demographic",
"type": "schools"
},
{
"key": "773673316042450",
"name": "Swimming Coach",
"category": "demographic",
"type": "major"
}
]
}
The above command returns JSON structured like this:
{
"data": [
{
"key": "3875",
"name": "New York (United States)",
"type": "region",
"country_code": "US",
"country_name": "United States",
"supports_region": true,
"supports_city": true
},
{
"key": "DMA:501",
"name": "New York (DMA)",
"type": "geo_market",
"country_code": "US",
"country_name": "United States",
"supports_region": true,
"supports_city": true
},
{
"key": "2490299",
"name": "New York",
"type": "city",
"country_code": "US",
"country_name": "United States",
"region": "New York",
"region_id": 3875,
"supports_region": true,
"supports_city": true
}
]
}
This endpoint return a list of locations or interests
HTTP Request
GET https://api.mysocialpixel.com/accounts/{{ACCOUNT_ID}}/target_search
URI Parameters
| Parameter | Description |
|---|---|
| ACCOUNT_ID | The ID of the account for the search |
| SEARCH_TYPE | The search type |
| QUERY | The query to search |
Query Parameters
| Parameter | Optional | Default | Description |
|---|---|---|---|
| q | no | The query for the search calls. Spaces are allowed. | |
| type | no | Type of the search. Allowed value are location or interest |
Ad Sets
Get Ad Sets from Campaign
curl -X GET \
'https://api.mysocialpixel.com/clients/{{MEDIAPLAN_ID}}/campaigns/{{CAMPAIGN_ID}}/adsets?key={{AGENCY_TOKEN}}' \
-H 'cache-control: no-cache'
The above command returns JSON structured like this:
{
"data": [
{
"id": "1",
"daily_budget": 123,
"name": "ad-set-name-1",
"operation_status": "not_sync",
"status": "pause",
"bid": "1.23",
"promoted_object": "159753",
"adset_billing_event": "impressions",
"adset_optimization_goal": "post_engagement",
"computed_status": "not_sync"
},
{
"id": "2",
"daily_budget": 456,
"name": "ad-set-name-2",
"operation_status": "not_sync",
"status": "pause",
"bid": "4.56",
"promoted_object": "357951",
"adset_billing_event": "impressions",
"adset_optimization_goal": "post_engagement",
"computed_status": "not_sync"
},
[...]
],
"range": {
"total": 200,
"limit": 100,
"nb_pages": 2,
"page": 1,
"results": 100,
"next": "https://api.mysocialpixel.com/clients/{{MEDIAPLAN_ID}}/campaigns/{{CAMPAIGN_ID}}/adsets?limit=100&key={{AGENCY_TOKEN}}&page=2"
}
}
This endpoint retrieves all ad sets from a campaign.
The response is returned with pagination. The result resources are under data key, and the pagination informations are under range key.
HTTP Request
GET https://api.mysocialpixel.com/clients/{{MEDIAPLAN_ID}}/campaigns/{{CAMPAIGN_ID}}/adsets
URI Parameters
| Parameter | Description |
|---|---|
| MEDIAPLAN_ID | The ID of the ad set mediaplan to retrieve |
| CAMPAIGN_ID | The ID of the ad set campaign to retrieve |
Query Parameters
| Parameter | Optional | Default | Description |
|---|---|---|---|
| limit | yes | 100 | The maximum number of resource by page (Max 300) |
| page | yes | 1 | The requested page |
Get a specific Ad Set
curl -X GET \
'https://api.mysocialpixel.com/clients/{{MEDIAPLAN_ID}}/campaigns/{{CAMPAIGN_ID}}/adsets/{{ADSET_ID}}?key={{AGENCY_TOKEN}}' \
-H 'cache-control: no-cache'
The above command returns JSON structured like this:
{
"data":
{
"id": "1",
"daily_budget": 123,
"name": "ad-set-name-1",
"operation_status": "not_sync",
"status": "pause",
"bid": "1.23",
"promoted_object": "159753",
"adset_billing_event": "impressions",
"adset_optimization_goal": "post_engagement",
"computed_status": "not_sync"
}
}
This endpoint retrieves a specific ad set.
HTTP Request
GET https://api.mysocialpixel.com/clients/{{MEDIAPLAN_ID}}/campaigns/{{CAMPAIGN_ID}}/adsets/{{ADSET_ID}}
URI Parameters
| Parameter | Description |
|---|---|
| MEDIAPLAN_ID | The ID of the ad set mediaplan to retrieve |
| CAMPAIGN_ID | The ID of the ad set campaign to retrieve |
| ADSET_ID | The ID of the ad set to retrieve |
Create a new Ad Set
curl -X POST \
'https://api.mysocialpixel.com/clients/{{MEDIAPLAN_ID}}/campaigns/{{CAMPAIGN_ID}}/adsets?key={{AGENCY_TOKEN}}' \
-F name={{ADSET_NAME}} \
-F target={{TARGET_ID}} \
-F bid={{BID_AMOUNT}} \
-F adset_billing_event={{BILLING_EVENT}} \
-F adset_optimization_goal={{OPTIMIZATION_GOAL}}
The above command returns JSON structured like this:
[
{
"id": "2282",
"adset_bid_strategy": "lowest_cost_with_bid_cap",
"adset_optimization_goal": "impressions",
"adset_billing_event": "impressions",
"bid": "1",
"status": "play",
"daily_budget": 0.05,
"name": "name",
"computed_status": "not_sync"
}
]
Create a new Ad Set. Only available for Facebook Campaigns.
HTTP Request
POST https://api.mysocialpixel.com/clients/{{MEDIAPLAN_ID}}/campaigns/{{CAMPAIGN_ID}}/adsets
URI Parameters
| Parameter | Description |
|---|---|
| MEDIAPLAN_ID | The ID of the ad set mediaplan to create on |
| CAMPAIGN_ID | The ID of the ad set campaign to create on |
Query Parameters (Facebook)
| Parameter | Required | Default | Description | Enum | Incompatible with |
|---|---|---|---|---|---|
| bid | yes | Bid amount | |||
| status | yes | Ad Set status | play / pause | ||
| audience | no | Ad Set audience | target | ||
| target | no | Ad Set target | audience | ||
| sync | no | Ad Set sync | true / false | ||
| name | no | Ad Set name | |||
| adset_billing_event | yes | Ad Set billing event | APP_INSTALLS / IMPRESSIONS / LINK_CLICKS / NONE / PAGE_LIKES / POST_ENGAGEMENT / VIDEO_VIEWS / THRUPLAY / OFFER_CLAIMS | ||
| adset_optimization_goal | yes | Ad Set optimization goal | APP_INSTALLS / IMPRESSIONS / EVENT_RESPONSES / ENGAGED_USERS / POST_ENGAGEMENT / REACH / LINK_CLICKS / LANDING_PAGE_VIEWS / AD_RECALL_LIFT / LEAD_GENERATION / OFFER_CLAIMS / PAGE_LIKES / VIDEO_VIEWS / THRUPLAY / OFFSITE_CONVERSIONS / BRAND_AWARENESS / STORE_VISITS / TWO_SECOND_CONTINUOUS_VIDEO_VIEWS / VALUE / NONE | ||
| adset_attribution_window_days | yes | Ad Set attribution window days | 1 / 7 | ||
| adset_bid_strategy | yes | Ad Set bid strategy | lowest_cost_without_cap / lowest_cost_with_bid_cap / lowest_cost_with_cost_cap / target_cost | ||
| optimization_sub_event | no | Ad Set optimisation sub event | |||
| promoted_object | no | Ad Set promoted object ID | |||
| dynamic_product_mode | no | Ad Set dynamic product mode ID |
Update a specific Ad Set
curl -X PUT \
'https://api.mysocialpixel.com/clients/{{MEDIAPLAN_ID}}/campaigns/{{CAMPAIGN_ID}}/adsets/{{ADSET_ID}}?key={{AGENCY_TOKEN}}' \
-F name={{NEW_ADSET_NAME}}
The above command returns JSON structured like this:
[
{
"id": "12345",
"adset_bid_strategy": "lowest_cost_with_bid_cap",
"adset_optimization_goal": "impressions",
"adset_billing_event": "impressions",
"bid": "1",
"status": "play",
"daily_budget": 0.05,
"name": "new name",
"computed_status": "not_sync"
}
]
Update an existing Ad Set. Only available for Facebook Campaigns.
HTTP Request
PUT https://api.mysocialpixel.com/clients/{{MEDIAPLAN_ID}}/campaigns/{{CAMPAIGN_ID}}/adsets/{{ADSET_ID}}
URI Parameters
| Parameter | Description |
|---|---|
| MEDIAPLAN_ID | The ID of the ad set mediaplan |
| CAMPAIGN_ID | The ID of the ad set campaign |
| ADSET_ID | The ID of the ad set |
Query Parameters (Facebook)
| Parameter | Description | Enum | Incompatible with |
|---|---|---|---|
| bid | Bid amount | ||
| status | Ad Set status | play / pause | |
| name | Ad Set name | ||
| audience | Ad Set audience | target | |
| target | Ad Set target | audience | |
| sync | Ad Set sync | true / false | |
| adset_billing_event | Ad Set billing event | APP_INSTALLS / IMPRESSIONS / LINK_CLICKS / NONE / PAGE_LIKES / POST_ENGAGEMENT / VIDEO_VIEWS / THRUPLAY / OFFER_CLAIMS | |
| adset_optimization_goal | Ad Set optimization goal | APP_INSTALLS / IMPRESSIONS / EVENT_RESPONSES / ENGAGED_USERS / POST_ENGAGEMENT / REACH / LINK_CLICKS / LANDING_PAGE_VIEWS / AD_RECALL_LIFT / LEAD_GENERATION / OFFER_CLAIMS / PAGE_LIKES / VIDEO_VIEWS / THRUPLAY / OFFSITE_CONVERSIONS / BRAND_AWARENESS / STORE_VISITS / TWO_SECOND_CONTINUOUS_VIDEO_VIEWS / VALUE / NONE | |
| adset_attribution_window_days | Ad Set attribution window days | 1 / 7 | |
| adset_bid_strategy | Ad Set bid strategy | lowest_cost_without_cap / lowest_cost_with_bid_cap / lowest_cost_with_cost_cap / target_cost | |
| optimization_sub_event | Ad Set optimisation sub event | ||
| promoted_object | Ad Set promoted object ID | ||
| dynamic_product_mode | Ad Set dynamic product mode ID |
Ads
Get Ads from Campaign
curl -X GET \
'https://api.mysocialpixel.com/clients/{{MEDIAPLAN_ID}}/campaigns/{{CAMPAIGN_ID}}/ads?key={{AGENCY_TOKEN}}' \
-H 'cache-control: no-cache'
The above command returns JSON structured like this:
{
"data": [
{
"id": "1",
"deleted": false,
"type": "bulk_page_post_ad",
"target": {
"location": [
{
"label": "San Francisco",
"type": "city"
}
],
"age": [
"18-22"
],
"gender": "both"
},
"placement": {
"device": [
"mobile",
"desktop"
],
"publisher": [
"facebook",
"network",
"messenger"
],
"position": [
"feed",
"rhs",
"instant_article",
"network_classic",
"messenger_home"
]
},
"name": "ad name 1",
"status": "pause",
"synchro_status": "not_active",
"bid": 0.01,
"adset_billing_event": "impressions",
"adset_optimization_goal": "link_clicks",
"adset_bid_strategy": "lowest_cost_with_bid_cap",
"url": "http://www.my-url.com",
"src": "fb"
},
{
"id": "2",
"deleted": false,
"type": "page_post_ad",
"target": {
"location": [
{
"label": "San Francisco",
"type": "city"
}
],
"age": [
"18-22"
],
"gender": "both"
},
"placement": {
"device": [
"mobile",
"desktop"
],
"publisher": [
"facebook",
"network",
"messenger"
],
"position": [
"feed",
"rhs",
"instant_article",
"network_classic",
"messenger_home"
]
},
"name": "ad name 2",
"status": "pause",
"synchro_status": "not_active",
"bid": 0.01,
"adset_billing_event": "impressions",
"adset_optimization_goal": "link_clicks",
"adset_bid_strategy": "lowest_cost_with_bid_cap",
"headline": "my_headline",
"url": "http://www.my-url.com",
"message": "my_message",
"description": "my description",
"page": "123456789",
"src": "fb"
},
[...]
],
"range": {
"total": 1000,
"limit": 100,
"nb_pages": 10,
"page": 1,
"results": 100,
"next": "https://api.mysocialpixel.com/clients/{{MEDIAPLAN_ID}}/campaigns/{{CAMPAIGN_ID}}/ads?key={{AGENCY_TOKEN}}&page=2"
}
}
This endpoint retrieves all Ads from a Campaign.
The response is returned with pagination. The result resources are under data key, and the pagination informations are under range key.
HTTP Request
GET https://api.mysocialpixel.com/clients/{{MEDIAPLAN_ID}}/campaigns/{{CAMPAIGN_ID}}/ads
URI Parameters
| Parameter | Description |
|---|---|
| MEDIAPLAN_ID | The ID of the ad's mediaplan to retrieve |
| CAMPAIGN_ID | The ID of the ad's campaign to retrieve |
Query Parameters
| Parameter | Optional | Default | Description |
|---|---|---|---|
| limit | yes | 100 | The maximum number of resource by page (Max 300) |
| page | yes | 1 | The requested page |
Get Ads from Adset
curl -X GET \
'https://api.mysocialpixel.com/clients/{{MEDIAPLAN_ID}}/campaigns/{{CAMPAIGN_ID}}/adsets/{{ADSET_ID}}/ads?key={{AGENCY_TOKEN}}' \
-H 'cache-control: no-cache'
The above command returns JSON structured like this:
{
"data": [
{
"id": "1",
"deleted": false,
"type": "bulk_page_post_ad",
"target": {
"location": [
{
"label": "San Francisco",
"type": "city"
}
],
"age": [
"18-22"
],
"gender": "both"
},
"placement": {
"device": [
"mobile",
"desktop"
],
"publisher": [
"facebook",
"network",
"messenger"
],
"position": [
"feed",
"rhs",
"instant_article",
"network_classic",
"messenger_home"
]
},
"name": "ad name 1",
"status": "pause",
"synchro_status": "not_active",
"bid": 0.01,
"adset_billing_event": "impressions",
"adset_optimization_goal": "link_clicks",
"adset_bid_strategy": "lowest_cost_with_bid_cap",
"url": "http://www.my-url.com",
"src": "fb"
},
{
"id": "2",
"deleted": false,
"type": "page_post_ad",
"target": {
"location": [
{
"label": "San Francisco",
"type": "city"
}
],
"age": [
"18-22"
],
"gender": "both"
},
"placement": {
"device": [
"mobile",
"desktop"
],
"publisher": [
"facebook",
"network",
"messenger"
],
"position": [
"feed",
"rhs",
"instant_article",
"network_classic",
"messenger_home"
]
},
"name": "ad name 2",
"status": "pause",
"synchro_status": "not_active",
"bid": 0.01,
"adset_billing_event": "impressions",
"adset_optimization_goal": "link_clicks",
"adset_bid_strategy": "lowest_cost_with_bid_cap",
"headline": "my_headline",
"url": "http://www.my-url.com",
"message": "my_message",
"description": "my description",
"page": "123456789",
"src": "fb"
},
[...]
],
"range": {
"total": 1000,
"limit": 100,
"nb_pages": 10,
"page": 1,
"results": 100,
"next": "https://api.mysocialpixel.com/clients/{{MEDIAPLAN_ID}}/campaigns/{{CAMPAIGN_ID}}/adsets/{{ADSET_ID}}/ads?key={{AGENCY_TOKEN}}&page=2"
}
}
This endpoint retrieves all Ads form an Adset.
The response is returned with pagination. The result resources are under data key, and the pagination informations are under range key.
HTTP Request
GET https://api.mysocialpixel.com/clients/{{MEDIAPLAN_ID}}/campaigns/{{CAMPAIGN_ID}}/adsets/{{ADSET_ID}}/ads
URI Parameters
| Parameter | Description |
|---|---|
| MEDIAPLAN_ID | The ID of the ad's mediaplan to retrieve |
| CAMPAIGN_ID | The ID of the ad's campaign to retrieve |
| ADSET_ID | The ID of the ad's adset to retrieve |
Query Parameters
| Parameter | Optional | Default | Description |
|---|---|---|---|
| limit | yes | 100 | The maximum number of resource by page (Max 300) |
| page | yes | 1 | The requested page |
Get a specific Ad
curl -X GET \
'https://api.mysocialpixel.com/clients/{{MEDIAPLAN_ID}}/campaigns/{{CAMPAIGN_ID}}/adsets/{{ADSET_ID}}/ads/{{AD_ID}}?key={{AGENCY_TOKEN}}' \
-H 'cache-control: no-cache'
The above command returns JSON structured like this:
{
"id": "1",
"deleted": false,
"type": "bulk_page_post_ad",
"target": {
"location": [
{
"label": "San Francisco",
"type": "city"
}
],
"age": [
"18-22"
],
"gender": "both"
},
"placement": {
"device": [
"mobile",
"desktop"
],
"publisher": [
"facebook",
"network",
"messenger"
],
"position": [
"feed",
"rhs",
"instant_article",
"network_classic",
"messenger_home"
]
},
"name": "ad name 1",
"status": "pause",
"synchro_status": "not_active",
"bid": 0.01,
"adset_billing_event": "impressions",
"adset_optimization_goal": "link_clicks",
"adset_bid_strategy": "lowest_cost_with_bid_cap",
"url": "http://www.my-url.com",
"src": "fb"
}
This endpoint retrieves a specific Ad.
HTTP Request
GET https://api.mysocialpixel.com/clients/{{MEDIAPLAN_ID}}/campaigns/{{CAMPAIGN_ID}}/adsets/{{ADSET_ID}}/ads/{{AD_ID}}
URI Parameters
| Parameter | Description |
|---|---|
| MEDIAPLAN_ID | The ID of the ad's mediaplan to retrieve |
| CAMPAIGN_ID | The ID of the ad's campaign to retrieve |
| ADSET_ID | The ID of the ad's adset to retrieve |
| AD_ID | The ID of the ad to retrieve |
Create a new Ad
curl -X POST \
'http://api.mysocialpixel.com/clients/{{MEDIAPLAN_ID}}/campaigns/{{CAMPAIGN_ID}}/adsets/{{ADSET_ID}}/ads?key={{TOKEN_ID}}' \
-H 'Cache-Control: no-cache' \
-F name={{VALUE}}
-F creative={{VALUE}}
-F bid={{VALUE}}
-F headline={{VALUE}}
-F message={{VALUE}}
-F call_to_action={{VALUE}}
-F type={{VALUE}}
-F product_set={{VALUE}}
-F page={{VALUE}}
-F multi_share_optimized={{VALUE}}
-F multi_share_end_card={{VALUE}}
-F child_attachments={{VALUE}}
-F description={{VALUE}}
-F view_tag={{VALUE}}
-F url_tag={{VALUE}}
-F url={{VALUE}}
-F image={{VALUE}}
-F sync={{VALUE}}
{
"id": "1",
"deleted": false,
"type": "bulk_page_post_ad",
"target": {
"location": [
{
"label": "San Francisco",
"type": "city"
}
],
"age": [
"18-22"
],
"gender": "both"
},
"placement": {
"device": [
"mobile",
"desktop"
],
"publisher": [
"facebook",
"network",
"messenger"
],
"position": [
"feed",
"rhs",
"instant_article",
"network_classic",
"messenger_home"
]
},
"name": "my ad name",
"status": "pause",
"synchro_status": "not_active",
"bid": 0.02,
"adset_billing_event": "impressions",
"adset_optimization_goal": "link_clicks",
"adset_bid_strategy": "lowest_cost_with_bid_cap",
"url": "http://my-url.com",
"src": "fb"
}
This endpoint add a specific Ad.
HTTP Request
POST https://api.mysocialpixel.com/clients/{{MEDIAPLAN_ID}}/campaigns/{{CAMPAIGN_ID}}/adsets/{{ADSET_ID}}/ads
URI Parameters
| Parameter | Description |
|---|---|
| MEDIAPLAN_ID | The ID of the ad's mediaplan to update |
| CAMPAIGN_ID | The ID of the ad's campaign to update |
| ADSET_ID | The ID of the ad's adset to update |
Query Parameters
| Parameter | Optional | type | description | values | information |
|---|---|---|---|---|---|
| name | yes | string | if specified will overrite naming convention, if not will be auto generated. | ||
| creative | yes | int | Id creative | only if type and product_set not exist | |
| type | yes | string | type of creative | 'post', 'carousel' | only if creative and product_set not exist |
| product_set | yes | string | publisher id of product set | ||
| bid | yes | float | the bid value | ||
| description | yes | string | description will be displayed in ads | ||
| view_tag | yes | string | wiew tags | ||
| url_tag | yes | string | url tags | ||
| headline | yes | string | headline will be displayed in ads | only if creative and product_set not exist | |
| message | yes | string | message will be displayed in ads | only if creative and product_set not exist | |
| call_to_action | yes | string | call to action be displayed in ads | 'OPEN_LINK', 'BOOK_TRAVEL', 'SHOP_NOW', 'LEARN_MORE', 'LISTEN_MUSIC', 'WATCH_MORE', 'SIGN_UP', 'DOWNLOAD', 'DONATE_NOW', 'APPLY_NOW', 'CONTACT_US', 'GET_QUOTE', 'SUBSCRIBE', 'NO_BUTTON' | only if creative, product_set and child_attachment not exist |
| page | yes | string | page/place id | only if creative and product_set not exist | |
| instagram_page | yes | string | publisher instagram id or default_destination_value |
only if creative not exist | |
| url | yes | string | redirection url of your ads | ||
| image | yes | string | url to the picture | ||
| multi_share_optimized | yes | string | multi share iptimized | 'true', 'false' | only if creative and product_set not exist and type is 'carousel' |
| multi_share_end_card | yes | string | add end card | 'true', 'false' | only if creative and product_set not exist and type is 'carousel' |
| child_attachments | yes | array | only if creative and product_set not exist and type is 'carousel' | ||
| sync | yes | bool | push the ad on publishers |
Perform an action on specific Ad
curl -X PATCH \
'http://api.mysocialpixel.com/clients/{{MEDIAPLAN_ID}}/campaigns/{{CAMPAIGN_ID}}/ads/{{AD_ID}}/performs/{{ACTION}}?key={{TOKEN_ID}}' \
-H 'Cache-Control: no-cache' \
-d bid={{VALUE}}
{
"id": "`",
"deleted": false,
"type": "bulk_page_post_ad",
"target": {
"location": [
{
"label": "San Francisco",
"type": "city"
}
],
"age": [
"18-22"
],
"gender": "both"
},
"placement": {
"device": [
"mobile",
"desktop"
],
"publisher": [
"facebook",
"network",
"messenger"
],
"position": [
"feed",
"rhs",
"instant_article",
"network_classic",
"messenger_home"
]
},
"name": "my ad name",
"status": "pause",
"synchro_status": "not_active",
"bid": 0.02,
"adset_billing_event": "impressions",
"adset_optimization_goal": "link_clicks",
"adset_bid_strategy": "lowest_cost_with_bid_cap",
"url": "http://my-url.com",
"src": "fb"
}
This endpoint perform an action on a specific Ad.
HTTP Request
PATCH https://api.mysocialpixel.com/clients/{{MEDIAPLAN_ID}}/campaigns/{{CAMPAIGN_ID}}/ads/{{AD_ID}}/performs/{{ACTION}}
URI Parameters
| Parameter | Description | Values |
|---|---|---|
| MEDIAPLAN_ID | The ID of the ad's mediaplan to perform | |
| CAMPAIGN_ID | The ID of the ad's campaign to perform | |
| AD_ID | The ID of the ad to perform | |
| ACTION | Action to perform | play, pause, bid-update, custom-text-update, custom-value-update |
Query Parameters
| Parameter | Optional | Description |
|---|---|---|
| bid | yes | Required for action 'bid-update' (float) |
| value | yes | Required for action 'custom-text-update' (string) or action 'custom-value-update' (float) |
Update a specific Ad
curl -X PUT \
'http://api.mysocialpixel.com/clients/{{MEDIAPLAN_ID}}/campaigns/{{CAMPAIGN_ID}}/adsets/{{ADSET_ID}}/ads/{{AD_ID}}?key={{TOKEN_ID}}' \
-H 'Cache-Control: no-cache' \
-d name={{VALUE}}
-d creative={{VALUE}}
-d bid={{VALUE}}
-d headline={{VALUE}}
-d message={{VALUE}}
-d call_to_action={{VALUE}}
-d type={{VALUE}}
-d product_set={{VALUE}}
-d page={{VALUE}}
-d multi_share_optimized={{VALUE}}
-d multi_share_end_card={{VALUE}}
-d child_attachments={{VALUE}}
-d description={{VALUE}}
-d view_tag={{VALUE}}
-d url_tag={{VALUE}}
-d url={{VALUE}}
-d image={{VALUE}}
-d sync={{VALUE}}
{
"id": "1",
"deleted": false,
"type": "bulk_page_post_ad",
"target": {
"location": [
{
"label": "San Francisco",
"type": "city"
}
],
"age": [
"18-22"
],
"gender": "both"
},
"placement": {
"device": [
"mobile",
"desktop"
],
"publisher": [
"facebook",
"network",
"messenger"
],
"position": [
"feed",
"rhs",
"instant_article",
"network_classic",
"messenger_home"
]
},
"name": "my ad name",
"status": "pause",
"synchro_status": "not_active",
"bid": 0.02,
"adset_billing_event": "impressions",
"adset_optimization_goal": "link_clicks",
"adset_bid_strategy": "lowest_cost_with_bid_cap",
"url": "http://my-url.com",
"src": "fb"
}
This endpoint update a specific Ad.`
HTTP Request
PUT https://api.mysocialpixel.com/clients/{{MEDIAPLAN_ID}}/campaigns/{{CAMPAIGN_ID}}/adsets/{{ADSET_ID}}/ads/{{AD_ID}}
URI Parameters
| Parameter | Description |
|---|---|
| MEDIAPLAN_ID | The ID of the ad's mediaplan to update |
| CAMPAIGN_ID | The ID of the ad's campaign to update |
| ADSET_ID | The ID of the ad's adset to update |
| AD_ID | The ID of the ad to update |
Query Parameters
| Parameter | Optional | type | description | values | information |
|---|---|---|---|---|---|
| name | yes | string | if specified will overrite naming convention, if not will be auto generated. | ||
| creative | yes | int | Id creative | only if type and product_set not exist | |
| type | yes | string | type of creative | 'post', 'carousel' | only if creative and product_set not exist |
| product_set | yes | string | publisher id of product set | ||
| bid | yes | float | the bid value | ||
| description | yes | string | description will be displayed in ads | ||
| view_tag | yes | string | wiew tags | ||
| url_tag | yes | string | url tags | ||
| headline | yes | string | headline will be displayed in ads | only if creative and product_set not exist | |
| message | yes | string | message will be displayed in ads | only if creative and product_set not exist | |
| call_to_action | yes | string | call to action be displayed in ads | 'OPEN_LINK', 'BOOK_TRAVEL', 'SHOP_NOW', 'LEARN_MORE', 'LISTEN_MUSIC', 'WATCH_MORE', 'SIGN_UP', 'DOWNLOAD', 'DONATE_NOW', 'APPLY_NOW', 'CONTACT_US', 'GET_QUOTE', 'SUBSCRIBE', 'NO_BUTTON' | only if creative, product_set and child_attachment not exist |
| page | yes | string | page/place id | only if creative and product_set not exist | |
| instagram_page | yes | string | publisher instagram id or default_destination_value |
only if creative not exist | |
| url | yes | string | redirection url of your ads | ||
| image | yes | string | url to the picture | ||
| multi_share_optimized | yes | string | multi share optimized | 'true', 'false' | only if creative and product_set not exist and type is 'carousel' |
| multi_share_end_card | yes | string | add end card | 'true', 'false' | only if creative and product_set not exist and type is 'carousel' |
| child_attachments | yes | array | only if creative and product_set not exist and type is 'carousel' | ||
| sync | yes | bool | push the ad on publishers |
Delete a specific Ad
curl -X DELETE \
'https://api.mysocialpixel.com/clients/{{MEDIAPLAN_ID}}/campaigns/{{CAMPAIGN_ID}}/adsets/{{ADSET_ID}}/ads/{{AD_ID}}?key={{AGENCY_TOKEN}}' \
-H 'cache-control: no-cache'
The above command returns JSON structured like this:
{
"id": "1",
"deleted": true,
"type": "bulk_page_post_ad",
"target": {
"location": [
{
"label": "San Francisco",
"type": "city"
}
],
"age": [
"18-22"
],
"gender": "both"
},
"placement": {
"device": [
"mobile",
"desktop"
],
"publisher": [
"facebook",
"network",
"messenger"
],
"position": [
"feed",
"rhs",
"instant_article",
"network_classic",
"messenger_home"
]
},
"name": "ad name 1",
"status": "pause",
"synchro_status": "not_active",
"bid": 0.01,
"adset_billing_event": "impressions",
"adset_optimization_goal": "link_clicks",
"adset_bid_strategy": "lowest_cost_with_bid_cap",
"url": "http://www.my-url.com",
"src": "fb"
}
This endpoint delete a specific Ad.
HTTP Request
DELETE https://api.mysocialpixel.com/clients/{{MEDIAPLAN_ID}}/campaigns/{{CAMPAIGN_ID}}/adsets/{{ADSET_ID}}/ads/{{AD_ID}}
URI Parameters
| Parameter | Description |
|---|---|
| MEDIAPLAN_ID | The ID of the mediaplan to retrieve |
| CAMPAIGN_ID | The ID of the campaign to retrieve |
| ADSET_ID | The ID of the adset to retrieve |
| AD_ID | The ID of the ad to retrieve |
Advertisers
Get all Advertisers
curl -X GET \
'https://api.mysocialpixel.com/advertisers?key={{AGENCY_TOKEN}}' \
-H 'cache-control: no-cache'
The above command returns JSON structured like this:
{
"data":[
{
"id":"1",
"name":"Advertiser 1",
"currency":"GBP",
"reporting_week":"Saturday_Friday"
},
{
"id":"2",
"name":"Advertiser 2",
"currency":"USD",
"reporting_week":"Tuesday_Monday"
},
[...]
],
"range": {
"total": 1000,
"limit": 100,
"nb_pages": 10,
"page": 1,
"results": 100,
"next": "https://api.mysocialpixel.com/advertisers?key={{AGENCY_TOKEN}}&page=2"
}
}
This endpoint retrieves all advertisers.
The response is returned with pagination. The result resources are under data key, and the pagination informations are under range key.
HTTP Request
GET https://api.mysocialpixel.com/advertisers
Query Parameters
| Parameter | Optional | Default | Description |
|---|---|---|---|
| limit | yes | 100 | The maximum number of resource by page (Max 300) |
| page | yes | 1 | The requested page |
Get a specific Advertiser
curl -X GET \
'https://api.mysocialpixel.com/advertisers/{{ADVERTISER_ID}}?key={{AGENCY_TOKEN}}' \
-H 'cache-control: no-cache'
The above command returns JSON structured like this:
{
"id":"1",
"name":"advertiser 1",
"currency":"USD",
"reporting_week":"Saturday_Friday"
}
This endpoint retrieves a specific advertiser.
HTTP Request
GET https://api.mysocialpixel.com/advertisers/{{ADVERTISER_ID}}
URI Parameters
| Parameter | Description |
|---|---|
| ADVERTISER_ID | The ID of the advertiser to retrieve |
Query Parameters
Add a new Advertiser
curl -X POST \
'http://api.mysocialpixel.com/advertisers?key={{AGENCY_TOKEN}}' \
-H 'Cache-Control: no-cache' \
-F name={{ADVERTISER_NAME}} \
-F currency={{ADVERTISER_CURRENCY}} \
-F autopause_value={{AUTOPAUSE_VALUE}} \
-F contact_name={{CONTACT_NAME}} \
-F contact_phone={{CONTACT_PHONE}} \
-F contact_mail={{CONTACT_MAIL}} \
-F reporting_week={{REPORTING_WEEK}}
The above command returns JSON structured like this:
{
"id": "2",
"name": "advertiser name",
"currency": "EUR",
"contact_name": "name",
"contact_mail": "my@email.com",
"contact_phone": "0102030405",
"autopause_value": 100,
"reporting_week":"Saturday_Friday"
}
This endpoint add a specific Advertiser.
HTTP Request
POST https://api.mysocialpixel.com/advertisers
Query Parameters
| Parameter | Optional | Description |
|---|---|---|
| name | no | The name of the advertiser: it must be unique inside the agency |
| currency | no | The currency of the advertiser |
| autopause_value | yes | The auto pause value if you want an autopause |
| contact_name | yes | The contact name |
| contact_phone | yes | The contact phone |
| contact_mail | yes | The contact email |
| reporting_week | yes | The reporting week. Default value: "Sunday_Saturday" |
| timezone | yes | The timezone of the advertiser (default: "Europe/Paris") |
Update a specific Advertiser
curl -X PUT \
'http://api.mysocialpixel.com/advertisers/{{ADVERTISER_ID}}?key={{AGENCY_TOKEN}}' \
-H 'Cache-Control: no-cache' \
-d 'name={{ADVERTISER_NAME}}¤cy={{ADVERTISER_CURRENCY}}&{{AUTOPAUSE_VALUE}}=100&contact_name={{CONTACT_NAME}}&contact_phone={{CONTACT_PHONE}}&contact_mail={{CONTACT_MAIL}}&reporting_week={{REPORTING_WEEK}}'
This endpoint update a specific advertiser.
{
"id": "2",
"name": "advertiser name",
"currency": "EUR",
"contact_name": "name",
"contact_mail": "my@email.com",
"contact_phone": "0102030405",
"autopause_value": 100,
"reporting_week":"Saturday_Friday"
}
HTTP Request
PUT https://api.mysocialpixel.com/advertisers/{{ADVERTISER_ID}}
URI Parameters
| Parameter | Description |
|---|---|
| ADVERTISER_ID | The ID of the advertiser to update |
Query Parameters
| Parameter | Optional | Description |
|---|---|---|
| name | yes | The name of the advertiser: it must be unique inside the agency |
| currency | yes | The currency of the advertiser |
| autopause_value | yes | The auto pause value if you want an autopause |
| contact_name | yes | The contact name |
| contact_phone | yes | The contact phone |
| contact_mail | yes | The contact email |
| reporting_week | yes | The reporting week |
Delete a specific Advertiser
curl -X DELETE \
'https://api.mysocialpixel.com/advertisers/{{ADVERTISER_ID}}?key={{AGENCY_TOKEN}}' \
-H 'cache-control: no-cache'
This endpoint deletes a specific advertiser.
{
"data": {
"id": "2",
"name": "advertiser name",
"currency": "EUR",
"contact_name": "name",
"contact_mail": "my@email.com",
"contact_phone": "0102030405",
"autopause_value": 10000,
"reporting_week":"Saturday_Friday"
}
}
HTTP Request
DELETE https://api.mysocialpixel.com/advertisers/{{ADVERTISER_ID}}
URI Parameters
| Parameter | Description |
|---|---|
| ADVERTISER_ID | The ID of the advertiser to delete |
Campaigns
Get all Campaigns of your agency
curl -X GET \
'https://api.mysocialpixel.com/campaigns?key={{AGENCY_TOKEN}}' \
-H 'cache-control: no-cache'
The above command returns JSON structured like this:
{
"data" : [
{
"status" : "pause",
"account_id" : "101",
"deleted" : false,
"campaign_naming" : "{campaign-name}-{age-min}-{age-max}-{country}-{interest}",
"start_date" : "2017-10-16T11:15:00+0000",
"ads_naming" : "{campaign-name}-{age-min}-{age-max}-{picture}-{title}",
"budget_type" : "daily",
"url_reporting" : "https://social.marinsoftware.com/report/en/spent/{{CAMPAIGN_HASH_ID}}",
"daily_budget" : 10,
"client_id" : "105",
"budget" : 10,
"name" : "campaign 1",
"id" : "1",
"archived" : false,
"src" : "fb"
},
{
"client_id" : "101",
"daily_budget" : 10,
"url_reporting" : "https://social.marinsoftware.com/report/en/spent/{{CAMPAIGN_HASH_ID}}",
"src" : "tw",
"lifetime_budget" : 200,
"archived" : false,
"id" : "2",
"name" : "campaign 2",
"start_date" : "2018-04-26T12:04:00+0000",
"campaign_naming" : "{campaign-name}-{country}-{gender}-{interest}-{twitteraccounts}-{keywords}",
"ads_naming" : "{campaign-name}-{country}-{gender}-{interest}-{twitteraccounts}-{keywords}-{tweetId}",
"deleted" : false,
"account_id" : "102",
"funding_instrument_id" : "201",
"status" : "pause"
},
[...]
],
"range" : {
"nb_pages" : 10,
"next" : "https://api.mysocialpixel.com/campaigns?limit=100&key={{AGENCY_TOKEN}}&page=2",
"limit" : 100,
"results" : 100,
"total" : 10000,
"page" : 1
}
}
This endpoint retrieves all campaigns.
The response is returned with pagination. The result resources are under data key, and the pagination informations are under range key.
HTTP Request
GET https://api.mysocialpixel.com/campaigns
Query Parameters
| Parameter | Optional | Default | Description |
|---|---|---|---|
| limit | yes | 100 | The maximum number of resource by page (Max 300) |
| page | yes | 1 | The requested page |
Get all Campaigns of a media plan
curl -X GET \
'https://api.mysocialpixel.com/clients/{{MEDIAPLAN_ID}}/campaigns?key={{AGENCY_TOKEN}}' \
-H 'cache-control: no-cache'
The above command returns JSON structured like this:
{
"data" : [
{
"status" : "pause",
"account_id" : "101",
"deleted" : false,
"campaign_naming" : "{campaign-name}-{age-min}-{age-max}-{country}-{interest}",
"start_date" : "2017-10-16T11:15:00+0000",
"ads_naming" : "{campaign-name}-{age-min}-{age-max}-{picture}-{title}",
"budget_type" : "daily",
"url_reporting" : "https://social.marinsoftware.com/report/en/spent/{{CAMPAIGN_HASH_ID}}",
"daily_budget" : 10,
"client_id" : "105",
"budget" : 10,
"name" : "campaign 1",
"id" : "1",
"archived" : false,
"src" : "fb",
"special_ad_category": "housing"
},
[...]
],
"range" : {
"nb_pages" : 10,
"next" : "https://api.mysocialpixel.com/clients/{{MEDIAPLAN_ID}}/campaigns?limit=100&key={{AGENCY_TOKEN}}&page=2",
"limit" : 100,
"results" : 100,
"total" : 10000,
"page" : 1
}
}
This endpoint retrieves all campaigns.
The response is returned with pagination. The result resources are under data key, and the pagination informations are under range key.
HTTP Request
GET https://api.mysocialpixel.com/clients/{{MEDIAPLAN_ID}}/campaigns
URI Parameters
| Parameter | Description |
|---|---|
| MEDIAPLAN_ID | The ID of the media plan containing a list of campaigns |
Query Parameters
| Parameter | Optional | Default | Description |
|---|---|---|---|
| limit | yes | 100 | The maximum number of resource by page (Max 300) |
| page | yes | 1 | The requested page |
Get a specific Campaign
curl -X GET \
'https://api.mysocialpixel.com/clients/{{MEDIAPLAN_ID}}/campaigns/{{CAMPAIGN_ID}}?key={{AGENCY_TOKEN}}' \
-H 'cache-control: no-cache'
The above command returns JSON structured like this:
{
"data" : {
"status" : "pause",
"account_id" : "101",
"deleted" : false,
"campaign_naming" : "{campaign-name}-{age-min}-{age-max}-{country}-{interest}",
"start_date" : "2017-10-16T11:15:00+0000",
"ads_naming" : "{campaign-name}-{age-min}-{age-max}-{picture}-{title}",
"budget_type" : "daily",
"url_reporting" : "https://social.marinsoftware.com/report/en/spent/{{CAMPAIGN_HASH_ID}}",
"daily_budget" : 10,
"client_id" : "105",
"budget" : 10,
"name" : "campaign 1",
"id" : "1",
"archived" : false,
"src" : "fb",
"special_ad_category": "none"
}
}
This endpoint retrieves a specific campaign.
HTTP Request
GET https://api.mysocialpixel.com/clients/{{MEDIAPLAN_ID}}/campaigns/{{CAMPAIGN_ID}}
URI Parameters
| Parameter | Description |
|---|---|
| MEDIAPLAN_ID | The ID of the media plan containing the campaign |
| CAMPAIGN_ID | The ID of the campaign to retrieve |
Create a new Campaign
curl -X POST \
'https://api.mysocialpixel.com/clients/{{MEDIAPLAN_ID}}/campaigns?key={{AGENCY_TOKEN}}' \
-H 'cache-control: no-cache' \
-F 'name={{CAMPAIGN_NAME}}' \
-F 'status={{CAMPAIGN_STATUS}}' \
-F 'objective={{CAMPAIGN_OBJECTIVE}}' \
-F 'budget_type={{BUDGET_TYPE}}' \
-F 'daily_budget={{BUDGET_VALUE}}' \
-F 'lifetime_budget={{BUDGET_VALUE}}' \
-F 'start_date={{TIMESTAMP}}' \
-F 'useReachAndFrequency=false' \
-F 'special_ad_category={{SPECIAL_AD_CATEGORY_VALUE}}'
The above command returns JSON structured like this:
{
"status" : "pause",
"account_id" : "101",
"deleted" : false,
"campaign_naming" : "{campaign-name}-{age-min}-{age-max}-{country}-{interest}",
"start_date" : "2017-10-16T11:15:00+0000",
"ads_naming" : "{campaign-name}-{age-min}-{age-max}-{picture}-{title}",
"budget_type" : "daily",
"url_reporting" : "https://social.marinsoftware.com/report/en/spent/{{CAMPAIGN_HASH_ID}}",
"daily_budget" : 10,
"client_id" : "105",
"budget" : 10,
"name" : "campaign 1",
"id" : "1",
"archived" : false,
"src" : "fb",
"special_ad_category": "credit"
}
HTTP Request
POST https://api.mysocialpixel.com/clients/{{MEDIAPLAN_ID}}/campaigns
URI Parameters
| Parameter | Description |
|---|---|
| MEDIAPLAN_ID | The ID of the media plan containing a list of campaigns |
Query Parameters (Facebook)
| Parameter | Optional | Default | Description | Enum |
|---|---|---|---|---|
| name | no | |||
| status | no | play / pause | ||
| objective | no | fan_acq / event / eng / outside_traffic / offer / app_installs / video_play / product_catalog_sales / website_conv / lead_gen / brand_awareness / store_visits / reach | ||
| budget_type | no | If you create campaign with a daily budget, the campaign must be at least 24h long or more. If it's not the case, lifetime will be used |
daily / lifetime | |
| daily_budget | yes | Required if budget type is daily | ||
| lifetime_budget | yes | Required if budget type is daily | ||
| start_date | no | Unix timestamp value of the start date | ||
| end_date | yes | Unix timestamp value of the end date | ||
| useReachAndFrequency | no | Only use this field if the campaign is Reach and Frequency | ||
| io_number | yes | |||
| rule | yes | Rule ID used by the campaign | ||
| sync | yes | false | Defined if the newly campaign should be sync | true / false |
| campaign_naming | yes | {campaign-name}-{age-min}-{age-max}-{country}-{interest} | {formId} / {form-name} works only with lead_gen objective | {campaign-name} / {campaign-objective} / {adId} / {age-min} / {age-max} / {country} / {town} / {language} / {interest} / {os} / {device} / {behaviors} / {picture} / {title} / {gender} / {placement} / {postId} / {creativeId} / {titleId} / {bodyId} / {imageId} / {includedcustomaudience} / {excludedcustomaudience} / {ioNumber} / {office} / {endAdvertiser} / {audiencename} / {creationdate} / {format} / {productSet-name} / {productAudience-name} / {productTemplate-name} / {post-type} / {location-cluster} / {interest-cluster} / {dpa-mode} / {publisher} / {page-name} / {formId} / {form-name} |
| ads_naming | yes | {campaign-name}-{age-min}-{age-max}-{picture}-{title} | {formId} / {form-name} works only with lead_gen objective | {campaign-name} / {campaign-objective} / {adId} / {age-min} / {age-max} / {country} / {town} / {language} / {interest} / {os} / {device} / {behaviors} / {picture} / {title} / {gender} / {placement} / {postId} / {creativeId} / {titleId} / {bodyId} / {imageId} / {includedcustomaudience} / {excludedcustomaudience} / {ioNumber} / {office} / {endAdvertiser} / {audiencename} / {creationdate} / {format} / {productSet-name} / {productAudience-name} / {productTemplate-name} / {post-type} / {location-cluster} / {interest-cluster} / {dpa-mode} / {publisher} / {page-name} / {formId} / {form-name} / {adset-name} / {marinadid} |
| spend_cap | yes | |||
| business_manager_id | yes | Required if objective is product_catalog_sales |
||
| product_catalog_id | yes | Required if objective is product_catalog_sales |
||
| pixel_external_id | yes | Required if objective is website_conv |
||
| pixel_event | yes | Required if objective is website_conv |
ViewContent / Search / AddToCart / AddToWishlist / InitiateCheckout / AddPaymentInfo / Purchase / Lead / CompleteRegistration | |
| pacing_type | yes | standard / no_pacing | ||
| special_ad_category | yes | Special ad category | credit / housing / employment / none |
Query Parameters (Twitter)
| Parameter | Optional | Default | Description | Enum |
|---|---|---|---|---|
| name | no | |||
| status | no | play / pause | ||
| objective | no | APP_ENGAGEMENTS / APP_INSTALLS / TWEET_ENGAGEMENTS / WEBSITE_CLICKS / WEBSITE_CONVERSIONS / VIDEO_VIEWS / AWARENESS | ||
| daily_budget | no | |||
| lifetime_budget | no | |||
| start_date | no | Unix timestamp value of the start date | ||
| end_date | yes | Unix timestamp value of the end date | ||
| io_number | yes | |||
| sync | yes | false | Defined if the newly campaign should be sync | true / false |
| campaign_naming | yes | {campaign-name}-{country}-{gender}-{interest}-{twitteraccounts}-{keywords} | {campaign-name} / {campaign-objective} / {country} / {interest} / {gender} / {twitteraccounts} / {keywords} / {tweetId} / {os} / {device} / {keyword-cluster} / {handle-cluster} / {placement} / {tailored-audience} / {handle} / {ioNumber} / {publisher} / {page-name} | |
| ads_naming | yes | {campaign-name}-{country}-{gender}-{interest}-{twitteraccounts}-{keywords}-{tweetId} | {campaign-name} / {campaign-objective} / {country} / {interest} / {gender} / {twitteraccounts} / {keywords} / {tweetId} / {os} / {device} / {keyword-cluster} / {handle-cluster} / {placement} / {tailored-audience} / {handle} / {ioNumber} / {publisher} / {page-name} / {adset-name} / {marinadid} | |
| funding_instrument_id | no | |||
| rule | yes | Rule ID used by the campaign |
Update a Campaign
curl -X PUT \
'https://api.mysocialpixel.com/clients/{{MEDIAPLAN_ID}}/campaigns/{{CAMPAIGN_ID}}?key={{AGENCY_TOKEN}}' \
-H 'cache-control: no-cache' \
-d 'name={{UPDATED_CAMPAIGN_NAME}}'
The above command returns JSON structured like this:
{
"status" : "pause",
"account_id" : "101",
"deleted" : false,
"campaign_naming" : "{campaign-name}-{age-min}-{age-max}-{country}-{interest}",
"start_date" : "2017-10-16T11:15:00+0000",
"ads_naming" : "{campaign-name}-{age-min}-{age-max}-{picture}-{title}",
"budget_type" : "daily",
"url_reporting" : "https://social.marinsoftware.com/report/en/spent/{{CAMPAIGN_HASH_ID}}",
"daily_budget" : 10,
"client_id" : "105",
"budget" : 10,
"name" : "campaign 1 - edited",
"id" : "1",
"archived" : false,
"src" : "fb",
"special_ad_category": "credit"
}
HTTP Request
PUT https://api.mysocialpixel.com/clients/{{MEDIAPLAN_ID}}/campaigns/{{CAMPAIGN_ID}}
URI Parameters
| Parameter | Description |
|---|---|
| MEDIAPLAN_ID | The ID of the media plan containing the campaign to update |
| CAMPAIGN_ID | The ID of the campaign to update |
Query Parameters (Facebook)
| Parameter | Optional | Description | Enum |
|---|---|---|---|
| name | yes | ||
| io_number | yes | ||
| rule | yes | ||
| daily_budget | yes | Only if budget_type is daily |
|
| lifetime_budget | yes | Only if budget_type is lifetime |
|
| start_date | yes | Unix timestamp value of the start date | |
| end_date | yes | Unix timestamp value of the end date | |
| campaign_naming | yes | {formId} / {form-name} works only with lead_gen objective | {campaign-name} / {campaign-objective} / {adId} / {age-min} / {age-max} / {country} / {town} / {language} / {interest} / {os} / {device} / {behaviors} / {picture} / {title} / {gender} / {placement} / {postId} / {creativeId} / {titleId} / {bodyId} / {imageId} / {includedcustomaudience} / {excludedcustomaudience} / {ioNumber} / {office} / {endAdvertiser} / {audiencename} / {creationdate} / {format} / {productSet-name} / {productAudience-name} / {productTemplate-name} / {post-type} / {location-cluster} / {interest-cluster} / {dpa-mode} / {publisher} / {page-name} / {formId} / {form-name} |
| ads_naming | yes | {formId} / {form-name} works only with lead_gen objective | {campaign-name} / {campaign-objective} / {adId} / {age-min} / {age-max} / {country} / {town} / {language} / {interest} / {os} / {device} / {behaviors} / {picture} / {title} / {gender} / {placement} / {postId} / {creativeId} / {titleId} / {bodyId} / {imageId} / {includedcustomaudience} / {excludedcustomaudience} / {ioNumber} / {office} / {endAdvertiser} / {audiencename} / {creationdate} / {format} / {productSet-name} / {productAudience-name} / {productTemplate-name} / {post-type} / {location-cluster} / {interest-cluster} / {dpa-mode} / {publisher} / {page-name} / {formId} / {form-name} / {adset-name} / {marinadid} |
| product_catalog_id | yes | Only if objective is product_catalog_sales |
|
| spend_cap | yes | ||
| special_ad_category | yes | Special ad category | credit / employment / housing / none |
Query Parameters (Twitter)
| Parameter | Optional | Description | Enum |
|---|---|---|---|
| name | yes | ||
| io_number | yes | ||
| rule | yes | ||
| daily_budget | yes | ||
| lifetime_budget | yes | ||
| start_date | yes | Unix timestamp value of the start date | |
| end_date | yes | Unix timestamp value of the end date | |
| campaign_naming | yes | {campaign-name} / {campaign-objective} / {country} / {interest} / {gender} / {twitteraccounts} / {keywords} / {tweetId} / {os} / {device} / {keyword-cluster} / {handle-cluster} / {placement} / {tailored-audience} / {handle} / {ioNumber} / {publisher} / {page-name} | |
| ads_naming | yes | {campaign-name} / {campaign-objective} / {country} / {interest} / {gender} / {twitteraccounts} / {keywords} / {tweetId} / {os} / {device} / {keyword-cluster} / {handle-cluster} / {placement} / {tailored-audience} / {handle} / {ioNumber} / {publisher} / {page-name} / {adset-name} / {marinadid} |
Perform action on a Campaign (play/pause)
curl -X PATCH \
'https://api.mysocialpixel.com/clients/{{MEDIAPLAN_ID}}/campaigns/{{CAMPAIGN_ID}}/performs/{{ACTION}}?key={{AGENCY_TOKEN}}' \
-H 'cache-control: no-cache'
The above command returns JSON structured like this:
{
"status" : "pause",
"account_id" : "101",
"deleted" : false,
"campaign_naming" : "{campaign-name}-{age-min}-{age-max}-{country}-{interest}",
"start_date" : "2017-10-16T11:15:00+0000",
"ads_naming" : "{campaign-name}-{age-min}-{age-max}-{picture}-{title}",
"budget_type" : "daily",
"url_reporting" : "https://social.marinsoftware.com/report/en/spent/{{CAMPAIGN_HASH_ID}}",
"daily_budget" : 10,
"client_id" : "105",
"budget" : 10,
"name" : "campaign 1 - edited",
"id" : "1",
"archived" : false,
"src" : "fb"
}
HTTP Request
PATCH https://api.mysocialpixel.com/clients/{{MEDIAPLAN_ID}}/campaigns/{{CAMPAIGN_ID}}/performs/{{ACTION}}
URI Parameters
| Parameter | Description |
|---|---|
| MEDIAPLAN_ID | The ID of the media plan containing the campaign to perform the action |
| CAMPAIGN_ID | The ID of the campaign to perform the action |
| ACTION | Action to perform (play/pause) |
Custom audiences
Get all custom audiences of an account
curl -X GET \
'https://api.mysocialpixel.com/accounts/{{ACCOUNT_ID}}/audiences?key={{AGENCY_TOKEN}}' \
-H 'cache-control: no-cache'
The above command returns JSON structured like this:
{
"data" : [
{
"id" : "1",
"name" : "Custom Audience Travel - name",
"created_at" : "2018-02-09T03:15:06+0000",
"network_id" : "{{FACEBOOK_ID}}",
"nb_users" : "1000",
"description" : "Custom Audience Travel - description",
"type" : "dynamic - travel"
},
{
"name" : "Custom Audience Website - name",
"id" : "2",
"rule" : {{JSON_FACEBOOK_RULE}},
"created_at" : "2018-08-19T03:15:35+0000",
"nb_users" : "1000",
"network_id" : "{{FACEBOOK_ID}}",
"type" : "website"
},
[...]
],
"range" : {
"nb_pages" : 10,
"next" : "https://api.mysocialpixel.com/accounts/{{ACCOUNT_ID}}/audiences?limit=100&key={{AGENCY_TOKEN}}&page=2",
"limit" : 100,
"results" : 100,
"total" : 10000,
"page" : 1
}
}
This endpoint retrieves all custom audiences from an account.
The response is returned with pagination. The result resources are under data key, and the pagination informations are under range key.
HTTP Request
GET https://api.mysocialpixel.com/accounts/{{ACCOUNT_ID}}/audiences
URI Parameters
| Parameter | Description |
|---|---|
| ACCOUNT_ID | The ID of the account containing a list of custom audiences |
Query Parameters
| Parameter | Optional | Default | Description |
|---|---|---|---|
| limit | yes | 100 | The maximum number of resource by page (Max 300) |
| page | yes | 1 | The requested page |
Create a custom audience
curl -X POST \
'https://api.mysocialpixel.com/accounts/{{ACCOUNT_ID}}/audiences?subtype={{WEBSITE}}&key={{AGENCY_TOKEN}}' \
-H 'cache-control: no-cache' \
-F 'name={{CUSTOM_AUDIENCE_NAME}}' \
-F 'description={{CUSTOM_AUDIENCE_DESCRIPTION}}' \
-F 'rule={{CUSTOM_AUDIENCE_WEBSITE_RULE}}' \
-F 'customer_file_source={{CUSTOMER_FILE_SOURCE}}'
The above command returns JSON structured like this:
{
"name" : "Custom Audience Website - name",
"id" : "2",
"rule" : {{JSON_FACEBOOK_RULE}},
"customer_file_source" : {{CUSTOMER_FILE_SOURCE}},
"created_at" : "2018-08-19T03:15:35+0000",
"nb_users" : "1000",
"network_id" : "{{FACEBOOK_ID}}",
"type" : "website"
}
HTTP Request
POST https://api.mysocialpixel.com/accounts/{{ACCOUNT_ID}}/audiences
URI Parameters
| Parameter | Description |
|---|---|
| ACCOUNT_ID | The ID of the account |
Query Parameters
| Parameter | Optional | Default | Description | Enum |
|---|---|---|---|---|
| name | no | |||
| description | yes | |||
| subtype | yes | Used to create a website custom audience | website, mobile, lead-gen, offline-event, page-engagement | |
| rule | no | Required if subtype is website |
||
| customer_file_source | no | Source of customer information in the uploaded file. | USER_PROVIDED_ONLY, PARTNER_PROVIDED_ONLY, BOTH_USER_AND_PARTNER_PROVIDED |
Create a new lookalike audience
curl -X POST \
'https://api.mysocialpixel.com/accounts/{{ACCOUNT_ID}}/audiences/{{AUDIENCE_ID}}/lookalikes?key={{AGENCY_TOKEN}}' \
-H 'cache-control: no-cache' \
-F 'name={{LOOKALIKE_NAME}}' \
-F 'description={{LOOKALIKE_DESCRIPTION}}' \
-F 'country={{LOOKALIKE_COUNTRY}}' \
-F 'ratio={{LOOKALIKE_RATIO}}'
The above command returns JSON structured like this:
{
"country" : "FR",
"name" : "Custom Audience Lookalike",
"network_id" : "{{FACEBOOK_ID}}",
"lookalike_type" : "{{LOOKALIKE_TYPE}}",
"id" : "1",
"nb_users" : "4200000",
"type" : "lookalike",
"origin_audience_network_id" : "{{FACEBOOK_ID}}",
"created_at" : "2018-07-31T03:15:32+0000"
}
HTTP Request
POST https://api.mysocialpixel.com/accounts/{{ACCOUNT_ID}}/audiences/{{AUDIENCE_ID}}/lookalikes
URI Parameters
| Parameter | Description |
|---|---|
| ACCOUNT_ID | The ID of the account |
| AUDIENCE_ID | The ID of the custom audience the lookalike will be base on |
Query Parameters
| Parameter | Optional | Default | Description | Enum |
|---|---|---|---|---|
| name | yes | |||
| description | yes | |||
| country | no | Country code (FR, EN, ES, US , etc...) | ||
| ratio | no | values between 1 and 20 |
Update a custom audience
curl -X PUT \
'https://api.mysocialpixel.com/accounts/{{ACCOUNT_ID}}/audiences/{{AUDIENCE_ID}}?key={{AGENCY_TOKEN}}' \
-H 'cache-control: no-cache' \
-d 'name={{CUSTOM_AUDIENCE_NAME}}'
The above command returns JSON structured like this:
{
"name" : "Custom Audience Website - name",
"id" : "2",
"rule" : {{JSON_FACEBOOK_RULE}},
"customer_file_source" : {{CUSTOMER_FILE_SOURCE}},
"created_at" : "2018-08-19T03:15:35+0000",
"nb_users" : "1000",
"network_id" : "{{FACEBOOK_ID}}",
"type" : "website"
}
HTTP Request
PUT https://api.mysocialpixel.com/accounts/{{ACCOUNT_ID}}/audiences/{{AUDIENCE_ID}}
URI Parameters
| Parameter | Description |
|---|---|
| ACCOUNT_ID | The ID of the account |
| AUDIENCE_ID | The ID of the custom audience |
Query Parameters
| Parameter | Optional | Default | Description | Enum |
|---|---|---|---|---|
| name | no | |||
| description | yes | |||
| rule | no | Required for website custom audience | ||
| customer_file_source | no | Source of customer information in the uploaded file. | USER_PROVIDED_ONLY, PARTNER_PROVIDED_ONLY, BOTH_USER_AND_PARTNER_PROVIDED |
Delete a custom audience
curl -X DELETE \
'https://api.mysocialpixel.com/accounts/{{ACCOUNT_ID}}/audiences/{{AUDIENCE_ID}}?key={{AGENCY_TOKEN}}' \
-H 'cache-control: no-cache'
The above command returns JSON structured like this:
{
"success": true
}
HTTP Request
DELETE https://api.mysocialpixel.com/accounts/{{ACCOUNT_ID}}/audiences/{{AUDIENCE_ID}}
URI Parameters
| Parameter | Description |
|---|---|
| ACCOUNT_ID | The ID of the account |
| AUDIENCE_ID | The ID of the custom audience |
Add or delete users in a datafile custom audience
curl -X PATCH \
'https://api.mysocialpixel.com/accounts/{{ACCOUNT_ID}}/audiences/{{AUDIENCE_ID}}/users?key={{AGENCY_TOKEN}}' \
-H 'cache-control: no-cache' \
-d 'add={{USER_TO_ADD}}' \
-d 'delete={{USER_TO_DELETE}}' \
The above command returns JSON structured like this:
{
"add" : "{{NUMBER_OF_USERS}}",
"delete" : "{{NUMBER_OF_USERS}}"
}
HTTP Request
PATCH https://api.mysocialpixel.com/accounts/{{ACCOUNT_ID}}/audiences/{{AUDIENCE_ID}}/users
URI Parameters
| Parameter | Description |
|---|---|
| ACCOUNT_ID | The ID of the account |
| AUDIENCE_ID | The ID of the custom audience |
Query Parameters
| Parameter | Optional | Default | Description | Enum |
|---|---|---|---|---|
| add | yes | Array of users: [{user}:{type}, ...] |
||
| delete | yes | Array of users: [{user}:{type}, ...] |
Media plans
Get all Media plans
curl -X GET \
'https://api.mysocialpixel.com/clients?key={{AGENCY_TOKEN}}' \
-H 'cache-control: no-cache'
The above command returns JSON structured like this:
{
"data":[
{
"id": "105",
"margin_type": 0,
"advertiser_id": "101",
"deleted": false,
"general_objective": "fan_acq",
"archived": false,
"name": "My name",
"account_network_id": "1234567891234567",
"ads_naming": "{campaign-name}-{age-min}-{age-max}-{picture}-{title}",
"margin_value": 0,
"io_number": "mediaPlanIoNumber",
"campaign_naming": "{campaign-name}-{age-min}-{age-max}-{country}-{interest}",
"account_id": "101",
"autopause_value": "0",
"business_manager_id": "9876543219876543",
"src": "fb",
"url_reporting": "https://social.marinsoftware.com/report/en/spent/200db8841ae598b716f622d8",
"url_connection": "https://social.marinsoftware.com/datagrid/105"
},
[...]
],
"range": {
"total": 1000,
"limit": 100,
"nb_pages": 10,
"page": 1,
"results": 100,
"next": "https://api.mysocialpixel.com/clients?key={{AGENCY_TOKEN}}&page=2"
}
}
This endpoint retrieves all media plans.
The response is returned with pagination. The result resources are under data key, and the pagination informations are under range key.
HTTP Request
GET https://api.mysocialpixel.com/clients
Query Parameters
| Parameter | Optional | Default | Description |
|---|---|---|---|
| limit | yes | 100 | The maximum number of resource by page (Max 300) |
| page | yes | 1 | The requested page |
Get a specific media plan
curl -X GET \
'https://api.mysocialpixel.com/clients/{{MEDIAPLAN_ID}}?key={{AGENCY_TOKEN}}' \
-H 'cache-control: no-cache'
The above command returns JSON structured like this:
{
"data": {
"id": "105",
"margin_type": 0,
"advertiser_id": "101",
"deleted": false,
"general_objective": "fan_acq",
"archived": false,
"name": "My name",
"account_network_id": "1234567891234567",
"ads_naming": "{campaign-name}-{age-min}-{age-max}-{picture}-{title}",
"margin_value": 0,
"io_number": "mediaPlanIoNumber",
"campaign_naming": "{campaign-name}-{age-min}-{age-max}-{country}-{interest}",
"account_id": "101",
"autopause_value": "0",
"business_manager_id": "9876543219876543",
"src": "fb",
"url_reporting": "https://social.marinsoftware.com/report/en/spent/200db8841ae598b716f622d8",
"url_connection": "https://social.marinsoftware.com/datagrid/105"
}
}
This endpoint retrieves a mediaplan with id or io_number.
HTTP Request
GET https://api.mysocialpixel.com/clients/{{MEDIAPLAN_ID}}
URI Parameters
| Parameter | Description |
|---|---|
| MEDIAPLAN_ID | id or io_number of the client(s) |
Get statistics about specific Media plan
curl -X GET \
'https://api.mysocialpixel.com/clients/{{MEDIAPLAN_ID}}/statistics?key={{AGENCY_TOKEN}}' \
-H 'cache-control: no-cache'
The above command returns JSON structured like this:
{
"data": [
{
"ctr": 0,
"ctrLinks": 0,
"convRate": 0,
"convRateLinks": 0,
"cpc": 0,
"cpm": 0,
"cpa": 0,
"income": 0,
"roi": 0,
"main_metrics": [
{
"name": "like",
"amount": 0,
"number": 0,
"object_id": ""
},
{
"name": "rsvp",
"amount": 0,
"number": 0,
"object_id": ""
},
{
"name": "post_like",
"amount": 0,
"number": 0,
"object_id": ""
},
{
"name": "comment",
"amount": 0,
"number": 0,
"object_id": ""
},
{
"name": "post",
"amount": 0,
"number": 0,
"object_id": ""
},
{
"name": "photo_view",
"amount": 0,
"number": 0,
"object_id": ""
},
{
"name": "video_view",
"amount": 0,
"number": 0,
"object_id": ""
},
{
"name": "estimated_ad_recallers",
"amount": 0,
"number": 0,
"object_id": ""
},
{
"name": "mobile_app_install",
"amount": 0,
"number": 0,
"object_id": ""
},
{
"name": "deeplink_clicks",
"amount": 0,
"number": 0,
"object_id": ""
},
{
"name": "app_custom_event.fb_mobile_purchase",
"amount": 0,
"number": 0,
"object_id": ""
},
{
"name": "app_install",
"amount": 0,
"number": 0,
"object_id": ""
},
{
"name": "credit_spent",
"amount": 0,
"number": 0,
"object_id": ""
},
{
"name": "call_to_action_clicks",
"amount": 0,
"number": 0,
"object_id": ""
},
{
"name": "website_clicks",
"amount": 0,
"number": 0,
"object_id": ""
},
{
"name": "receive_offer",
"amount": 0,
"number": 0,
"object_id": ""
},
{
"name": "leadgen.other",
"amount": 0,
"number": 0,
"object_id": ""
},
{
"name": "link_click",
"amount": 0,
"number": 0,
"object_id": ""
},
{
"name": "store_visits",
"amount": 0,
"number": 0,
"object_id": ""
}
],
"other_metrics": [],
"impression": 0,
"click": 0,
"spent": 0
},
[...]
],
"range": {
"total": 1000,
"limit": 100,
"nb_pages": 10,
"page": 1,
"results": 100,
"next": "https://api.mysocialpixel.com/clients/{{MEDIAPLAN_ID}}/statistics?key={{AGENCY_TOKEN}}&page=2"
}
}
This endpoint retrieves statistics about a mediaplan.
The response is returned with pagination. The result resources are under data key, and the pagination informations are under range key.
HTTP Request
GET https://api.mysocialpixel.com/clients/{{MEDIAPLAN_ID}}/statistics
URI Parameters
| Parameter | Description |
|---|---|
| MEDIAPLAN_ID | id or io_number of the client(s) |
Query Parameters
| Parameter | Optional | Format | Values | Default | Description |
|---|---|---|---|---|---|
| aggregate | yes | enum | month, day, period | period | Time aggregation |
| start_date | yes if aggregate is period | UNIX Timestamp | Start timestamp | ||
| end_date | yes if aggregate if month or day or if start_date is filled | UNIX Timestamp | End timestamp | ||
| limit | yes | integer | 100 | The maximum number of resource by page (Max 300) | |
| page | yes | integer | 1 | The requested page | |
| level | yes | string | client, campaign, adset, ad, channel_connect | The depth of statistic |
Get statistics about specific Campaign
curl -X GET \
'https://api.mysocialpixel.com/clients/{{MEDIAPLAN_ID}}/campaigns/{{CAMPAIGN_ID}}/statistics?key={{AGENCY_TOKEN}}' \
-H 'cache-control: no-cache'
The above command returns JSON structured like this:
{
"data": [
{
"ctr": 0,
"ctrLinks": 0,
"convRate": 0,
"convRateLinks": 0,
"cpc": 0,
"cpm": 0,
"cpa": 0,
"income": 0,
"roi": 0,
"main_metrics": [
{
"name": "like",
"amount": 0,
"number": 0,
"object_id": ""
},
{
"name": "rsvp",
"amount": 0,
"number": 0,
"object_id": ""
},
{
"name": "post_like",
"amount": 0,
"number": 0,
"object_id": ""
},
{
"name": "comment",
"amount": 0,
"number": 0,
"object_id": ""
},
{
"name": "post",
"amount": 0,
"number": 0,
"object_id": ""
},
{
"name": "photo_view",
"amount": 0,
"number": 0,
"object_id": ""
},
{
"name": "video_view",
"amount": 0,
"number": 0,
"object_id": ""
},
{
"name": "estimated_ad_recallers",
"amount": 0,
"number": 0,
"object_id": ""
},
{
"name": "mobile_app_install",
"amount": 0,
"number": 0,
"object_id": ""
},
{
"name": "deeplink_clicks",
"amount": 0,
"number": 0,
"object_id": ""
},
{
"name": "app_custom_event.fb_mobile_purchase",
"amount": 0,
"number": 0,
"object_id": ""
},
{
"name": "app_install",
"amount": 0,
"number": 0,
"object_id": ""
},
{
"name": "credit_spent",
"amount": 0,
"number": 0,
"object_id": ""
},
{
"name": "call_to_action_clicks",
"amount": 0,
"number": 0,
"object_id": ""
},
{
"name": "website_clicks",
"amount": 0,
"number": 0,
"object_id": ""
},
{
"name": "receive_offer",
"amount": 0,
"number": 0,
"object_id": ""
},
{
"name": "leadgen.other",
"amount": 0,
"number": 0,
"object_id": ""
},
{
"name": "link_click",
"amount": 0,
"number": 0,
"object_id": ""
},
{
"name": "store_visits",
"amount": 0,
"number": 0,
"object_id": ""
}
],
"other_metrics": [],
"impression": 0,
"click": 0,
"spent": 0
},
[...]
],
"range": {
"total": 1000,
"limit": 100,
"nb_pages": 10,
"page": 1,
"results": 100,
"next": "https://api.mysocialpixel.com/clients/{{MEDIAPLAN_ID}}/campaigns/{{CAMPAIGN_ID}}/statistics?key={{AGENCY_TOKEN}}&page=2"
}
}
This endpoint retrieves statistics about a specific campaign.
The response is returned with pagination. The result resources are under data key, and the pagination informations are under range key.
HTTP Request
GET https://api.mysocialpixel.com/clients/{{MEDIAPLAN_ID}}/campaigns/{{CAMPAIGN_ID}}/statistics
URI Parameters
| Parameter | Description |
|---|---|
| MEDIAPLAN_ID | id or io_number of the client(s) |
| CAMPAIGN_ID | id of the campaign |
Query Parameters
| Parameter | Optional | Format | Values | Default | Description |
|---|---|---|---|---|---|
| aggregate | yes | enum | month, day, period | period | Time aggregation |
| start_date | yes if aggregate is period | UNIX Timestamp | Start timestamp | ||
| end_date | yes if aggregate if month or day or if start_date is filled | UNIX Timestamp | End timestamp | ||
| limit | yes | integer | 100 | The maximum number of resource by page (Max 300) | |
| page | yes | integer | 1 | The requested page | |
| level | yes | string | client, campaign, adset, ad, channel_connect | campaign | The depth of statistic |
Get statistics about specific Ad Set
curl -X GET \
'https://api.mysocialpixel.com/clients/{{MEDIAPLAN_ID}}/campaigns/{{CAMPAIGN_ID}}/adsets/{{ADSET_ID}}/statistics?key={{AGENCY_TOKEN}}' \
-H 'cache-control: no-cache'
The above command returns JSON structured like this:
{
"data": [
{
"ctr": 0,
"ctrLinks": 0,
"convRate": 0,
"convRateLinks": 0,
"cpc": 0,
"cpm": 0,
"cpa": 0,
"income": 0,
"roi": 0,
"main_metrics": [
{
"name": "like",
"amount": 0,
"number": 0,
"object_id": ""
},
{
"name": "rsvp",
"amount": 0,
"number": 0,
"object_id": ""
},
{
"name": "post_like",
"amount": 0,
"number": 0,
"object_id": ""
},
{
"name": "comment",
"amount": 0,
"number": 0,
"object_id": ""
},
{
"name": "post",
"amount": 0,
"number": 0,
"object_id": ""
},
{
"name": "photo_view",
"amount": 0,
"number": 0,
"object_id": ""
},
{
"name": "video_view",
"amount": 0,
"number": 0,
"object_id": ""
},
{
"name": "estimated_ad_recallers",
"amount": 0,
"number": 0,
"object_id": ""
},
{
"name": "mobile_app_install",
"amount": 0,
"number": 0,
"object_id": ""
},
{
"name": "deeplink_clicks",
"amount": 0,
"number": 0,
"object_id": ""
},
{
"name": "app_custom_event.fb_mobile_purchase",
"amount": 0,
"number": 0,
"object_id": ""
},
{
"name": "app_install",
"amount": 0,
"number": 0,
"object_id": ""
},
{
"name": "credit_spent",
"amount": 0,
"number": 0,
"object_id": ""
},
{
"name": "call_to_action_clicks",
"amount": 0,
"number": 0,
"object_id": ""
},
{
"name": "website_clicks",
"amount": 0,
"number": 0,
"object_id": ""
},
{
"name": "receive_offer",
"amount": 0,
"number": 0,
"object_id": ""
},
{
"name": "leadgen.other",
"amount": 0,
"number": 0,
"object_id": ""
},
{
"name": "link_click",
"amount": 0,
"number": 0,
"object_id": ""
},
{
"name": "store_visits",
"amount": 0,
"number": 0,
"object_id": ""
}
],
"other_metrics": [],
"impression": 0,
"click": 0,
"spent": 0
},
[...]
],
"range": {
"total": 1000,
"limit": 100,
"nb_pages": 10,
"page": 1,
"results": 100,
"next": "https://api.mysocialpixel.com/clients/{{MEDIAPLAN_ID}}/campaigns/{{CAMPAIGN_ID}}/adsets/{{ADSET_ID}}/statistics?key={{AGENCY_TOKEN}}&page=2"
}
}
This endpoint retrieves statistics about a specific ad set.
The response is returned with pagination. The result resources are under data key, and the pagination informations are under range key.
HTTP Request
GET https://api.mysocialpixel.com/clients/{{MEDIAPLAN_ID}}/campaigns/{{CAMPAIGN_ID}}/adsets/{{ADSET_ID}}/statistics
URI Parameters
| Parameter | Description |
|---|---|
| MEDIAPLAN_ID | id or io_number of the client(s) |
| CAMPAIGN_ID | id of the campaign |
| ADSET_ID | id of the ad set |
Query Parameters
| Parameter | Optional | Format | Values | Default | Description |
|---|---|---|---|---|---|
| aggregate | yes | enum | month, day, period | period | Time aggregation |
| start_date | yes if aggregate is period | UNIX Timestamp | Start timestamp | ||
| end_date | yes if aggregate if month or day or if start_date is filled | UNIX Timestamp | End timestamp | ||
| limit | yes | integer | 100 | The maximum number of resource by page (Max 300) | |
| page | yes | integer | 1 | The requested page | |
| level | yes | string | client, campaign, adset, ad, channel_connect | adset | The depth of statistic |
Get Statistic from a specific Ad
curl -X GET \
'https://api.mysocialpixel.com/clients/{{MEDIAPLAN_ID}}/campaigns/{{CAMPAIGN_ID}}/ads/{{AD_ID}}/statistics?key={{AGENCY_TOKEN}}' \
-H 'cache-control: no-cache'
{
"data": [
{
"ctr": 0,
"ctrLinks": 0,
"convRate": 0,
"convRateLinks": 0,
"cpc": 0,
"cpm": 0,
"cpa": 0,
"income": 0,
"roi": 0,
"main_metrics": [
{
"name": "like",
"amount": 0,
"number": 0,
"object_id": ""
},
{
"name": "rsvp",
"amount": 0,
"number": 0,
"object_id": ""
},
{
"name": "post_like",
"amount": 0,
"number": 0,
"object_id": ""
},
{
"name": "comment",
"amount": 0,
"number": 0,
"object_id": ""
},
{
"name": "post",
"amount": 0,
"number": 0,
"object_id": ""
},
{
"name": "photo_view",
"amount": 0,
"number": 0,
"object_id": ""
},
{
"name": "video_view",
"amount": 0,
"number": 0,
"object_id": ""
},
{
"name": "estimated_ad_recallers",
"amount": 0,
"number": 0,
"object_id": ""
},
{
"name": "mobile_app_install",
"amount": 0,
"number": 0,
"object_id": ""
},
{
"name": "deeplink_clicks",
"amount": 0,
"number": 0,
"object_id": ""
},
{
"name": "app_custom_event.fb_mobile_purchase",
"amount": 0,
"number": 0,
"object_id": ""
},
{
"name": "app_install",
"amount": 0,
"number": 0,
"object_id": ""
},
{
"name": "credit_spent",
"amount": 0,
"number": 0,
"object_id": ""
},
{
"name": "call_to_action_clicks",
"amount": 0,
"number": 0,
"object_id": ""
},
{
"name": "website_clicks",
"amount": 0,
"number": 0,
"object_id": ""
},
{
"name": "receive_offer",
"amount": 0,
"number": 0,
"object_id": ""
},
{
"name": "leadgen.other",
"amount": 0,
"number": 0,
"object_id": ""
},
{
"name": "link_click",
"amount": 0,
"number": 0,
"object_id": ""
},
{
"name": "store_visits",
"amount": 0,
"number": 0,
"object_id": ""
}
],
"other_metrics": [],
"impression": 0,
"click": 0,
"spent": 0
},
[...]
],
"range": {
"total": 1000,
"limit": 100,
"nb_pages": 10,
"page": 1,
"results": 100,
"next": "https://api.mysocialpixel.com/clients/{{MEDIAPLAN_ID}}/campaigns/{{CAMPAIGN_ID}}/adsets/{{ADSET_ID}}/ads/{{AD_ID}}/statistics?key={{AGENCY_TOKEN}}&page=2"
}
}
This endpoint retrieves Statistic from a specific Ad.
HTTP Request
GET https://api.mysocialpixel.com/clients/{{MEDIAPLAN_ID}}/campaigns/{{CAMPAIGN_ID}}/ads/{{AD_ID}}/statistics
URI Parameters
| Parameter | Description |
|---|---|
| MEDIAPLAN_ID | The ID of the ad's mediaplan to retrieve |
| CAMPAIGN_ID | The ID of the ad's campaign to retrieve |
| AD_ID | The ID of the ad to retrieve |
Create a new media plan
curl -X POST \
'https://api.mysocialpixel.com/clients/{{SOURCE}}?key={{AGENCY_TOKEN}}' \
-H 'cache-control: no-cache'
The above command returns JSON structured like this:
{
"id": "1234",
"account_id": "5678",
"account_network_id": "1234567891234567",
"advertiser_id": "123",
"deleted": false,
"name": "My name",
"archived": false,
"campaign_naming": "{campaign-name}-{age-min}-{age-max}-{country}-{interest}",
"ads_naming": "{campaign-name}-{age-min}-{age-max}-{picture}-{title}",
"margin_value": 0,
"margin_type": 0,
"src": "fb",
"url_reporting": "https://social.marinsoftware.com/report/en/spent/5bfea52b7d43fe8fc6443d02",
"url_connection": "https://social.marinsoftware.com/datagrid/1402"
}
This endpoint create a new media plan.
HTTP Request
POST https://api.mysocialpixel.com/clients/{{SOURCE}}
URI Parameters
| Parameter | Type | Values | Description |
|---|---|---|---|
| SOURCE | enum | fb, tw | The social network concerned |
Body Parameters
| Parameter | Required | Type | Values | Default | Description |
|---|---|---|---|---|---|
| name | yes | string | Media plan name | ||
| advertiser_id | yes | string | Advertiser ID | ||
| io_number | no | string | IO number | ||
| office | no | string | office | ||
| account_id | yes | string | Account ID | ||
| notes | no | string | Notes | ||
| general_objective | no | enum | For Twitter: FOLLOWERS, TWEET_ENGAGEMENTS, APP_ENGAGEMENTS, APP_INSTALLS, WEBSITE_CLICKS, WEBSITE_CONVERSIONS, VIDEO_VIEWS ; For Facebook: fan_acq, event, eng, mobile_app_install, mobile_re_eng, offer, outside_traffic, website_conv, lead_gen, app_install, re_eng, video_play, custom | General objective | |
| autopause_type | no | enum | clics, impression, spent, acquisitions | Autopause type | |
| autopause_value | no | string | Autopause value | ||
| margin_type | no | int | 0 (Margin), 1 (Fixed CPC), 2 (Fixed on main metric) | Margin type | |
| margin_value | no | string | Margin value | ||
| campaign_naming | no | string | Campaign naming | ||
| ads_naming | no | string | Ads naming | ||
| funding_instrument_id | yes | string | Funding instrument ID (Twitter only) |
Update a media plan
curl -X PUT \
'https://api.mysocialpixel.com/clients/{{MEDIAPLAN_ID}}?key={{AGENCY_TOKEN}}' \
-H 'cache-control: no-cache'
The above command returns JSON structured like this:
{
"id": "1234",
"account_id": "5678",
"account_network_id": "1234567891234567",
"advertiser_id": "123",
"deleted": false,
"name": "My name",
"archived": false,
"campaign_naming": "{campaign-name}-{age-min}-{age-max}-{country}-{interest}",
"ads_naming": "{campaign-name}-{age-min}-{age-max}-{picture}-{title}",
"margin_value": 0,
"margin_type": 0,
"src": "fb",
"url_reporting": "https://social.marinsoftware.com/report/en/spent/5bfea52b7d43fe8fc6443d02",
"url_connection": "https://social.marinsoftware.com/datagrid/1402"
}
This endpoint update a mediaplan.
HTTP Request
PUT https://api.mysocialpixel.com/clients/{{MEDIAPLAN_ID}}
URI Parameters
| Parameter | Type | Values | Description |
|---|---|---|---|
| MEDIAPLAN_ID | string | Media plan ID |
Body Parameters
| Parameter | Required | Type | Values | Default | Description |
|---|---|---|---|---|---|
| name | no | string | Media plan name | ||
| io_number | no | string | IO number | ||
| office | no | string | office | ||
| notes | no | string | Notes | ||
| autopause_type | no | enum | clics, impression, spent, acquisitions | Autopause type | |
| autopause_value | no | string | Autopause value | ||
| margin_type | no | int | 0 (Margin), 1 (Fixed CPC), 2 (Fixed on main metric) | Margin type | |
| margin_value | no | string | Margin value | ||
| campaign_naming | no | string | Campaign naming | ||
| ads_naming | no | string | Ads naming | ||
| funding_instrument_id | yes | string | Funding instrument ID (Twitter only) |
Get media plan managers
curl -X GET \
'https://api.mysocialpixel.com/clients/{{MEDIAPLAN_ID}}/users?key={{AGENCY_TOKEN}}' \
-H 'cache-control: no-cache'
The above command returns JSON structured like this:
{
"data": [
{
"id": "123",
"username": "account_1@mail.com",
"email": "account_1@mail.com",
"firstname": "John",
"lastname": "Doe",
"role": "ROLE_ADMIN",
"created_at": "2018-01-01T08:00:00+0000"
},
{
"id": "456",
"username": "account_2@mail.com",
"email": "account_2@mail.com",
"firstname": "John Jr",
"lastname": "Doe",
"role": "ROLE_ADMIN",
"created_at": "2018-01-01T08:00:00+0000"
},
[...]
],
"range": {
"total": 1000,
"limit": 100,
"nb_pages": 10,
"page": 1,
"results": 100,
"next": "https://api.mysocialpixel.com/clients/{{MEDIAPLAN_ID}}/users?key={{AGENCY_TOKEN}}&page=2"
}
}
This endpoint returns a collection of users, corresponding to the client managers.
The response is returned with pagination. The result resources are under data key, and the pagination informations are under range key.
HTTP Request
GET https://api.mysocialpixel.com/clients/{{MEDIAPLAN_ID}}/users
URI Parameters
| Parameter | Type | Values | Description |
|---|---|---|---|
| MEDIAPLAN_ID | string | Media plan ID |
Query Parameters
| Parameter | Optional | Default | Description |
|---|---|---|---|
| limit | yes | 100 | The maximum number of resource by page (Max 300) |
| page | yes | 1 | The requested page |
Add new manager
curl -X POST \
'https://api.mysocialpixel.com/clients/{{MEDIAPLAN_ID}}/users?key={{AGENCY_TOKEN}}' \
-H 'cache-control: no-cache'
-H 'Content-Type: application/json' \
-d '{
"user_id": {{USER_ID}}
}'
The above command returns JSON structured like this:
{
"message": "Success"
}
This endpoint assign a new manager to a media plan.
HTTP Request
POST https://api.mysocialpixel.com/clients/{{MEDIAPLAN_ID}}/users
URI Parameters
| Parameter | Type | Values | Description |
|---|---|---|---|
| MEDIAPLAN_ID | string | Media plan ID |
Body Parameters
| Parameter | Required | Default | Description |
|---|---|---|---|
| user_id | yes | User ID |
Delete a manager
curl -X DELETE \
'https://api.mysocialpixel.com/clients/{{MEDIAPLAN_ID}}/users?key={{AGENCY_TOKEN}}' \
-H 'cache-control: no-cache'
-H 'Content-Type: application/json' \
-d '{
"user_id": {{USER_ID}}
}'
The above command returns JSON structured like this:
{
"message": "Success"
}
This endpoint remove a manager of a media plan.
HTTP Request
DELETE https://api.mysocialpixel.com/clients/{{MEDIAPLAN_ID}}/users
URI Parameters
| Parameter | Type | Values | Description |
|---|---|---|---|
| MEDIAPLAN_ID | string | Media plan ID |
Body Parameters
| Parameter | Required | Default | Description |
|---|---|---|---|
| user_id | yes | User ID |
Users
Get all Users
curl -X GET \
'https://api.mysocialpixel.com/users?key={{AGENCY_TOKEN}}' \
-H 'cache-control: no-cache'
The above command returns JSON structured like this:
{
"data" : [
{
"id" : "1",
"username" : "user1@email.com",
"role" : "ROLE_ADMIN",
"created_at" : "2017-11-28T10:18:11+00:00",
"email" : "user1@email.com",
"firstname" : "firstname 1",
"lastname" : "lastname 1"
},
{
"id" : "2",
"username" : "user2@email.com",
"role" : "ROLE_USER",
"created_at" : "2017-11-28T10:18:11+00:00",
"email" : "user2@email.com",
"firstname" : "firstname 2",
"lastname" : "lastname 2"
},
[...]
],
"range" : {
"total" : 1000,
"nb_pages" : 10,
"page" : 1,
"results" : 100,
"limit" : 100,
"next" : "https://api.mysocialpixel.com/users?key={{AGENCY_TOKEN}}&page=2"
}
}
This endpoint retrieves all users.
The response is returned with pagination. The result resources are under data key, and the pagination informations are under range key.
HTTP Request
GET https://api.mysocialpixel.com/users
Query Parameters
| Parameter | Optional | Default | Description |
|---|---|---|---|
| limit | yes | 100 | The maximum number of resource by page (Max 300) |
| page | yes | 1 | The requested page |
Get a specific User
curl -X GET \
'https://api.mysocialpixel.com/users/{{USER_ID}}?key={{AGENCY_TOKEN}}' \
-H 'cache-control: no-cache'
The above command returns JSON structured like this:
{
"data" : {
"lastname" : "lastname 1",
"role" : "ROLE_ADMIN",
"username" : "user1@email.com",
"email" : "user1@email.com",
"id" : "1",
"created_at" : "2017-11-28T10:18:11+00:00",
"firstname" : "firstname 1"
}
}
This endpoint retrieves a specific user.
HTTP Request
GET https://api.mysocialpixel.com/users/{{USER_ID}}
URI Parameters
| Parameter | Description |
|---|---|
| USER_ID | The ID of the user to retrieve |
Targeting Clusters
Get a specific Targeting Cluster
curl -X GET \
'https://api.mysocialpixel.com/accounts/{{ACCOUNT_ID}}/targeting-clusters/{{TARGETING_CLUSTER_ID}}?key={{AGENCY_TOKEN}}' \
-H 'cache-control: no-cache'
The above command returns JSON structured like this:
{
"id": 2200,
"name": "targeting cluster name",
"targets": [
{
"typeLocation": [
"home",
"recent"
],
"genders": [
"male",
"female"
],
"ageMin": 18,
"ageMax": 24,
"ages": [
"18-24"
],
"locations": [
{
"key": "777934",
"name": "Paris (Île-de-France)",
"type": "city",
"country_code": "FR",
"country_name": "France",
"region": "Île-de-France",
"region_id": 1078,
"supports_region": true,
"supports_city": true
}
],
"placements": [
"{\"device\":[],\"publisher\":[],\"position\":[]}"
],
"createdAt": "2020-01-22T15:37:10+00:00",
"updatedAt": "2020-01-22T15:37:10+00:00",
"id": 4314
},
{...}
]
}
This endpoint retrieves a specific Targeting Cluster.
HTTP Request
GET https://api.mysocialpixel.com/accounts/{{ACCOUNT_ID}}/targeting-clusters/{{TARGETING_CLUSTER_ID}}
URI Parameters
| Parameter | Description |
|---|---|
| ACCOUNT_ID | The ID of the targeting cluster's account to retrieve |
| TARGETING_CLUSTER_ID | The ID of the targeting cluster to retrieve |
Get Targeting Clusters from Account
curl -X GET \
'https://api.mysocialpixel.com/accounts/{{ACCOUNT_ID}}/targeting-clusters?key={{AGENCY_TOKEN}}' \
-H 'cache-control: no-cache'
The above command returns JSON structured like this:
{
"data": [
{
"id": 2200,
"name": "targeting cluster name",
"targets": [
{
"typeLocation": [
"home",
"recent"
],
"genders": [
"male",
"female"
],
"ageMin": 18,
"ageMax": 24,
"ages": [
"18-24"
],
"locations": [
{
"key": "777934",
"name": "Paris (Île-de-France)",
"type": "city",
"country_code": "FR",
"country_name": "France",
"region": "Île-de-France",
"region_id": 1078,
"supports_region": true,
"supports_city": true
}
],
"placements": [
"{\"device\":[],\"publisher\":[],\"position\":[]}"
],
"createdAt": "2020-01-22T15:37:10+00:00",
"updatedAt": "2020-01-22T15:37:10+00:00",
"id": 4314
},
{...}
]
},
{...}
]
}
This endpoint retrieves all Targeting Cluster from an Account.
The response is returned with pagination. The result resources are under data key, and the pagination informations are under range key.
HTTP Request
GET https://api.mysocialpixel.com/accounts/{{ACCOUNT_ID}}/targeting-clusters
URI Parameters
| Parameter | Description |
|---|---|
| ACCOUNT_ID | The ID of the targeting cluster's account to retrieve |
Query Parameters
| Parameter | Optional | Default | Description |
|---|---|---|---|
| limit | yes | 100 | The maximum number of resource by page (Max 300) |
| page | yes | 1 | The requested page |
Create new Targeting Cluster
curl -X POST 'https://api.mysocialpixel.com/accounts/{{ACCOUNT_ID}}/targeting-clusters?key={{AGENCY_TOKEN}}' \
--header 'Content-Type: application/json' \
--data-raw '{
"name": {{value}},
"genders": {{values}},
"ages": {{values}},
"locations": {{values}},
"interests": {{values}},
"placements": {{values}}
}'
The above command returns JSON structured like this:
{
"id": 2200,
"name": "targeting cluster name",
"targets": [
{
"typeLocation": [
"home",
"recent"
],
"genders": [
"male",
"female"
],
"ageMin": 18,
"ageMax": 24,
"ages": [
"18-24"
],
"locations": [
{
"key": "777934",
"name": "Paris (Île-de-France)",
"type": "city",
"country_code": "FR",
"country_name": "France",
"region": "Île-de-France",
"region_id": 1078,
"supports_region": true,
"supports_city": true
}
],
"placements": [
"{\"device\":[],\"publisher\":[],\"position\":[]}"
],
"createdAt": "2020-01-22T15:37:10+00:00",
"updatedAt": "2020-01-22T15:37:10+00:00",
"id": 4314
},
{...}
]
}
This endpoint add a specific Targeting Cluster.
HTTP Request
POST https://api.mysocialpixel.com/accounts/{{ACCOUNT_ID}}/targeting-clusters/{{TARGETING_CLUSTER_ID}}
URI Parameters
| Parameter | Description |
|---|---|
| ACCOUNT_ID | The ID of the targeting cluster's account to retrieve |
| TARGETING_CLUSTER_ID | The ID of the targeting cluster to retrieve |
Body Parameters
| Parameter | Required | Type | Values | Default | Description |
|---|---|---|---|---|---|
| name | yes | string | Targeting Cluster name | ||
| locations | yes | array | List of locations. Example : [[{"key":"FR","name":"France","type":"country","country_code":"FR","country_name":"France","supports_region":true,"supports_city":true},{"key":"793519","name":"Toulon (Provence-Alpes-Côte d'Azur)","type":"city","country_code":"FR","country_name":"France","region":"Provence-Alpes-Côte d'Azur","region_id":1087,"supports_region":true,"supports_city":true}]] |
||
| placements | no | array | [{"device" => [], "publisher" => [], "position" => []}] | List of placements | |
| interests | no | array | List of interests. Example : [[{"key":"6003019801929","name":"Superior Hiking Trail","category":"interests","type":"interests"},{"key":"110720126115","name":"Epitech","category":"demographic","type":"schools"}]] |
||
| ages | no | array | ["18-65"] | List of ages | |
| genders | no | array | ["both"] | List of genders. Allowed values are both, male or female |
Delete a specific Targeting Cluster
curl -X DELETE \
'https://api.mysocialpixel.com/accounts/{{ACCOUNT_ID}}/targeting-clusters/{{TARGETING_CLUSTER_ID}}?key={{AGENCY_TOKEN}}' \
-H 'cache-control: no-cache'
The above command returns JSON structured like this:
{
"message": "Targeting cluster deleted successfully"
}
This endpoint delete a specific Targeting Cluster.
HTTP Request
DELETE https://api.mysocialpixel.com/accounts/{{ACCOUNT_ID}}/targeting-clusters/{{TARGETING_CLUSTER_ID}}
URI Parameters
| Parameter | Description |
|---|---|
| ACCOUNT_ID | The ID of the targeting cluster's account to retrieve |
| TARGETING_CLUSTER_ID | The ID of the targeting cluster to retrieve |