Our newest release of our self-service API, pivots from the traditional cart and order model and corresponding endpoints to using a draft versioning system for a campaign that is more aligned with AdButler's overall campaign management API.

What's changed from our previous version?

Old API documentation is still available for any customers actively using the previous API, and can still be used today, but it will not see any further signifant new features added to this API, however it will remain maintained and available.

• Removed 'Orders' endpoint.
• Removed 'Order Items' endpoint
• Removed 'Carts' endpoint.
• Removed 'Cart Items' endpoint.
• Added 'Campaign Drafts' endpoint
• Added 'Campaign Draft Ads' endpoint.
• Added 'Campaign Draft Products' endpoint.
• Added 'Campaign Ad Items' endpoint.
• Added 'Campaign Placements' endpoint.
• Added 'Transactions' endpoint.

Workflow Storyboard

First and foremost, you'll need to start by creating your self-service portal. This can be done via the AdButler Administrative Dashboard. After you've created your self-service portal, and configured the Zone Inventory to your desired specifications, it's time to start building your dashboard with our new self-service v1 API.

1. Creating your customer

2. Creating your campaign draft

3. Uploading your creative assets

4. Creating the draft ad-item

5. Creating the draft placement

6. Submitting the order

7. Order approval and rejection

Creating your customer

The first part of any self-service experience will be your 'Customer'. These are advertisers and customers who will be buying your zone inventory through your self-service dashboard.

To create a 'Customer' in the self-service dashboard, you'll be hitting the following endpoint.

POST https://api.adbutler.com/v2/self-serve/customers

{
    "name" : "New Customer",
    "email" : "new@example.com",
    "portal" : ID_OF_YOUR_PORTAL,
}

optional fields, first_name, last_name, company_name

This will allow you to create your customer in your self-service portal. You will be able to modify the customer with a PUT request later to add funds to their wallet, or update information.

When building your own self-service dashboard, this customer ID will need to be retained when building campaign drafts, as we will require the portal ID and customer ID for those drafts.

Creating a campaign draft

A campaign draft is where the information about this customers campaign is stored in 'draft' mode that can be modified before being submitted for approval.

POST https://api.adbutler.com/v2/self-serve/portals/YOUR_PORTAL_ID_HERE/campaign-draft

{
    "customer_id" : CUSTOMER_ID,
    "name ": "Sample Campaign Name",
    "start_date" : "2023-06-01T00:00:00Z",
    "end_date" : "2023-06-301T00:00:00Z",
    "budget" :1 000,
    "geo-target" : {}
}

A campaign draft ID will be returned, that will be used in future steps for creating draft placements and ad items.

At this stage, after your campaign draft has been created, it's time to start with ad item creation. This path may fork depending on your dashboard. If you plan to allow image ads, you may choose to upload the image to your media library at this stage, so that the file exist and can be referred in the draft ad item. A common use case would be if you provide your customers with a WYSIWYG Ad Builder similar to Canva or other design tools, the final creative asset will be uploaded to as the creative file.

Uploading the creative file

When you're ready to upload the creative asset to the media library, you'll want to use our regular creatives API endpoint to upload the asset.

POST https://api.adbutler.com/v2/creatives/image

{
    file : string
}

After uploading the creative file, the API will return a JSON response with a file_id This ID will be used in your draft ad item in the next step.

Creating draft ad items

Draft ad items are the ad items that will serve within this campaign when approved.

POST https://api.adbutler.com/v2/self-serve/portals/YOUR_PORTAL_ID_HERE/campaign-draft/ads

{
    "customer_id" : CUSTOMER_ID,
    "name" : "Sample Image Ad",
    "type" : "image",
    "width" : 300,
    "height" : 250,
    "file_id" : CREATIVE_FILE_ID,
    "destination_url" : "https://example.com",
}

After your draft ad item has been completed, you'll want to create the draft campaign placement. The draft campaign placement is the draft portal zone inventory where you will be showing this ad.

Creating draft campaign placements

Campaign Draft placements are the connection between your ad campaign, the creative (ad items), and the inventory (zone) where it will run.

POST https://api.adbutler.com/v2/self-serve/portals/YOUR_PORTAL_ID_HERE/campaign-draft/placements
{
    "customer_id" : CUSTOMER_ID,
    "portal_zone" : PORTAL_ZONE_ID,
    "bidding_strategy": "MAX_IMPRESSIONS",
    "selected": true,
    "max_bid": "",
    "dayparting": null,
    "ad_count": 1,

}

Submitting the Campaign

After your draft is completed, you will want to submit the campaign for approval.

POST https://api.adbutler.com/v2/self-serve
{
}

Approving the Campaign

Campaigns can either be approved directly within the AdButler dashboard after being reviewed by your sales team, however approval and rejection statuses can also be automated using the campaign approval API available here.