List Campaigns

GET /campaigns
Copied
Arrow
                https://api.ocamba.com/v2/adex/campaigns

Returns a list of Campaigns

query Parameters
Arrow
Name
Description
fieldsstring
The client can request more efficient filtered representation of the resource showing only specific field(s), using the “fields” query parameter. Note that the “fields” parameter has precedence over the “view” parameter.

Example GET /VERSION/adex/RESOURCE_NAME?fields=id,name

See "Tips" for the list of filterable parameters.


Example: fields=field1,field2,field3
viewstring
Adex API returns full representation of the resource using the “view=full” query parameter. If not specified, the default view will be used.

Note that the “fields” parameter has precedence over the “view” parameter.


Example: view=full/default
sortstring
Sorts the response by specified field(s) with the option to specify sorting order (ascending by default, add prefix "-" for descending).

Examples:
GET /VERSION/adex/RESOURCE_NAME?sort=name → sorts per name, ascending
GET /VERSION/adex/RESOURCE_NAME?sort=-id → sorts per id descending
GET /VERSION/adex/RESOURCE_NAME?sort=id,-name → sorts per id ascending, then name descending

See tips for the list of sortable fields.


Example: sort=-field1,field2
pagestring
The page number indicates which set of items will be returned in the response. The format of request is "page=N,M" where 'N' (required) represents page number and 'M' (optional) is number of items per page.

Examples:
N=1, M=20 → returns page 1 with 20 items
N=2, M=20 → returns page 2 with 20 items (items 21-40)
N=3 → returns page 3. The number of objects returned depends on the resource settings.


Example: page=1,10
qstring
Set the q parameter value to search for a keyword or search term.

Example:
GET /VERSION/adex/RESOURCE_NAME?q=sou → returns a certain resource that contain string 'sou'

See tips for the list of searchable parameters.
q_fieldsstring
Use the q_fields parameter to list all fields you want to include in the search using q parameter. Note that not all fields are searchable on a specific object. If parameter q_fields is not specified, search is performed on a default search field.

Examples:
GET /VERSION/adex/RESOURCE_NAME?q=sou&q_fields=lname → API retuns a certain resource whose lname contains string 'sou'.
GET /VERSION/adex/RESOURCE_NAME?q=sou&q_fields=fname,lname,email → API returns a certain resource that contain string 'sou' in any of the specified fields.

See tips for the list of searchable parameters.
namestring
Name of the object.


Example: name=ExampleName
statusstring
Describe status of the object.


Example: status=status1
typestring
Describe type of the object.


Example: type=type1
account_idstring
Unique account identifier defined as a query parameter.


Example: account_id=12345
creator_idstring
Unique creator identifier defined as a query parameter.


Example: creator_id=12345
stat_datestring
Date associated with the stats data. Retention policy is 100 days.


Example: stat_date=rf:2024-04-04,2024-04-23
pricing_modelstring



Example: pricing_model=cpc
Response status codes
Arrow
200 - OK
Arrow
Name
Description
accountobject
General information about the account referenced by account_id. Shown only if requested through the field query parameter.
Name
Description
idstring
Id of the account, same as account_id.


Example: 10073337
imagestring
A link to the account image.


Example: https://dev-storage.ocamba.com/6197120/adex/accounts/90130201/images/%D9%8A%D9%8A%D9%8A%D9%8A%D9%8A.png
namestring
Name of the accound holder.


Example: John Smith
statusstring
Status of the account.


Example: active
account_idstring
A unique account identifier generated by the Ocamba platform.


Example: 52794322
bid_modifiers[ string ]
Array of bid modifier ids. Each element must be a unique bid modifier id supported by Ocamba.


Example: 1213,2232,4432
company_idstring
A unique company identifier generated by the Ocamba platform.


Example: 7196310
cpc_bid_strategy_idstring
Valid cpc bid strategy id supported by Ocamba.


Example: 1231
cpm_bid_strategy_idstring
Valid cpm bid strategy id supported by Ocamba.


Example: 1332
create_timestring
Timezone: GMT.


Example: 2021-10-29 12:47:00
creative_distributionnumber (int)
Describes the status of creative distribution on a campaign. Settable only through the distribute endpoints.


Example: 1

Possible values: 0 | 1
creative_typesstring
Describes the types of creatives on a campaign.


Example: dynamic-native,web-push-object
creatorobject
General information about the creator referenced by creator_id. Shown only if requested through the field query parameter.
Name
Description
idstring
Id of the creator, same as creator_id.


Example: 1000225
imagestring
Image of the creator.


Example: https://dev-storage.ocamba.com/6197120/adex/accounts/90130201/images/%D9%8A%D9%8A%D9%8A%D9%8A%D9%8A.png
namestring
Name of the creator.


Example: John Smith
creator_idstring
A unique creator identifier generated by the Ocamba platform.


Example: 1000225
descriptionstring
Additional description of campaign, maximum 2000 characters.


Example: Description goes here
effective_statusstring
The status of the campaign set by background processes. The same as status if campaign is not in limit.


Example: monthly-limit

Possible values: active | verification | rejected | paused | inactive | archived | hourly-limit | daily-limit | monthly-limit | lifetime-limit
end_timedateTime
A time when the campaign employment is over. At this point, campaign status will be automatically changed to 'paused' by backed processes. Timezone: GMT.


Example: 2021-10-29 13:07:04
external_demandobject
External demand object. Shown only if requested through the fields query parameter, or in a full view. Fields shown are id and name.
Name
Description
idstring
Id of the external demand, same as external_demand_id.


Example: 7552
namestring
Name of the external demand.


Example: Demo External Demand
partner_idstring
Id of the external demand partner.


Example: 280
statusstring
Status of the external demand.


Example: active
external_demand_idstring
External demand id created on the Ocamba platform. If external_demand_id is set, the campaign type will be implicitly set to "external" otherwise, the campaign type will be "internal". Pricing model of external demand must match the pricing model of the campaign.


Example: 12341
frequency_capobject
A feature that limits the number of times that your ads will appear to the same user for a given time frame.
Name
Description
clickobject
Frequency of clicks.
Name
Description
expiry_timenumber
Time frame for frequency capping, expressed in hours.


Example: 10
max_countnumber
Max number of times a user sees ads for a given time frame.


Example: 2
conversionobject
Frequency of conversions.
Name
Description
expiry_timenumber
Time frame for frequency capping, expressed in hours.


Example: 10
max_countnumber
Max number of times a user sees ads for a given time frame.


Example: 2
impressionobject
Frequency of impressions.
Name
Description
expiry_timenumber
Time frame for frequency capping, expressed in hours.


Example: 10
max_countnumber
Max number of times a user sees ads for a given time frame.


Example: 2
has_creativesnumber (int)
Shows if campaign has any creatives.


Example: 1

Possible values: 0 | 1
iab_categories[ string ]
Array of unique iab category ids, supported by Ocamba. Maximum number of elements is 3.


Example: IAB1,IAB2
idstring
A unique identifier generated by the Ocamba platform.


Example: 10001233
max_bidfloat
Maximum bid on a campaign.


Example: 12.24
metadataobject
The metadata field contains additional key-value pairs associated with the object.
Maximum number of key-value pairs is 50.
Name
Description
keystring
Key for the metadata.
Each key must be unique within the metadata object. Maximum 100 characters.


Example: key1
valuestring
Value for the metadata. Maximum 500 characters.


Example: value1
namestring
Name of the campaign, max 200 characters.


Example: DemoCampaign
pricing_modelstring
Assigning the wanted pricing model to campaign.


Example: cpc

Possible values: cpc | cpm | cpa
remote_idstring
Campaign id from an external source. Can not have two campaigns with the same remote id.


Example: 1241412
scorenumber (integer)
Campaign score. Minimum value - 0, Maximum value - 100.


Example: 78

Default: 50
source_campaign_idstring
Original campaign id. Exists only for copied campaigns.


Example: 1231412
start_timedateTime
A time when the campaign will be employed. Only campaigns with active status will be employed once the start time is reached. If the start time is not specified, the campaign will start immediately. Timezone: GMT.


Example: 2021-10-20 12:47:00
statsobject
Statistics about the campaign in the last 100 days. Shown only if requested through the field query parameter.
Name
Description
clicknumber
Number of clicks.


Example: 451
conversionnumber
Number of conversions.


Example: 661
ctrfloat
The rate of clicks to impressions.


Example: 10.84
impressionnumber
Number of impressions.


Example: 111
incomefloat
The total income.


Example: 125.65
spam_clicknumber
Number of spam clicks.


Example: 113
statusstring
The status of the campaign set by the user. May differ from the actual status of the campaign.


Example: active

Possible values: active | verification | rejected | paused | inactive | archived
sync_statusstring
Describes the sync status of a campaign.


Example: 2
targetingcampaign-targeting
Targeting object.
Campaign Targeting
Name
Description
browsersobject
Browsers object
Name
Description
items[ object ]
Array of browser items, maximum length limited by subscription plan.
categoriesobject

Name
Description
itemsarray
Array of strings containing category ids.
opstring
String describing operation. Possible values are eq and neq
connectionsobject
Connection type object
Name
Description
items[ string ]
Array of valid connection types supported by Ocamba.
opstring



Example: nin

Possible values: in | nin
containersobject
Container object
Name
Description
items[ string ]
Array of strings containing containers ids. Maximum length limited by subscription plan.
opstring
String describing operation.


Example: in

Possible values: in
countriesobject
Countries object.
Name
Description
items[ string ]
Array of country codes supported by ocamba (ISO 3166-1, 2 letter country codes), maximum length limited by subscription plan. Required if lists is not present.
lists[ string ]
Array of list ids created by the Ocamba platform. Lists must be of type country, maximum length limited by subscription plan. Required if items is not present.
opstring



Example: in

Possible values: in | nin
device_manufacturersobject
Device manufacturer object.
Name
Description
items[ string ]
Array of device manufacturer ids, maximum length limited by subscription plan.
opstring



Example: in

Possible values: in | nin
device_trackingnumber (integer)
Describes the status of device tracking.


Example: 1

Possible values: 0 | 1
device_typesobject
Device type object.
Name
Description
items[ string ]
Array of device types, maximum length limited by subscription plan.
opstring



Example: in

Possible values: in | nin
has_user_datanumber (integer)
Describes the availability of user data


Example: 1

Possible values: 0 | 1
ipobject
Ip object.
Name
Description
items[ string ]
Array of ips, each element must be a valid ipv4/cidr, maximum length limited by subscription plan. Required if lists is not present.
lists[ string ]
Array of list ids created by the Ocamba platform. Lists must be of type ip, maximum length limited by subscription plan. Required if items is not present.
opstring



Example: in

Possible values: in | nin
keywordsobject

Name
Description
itemsarray
Array of unique strings containing keywords. One item can be a string with minimum length of 3 and maximum of 150, containing max 20 groups separated by \|. Each group can be made up of these characters: a-zA-Z0-9_%!


Example: keyword01!\|keyword02_%
languagesobject
Languages object
Name
Description
items[ string ]
Array of unique strings. Each element must be a valid 2-letter language code supported by Ocamba platform, maximum number of items limited by subscription plan.
opstring



Example: nin

Possible values: in | nin
osobject
Os object
Name
Description
items[ object ]
Array of os items, maximum length limited by subscription plan.
pagesobject
Page object.
Name
Description
items[ string ]
Array of domains, maximum length limited by subscription plan. Required if lists is not present.
lists[ string ]
Array of list ids created by the Ocamba platform. Lists must be of type domain, maximum length limited by subscription plan. Required if items is not present.
opstring



Example: in

Possible values: in | nin
regionsobject
Regions object.
Name
Description
items[ string ]
Array of region ids generated by the Ocamba platform, maximum length limited by subscription plan. Required if lists is not present.
lists[ string ]
Array of list ids created by the Ocamba platform. Lists must be of type region, maximum length limited by subscription plan. Required if items is not present.
opstring



Example: in

Possible values: in | nin
subidsobject
Subid object.
Name
Description
items[ string ]
Array of subids, maximum length limited by subscription plan. Required if lists is not present.
lists[ string ]
Array of list ids created by the Ocamba platform. Lists must be of type subid, maximum length limited by subscription plan. Required if items is not present.
opstring



Example: in

Possible values: in | nin
tagsobject
Tag object.
Name
Description
items[ string ]
Array of tag ids, maximum length limited by subscription plan. This field is deprecated and will be removed in future. Please use container as a replacement.
opstring



Example: in

Possible values: in | nin
timeobject
Time object.
Name
Description
items[ string ]
Array of valid cron expressions, maximum length limited by subscription plan.
opstring



Example: in

Possible values: in | nin
user_ageobject

Name
Description
fromnumber (integer)



Example: 20
time_unitstring



Example: hour

Possible values: hour | day
tonumber (integer)



Example: 30
typestring
Describes type of the campaign. Type is set on creation of a campaign.


Example: internal

Possible values: internal | external
update_timestring
Timezone: GMT.


Example: 2021-10-30 14:27:26

tip
1 Searchable fields are id, name and description.
2 Default sorting field is name.
3 Filterable fields are: id, name, external_demand_id, source_campaign_id, remote_id, type, status, pricing_model, score, cpc_bid_strategy_id, cpm_bid_strategy_id, creative_types, start_time, end_time, create_time and update_time.
info
1 The response example is representing a full view.

Response examples
Copied
Arrow
200 Arrow
  • 200
  • 200
{
  "total": 92,
  "items": [
    {
      "id": "10001233",
      "company_id": "7196310",
      "account_id": "52794322",
      "account": {
        "id": "10073337",
        "name": "John Smith",
        "status": "active",
        "image": "https://dev-storage.ocamba.com/6197120/adex/accounts/90130201/images/%D9%8A%D9%8A%D9%8A%D9%8A%D9%8A.png"
      },
      "creator_id": "1000225",
      "creator": {
        "id": "1000225",
        "name": "John Smith",
        "image": "https://dev-storage.ocamba.com/6197120/adex/accounts/90130201/images/%D9%8A%D9%8A%D9%8A%D9%8A%D9%8A.png"
      },
      "external_demand_id": "12341",
      "external_demand": {
        "id": "7552",
        "partner_id": "280",
        "status": "active",
        "name": "Demo External Demand"
      },
      "source_campaign_id": "1231412",
      "remote_id": "1241412",
      "name": "DemoCampaign",
      "description": "Description goes here",
      "status": "active",
      "effective_status": "monthly-limit",
      "type": "internal",
      "pricing_model": "cpc",
      "score": 78,
      "bid_modifiers": [
        null
      ],
      "cpc_bid_strategy_id": "1231",
      "cpm_bid_strategy_id": "1332",
      "max_bid": 12.24,
      "creative_types": "dynamic-native,web-push-object",
      "creative_distribution": 1,
      "has_creatives": 1,
      "iab_categories": [
        null
      ],
      "frequency_cap": {
        "impression": {
          "expiry_time": 10,
          "max_count": 2
        },
        "click": {
          "expiry_time": 10,
          "max_count": 2
        },
        "conversion": {
          "expiry_time": 10,
          "max_count": 2
        }
      },
      "start_time": "2021-10-20 12:47:00",
      "end_time": "2021-10-29 13:07:04",
      "stats": {
        "impression": 111,
        "click": 451,
        "spam_click": 113,
        "conversion": 661,
        "income": 125.65,
        "ctr": 10.84
      },
      "targeting": {
        "countries": {
          "items": [
            "RS"
          ],
          "lists": [
            "1838"
          ],
          "op": "in"
        },
        "regions": {
          "items": [
            "2661876"
          ],
          "lists": [
            "2934"
          ],
          "op": "in"
        },
        "subids": {
          "items": [
            "fut_t10_18-24-MULTI_GG"
          ],
          "lists": [
            "1835"
          ],
          "op": "in"
        },
        "ip": {
          "items": [
            "123.523.123.4"
          ],
          "lists": [
            "2691"
          ],
          "op": "in"
        },
        "pages": {
          "items": [
            "ocamba.com"
          ],
          "lists": [
            "2725"
          ],
          "op": "in"
        },
        "tags": {
          "items": [
            "1303"
          ],
          "op": "in"
        },
        "device_types": {
          "items": [
            "console"
          ],
          "op": "in"
        },
        "device_manufacturers": {
          "items": [
            "13"
          ],
          "op": "in"
        },
        "os": {
          "items": [
            {
              "id": "12",
              "op": "in",
              "versions": [
                "10.0"
              ]
            }
          ]
        },
        "browsers": {
          "items": [
            {
              "id": "10",
              "op": "in",
              "versions": [
                "10.0"
              ]
            }
          ]
        },
        "connections": {
          "items": [
            "1"
          ],
          "op": "nin"
        },
        "time": {
          "items": [
            "[0,15,30,45 12,13,14 * 6 1]"
          ],
          "op": "in"
        },
        "languages": {
          "items": [
            "sr"
          ],
          "op": "nin"
        },
        "keywords": {
          "items": "keyword01!\\|keyword02_%"
        },
        "categories": {},
        "user_age": {
          "from": 20,
          "to": 30,
          "time_unit": "hour"
        },
        "device_tracking": 1,
        "has_user_data": 1
      },
      "metadata": {
        "key1": "value1"
      },
      "sync_status": "2",
      "create_time": "2021-10-29 12:47:00",
      "update_time": "2021-10-30 14:27:26"
    }
  ]
}

{
  "id": "10001233",
  "company_id": "7196310",
  "account_id": "52794322",
  "account": {
    "id": "10073337",
    "name": "John Smith",
    "status": "active",
    "image": "https://dev-storage.ocamba.com/6197120/adex/accounts/90130201/images/%D9%8A%D9%8A%D9%8A%D9%8A%D9%8A.png"
  },
  "creator_id": "1000225",
  "creator": {
    "id": "1000225",
    "name": "John Smith",
    "image": "https://dev-storage.ocamba.com/6197120/adex/accounts/90130201/images/%D9%8A%D9%8A%D9%8A%D9%8A%D9%8A.png"
  },
  "external_demand_id": "12341",
  "external_demand": {
    "id": "7552",
    "partner_id": "280",
    "status": "active",
    "name": "Demo External Demand"
  },
  "source_campaign_id": "1231412",
  "remote_id": "1241412",
  "name": "DemoCampaign",
  "description": "Description goes here",
  "status": "active",
  "effective_status": "monthly-limit",
  "type": "internal",
  "pricing_model": "cpc",
  "score": 78,
  "bid_modifiers": [
    null
  ],
  "cpc_bid_strategy_id": "1231",
  "cpm_bid_strategy_id": "1332",
  "max_bid": 12.24,
  "creative_types": "dynamic-native,web-push-object",
  "creative_distribution": 1,
  "has_creatives": 1,
  "iab_categories": [
    null
  ],
  "frequency_cap": {
    "impression": {
      "expiry_time": 10,
      "max_count": 2
    },
    "click": {
      "expiry_time": 10,
      "max_count": 2
    },
    "conversion": {
      "expiry_time": 10,
      "max_count": 2
    }
  },
  "start_time": "2021-10-20 12:47:00",
  "end_time": "2021-10-29 13:07:04",
  "stats": {
    "impression": 111,
    "click": 451,
    "spam_click": 113,
    "conversion": 661,
    "income": 125.65,
    "ctr": 10.84
  },
  "targeting": {
    "countries": {
      "items": [
        "RS"
      ],
      "lists": [
        "1838"
      ],
      "op": "in"
    },
    "regions": {
      "items": [
        "2661876"
      ],
      "lists": [
        "2934"
      ],
      "op": "in"
    },
    "subids": {
      "items": [
        "fut_t10_18-24-MULTI_GG"
      ],
      "lists": [
        "1835"
      ],
      "op": "in"
    },
    "ip": {
      "items": [
        "123.523.123.4"
      ],
      "lists": [
        "2691"
      ],
      "op": "in"
    },
    "pages": {
      "items": [
        "ocamba.com"
      ],
      "lists": [
        "2725"
      ],
      "op": "in"
    },
    "tags": {
      "items": [
        "1303"
      ],
      "op": "in"
    },
    "containers": {
      "items": [
        "1020"
      ],
      "op": "in"
    },
    "device_types": {
      "items": [
        "console"
      ],
      "op": "in"
    },
    "device_manufacturers": {
      "items": [
        "13"
      ],
      "op": "in"
    },
    "os": {
      "items": [
        {
          "id": "12",
          "op": "in",
          "versions": [
            "10.0"
          ]
        }
      ]
    },
    "browsers": {
      "items": [
        {
          "id": "10",
          "op": "in",
          "versions": [
            "10.0"
          ]
        }
      ]
    },
    "connections": {
      "items": [
        "1"
      ],
      "op": "nin"
    },
    "time": {
      "items": [
        "[0,15,30,45 12,13,14 * 6 1]"
      ],
      "op": "in"
    },
    "languages": {
      "items": [
        "sr"
      ],
      "op": "nin"
    },
    "keywords": {
      "items": "keyword01!\\|keyword02_%"
    },
    "categories": {},
    "user_age": {
      "from": 20,
      "to": 30,
      "time_unit": "hour"
    },
    "device_tracking": 1,
    "has_user_data": 1
  },
  "metadata": {
    "key": "key1",
    "value": "value1"
  },
  "sync_status": "2",
  "create_time": "2021-10-29 12:47:00",
  "update_time": "2021-10-30 14:27:26"
}