跳至主要内容
API docs by Redocly

Optimise Network API (1.0.0)

Download OpenAPI specification:Download

This is the documentation for the Optimise Network API.

Authentication

To authenticate an apikey must be specified in the header of the request. The API Key can be generated by creating a Service Account in Insights Dashboard.

Campaigns

List Campaigns

This endpoint returns a list of Campaigns. The list can be filtered by statuses to return those Campaigns where the Publisher has a relationship.

Authorizations:
None
query Parameters
contactId
required
integer <int64>

contactId of the advertiser or publisher

agencyId
required
integer <int64>
contactType
integer <int64>

Contact Type

offset
integer <int64>
Default: 0

How many items to skip for pagination

limit
integer <int64>
Default: 50
showInactive
boolean

contact deactivated flag

sortColumnName
string

Name of column to sort by

sortDirection
string

direction of column to sort 'asc'/'desc'

statuses
Array of strings

status of the campaigns

campaignTypeIds
Array of integers <int64> [ items <int64 > ]

ids of the campaign types

advertiserContactIds
Array of integers <int64> [ items <int64 > ]

ids of the advertisers

payoutTypeIds
Array of integers <int64> [ items <int64 > ]

ids of the payout Type

sectorIds
Array of integers <int64> [ items <int64 > ]

ids of the sectors

platformTypeIds
Array of integers <int64> [ items <int64 > ]

ids of the platforms

countryIds
Array of integers <int64> [ items <int64 > ]

ids of the countries

returnPublishersForCampaign
boolean

If true it will return the publishers for the returned campaigns

orderBy
string

ordering the results (productId, alphabetically, launchDate)

hostname
string

hostname to filter by

productIds
Array of integers <int64> [ items <int64 > ]

Filter based on product ids

hasEnquiryCriteria
boolean

Include campaigns which have enquiry criteria

advertiserCampaignStatuses
Array of strings

status of the campaigns

isItemLevelCommissionGroup
boolean

Include campaigns based on commission group type

searchTerm
string

Search term to filter the campaigns by name or id

managedBy
string

Filter the campaigns by who they're managed by (optimise, advertiser)

Responses

Response samples

Content type
application/json
[ ]

Get Campaign

This endpoint returns the details of a specific Campaign for the given campaignId/productId

NOTE: Does not yet support requests from the Advertiser scope.

Authorizations:
None
path Parameters
productId
required
integer <int64>

Id of the campaign

query Parameters
contactId
required
integer <int64>

contactId of the advertiser or publisher

agencyId
required
integer <int64>

Responses

Response samples

Content type
application/json
{
  • "id": 0,
  • "campaignId": "string",
  • "name": "string",
  • "description": "string",
  • "status": "string",
  • "productTypeName": "string",
  • "countryName": "string",
  • "platformName": "string",
  • "currencyCode": "string",
  • "validationWindow": "string",
  • "validationPeriod": "string",
  • "liveDate": "string",
  • "rejectedDate": "string",
  • "appliedDate": "string",
  • "cancelledDate": "string",
  • "advertiserId": "string",
  • "advertiserName": "string",
  • "EPC": "string",
  • "autoCrossSell": "string",
  • "deepLinkEnabled": "string",
  • "uidEnabled": "string",
  • "cookieDuration": "string",
  • "dailyCap": "string",
  • "firstLastCookie": "string",
  • "cashback": "string",
  • "voucher": "string",
  • "brandBidding": "string",
  • "email": "string",
  • "socialMedia": "string",
  • "behaviouralRetargeting": "string",
  • "adultContent": "string",
  • "fCAAuthorised": "string",
  • "popUnderUp": "string",
  • "postView": "string",
  • "agencyName": "string",
  • "trackingType": "string",
  • "itpCompliant": "string",
  • "postback": "string",
  • "commission": {
    },
  • "vertical": {
    },
  • "payout": {
    },
  • "baseTrackingUrl": "string",
  • "markets": [
    ],
  • "defaultCampaign": true,
  • "signupType": "default",
  • "conversionEnquiryValidation": {
    },
  • "primaryLogo": {
    },
  • "lastModifiedDate": "string",
  • "advertiserAccountTypeID": 0,
  • "primaryContactEmail": "string"
}

List Campaign Commission Groups

Gets a list of commission groups for the given Campaign

Authorizations:
None
path Parameters
campaignId
required
integer <int64>

Id of the campaign

query Parameters
contactId
required
integer <int64>

contactId of the advertiser or publisher

agencyId
required
integer <int64>
offset
integer <int64>
Default: 0

How many items to skip for pagination

limit
integer <int64>
Default: 50

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Invoices

List Invoices

Gets a list of invoices for an Advertiser

Authorizations:
None
query Parameters
agencyId
required
integer <int32>

Agency Id

contactId
required
integer <int32>

Contact Id

startDate
required
string <datetime>

Start date

endDate
string <datetime>

End date

status
string

Status

accountManager
integer <int64>

Status

showPayments
boolean

Show the payments

invoiceId
integer <int64>

Invoice Id

culture
string

Invoice Id

invoiceTypeId
integer <int32>

The type on invoice

includeDeleted
boolean

Show the deleted invoices

campaignName
string

Name of the campaign

showOnlyInvoicesWithNoOutstanding
boolean

Show invoices that are not outstanding

commissionTypeId
integer <int32>

Commission Type

currencyId
integer <int32>

currencyId

offset
integer <int32>

offset

limit
integer <int32>

limit

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Placements

Create Placement

Create a new placement

Authorizations:
None
query Parameters
advertiserId
required
integer <int64>

contactId of the advertiser

agencyId
required
integer <int64>

Id of the agency

Request Body schema: application/json

The new placement to create

campaignId
integer

Id of the Publisher Campaign the Placement will be linked to

placementName
string

Name of the new placement

type
integer

Placement type

placementDescription
string

Description of the placement

destinationUrl
string or null

Destination URL

Responses

Request samples

Content type
application/json
{
  • "campaignId": 0,
  • "placementName": "string",
  • "type": 0,
  • "placementDescription": "string",
  • "destinationUrl": "string"
}

List Placements

Gets a list of placements

Authorizations:
None
query Parameters
campaignIds
Array of strings

Id(s) of the campaign(s) to filter on

advertiserId
required
integer <int64>

contactId of the advertiser

publisherIds
Array of strings

contactId(s) of the publisher(s) to filter on

agencyId
required
integer <int64>

Id of the agency

offset
integer <int64>
Default: 0

How many items to skip for pagination

limit
integer <int64>
Default: 50

Number of items to return

fromDate
required
string <date>

Filter by from date

toDate
required
string <date>

Filter by to date

sort
string

Sort by column name

direction
string

Sort by direction

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get Placement

Gets a specific placement by ID

Authorizations:
None
path Parameters
placementId
required
integer <int64>

Id of the placement

query Parameters
advertiserId
required
integer <int64>

contactId of the advertiser

agencyId
required
integer <int64>

Id of the agency

Responses

Conversions

List Conversions

This endpoint returns a detailed list of Conversions for the given Publisher or Advertiser.

ConversionType can be changed to return a list of Conversions with basket items or related to a specific payment.

Use dateField to query the Conversions based on different date events.

Authorizations:
None
query Parameters
agencyId
required
integer <int64>
contactId
required
integer <int64>

For Advertisers use MID, for Publishers use AID

campaignId
Array of integers <int64> [ items <int64 > ]

Filter conversions by campaign id (for conversionType conversions, conversionsByBasketItem)

advertiserId
Array of integers <int64> [ items <int64 > ]

For Publishers, filter conversions by MID/advertiserId (for conversionType conversions, conversionsByBasketItem)

publisherId
Array of integers <int64> [ items <int64 > ]

For Advertisers, filter conversions by AID/publisherId (for conversionType conversions & contactType advertiser)

invoicePayoutId
Array of integers <int64> [ items <int64 > ]

For Publishers, filter conversions by invoice payout id (for coversionType conversionsByPayment)

queryAppGuid
string

Search app guid (for conversionType conversions, conversionsByBasketItem)

queryMerchantRef
Array of strings

For Advertisers, filters by merchantappid or order reference (for conversionType conversions, conversionsByBasketItem)

queryUid
string

For Publishers, Filter by UID/SubID (for conversionType conversions)

status
Array of strings
Items Enum: "approved" "pending" "rejected"

Filter conversions by status (for conversionType conversions, conversionsByBasketItem)

paymentStatus
string
Enum: "nextPayment" "advertiserInvoiced" "awaitingInvoicing" "paymentSent"

Filter conversions by payment status (for conversionType conversions)

fromDate
required
string <date>

Filter conversion from after the specified date (yyyy-mm-dd) (required for conversionType conversions, conversionsByBasketItem)

toDate
required
string <date>

Filter conversion from before the specified date (yyyy-mm-dd) (required for conversionType conversions, conversionsByBasketItem)

dateField
required
string
Enum: "impression" "click" "conversion" "invoice" "lastModifiedDate"

The event date field we want to filter down by (required for conversionType conversions, conversionsByBasketItem)

legacyId
integer <int64>

Old legacy conversion id

offset
integer >= 0

The number of conversions to skip

limit
integer [ 1 .. 500 ]
Default: 50

The number of conversions to return

conversionType
string
Default: "conversions"
Enum: "conversions" "conversionsByPayment" "conversionsByBasketItem"

The type of the conversion to get

targetCurrencyCode
required
string

Target conversion currency

Responses

Response samples

Content type
[
  • {
    }
]

Bulk Update Conversions

Updates a conversion. This endpoint does not currently support batch updates, so pass in conversions as an array of length 1.

Authorizations:
None
query Parameters
agencyId
required
integer <int64>
contactId
required
integer <int64>

For Advertisers use MID, for Publishers use AID

Request Body schema: application/json
Array of objects
Array
advertiserConversionId
string

The orderId for the Conversion

advertiserId
integer

MID or advertiserId

status
string
Enum: "pending" "approved" "rejected"

Sets the validation status of the Conversion

invoiceDate
string

Add the Conversion to a specified invoice period. Leave empty to use default value.

calcDate
string

Used to apply commission rates used at an earlier date. Specify a date for a previous commission group. Leave empty to use default value.

object

Update the Conversion Value in format ##,###.##

rejectionCode
string

Include a rejection code if the conversion is being rejected

object
Array of objects

Responses

Request samples

Content type
application/json
{
  • "conversions": [
    ]
}

Conversion Enquiries

List Conversion Enquiries

Use this endpoint to view Conversion Enquiries for a Publisher Account.

Authorizations:
None
query Parameters
agencyId
required
integer <int64>

AgencyId for the active session

contactId
required
integer <int64>

ContactId for the active session

enquiryIds
Array of integers

Enquiry ids to select

statusIds
Array of integers

statusIds to filter by

advertiserIds
Array of integers

Advertiser ids to filter by

publisherIds
Array of integers

Publisher ids to filter by

uIds
Array of strings

UIDS to filter by

advertiserAppId
string

MerchantAppID to filter by

publisherRefs
Array of strings

publisherRefs to filter by

productId
integer <int64>

Product id to filter by

customerName
string

Customer name to search by

fromDate
string <date>

Filter the from date

toDate
string <date>

Filter the to date

direction
string
Default: "desc"
Enum: "asc" "desc"

The direction of the results

offset
required
integer >= 0

The number to skip

limit
required
integer >= 1
Default: 50

The number to return

Responses

Response samples

Content type
application/json
{
  • "enquiryId": 0,
  • "optimiseNotes": "string",
  • "notes": "string",
  • "uId": "string",
  • "commissionValue": 0,
  • "statusId": 0,
  • "status": "string",
  • "agencyId": 0,
  • "campaign": {
    },
  • "publisher": {
    },
  • "advertiser": {
    },
  • "conversion": {
    }
}

Files

Upload File

Uploads a file to file explorer

Authorizations:
None
query Parameters
agencyId
required
integer

ID of Agency to upload file to

contactId
required
integer

AID or MID of the account to upload the file

Request Body schema: multipart/form-data

The file you want to enter

folderId
integer

The ID of the folder to upload to. Leave blank

name
string

Used to provide a custom name for the file

categoryId
integer

Set the categoryId for the file to allow automatic processing

description
string

Sets a description for the file

notifyUserIds
integer

Notifies the specified users of the file upload

file
string <binary>

The file to upload

Responses

Response samples

Content type
application/json
0
0

List Files

Retrieves a list of file entries.

Authorizations:
None
query Parameters
agencyId
required
integer <int64>

The agency Id

contactId
required
integer <int64>

The contact Id

contactId
integer <int64>

The user Id

sort
string

The property to sort on

direction
string

The direction to sort on (asc/desc)

offset
required
integer <int64>

The offset to fetch entries for

limit
required
integer <int64>

The limit of entries returned

categoryId
Array of integers <int64> [ items <int64 > ]
Default: 1

The category Id(s) of the files to list. Defaults to 1 (Validations) if no value is provided. Category Lookup Table

entryType
string
Default: "FILE"

Entry Type (FILE or FOLDER)

folderId
integer <int64>

Required if searching for files saved inside a folder/subfolder. To obtain a list of available folders and their Ids, call this endpoint passing &entryType=FOLDER as a query parameter'.

Responses

Response samples

Content type
application/json
{
  • "id": 0,
  • "agencyId": 0,
  • "contactId": 0,
  • "category": {
    },
  • "user": {
    },
  • "entryType": {
    },
  • "parentEntryId": 0,
  • "name": "string",
  • "description": "string",
  • "fileExtension": "string",
  • "fileSize": 0,
  • "filePath": "string",
  • "creationDate": "string",
  • "deleted": true,
  • "deletionUser": {
    },
  • "deletionDate": "string",
  • "lastDownloadDate": "string",
  • "downloadCount": 0,
  • "lastDownloadUser": {
    }
}

Get File

Retrieve a file

Authorizations:
None
path Parameters
id
required
integer

The ID of the file to access

query Parameters
agencyId
required
integer

ID of Agency to upload file to

contactId
required
integer

AID or MID of the account to upload the file

download
boolean

Whether to download the file

includeSubEntries
boolean

Whether to include files within folders

Responses

Response samples

Content type
application/json
"string"

Publisher Payment

Publisher Payment Overview

Retrieves a commission status report for the Publisher.

Authorizations:
None
query Parameters
agencyId
required
integer <int64>

The agency Id

contactId
required
integer <int64>

The contact Id

startYear
required
string <date-time>

The Start year

startMonth
required
string <date-time>

The Start month

endYear
required
string <date-time>

The end year

endMonth
required
string <date-time>

The end month

advertiserId
required
integer <int64>

contactId of the advertiser

campaignId
required
integer <int64>

Id of the campaign

paymentStatus
required
string
Enum: "Payment Sent" "Next Payment" "Advertiser Invoiced" "No Commission" "Fast" "Fast (Adjustment)" "Fast (Reversal)"

Filter report by payment status

Responses

Response samples

Content type
application/json
{
  • "CampaignStatID": 0,
  • "BillingYear": 0,
  • "BillingMonth": 0,
  • "OptimiseCompany": "string",
  • "Merchant": "string",
  • "Product": "string",
  • "Imp": 0,
  • "Clicks": 0,
  • "VT": 0,
  • "Currency": "string",
  • "ValidatedCommission": 0,
  • "OutStandingCommission": 0,
  • "PaymentStatus": "string",
  • "PaymentType": "string",
  • "InvoiceNumber": 0,
  • "InvoiceNumberList": "string",
  • "MID": 0,
  • "PID": 0,
  • "PaymentDate": "2019-08-24T14:15:22Z",
  • "ProductCurrencyRate": 0,
  • "UV": 0
}

Vouchercodes

List Voucher Codes

Retrieves offers & voucher code for campaigns that Publishers are promoting.

Authorizations:
None
query Parameters
agencyId
required
integer <int64>

The agency Id

contactId
required
integer <int64>

The contact Id

advertiserContactId
integer <int64>

The advertiser Id

categoryId
integer <int32>

The category Id. Category Lookup Table

active
boolean
Default: true

Include active voucher codes

expired
boolean
Default: false

Include expired voucher codes

startDate
string <date-time>

The Start date

endDate
string <date-time>

The end date

historyDays
integer <int32>

Number of days to search

id
integer <int32>

Voucher code Id

pid
integer <int32>

The product Id

offset
integer <int32>

The offset

limit
integer <int32>

The limit

cultureCode
string <cultureCode>

The culture code

exclusive
boolean

Exlusive

Responses

Response samples

Content type
application/json
{
  • "id": 0,
  • "productId": 0,
  • "campaignName": "string",
  • "companyName": "string",
  • "code": "string",
  • "description": "string",
  • "activationDate": "2019-08-24T14:15:22Z",
  • "expiryDate": "2019-08-24T14:15:22Z",
  • "title": "string",
  • "campaignId": 0,
  • "deepLinkURL": "string",
  • "trackingURL": "string",
  • "addedon": "2019-08-24T14:15:22Z",
  • "categoryName": "string",
  • "type": "string",
  • "discount": "string",
  • "categoryId": 0,
  • "status": "string",
  • "affiliateSpecific": true,
  • "CultureCode": "string",
  • "Exclusive": true
}

Product Feeds

List Product Feeds

Gets a list of product feeds for campaigns that Publishers are promoting. The feedId can be combined with AID to create a download URL

Authorizations:
None
query Parameters
contactId
required
integer <int64>

ContactId for the active session

agencyId
required
integer <int64>

AgencyId for the active session

offset
integer <int64>
Default: 0

How many items to skip for pagination

limit
integer <int64>
Default: 50

How many items to limit to for pagination

feedId
integer <int32>

pass feedId

pid
integer <int64>

pass pid

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Payments

List Payments

This endpoint returns a list of payments made to a specific Publisher.

Authorizations:
None
query Parameters
id
integer <int64>

Invoice payout id

contactId
required
integer <int64>

ContactId for the active session

agencyId
required
integer <int64>

agencyId for the active session

status
string

Publisher status

startDate
required
string <date>

publisher payment start date

endDate
required
string <date>

publisher payment end date

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Reporting

Execute

This endpoint returns the result of the executed report.

Authorizations:
None
query Parameters
contactId
required
integer <int64>

Id of the contact

agencyId
required
integer <int64>

Id of the agency

Request Body schema: application/json
measures
required
Array of strings
Items Enum: "validatedConversions" "rejectedConversions" "pendingConversions" "totalConversions" "assistedConversions" "clicks" "pendingCommission" "validatedCommission" "rejectedCommission" "averageCommission" "clickCommission" "validatedConversionCommission" "totalCommission" "commissionpending" "uniqueVisitors" "conversionRate" "validatedConversionRate" "validationRate" "assistedConversionRate" "rejectedConversionRate" "ctr" "epc" "ecpm" "averageOrderValue" "originalOrderValue" "impressions" "averageValidatedCost" "pendingNetCost" "validatedCost" "validatedNetCost" "rejectedNetCost" "totalNetCost" "averageCost" "clickCost" "validatedConversionCost" "quoteEvent" "homepageEvent" "landingPageEvent" "contentPageEvent" "applicationStartEvent" "basketEvent" "applicationEndEvent" "quoteStartEvent" "applicationDeclineEvent" "applicationReferralEvent" "returnOnAdSpend" "returnOnInvestment" "completedApplications" "pendingReturnOnAdSpend" "pendingReturnOnInvestment" "estimatedValidatedConversions" "estimatedValidatedCommission" "estimatedValidatedNetCost"

Measures with which to build the report query. Additional information on available measures can be found in the reference table

dimensions
required
Array of strings
Items Enum: "invoiceDateId" "dateId" "date" "dayName" "week" "weekCommencing" "month" "monthName" "monthNo" "quarter" "year" "invoiceDate" "InvoiceDayName" "invoiceWeek" "invoiceWeekCommencing" "invoiceMonth" "invoiceMonthNo" "invoiceMonthName" "invoiceQuarter" "invoiceYear" "hour" "minute" "websiteName" "websiteUrl" "adContainerId" "adContainerName" "adUnitId" "adUnitPath" "adUnitHeight" "adUnitWidth" "adUnitTypeName" "publisherId" "publisherName" "publisherType" "advertiserId" "advertiserName" "campaignId" "agencyId" "deviceType" "deviceTypeCount" "primaryVerticalId" "primaryVertical" "secondaryVerticalId" "secondaryVertical" "countryName" "countryCode" "city" "regionName" "placementId" "placementName" "placementDesc" "placementType" "PID" "campaignGroupId" "campaignGroup" "itemPolicyType" "itemCategory" "campaignStatus" "partnerType" "campaignType" "campaignTypeId" "operatingSystem" "customerType" "trackingType" "campaignCountry" "currencyCode" "voucherCode" "campaignName" "quoteAction"

Dimensions with which to build the report query. Additional information on available dimensions can be found in the reference table

required
Array of objects
required
Array of objects

Measures or dimensions by which data is to be ordered

dateType
required
string
Enum: "conversionDate" "invoiceDate"

Event-date against which a data point is held

fromDate
required
string

Defines start point for report data

toDate
required
string

Defines end point for report data

targetCurrency
string

Defines currency into which data should be converted

dateGroupBy
string
Enum: "daily" "weekly" "monthly" "quarterly" "weekCommencing" "yearly"

Defines time period by which to aggregate data

includeOriginalCurrency
boolean

Whether to return original currency

includeTargetCurrency
boolean

Whether to return target currency

Responses

Request samples

Content type
application/json
{
  • "measures": [
    ],
  • "dimensions": [
    ],
  • "conditions": [
    ],
  • "orderBys": [
    ],
  • "dateType": "conversionDate",
  • "fromDate": "string",
  • "toDate": "string",
  • "targetCurrency": "string",
  • "dateGroupBy": "daily",
  • "includeOriginalCurrency": true,
  • "includeTargetCurrency": true
}

Response samples

Content type
application/json
[
  • {
    }
]