List Deals

Copied

                https://api.ocamba.com/v1/hood/deals

Returns a list of Deals

query Parameters

Name

Description

fieldsstring

Fields parameter represents array of dimensions and measures. Dimensions are used to categorize, segment, and reveal the details of the data. Measures contain numeric, quantitative values that can be measured. At least one measure is required.

Example: fields=field1,field2,field3

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

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/hood/RESOURCE_NAME?sort=name → sorts per name, ascending
GET /VERSION/hood/RESOURCE_NAME?sort=-id → sorts per id descending
GET /VERSION/hood/RESOURCE_NAME?sort=id,-name → sorts per id ascending, then name descending

See tips for the list of sortable fields.

Example: sort=-field1,field2

qstring

Set the q parameter value to search for a keyword or search term.

Example:
GET /VERSION/hood/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/hood/RESOURCE_NAME?q=sou&q_fields=lname → API retuns a certain resource whose lname contains string 'sou'.
GET /VERSION/hood/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.

statusstring

Describe status of the object.

Example: status=status1

viewstring

Hood 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

Response status codes

200 - OK

Name

Description

items[ deal ]

An array of all created items.

Deals

Name

Description

archivednumber (integer)

Describes if a deal is archived. If a deal is archived its information can not be updated.

Example: 1

base_pricenumber (decimal)

Describes the base price that is set for the deal. Priority depends on field base_price_priority. Value must be between 0.01 and 10000.

Example: 2.24

base_price_priorityboolean

Describes if prices set in base_price or country_price have priority over the one sent as a query parameter.

Example: true

Possible values: true | false

budgetnumber (integer)

Value representing maximum total value a deal should earn. Minimum value 0, maximum 1000000.

Example: 2321

clickthroughboolean

Describes if a click event is required for a deal to be attributed.

Example: true

Possible values: true | false

company_idstring

Company ID

Example: 6197120

country_priceobject

Key-value pairs {key : value} representing price by country. If user country is defined, price for that country is added to the base price.

Name

Description

keystring

Country code supported by the Ocamba platform (ISO 3166-1, 2 letter country codes).

Example: DE

valuenumber (decimal)

Value of price per country, minimum 0.1, maximum 10000.

Example: 12.53

create_timedateTime

Timezone: GMT.

Example: 2021-10-29 15:40:10

descriptionstring

Deal Description

Example: The description of a Deal has the max of 2000 characters

device_priceobject

Key-value pairs {key : value} representing price by device. If device is defined, price for that device is added to the base price.

Name

Description

keystring

Device type, possible values are mobile and desktop.

Example: desktop

valuenumber (decimal)

Value of price per device, minimum 0, maximum 100.

Example: 12.53

effective_statusstring

Describes the status of the deal. Can be impacted by changes to partner.

Example: suspended

event_priceobject

Key-value pairs {key : value} representing price by event. If event is defined, price for that event is added to the base price.

Name

Description

keystring

Event name, maximum length 32 characters.

Example: click

valuenumber (decimal)

Value of price per event, minimum 0.1, maximum 10000.

Example: 12.53

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

max_valuenumber (int)

Describes the maximum number of time units that frequency cap will account for. Minimum 0, maximum 1.

Example: 12

per_unitstring

idstring

Deals Unique Identifier

Example: 13472

namestring

Deal name, maximum 100 characters

Example: Example Name

partner_idstring

Valid partner id, supported by the Ocamba platform.

Example: 1000232

performance_conditionsobject

Key-value pairs {key : value} representing score by event. If event is defined, score for that event is added to the user and campaign score when converison is attributed.

Name

Description

keystring

Event name, maximum length 32 characters.

Example: click

valuenumber (integer)

Value of score per event, minimum 1, maximum 100.

Example: 12

postbackstring

Deal url for clients to assign conversions to users.

Example: https://ocm.com/conv?click_id={OCMH_CLICK_ID}&price={PRICE}&currency={CURRENCY}

statsobject

Statistics about the deal. Shown only if requested through the field query parameter.

Name

Description

costnumber (decimal)

Total cost for the deal.

Example: 11.1

revenuenumber (decimal)

Total revenue for the deal.

Example: 34.1

roinumber (decimal)

Return on investment, shown in percentage.

Example: 229.2

statusstring

Deal Status can be active or inactive. Default value is 'active'.

Example: active

Possible values: active | inactive

structurestring

Deal payment structure. Describes the basis on which the price is calculated.

Example: cpi

Possible values: cpc | cpm | cpi | cpl | cpe | cps | cpv | performance-based | subscription-based | flat-fee | hybrid

systemnumber (int)

Indicates if the deal is a system deal. A system deal is automatically added when installing the Hood application.

Example: 1

time_windownumber (integer)

Describes how much time in seconds can pass between a click event and attribution, every attribution after that time window will be marked as spam. Value of 0 means there is no limit. Minimum value 0, maximum value 2592000.

Example: 3600

Possible values: 3600 | 21600 | 43200 | 86400 | 604800 | 1209600 | 2592000 | 5184000 | 7776000

typestring

Deal type, can be ssp or dsp.

Example: ssp

Possible values: ssp | dsp

unique_conversionboolean

Toggles check if deal is unique. Uniqueness is determined by reference provided by user when attributing deal. Default value false.

Example: true

update_timedateTime

Timezone: GMT.

Example: 2021-10-29 15:40:10

totalinteger

A total number of items.

Example: 31

500 - Internal Server Error

Name

Description

codeinteger

Http response status code.

Example: 500

messagestring

The human readable message that describes how to deal with error.

Example: Internal server error.

titlestring

The error title.

Example: Internal server error.

tip

1 Filterable fields are name, system, status, clickthrough, time_window, base_price_priority and archived.

Response examples

Copied

200

{
    "total": "31",
    "items": [
       {
          "id": "1000254",
          "company_id": "6197120",
          "name": "latest deal",
          "description": "second description",
          "status": "active",
          "effective_status": "active",
          "postback": "https://dev-t.ocmhood.com/conv?click_id={OCMH_CLICK_ID}&price={PRICE}&currency={CURRENCY}&ref={REFERENCE}&event={EVENT}&device={DEVICE}&session_id={SESSION_ID}",
          "frequency_cap": {
            "max_value": 12,
            "per_unit": "week"
          },
          "clickthrough": false,
          "time_window": 3600,
          "country_price": {
              "RS": 13.11
          },
          "base_price": 1.44,
          "system": 0,
          "base_price_priority": false,
          "create_time": "2024-07-18 11:37:08",
          "update_time": "2024-07-18 11:37:08"
      },
      {
          "id": "1000252",
          "company_id": "6197120",
          "name": "new other deal",
          "description": "first description",
          "status": "active",
          "effective_status": "active",
          "postback": "https://dev-t.ocmhood.com/conv?click_id={OCMH_CLICK_ID}&price={PRICE}&currency={CURRENCY}&ref={REFERENCE}&event={EVENT}&device={DEVICE}&session_id={SESSION_ID}",
          "frequency_cap": {
            "max_value": 6,
            "per_unit": "month"
          },
          "clickthrough": false,
          "time_window": 3600,
          "country_price": {
              "RS": 22.31
          },
          "base_price": 1.12,
          "system": 0,
          "base_price_priority": false,
          "create_time": "2024-07-18 11:28:23",
          "update_time": "2024-07-18 11:39:12"
      },
      {
          "id": "1000251",
          "company_id": "6197120",
          "name": "another deal",
          "description": "another example description",
          "status": "active",
          "effective_status": "active",
          "postback": "https://dev-t.ocmhood.com/conv?click_id={OCMH_CLICK_ID}&price={PRICE}&currency={CURRENCY}&ref={REFERENCE}&event={EVENT}&device={DEVICE}&session_id={SESSION_ID}",
          "frequency_cap": {
            "max_value": 124,
            "per_unit": "day"
          },
          "clickthrough": false,
          "time_window": 3600,
          "country_price": {
              "RS": 12.1
          },
          "base_price": 1.12,
          "system": 0,
          "base_price_priority": true,
          "create_time": "2024-07-18 11:27:55",
          "update_time": "2024-07-18 11:27:55"
      },
    ]
}

{
  "total": 31,
  "items": [
    {
      "id": "13472",
      "company_id": "6197120",
      "partner_id": "1000232",
      "name": "Example Name",
      "description": "The description of a Deal has the max of 2000 characters",
      "status": "active",
      "effective_status": "suspended",
      "type": "ssp",
      "structure": "cpi",
      "postback": "https://ocm.com/conv?click_id={OCMH_CLICK_ID}&price={PRICE}&amp;currency={CURRENCY}",
      "frequency_cap": {
        "max_value": 12,
        "per_unit": "day"
      },
      "clickthrough": true,
      "time_window": 3600,
      "base_price": 2.24,
      "country_price": {
        "key": "DE",
        "value": 12.53
      },
      "event_price": {
        "key": "click",
        "value": 12.53
      },
      "device_price": {
        "key": "desktop",
        "value": 12.53
      },
      "base_price_priority": true,
      "budget": 2321,
      "unique_conversion": true,
      "performance_conditions": {
        "key": "click",
        "value": 12
      },
      "system": 1,
      "stats": {
        "roi": 229.2,
        "revenue": 34.1,
        "cost": 11.1
      },
      "archived": 1,
      "create_time": "2021-10-29 15:40:10",
      "update_time": "2021-10-29 15:40:10"
    }
  ]
}

{
  "code": 500,
  "title": "Internal server error.",
  "message": "Internal server error."
}

List Deals

GET /dealsCopied https://api.ocamba.com/v1/hood/deals

GET /deals
Copied
`https://api.ocamba.com/v1/hood/deals`