3 Submission API

As in any database Adility allows you to execute insert and select commands. For the insert command we use the word submission and for the select command we use the word distribution. So there are Submission API and Distribution API in Adility.

You can use the Submission API if you as the card issuer have deals, gift cards that you would like to distribute or if you want to provide your clients/advertisers access to a new distribution channel for their offers. 

Base URL: https://api.adility.com/submission/beta


Introduction

This topic explains the basics of submitting offers to Adility. If you need more in-depth information on the submission workflow you can read the article Workflow For Submitters. The topic is divided into sections:
  • Manage Offers. How to submit an offer and beyond.
  • Callback/WebHook. After you submit an offer it can be changed on Adility. For example, its status changes from submitted to reviewed or a comment is added. This section gives you an overview how to get notified about such changes.
  • Offer Acceptance Process. Submitting an offer goes beyond adding the offer to Adility. We have structure an approval process to qualify offers before they are available to publishers. The approval process is led by account managers on Adility side. 
  • Communication between Advertiser and Account Manager. In order to help advertisers and account managers to communicate during the approval process, the Submission API allows to post comments to individual offers. 
  • Requesting Editorial Support for Offer Creative. Each offer needs creative copy and images such as headlines, illustrations and offer description. You may choose to compose creatives by yourself and submit them with offers. But you also can request editorial support from Adility editorial team. If you do so there's a certain process to collaborate with the editorial team and confirm creative.
  • Getting Distribution Report. After an offer is approved it may be published and generates sales. This section describes our reporting available to you.

Managing Offers

Offers are represented in the system by Offer status. You can submit an offer, update it and change its status. You can not delete an offer after the submission but you can cancel it. Below you will find each operation described in more details:
  • Submit offer
  • Offer statuses
  • Update offer
  • Suspend offer
  • Resume offer
  • Cancel offer

Submit offer

POST /offers

Creates an offer in The OfferDB. The offer obtains id that you can use later to refer to it.

Request

JSON
{
    "offer":
    { 
        "type": "deal",
        "title": "an Initial Chiropractic Exam, X-Rays, and 10-Minute Mechanical Traction",
        "price": {
            "currency_code": "USD",
            "amount": 3700
        },
        "value": {
            "currency_code": "USD",
            "amount": 22500
        },
        "advertiser_rebate": {
            "currency_code": "USD",
            "amount": 1500   
        },
        "fine_print": "Limit 1 per person per visit • Appointments required and subject to availability • Normal merchant cancellation policies apply; voucher subject to forfeiture • Other conditions apply • Promotional value expires on 06/04/11.",
        "start_date": "2010-07-26",
        "end_date": "2011-07-26",
        "quantity_in_stock": 200,
        "vouchers_expire": {
            "on": "2011-08-01"
        },
        "creative": {
         "requires_editorial_support": true,
         "headlines": ["$37 for an Initial Chiropractic Exam, X-Rays, and 10-Minute Mechanical Traction at Cohen Chiropractic Centre (Valued at $225.)", "$37 for $225 Worth of Initial Chiropractic Exam, X-Rays, and 10-Minute Mechanical Traction"],
         "description": "The only thing worse than back pain is having trouble finding a good chiropractor to straighten you out. With today's deal, consider your search over. Spend $37 for a full chiropractic consultation including range of motion testing, postural assessment, grip strength testing, and a thorough consultation at Cohen Chiropractic Centre, a $225 value. Dr. Cohen is a specialist in chiropractic care with years of experience providing the right touch to realign your out-of-whack back. Dr. Cohen is a local celebrity by being featured recently on CNN, CBS, and The Weather Channel as a health expert. If you are looking for a doctor that listens and cares, then Dr. Cohen is the go-to guy.",
         "original_media": [
           {
              "id": "40d8bec22936e650fc062c363c8c826699d8484c50a68fc1d5532e1242aca717" 
           },
           {
              "id": "a1573cd0284da6b71e7f6e90a48e58717d295f902085b551194f86dd5e7527cc"
           }
          ]
        },
        "advertiser": {
         "name": "Cohen Chiropractic Centre",
         "description": "<p>Chiropractic offers natural relief of chronic pain, headaches, disc disorders and personal injury cases. Chiropractors help newborns, infants, teenagers, adults and seniors. And health-conscious Atlanta families choose Cohen Chiropractic Centre.</p><p>
    Thanks for visiting! Please explore our information-rich website so you fully understand what chiropractic is, what chiropractors do and what you can expect in our office.</p><p>
    When you're ready, call a chiropractor who helps Atlanta residents whether they want relief or wellness. Find out for yourself why so many of your neighbors already have.</p>",
         "categories": [
                {
                    "id": "health-and-wellness/wellness-centers"
                }
            ],
         "redemption_locations": [
                {
                    "address_line_1": "2140 Peachtree Rd NW",
                    "address_line_2": "Suite 203",
                    "city": "Atlanta",
                    "state_code": "GA",
                    "postal_code": "30309",
                    "country_code": "US"
                }
            ],
         "website_url": "http://www.CohenChiropracticCentre.com",
         "public_phone": "(404) 355-5499",
         "payee_name": "Cohen Chiropractic Centre",
         "payee_address":
                {
                    "address_line_1": "2140 Peachtree Rd NW",
                    "address_line_2": "Suite 203",
                    "city": "Atlanta",
                    "state_code": "GA",
                    "postal_code": "30309",
                    "country_code": "US"

                },
         "payee_tax_id": "912-70-1234"
        }
    }
}

XML
<offer>  
    <type>deal</type>
    <title>an Initial Chiropractic Exam, X-Rays, and 10-Minute Mechanical Traction</title>
    <price>
        <currency_code>USD</currency_code>
        <amount>3700</amount>
    </price>
    <value>
<currency_code>USD</currency_code>
     <amount>22500</amount>
    </value>
    <advertiser_rebate>
<currency_code>USD</currency_code>
     <amount>1500</amount>
    </advertiser_rebate>
    <fine_print>Limit 1 per person per visit • Appointments required and subject to availability • Normal merchant cancellation policies apply; voucher subject to forfeiture • Other conditions apply • Promotional value expires on 06/04/11.</fine_print>
    <start_date>2010-07-26</start_date>
    <end_date>2011-07-26</end_date>
    <quantity_in_stock>200</quantity_in_stock>
    <vouchers_expire>
        <on>2011-08-01</on>
    </vouchers_expire>
    <creative>
     <requires_editorial_support>true</requires_editorial_support>
     <headlines>
            <headline>$37 for an Initial Chiropractic Exam, X-Rays, and 10-Minute Mechanical Traction at Cohen Chiropractic Centre (Valued at $225.)</headline>
            <headline>$37 for $225 Worth of Initial Chiropractic Exam, X-Rays, and 10-Minute Mechanical Traction</headline>
     </headlines>
     <description>The only thing worse than back pain is having trouble finding a good chiropractor to straighten you out. With today's deal, consider your search over. Spend $37 for a full chiropractic consultation including range of motion testing, postural assessment, grip strength testing, and a thorough consultation at Cohen Chiropractic Centre, a $225 value. Dr. Cohen is a specialist in chiropractic care with years of experience providing the right touch to realign your out-of-whack back. Dr. Cohen is a local celebrity by being featured recently on CNN, CBS, and The Weather Channel as a health expert. If you are looking for a doctor that listens and cares, then Dr. Cohen is the go-to guy.</description>
     <original_media>
            <attachment>
               <id>40d8bec22936e650fc062c363c...</id>
            </attachment>
            <attachment>
               <id>a1573cd0284da6b71e7f6e90a...</id>
            </attachment>
     </original_media>
    </creative>
    <advertiser>
     <name>Cohen Chiropractic Centre</name>
     <description>&lt;p&gt;Chiropractic offers natural relief of chronic pain, headaches, disc disorders and personal injury cases. Chiropractors help newborns, infants, teenagers, adults and seniors. And health-conscious Atlanta families choose Cohen Chiropractic Centre.&lt;/p&gt;
&lt;p&gt;Thanks for visiting! Please explore our information-rich website so you fully understand what chiropractic is, what chiropractors do and what you can expect in our office.&lt;/p&gt;
&lt;p&gt;When you're ready, call a chiropractor who helps Atlanta residents whether they want relief or wellness. Find out for yourself why so many of your neighbors already have.&lt;/p&gt;</description>
     <categories>
            <category>
                <id>health-and-wellness/wellness-centers</id>
            </category>
     </categories>
     <redemption_locations>
            <redemption_location>
                <address_line_1>2140 Peachtree Rd NW</address_line_1>
                <address_line_2>Suite 203</address_line_2>
                <city>Atlanta</city>
                <state_code>GA</state_code>
                <postal_code>30309</postal_code>
                <country_code>US</country_code>
            </redemption_location>
     </redemption_locations>
     <website_url>http://www.CohenChiropracticCentre.com</website_url>
     <public_phone>(404) 355-5499</public_phone>
        <payee_name>Cohen Chiropractic Centre</payee_name>
        <payee_address>
                <address_line_1>2140 Peachtree Rd NW</address_line_1>
                <address_line_2>Suite 203</address_line_2>
                <city>Atlanta</city>
                <state_code>GA</state_code>
                <postal_code>30309</postal_code>
                <country_code>US</country_code>
        </payee_location>
        <payee_tax_id>912-70-1234</payee_tax_id>
    </advertiser>
</offer>

Response

JSON
HTTP/1.1 200 OK
{
    "status": "OK",
    "offer": {
        ...
        "id": "bf8d739dc08b5d1385280003184db0a63ad48c278303ad108787111366afaf2b",
        "status": "pending",
        "creative": {
            ...
            "status": "approved_by_advertiser"
        }
        "illustrations": [
            {
                ...
                "url": "http://assets.adility.com/images/40d8bec22936e650fc062c363c8c8....jpg",
                "width": "315",
                "height": "286"
            },
            {
                ...
                "url": "http://assets.adility.com/images/a1573cd0284da6b71e7f6e90a48e5....jpg",
                "width": "400",
                "height": "350"
            }
        ]
        advertiser {
            categories [
                {
                    ...
                    "name": "Wellness Centers",
                    "parent_id": "health-and-wellness"
                }                
            ]
        }
    }
}

XML
HTTP/1.1 200 OK    
<?xml version="1.0" encoding="UTF-8"?>
<response>
    <status>OK</status>
    <offer>  
        ...
        <id>bf8d739dc08b5d1385280003184db0a63ad48c278303ad108787111366afaf2b</id>
        <status>pending</status>
        <creative>
            ...
            <status>approved_by_advertiser</status>
            <illustrations>
                <illustration>
                    <url>http://assets.adility.com/images/40d8bec22936....jpg</url>
                    <width>315</width>
                    <height>286</height>
                </illustration>
                <illustration>
                    <url>http://assets.adility.com/images/a1573cd0284d....jpg</url>
                    <width>400</width>
                    <height>350</height>
                </illustration>
         </illustrations>
        </creative>
        <advertiser>
            <categories>
                <category>
                    ...
                    <name>Wellness Centers</name>
                    <parent_id>health-and-wellness</parent_id>
                </category>
         </categories>
        </advertiser>
    </offer>
</response>


Example with Curl:
curl -k -X POST -H "Content-Type: application/json" -H "Accept: application/json" -H "X-ADILITY-API-KEY: <YOUR_API_KEY>" 'http://testapi.adility.com/submission/beta/offers' -d '{"offer": {"type": "deal","title": "Test Order from AY","price":{"currency_code":"USD","amount": 3700},"value": {"currency_code": "USD","amount": 22500}, "advertiser_rebate": {"currency_code": "USD","amount": 1500},"fine_print": "Trololo Fine_print", "start_date": "2011-09-15","end_date": "2013-07-26","quantity_in_stock": 200, "vouchers_expire": {"on": "2014-01-01"},"creative": {"requires_editorial_support": false,"headlines": ["$37 for an Initial Chiropractic Exam, X-Rays, and 10-Minute Mechanical Traction at Cohen Chiropractic Centre (Valued at $225.)","$37 for $225 Worth of Initial Chiropractic Exam, X-Rays, and 10-Minute Mechanical Traction"],"description": "The only thing worse than back pain is having trouble finding a good chiropractor to straighten you out.","original_media": []}, "advertiser": {"name": "Cohen Chiropractic Centre","description": "Chiropractic offers natural relief of chronic pain","categories": [{"id": "2126128138"}],"redemption_locations": [{"address_line_1": "2140 Peachtree Rd NW","address_line_2": "Suite 203", "city": "Atlanta","state_code": "GA","postal_code": "30309","country_code": "US"}],"website_url": "http://www.CohenChiropracticCentre.com","public_phone": "(404) 355-5499"}}}'

Uncapped offers

Uncapped offers are offers with unlimited quantity. If you want to submit uncapped offer, don't pass quantity_in_stock attribute within your request. 

Permanent offers

Permanent offers are offers with unlimited duration. If you want to submit permantnt offer, don't pass end_date attribute within your request.

Editorial support request

if you don't have creative for an offer you can request support from Adility editorial team. You just need to set requires_editorial_support attribute of creative Creative for the offer to true:

{
    "creative": {
        "requires_editorial_support": true
    }
}

This will change the offer approval workflow. Creative of the offer gets status draft and the editorial team begins work right after the offer is accepted by submission manager. As the creative is ready its status changes to on_advertiser_approval and you get notification about it by a webhook. Read more about the workflow for submitters in this guideline.
NOTE: it's not possible to require editorial support for exclusive offers.

Curl example:
curl -k -X POST -H "Content-Type: application/json" -H "Accept: application/json" -H "X-ADILITY-API-KEY: <YOUR_API_KEY>" 'http://testapi.adility.com/submission/beta/offers' -d '{"offer": {"type": "deal","title": "Test Order from AY","price":{"currency_code":"USD","amount": 3700},"value": {"currency_code": "USD","amount": 22500}, "advertiser_rebate": {"currency_code": "USD","amount": 1500},"fine_print": "Trololo Fine_print", "start_date": "2011-09-15","end_date": "2013-07-26","quantity_in_stock": 200, "vouchers_expire": {"on": "2014-01-01"},"creative": {"requires_editorial_support": true,"headlines": ["$37 for an Initial Chiropractic Exam, X-Rays, and 10-Minute Mechanical Traction at Cohen Chiropractic Centre (Valued at $225.)","$37 for $225 Worth of Initial Chiropractic Exam, X-Rays, and 10-Minute Mechanical Traction"],"description": "The only thing worse than back pain is having trouble finding a good chiropractor to straighten you out.","original_media": []}, "advertiser": {"name": "Cohen Chiropractic Centre","description": "Chiropractic offers natural relief of chronic pain","categories": [{"id": "2126128138"}],"redemption_locations": [{"address_line_1": "2140 Peachtree Rd NW","address_line_2": "Suite 203", "city": "Atlanta","state_code": "GA","postal_code": "30309","country_code": "US"}],"website_url": "http://www.CohenChiropracticCentre.com","public_phone": "(404) 355-5499"}}}'

Exclusive offers

You can set an offer exclusive to a specific publisher by adding the exclusivity attribute to the offer:

{
    "exclusivity": {
        "exclusive": true,
        "distributor_id": "0a3f749808c168528ba01a911ea63ee99a1eee3a7a6787dbd2159ebb6f4d372b"
    }
}

Curl example:
curl -X PUT -H "Content-Type: application/json" -H "Accept: application/json" -H "X-ADILITY-API-KEY: <your_api_key>" "http://testapi.adility.com/submission/beta/offers/<offer_id>" -d '
{
    "offer": {
        "exclusivity": {
            "exclusive": true,
            "distributor_id": "<desired_distributor_id>"
        }
    }
}
'

If you want to set offer exclusivity to yourself (being as well the Publisher) you can omit distributor_id. Exclusive offers have status submitted and don't require confirmation from a submission manager. You can share an offer with other distributors by setting exclusivity to false:

{
    "exclusivity": {
        "exclusive": false
    }
}

In this case the offer status changes to pending and the offer is no longer available for distribution until it's accepted and published by a submission manager.
Please remember that you need to change offer status to "withdrawn" to update its exclusivity settings and then set status back to pending.
NOTE: it's not possible to set requires_editorial_support to true  for exclusive offers (see Creative).

Offer Statuses

There are 9 offer statuses available in Submission API:
  1. submitted
  2. pending
  3. accepted
  4. rejected
  5. withdrawn
  6. published
  7. suspended
  8. resumed
  9. cancelled
Statuses submitted and pending are initial statuses for offers. Offer obtains one of these statuses after submission. Statuses accepted and rejected is a result of reviewing the offer by submission manager who decides if the offer is qualified to be published on the distribution network. Status withdrawn is set to the offer if advertiser wants to make some changes to it. Status published is set to the offer when it is well prepared and approved by submission manager and advertiser. Advertiser can suspend an offer and later resume it. Statuses suspended and resumed reflect that. Also, an offer can be cancelled by setting its status to cancelled. Cancelled offers can not be used any more.

Submitted

{
    "status": "submitted"
}

When you submit an exclusive offer it obtains the status submitted. Offers in this status are available for distribution via Distribution API only for the exclusive distributor set by exclusivity attribute of the offer. If you remove exclusivity for the offer its status changes to pending. You may also set the status to pending directly and it will remove exclusivity from the offer.

Pending

{
    "status": "pending"
}

Pending offers are set to be reviewed by the account manager. Account managers review recently submitted non-exclusive offers and approve if the offer is qualified for Adility. Normally it takes 24 hours for account managers to review an offer. If the offer is rejected account manager explains the reason as a comment to the offer.

Accepted

{
    "status": "accepted"
}

If the account manager accepts an offer, the offer changes to the status accepted. Accepted offers that don't require editorial support for their creatives automatically get published with the status published. Accepted offers that require editorial support are placed in the editorial team queue.

Rejected

{
    "status": "rejected"
}

If the account manager reviews a pending offer and finds reasons not to accept it he rejects the offer and provides an explanation as a comment to it. You can apply changes to the rejected offer and resubmit it by setting its status to pending. 

Withdrawn

{
    "status": "withdrawn"
}

If an offer is submitted and its status is pending but the advertiser wants to make changes to it the offer can be withdrawn by setting the status to withdrawn. Withdrawn offers can be updated. 

Published

{
    "status": "published"
}

Offers with the status published are available for distribution through the Distribution API. Only offers with the status accepted can get published. Accepted offers are published automatically if they don't require editorial support. Otherwise they become published after its creative is prepared by the editorial team and the advertiser approves the creative. A suspended offer that is set to the status resumed will immediately be published again.

Suspended

{
    "status": "suspended"
}

Only published offers can be suspended. If for any reason an advertiser wants to suspend a published offer for a while the offer status sets to suspended. Suspended offers are not available for publishers.

Resumed

{
    "status": "resumed"
}

Suspended offer can be resumed by setting its status to resumed. Status resumed automatically changes to the status published. 

Cancelled

{
    "status": "cancelled"
}

Any offer in any other status can be cancelled. If the offer is cancelled it's not available for distribution via Distribution API and it can't be updated any more.

Code sample for changing status
curl -k -X PUT -H "Content-Type: application/json" -H "Accept: application/json" -H "X-ADILITY-API-KEY:<YOUR_API_KEY>" 'http://testapi.adility.com/submission/beta/offers/<OFFER_ID>' -d '{"offer": {"status":"withdrawn"}}' 

Update offer

PUT /offers/<id>

You may want to update an offer after it is submitted but there are certain restrictions on update depending on the offer status. Offers in the status cancelled can not be updated. For exclusive offers in the status submitted you may update any attributes any time. For non-exclusive offers in the status pending, published or suspended you may update only the attributes status and quantity_in_stock. Non-exclusive offers with the statuses rejected and withdrawn allow to update any attribute.

This table shows what can be updated in an offer with a particular status.
 StatusAny Attribute Update Status Update Quantity Update 
 submitted Yes - -
 pending No Yes Yes
 accepted No Yes Yes
 rejected Yes - -
 withdrawn Yes - -
 published No Yes Yes
 suspended No Yes Yes
 resumed No Yes Yes
 cancelled No No No

Updating Attributes

In order to update one or more attributes of an offer you pass only those specific attributes:

{
    "fine_print": "Valid for 1 year.",
    "vouchers_activation_date": "2011-03-01"
}

Example:
curl -k -X PUT -H "Content-Type: application/json" -H "Accept: application/json" -H "X-ADILITY-API-KEY:<YOUR_API_KEY>" 'http://testapi.adility.com/submission/beta/offers/<OFFER_ID>' -d '{"offer": {
    "fine_print": "Valid for 1 year.",
    "vouchers_activation_date": "2011-03-01"
}}' 

Updating Quantity In Stock

{
    "quantity_in_stock": 200
}

Example:
curl -k -X PUT -H "Content-Type: application/json" -H "Accept: application/json" -H "X-ADILITY-API-KEY:<YOUR_API_KEY>" 'http://testapi.adility.com/submission/beta/offers/<OFFER_ID>' -d '{"offer": {
    "quantity_in_stock": 200
}}'


You may update quantity_in_stock attribute for an offer if the offer has any status but cancelled. A new value can not be less than reserved quantity for the offer stored in the reserved_quantity attribute. Using quantity_in_stock update you can increase or decrease a number of vouchers available for the offer.

Updating Status

When you change status for an offer there are some restrictions on it. You can do the following changes:
  • change submitted to pending
  • change pending to withdrawn
  • change accepted to withdrawn
  • change rejected to pending (offer resubmission)
  • change withdrawn to pending (offer resubmission)
  • change published to suspended
  • change suspended to resumed
You can set offer status to cancelled for offers in any status but cancelled. You'll get an error if you try to break these rules. 

Suspend offer

{
    "status": "suspended"
}

Example:
curl -k -X PUT -H "Content-Type: application/json" -H "Accept: application/json" -H "X-ADILITY-API-KEY:<YOUR_API_KEY>" 'http://testapi.adility.com/submission/beta/offers/<OFFER_ID>' -d '{"offer": {"status":"suspended"}}'

You may suspend a published offer. You need to remember that suspended offers become unavailable for distributors in 24 hours after actual suspension. This means vouchers of the offer can be bought or clipped during next 24 hours after you suspend it.

Resume offer

{
    "status": "resumed"
}

Example:
curl -k -X PUT -H "Content-Type: application/json" -H "Accept: application/json" -H "X-ADILITY-API-KEY:<YOUR_API_KEY>" 'http://testapi.adility.com/submission/beta/offers/<OFFER_ID>' -d '{"offer": {"status":"resumed"}}'

Suspended offers can be resumed any time. Resumed offers become published right after set to resumed, without additional approval as they were approved before they got suspended.

Cancel offer

{
    "status": "cancelled"
}

Example:
curl -k -X PUT -H "Content-Type: application/json" -H "Accept: application/json" -H "X-ADILITY-API-KEY:<YOUR_API_KEY>" 'http://testapi.adility.com/submission/beta/offers/<OFFER_ID>' -d '{"offer": {"status":"cancelled"}}'

Any offer can be cancelled at any time. If an offer is published and you cancel it the offer stays available for the distribution network during the next 24 hours (similar to suspension status).

Callback on Offer Change

Offers can be changed in Adility during their shelf life. In order to notify your application we use a webhooks approach. Read about webhooks on http://wiki.webhooks.org/ and http://groups.google.com/group/webhooks or see the video http://www.youtube.com/watch?v=Fw8EPrIjCOc.

Adility lets you know an offer is changed by making requests to a URL specified by you. This request can look like this:

POST http://app.yourdomain.com/adility/callback

The id of the offer that has changed is listed in the offer_id parameter of the request. At this point you should make a call to get the offer details and find out what has actually changed. You can set the callback url in your developer account at http://www.adility.com.

There are 4 triggers that may cause the callback:
  1. Status of the offer has changed
  2. Status of the offer creative has changed
  3. Status of a voucher of the offer has changed
  4. Comment has been added to the offer

Communication between Advertiser and Account Manager

Sometimes there's a need for advertisers and account managers to communicate about an offer. Advertiser might want to ask a question or pass image files to the editorial team so they use these files for the images that are created for the offer. Account managers can reject an offer and need to explain the reason to the advertiser. This communication is implemented with Comment and Attachment resources.

Comments

POST /offers/<offer_id>/comments

Curl example:
curl -X POST -H "X-ADILITY-API-KEY: <YOUR_API_KEY>" -H "Content-Type: application/json" "http://testapi.adility.com/submission/beta/offers/<OFFER_ID>/comments" -d '{"comment":{"author_name":"John Smith","content":"Very nice."}}'

Comment can be added to an offer if the offer has any status but cancelled. When a comment is created on Adility side you will get notified by the callback on offer change (read above) and you need to read the offer details to get the new comment content.

GET /offers/<offer_id>/comments

Curl example:
curl -X GET -H "Content-Type: application/json" -H "Accept: application/json" -H "X-ADILITY-API-KEY: <YOUR_API_KEY>" "http://testapi.adility.com/submission/beta/offers/<OFFER_ID>/comments"

Advertiser also can add attachments to comments. In order to send an attachment you need to pass its id with the comment.

{
    "id": "...",
    "author_name": "John Smith",
    "content": "I am uploading two more images for the coupon. Maybe you guys could use them.",
    "attachments": [
        {"attachment_id": "..."},
        {"attachment_id": "..."}
    ]
}

Attachments

Attachment is used for comments and original media which are presented by the comments attribute of Offer and the original_media attribute of Creative. You create an attachment and then use its id to make it a part of another resource such as Comment. 

Curl examples:
curl -X POST -F attachment[media]=@/path/to/image/file -H "Accept: application/json" -H "X-ADILITY-API-KEY:<YOUR_API_KEY>" "http://testapi.adility.com/submission/beta/attachments"

curl -X POST -H "X-ADILITY-API-KEY: <YOUR_API_KEY>" -H "Content-Type: application/json"
-H "Accept: application/json" "http://testapi.adility.com/submission/beta/offers/<OFFER_ID>/comments" -d '{"comment":{"author_name":"John Smith","content":"Very nice.", "attachments" : [{ "attachment_id" : "YOUR_ATTACHMENT_ID" }]}}'

Removing comments

You can remove your comment. Example:
curl -X DELETE -H "Content-Type: application/json" -H "Accept: application/json" -H "X-ADILITY-API-KEY: <YOUR_API_KEY>" "http://testapi.adility.com/submission/beta/offers/<OFFER_ID>/comments/<COMMENT_ID>"

Offer Acceptance Process

When a non-exclusive offer is submitted to Adility its status is set to pending and it is in the queue for the account manager to review. If the offer is ok in account manager's opinion, he will accept the offer and change the status to accepted. You will get notified by a callback on offer change. Offers that don't require editorial support for their creatives get published automatically after they are accepted.

{
    "creative": {
        "requires_editorial_support": false
    }
}

If account manager rejects an offer he adds a comment with an explanation why the offer is rejected and the offer status is set to rejected. Advertiser can change the offer according to the notes of the account manager and resubmit the offer. To resubmit the offer you need to change its status to pending. 

Editorial Work on Creative

Aside to basic offer attributes such as price, value and fine_print there are additional attributes required in the resource Creative. There are two options on who prepares the creative:
  1. you submit an offer with creative
  2. Adility editorial team helps prepare the creative
You choose an option by setting the requires_editorial_support attribute of Creative.

{
    "creative": {
        "requires_editorial_support": true
    }
}

If you go with the first option and submit an offer with the creative prepared the offer becomes published automatically after submission manager accepts it.

The second option involves Adility editorial team and it takes the offer through a certain approval workflow. This workflow has steps defined by the status attribute of Creative:
  • draft. 
  • on_advertiser_approval.
  • approved_by_advertiser. 

Creative in Draft

{
    "creative": {
        "status": "draft"
    }
}

When an offer is accepted by the account manager and has the requires_editorial_support attribute of Creative set to true the editorial team starts the work. It prepares headlines, description, illustrations, etc. While the editorial team is working on the offer the status of its creative is set to draft.

Creative On Advertiser Approval

{
    "creative": {
        "status": "on_advertiser_approval"
    }
}

When the editorial team has finished the offer's creative the account manager changes the status of creative to on_advertiser_approval and the callback on the offer is send so you get notified about the status change. Your application should pull the offer details and show the offer creative to the advertiser. If the advertiser agrees with the creative he can approve it and your application should change the status to approved_by_advertiser.

{
    "creative": {
        "status": "approved_by_advertiser"
    }
}

If the advertiser requests changes to the creative your application can change the status back to draft. This is important to accompany the change with a comment so the editorial team understands what to do.

Creative Approved By Advertiser

{
    "creative": {
        "status": "approved_by_advertiser"
    }
}

If an offer creative doesn't require editorial support the status is set to approved_by_advertiser automatically on submission. Otherwise it is set by your application after advertiser approves the creative.

Getting Distribution Reports

An Offer has a certain number of vouchers defined by the quantity_in_stock attribute.  

{
    "quantity_in_stock": 278
}

Vouchers are represented by Voucher resource. 

After an offer is published distributors promote it to consumers and consumers acquire these vouchers by purchasing deals, gift cards or clipping coupons. To get a general distribution report or a report by your offer and find out how many and which vouchers have been acquired or cancelled follow these instructions.

You can use the following filtering parameters in the reports:
  • recently_acquired. Vouchers acquired no more than a number of days ago defined by this parameter.
  • recently_cancelled. Vouchers cancelled no more than a number of days ago defined by this parameter.
  • recently_updated. Vouchers either acquired or cancelled no more than a number of days ago defined by this parameter.
NOTE: a number of days in the parameters above can't be greater than 31. Recommended value is 7 days (a week).

GET /vouchers?recently_updated=3

curl -k -X GET -H "Content-Type: application/json" -H "Accept: application/json" -H "X-ADILITY-API-KEY:YOUR_API_KEY" 'http://testapi.adility.com/submission/beta/vouchers?recently_acquired=<number_of_days>'

curl -k -X GET -H "Content-Type: application/json" -H "Accept: application/json" -H "X-ADILITY-API-KEY:YOUR_API_KEY" 'http://testapi.adility.com/submission/beta/vouchers?recently_updated=<number_of_days>'

curl -k -X GET -H "Content-Type: application/json" -H "Accept: application/json" -H "X-ADILITY-API-KEY:YOUR_API_KEY" 'http://testapi.adility.com/submission/beta/vouchers?recently_cancelled=<number_of_days>'

You can use only one of these three parameters in a single query.

Report By Offer

GET /offers/<id>/vouchers

You get all vouchers of the offer with their attributes including status. Filtering parameters recently_acquired, recently_cancelled and recently_updated are applicable.

Curl example
curl -k -X GET -H "Content-Type: application/json" -H "Accept: application/json" -H "X-ADILITY-API-KEY:YOUR_API_KEY" 'http://testapi.adility.com/submission/beta/offers/<OFFER_ID>/vouchers>'

General Report

GET /vouchers?filtering_parameter

You get all vouchers across all offers with their attributes including status. The query must contain one of the filtering parameters recently_acquired, recently_cancelled or recently_updated.

curl -k -X GET -H "Content-Type: application/json" -H "Accept: application/json" -H "X-ADILITY-API-KEY:YOUR_API_KEY" 'http://testapi.adility.com/submission/beta/vouchers?recently_acquired=<number_of_days>'

curl -k -X GET -H "Content-Type: application/json" -H "Accept: application/json" -H "X-ADILITY-API-KEY:YOUR_API_KEY" 'http://testapi.adility.com/submission/beta/vouchers?recently_updated=<number_of_days>'

curl -k -X GET -H "Content-Type: application/json" -H "Accept: application/json" -H "X-ADILITY-API-KEY:YOUR_API_KEY" 'http://testapi.adility.com/submission/beta/vouchers?recently_cancelled=<number_of_days>'

Redeem Voucher

PUT /offers/<offer_id>/vouchers/<voucher_id>

You can allow advertisers to redeem vouchers from your application. Redemption is implemented by setting the status of Voucher to redeemed.

{
 "voucher":
    {"status": "redeemed"}
}

Curl example:
curl -k -X PUT -H "Content-Type: application/json" -H "Accept: application/json" -H "X-ADILITY-API-KEY:SUBMISSION_API_KEY" 'http://testapi.adility.com/submission/beta/offers/<offer_id>/vouchers/<voucher_id>' -d '{"voucher": {"status": "redeemed"}}'

Voucher can be marked as redeemed only if it was acquired which means its status is set to acquired.

Next Step: Distribution API.


Comments