Home B2Core IB API Campaigns

Campaigns

On this page:

THE CAMPAIGN OBJECT

A detailed description of the JSON object

GET[base]/campaigns

Get a campaigns list

GET[base]/campaigns/{campaignId}

Get campaign details

POST[base]/campaigns

Add a new campaign

PUT[base]/campaigns/{campaignId}

Update a campaign

DELETE[base]/campaigns/{campaignId}

Delete a campaign

The Campaign object

This object provides the following data about a campaign:

campaignId string

The campaign identifier.

name string

The campaign name.

utmCampaign string

The URI parameter that specifies an individual campaign name.

utmContent string

The URI parameter that’s used to differentiate similar content, or links within the same ad. For example, if you have two call-to-action links within the same email message, you can use utmContent and set different values for each so you can tell which version is more effective.

utmMedium string

The URI parameter that specifies advertising or marketing media, for example: cpc, banner, email.

utmSource string

The URI parameter that identifies an advertiser, site, publication, that’s sending traffic to your property, for example: google, youtube.

utmTerm string

The URI parameter that identifies paid search keywords.

uri string

The URI of a campaign.

linkId string

The link identifier.

createTime string

The date and time when the object has been created.

updateTime string

The date and time when the object has been last updated.

uuid string

The universally unique identifier of the object (if provided). Refer to Integrations for more information.

THE CAMPAIGN OBJECT 
{
  "campaignId": "6006dda272f002519c3eb505",
  "name": "UEFA Champions League",
  "utmCampaign": "sport",
  "utmContent": "UEFA",
  "utmMedium": "banner",
  "utmSource": "youtube.com",
  "utmTerm": "bitcoin",
  "uri": "https://my.stage.org/register?referral=1&utm_campaign=sport&utm_content=UEFA&utm_medium=banner&utm_source=youtube.com&utm_term=bitcoin",
  "linkId": "6006dda272f002519c3eb505",
  "createTime": "2021-01-01T00:00:00+00:00",
  "updateTime": "2021-01-01T00:00:00+00:00",
  "uuid": null
}

Get a campaigns list

Use this method to obtain a list of campaigns.

To obtain detailed information about a specified campaign, use a separate method to get campaign details.

Request

Header parameters:

  • Authorization: Bearer <token>

Query parameters:

This method supports pagination, sorting, filtering, and query. For details on applying the parameters, refer to the Query parameters section. Possible parameters for filtering, sorting, and query are listed below. For values description, refer to the Campaign object.

Possible values for the filter parameter:

  • linkId

  • campaignNameFilter

  • userId

  • utmCampaign

  • utmContent

  • utmMedium

  • utmSource

  • utmTerm

  • uuid

Possible values for the sort_by parameter:

  • campaignId

  • createTime default

  • name

  • updateTime

  • utmCampaign

  • utmContent

  • utmMedium

  • utmSource

  • utmTerm

Possible values for the query parameter:

  • metrics — information about the number of clicks on a link, the number of registrations by a link and the link conversion

  • link — information about the link

  • language — information about available link languages

GET[base]/campaigns

curl --location -g --request GET 'https://your.base-url.here/campaigns?limit=10&offset=0&sort_by=createTime&sort_order=desc&filter[linkId]=6006dda272f002519c3eb505&filter[name]=name&filter[userId]=6006dda272f002519c3eb505&filter[utmCampaign]=sport&filter[utmContent]=UEFA&filter[utmContent]=banner&filter[utmContent]=youtube.com&filter[utmContent]=bitcoin&filter[uuid]=9&query[metrics]=1&query[link]=1&query[language]=1' \
--header 'Authorization: Bearer <token>'

Response

Body:

In case of success, the response body contains an array of Campaign objects providing information about all campaigns that correspond to the query parameters specified in the request.

Additionally, the response body may contain the following information if any of these were specified in the query parameters of the request:

  • an array of metrics providing information about the number of clicks on a link, the number of registrations by a link and the link conversion

  • the Link object

  • an array of Link language objects

Get campaign details

Use this method to obtain detailed information about a specified campaign.

To obtain a list of campaigns, use a separate method to get a list of campaigns.

Request

Header parameters:

  • Authorization: Bearer <token>

Path parameters:

campaignId required

The campaign identifier.

Query parameters:

This method supports query. For details on applying the parameters, refer to the Query parameters section.

Possible values for the query parameter:

  • metrics — information about the number of clicks on a link, the number of registrations by a link and the link conversion

  • link — information about the link

  • language — information about available link languages

GET[base]/campaigns/{campaignId}

curl --location -g --request GET 'https://your.base-url.here/campaigns/60ba407d15951453e60e49f8?query[metrics]=1&query[link]=1&query[language]=1' \
--header 'Authorization: Bearer <token>'

Response

Body:

In case of success, the response body contains a Campaign object providing information about the specified campaigns.

Additionally, the response body may contain the following information if any of these were specified in the query parameters of the request:

  • an array of metrics providing information about the number of clicks on a link, the number of registrations by a link and the link conversion

  • the Link object

  • an array of Link language objects

Add a new campaign

Use this method to add a new campaign.

Request

Header parameters:

  • Authorization: Bearer <token>

  • Content-Type: application/json

Body:

linkId string required

The link identifier.

name string

The campaign name.

The string value length can’t exceed 255 characters.

utmCampaign string

The URI parameter that specifies an individual campaign name.

The string value length can’t exceed 1024 characters.

utmContent string

The URI parameter that’s used to differentiate similar content, or links within the same ad. For example, if you have two call-to-action links within the same email message, you can use utm_content and set different values for each so you can tell which version is more effective.

The string value length can’t exceed 1024 characters.

utmMedium string

The URI parameter that specifies advertising or marketing media, for example: cpc, banner, email.

The string value length can’t exceed 1024 characters.

utmSource string

The URI parameter that identifies an advertiser, site, publication, that’s sending traffic to your property, for example: google, youtube.

The string value length can’t exceed 1024 characters.

utmTerm string

The URI parameter that identifies paid search keywords.

The string value length can’t exceed 1024 characters.

userId string required

The user identifier in the system.

uuid string

The universally unique identifier of the object. Refer to Integrations for more information.

The string value length can’t exceed 255 characters.

POST[base]v1/campaigns

curl --location -g --request POST 'https://your.base-url.here/campaigns' \
--header 'Authorization: Bearer <token>' \
--data-raw '{
  "linkId": "6006dda272f002519c3eb505",
  "userId": "6006dda272f002519c3eb505",
  "name": "UEFA Champions League",
  "utmCampaign": "sport",
  "utmContent": "UEFA",
  "utmMedium": "banner",
  "utmSource": "youtube.com",
  "utmTerm": "bitcoin",
  "uuid": null
}'

Response

Body:

In case of success, the response body contains a Campaign object providing information about the newly created campaign.

Update a campaign

Use this method to update a specified campaign.

Note

Instead of the method described below, you can use a similar method that uses the HTTP verb PATCH.

Request

Header parameters:

  • Authorization: Bearer <token>

  • Content-Type: application/json

Path parameters:

campaignId required

The campaign identifier.

Body:

Values of the following fields can be updated:

linkId string required

The link identifier.

name string

The campaign name.

The string value length can’t exceed 255 characters.

utmCampaign string

The URI parameter that specifies an individual campaign name.

The string value length can’t exceed 1024 characters.

utmContent string

The URI parameter that’s used to differentiate similar content, or links within the same ad. For example, if you have two call-to-action links within the same email message, you can use utm_content and set different values for each so you can tell which version is more effective.

The string value length can’t exceed 1024 characters.

utmMedium string

The URI parameter that specifies advertising or marketing media, for example: cpc, banner, email.

The string value length can’t exceed 1024 characters.

utmSource string

The URI parameter that identifies an advertiser, site, publication, that’s sending traffic to your property, for example: google, youtube.

The string value length can’t exceed 1024 characters.

utmTerm string

The URI parameter that identifies paid search keywords.

The string value length can’t exceed 1024 characters.

uuid string

The universally unique identifier of the object. Refer to Integrations for more information.

The string value length can’t exceed 255 characters.

PUT[base]/campaigns/{campaignId}

curl --location -g --request PUT 'https://my.stage.org/v1/campaigns/60ba407d15951453e60e49f8' \
--header 'Authorization: Bearer <token>' \
--data-raw '{
  "linkId": "6006dda272f002519c3eb505",
  "name": "UEFA Champions League",
  "utmCampaign": "sport",
  "utmContent": "UEFA",
  "utmMedium": "banner",
  "utmSource": "youtube.com",
  "utmTerm": "bitcoin",
  "uuid": null
}'

Response

Body:

In case of success, the response body contains a Campaign object providing information about the updated campaign.

Delete a campaign

Use this method to delete a specified campaign.

Request

Header parameters:

  • Authorization: Bearer <token>

Path parameters:

campaignId required

The campaign identifier.

DELETE[base]/campaigns/{campaignId}

curl --location --request DELETE 'https://your.base-url.here/campaigns/60ba407d15951453e60e49f8' \
--header 'Authorization: Bearer <token>'

Response

Body:

In case of success, no response body is returned.