API Documentation

zferral API

Introduction

Campaign

All of the campaign attribute fields are returned from GET (read) operations. Only those attributes not marked as read only may be set via POST (create) operations. Only those attributes marked as edit may be set via PUT (update) operations.

Parameters:

id (Read Only) The unique identifier for this campaign
commission_type_id (Required) Commission type id
campaign_status_id (Required) Campaign status id
event_id (Required) Event id
reward_points_type_id (Optional)(Edit) Reward points type id (Required if is_monetary is set on false)
is_monetary (Required) Whether is monetary or not
name (Required)(Edit) Campaign name
date_start (Required)(Edit) Campaign start date
date_end (Required)(Edit) Campaign end date
has_tiered_commission (Optional)(Edit) Whether campaign has tiered commissions or not
has_stepped_commission (Optional)(Edit) Whether campaign has_stepped_commission or not
initial_commission (Required)(Edit) Initial commission (1st tier initial commission)
recurring_commission (Optional)(Edit) Recurring commission (1st tier recurring commission)
has_recurring_limited_by_renewals (Optional)(Edit) If recurrings are to be limited by renewals
renewals_number (Optional)(Edit) Number of renewals (Required if has_recurring_limited_by_renewals is set on true)
has_recurring_limited_by_period (Optional)(Edit) If recurring commissions are to be limited by period of time
recurring_period_in_days (Optional)(Edit) Number of days that recurring commissions are limited to (Required if has_recurring_limited_by_period is set on true)
has_auto_approval_commission (Optional)(Edit) If commissions created from this campaign are to be automatically approved
commission_approved_callback_url (Optional)(Edit) Callback url after commission is approved
description (Optional)(Edit) Description of campaign
created_at (Read Only) The creation date for this campaign

While creating if has_tiered_commission is set on true then it is required to give tiers parameters:

For each tier: <campaign_tier></campaign_tier>

level (Required) Level of tier
initial_commission (Required) Commission amount for tier

If has_stepped_commission is set on true additional parameter is required for each tier:

reccuring_commission (Required) Recurring commission amount for tier

Methods

get – retrieve campaign data

URL: "https://<subdomain>.zferral.com/api/<api_key>/campaign/<id>.<format>"
Method: GET
Format: xml or json
Required Parameters: id
Optional Parameters: affiliate_id or remote_id - to get text_link for campaign
Response: A single Campaign
XML and JSON example

list – retrieve list of campaigns

URL: "https://<subdomain>.zferral.com/api/<api_key>/campaigns.<format>"
Method: GET
Format: xml or json
Optional Parameters: page, limit, affiliate_id or remote_id - to get text_link for campaign
Response: An array of Campaigns, up to 50 per page
XML and JSON example

get – Usage Example

Scenarios [examples]:

Requirements:

Correct <api_key>
Returned data format <format>
Correct <id>

Scenario: Retrieve campaign data

Request

URL: "https://subdomain.zferral.com/api/<api_key>/campaign/12.<format>"

Response (return status code "200 OK"):

a) XML

        <?xml version="1.0" encoding="UTF-8"?>
        <campaign>
            <id>12</id>
            <commission_type_id>2</commission_type_id>
            <campaign_status_id>2</campaign_status_id>
            <event_id>3</event_id>
            <name>Campaign no. 7</name>
            <date_start>2009-04-01</date_start>
            <date_end>2009-10-01</date_end>
            <has_auto_approval_commission>1</has_auto_approval_commission>
            <initial_commission>7.00</initial_commission>
            <commission_approved_callback_url></commission_approved_callback_url>
            Description
            <created_at>2010-03-24 11:34:16</created_at>
            <has_tiered_commission>1</has_tiered_commission>
            <campaign_tiers>
                <campaign_tier_1>
                    <level>1</level>
                    <initial_commission>7.00</initial_commission>
                </campaign_tier_1>
                <campaign_tier_2>
                    <level>2</level>
                    <initial_commission>4.00</initial_commission>
                </campaign_tier_2>
                <campaign_tier_3>
                    <level>3</level>
                    <initial_commission>2.00</initial_commission>
                </campaign_tier_3>
            </campaign_tiers>
        </campaign>

b) JSON

        {
          "campaign": {
            "id"                                : 12,
            "commission_type_id"                : 2,
            "campaign_status_id"                : 2,
            "name"                              : "Campaign no. 7",
            "date_start"                        : "2009-04-01",
            "date_end"                          : "2009-10-01",
            "has_auto_approval_commission"      : true,
            "initial_commission"                : 7.00,
            "commission_approved_callback_url"  : null,
            "description"                       : null,
            "created_at"                        : "2010-03-24 11:34:16",
            "has_tiered_commission"             : 1,
            "campaign_tiers": {
              "campaign_tier_1": {
                "level"               : 1,
                "initial_commission"  : "7.00"
              },
              "campaign_tier_2": {
                "level"               : 2,
                "initial_commission"  : "4.00"
              },
              "campaign_tier_3": {
                "level"               : 3,
                "initial_commission"  : "2.00"
              }
            }
        }}

list – Usage Example