How To: Create a Campaign

This article describes the required steps for creating a new campaign with segments and bookings through the Ayuda PI API.

Setup: Login is Required

See How To: Log In for instructions for obtaining and using a Session ID. This is required for authentication with our servers.

Workflow

Creating a campaign through the API follows a top-down approach: the campaign is created first, followed by segments, then bookings. This is because a segment needs a campaign to which it can be attached, bookings need segments to which they can be attached, etc.

1. Create Campaign

1.1 Gather Required Information

The following information is required to create a campaign (see CampaignModel for a complete list of available fields):

  • string Name: The name you would like to give this campaign.
  • string SalesContractNumber: The contract number you would like to assign to this campaign.
  • Guid AdvertiserID: can be found using the GetByCode method on the AdvertiserController.
  • Guid CompanyID (a.k.a. Division in Splash): can be found using the GetAll method on the CompanyController
  • Guid AccountExecutiveID: This information cannot currently be retrieved through the API. Please contact your Ayuda representative for a list a valid values.
  • Guid SalesContractContentTypeID
    Use one of the following:
    • e1e4c872-9cc0-4ade-be9c-b9b92e72dd4e (Advertising)
    • 229cd76c-acde-418e-a807-87fcaddc0918 (Editorial)
  • Guid SalesContractStatusTypeID: This information cannot currently be retrieved through the API. Please contact your Ayuda representative for a list a valid values.
  • Guid SalesContractTypeID: This information cannot currently be retrieved through the API. Please contact your Ayuda representative for a list a valid values.

1.2 Execute Create Method

Once the required fields have been gathered, a call can be made to Create(CampaignModel) on the CampaignController.

Example
URL: https://example.ayudapreview.com/Splash/Pi/Campaign/Create
Body: 

{
  "name": "My New Campaign",
  "salesContractNumber: "123456",
  "advertiserID": "00000000-0000-0000-0000-000000000000",
  "companyID": "00000000-0000-0000-0000-000000000000",
  "accountExecutiveID": "00000000-0000-0000-0000-000000000000",
  "salesContractContentTypeID": "00000000-0000-0000-0000-000000000000",
  "salesContractStatusTypeID": "00000000-0000-0000-0000-000000000000",
  "salesContractTypeID": "00000000-0000-0000-0000-000000000000"
}

This will return a single Guid: the CampaignID.

2. Create a Segment

2.1 Gather Required Information

The following information is required to create a segment (see @Ayuda.BMS.Splash.PI.SDK.SegmentModel for a complete list of available fields):

  • Guid CampaignID: Returned by step 1.
  • DateTime StartDate: The start date for this segment.
  • DateTime EndDate: The end date for this segment.
  • Guid SalesMarket: can be found using the GetByCode method on the SalesMarketController.
  • Guid MediaTypeGroupID: can be found using the GetByCode or GetAll methods on the MediaTypeGroupController.
  • decimal BillingAmount: The gross amount for the segment.
  • Guid PurchaseTypeID: This information cannot currently be retrieved through the API. Please contact your Ayuda representative for a list a valid values.

2.2 Execute Create Method

Once the required fields have been gathered, a call can be made to Create(SegmentModel) on the SegmentController.

Example
URL: https://example.ayudapreview.com/Splash/Pi/Segment/Create
Body: 

{
  "campaignID": "00000000-0000-0000-0000-000000000000",
  "billingAmount": 10000.00,
  "startDate": "2020-01-01",
  "endDate": "2020-01-31",
  "salesMarketID": "00000000-0000-0000-0000-000000000000",
  "mediaTypeGroupID": "00000000-0000-0000-0000-000000000000",
  "purchaseTypeID": "00000000-0000-0000-0000-000000000000"
}

This will return a single Guid: the SegmentID.

3. Create Bookings

The type of bookings that can be created on a segment depend on the media type group of that segment (e.g. Static faces cannot be booked on a segment with a Digital media type group).

3.1 Static Bookings

Static faces and face packs are booked directly on a segment.

3.1.1 Face Booking

3.1.1.1 Gather Required Information

The following information is required to create a face booking (a.k.a. Face Selection) (see FaceSelectionModel for a complete list of available fields):

  • Guid SalesContractItemID: This is the SegmentID returned by step 2.2.
  • Guid FaceID: The face to book. Can be obtained using the GetByNumber method on the FaceController.
  • DateTime StartDate: The start date for this booking.
  • DateTime EndDate: The end date for this booking.
3.1.1.2 Execute Create Method

Once the required fields have been gathered, a call can be made to Create(FaceSelectionModel) on the FaceSelectionController.

Example
URL: https://example.ayudapreview.com/Splash/Pi/FaceSelection/Create
Body: 

{
  "salesContractItemID": "00000000-0000-0000-0000-000000000000",
  "faceID": "00000000-0000-0000-0000-000000000000",
  "startDate": "2020-01-01",
  "endDate": "2020-01-31"
}

This will return a single Guid: the FaceSelectionID.

3.1.2 Face Pack Booking

3.1.2.1 Gather Required Information

The following information is required to create a face pack booking (a.k.a. Face Pack Selection) (see FacePackSelectionModel for a complete list of available fields):

  • Guid SalesContractItemID: This is the SegmentID returned by step 2.2.
  • Guid FacePackID: The face pack to book. Can be obtained using the GetByName method on the FacePackController.
  • DateTime StartDate: The start date for this booking.
  • DateTime EndDate: The end date for this booking.
3.1.1.2 Execute Create Method

Once the required fields have been gathered, a call can be made to Create(FacePackSelectionModel) on the FacePackSelectionController.

Example
URL: https://example.ayudapreview.com/Splash/Pi/FacePackSelection/Create
Body: 

{
  "salesContractItemID": "00000000-0000-0000-0000-000000000000",
  "facePackID": "00000000-0000-0000-0000-000000000000",
  "startDate": "2020-01-01",
  "endDate": "2020-01-31"
}

This will return a single Guid: the FacePackSelectionID.

3.2 Digital Bookings

Digital faces and face packs must be booked on a Digital Booking Line (not directly on a segment).

3.2.1 Digital Booking Line

A Digital Booking Line holds digital face bookings and connects them to a segment.

3.2.1.1 Gather Required Information

The following information is required to create a digital booking line (see DigitalBookingLineModel for a complete list of available fields):

  • Guid SegmentID: returned by step 2.2.
  • DateTime StartDate: The start date for this digital booking line.
  • DateTime EndDate: The end date for this digital booking line.
  • float Saturation: The amount of under (less than 1) or over (greater than 1) saturation. For no saturation use 1.
  • Guid ScheduleTemplateID (a.k.a. Daypart in Splash): can be found using the GetFromCode method on the ScheduleTemplateController.
3.2.1.2 Execute Create Method

Once the required fields have been gathered, a call can be made to Create(DigitalBookingLineModel) on the DigitalBookingLineController.

Example
URL: https://example.ayudapreview.com/Splash/Pi/DigitalBookingLine/Create
Body: 

{
  "segmentID": "00000000-0000-0000-0000-000000000000",
  "startDate": "2020-01-01",
  "endDate": "2020-01-31",
  "saturation": 1,
  "scheduleTemplateID": "00000000-0000-0000-0000-000000000000"
}

This will return a single Guid: the DigitalBookingLineID.

3.2.2 Digital Face Booking

This step will book a single digital face on a digital booking line (and hence on the associated campaign).

3.2.2.1 Gather Required Information

The following information is required to create a digital face booking (a.k.a. Digital Booking Line Zone) (see DigitalBookingLineZoneModel for a complete list of available fields):

  • Guid DigitalBookingLineID: This is returned by step 3.2.1.
  • Guid FaceID: The face to book. Can be obtained using the GetByNumber method on the FaceController.
3.2.2.2 Execute Create Method

Once the required fields have been gathered, a call can be made to Create(DigitalBookingLineZoneModel) on the DigitalBookingLineZoneController.

Example
URL: https://example.ayudapreview.com/Splash/Pi/DigitalBookingLineZone/Create
Body: 

{
  "digitalBookingLineID": "00000000-0000-0000-0000-000000000000",
  "faceID": "00000000-0000-0000-0000-000000000000"
}

This will return a single Guid: the DigitalBookingLineZoneID. The digital face is now booked on the campaign.

3.2.3 Digital Pack

This step will book a single digital face pack on a digital booking line (and hence on the associated campaign).

3.2.2.1 Gather Required Information

The following information is required to create a digital face booking (a.k.a. Digital Booking Line Zone) (see DigitalBookingLineZoneModel for a complete list of available fields):

  • Guid DigitalBookingLineID: This is returned by step 3.2.1.
  • Guid SalesContractItemID: This is the SegmentID returned in step 2.2.
  • Guid FacePackID: The face pack to book. Can be obtained using the GetByName method on the FacePackController.
3.2.2.2 Execute Create Method

Once the required fields have been gathered, a call can be made to Create(digitalBookingLineID, salesContractItemID, facePackID) on the FacePackDigitalBookingLineZoneController.

Example
URL: https://example.ayudapreview.com/Splash/Pi/FacePackDigitalBookingLineZone/Create
Body: 

{
  "digitalBookingLineID": "00000000-0000-0000-0000-000000000000",
  "salesContractItemID": "00000000-0000-0000-0000-000000000000",
  "facePackID": "00000000-0000-0000-0000-000000000000"
}

This will return a single Guid: the FacePackDigitalBookingLineZoneID. The digital face pack is now booked on the campaign.