API Documentation

zferral API


Introduction

Authentication of affiliates

API Objects

Marketing Object

Methods:

Examples:


All of the commission 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 INT (Read Only) The unique identifier for this marketing object
  • type VARCHAR(25) (Required) Marketing object type (banner,text_ad,text_link,social_ad)
  • title VARCHAR(45) (Required if text_ad) Text ad title
  • name VARCHAR(100) (Required) Marketing object name
  • body VARCHAR(100) (Required if text ad or social ad) Marketing object description
  • destination_url TEXT (Required) Marketing object destination url
  • affiliate_id INT (Optional) Affiliate id (needed to get banner, ad code or text link)
  • banner_size VARCHAR(20) (Required if banner) Size of banner
  • campaign_id INT (Required) Campaign id
  • preview TEXT (Read Only) Object preview code
  • banner TEXT (Required if banner) Banner file url
  • created_at TIMESTAMP (Read Only) The creation date for this marketing object


Methods

create - creates new marketing object

URL: "https://<subdomain/>.zferral.com/api/<api_key>/marketing.<format>"
Method: POST
Format: xml or json
Required Parameters: XML or JSON data, as specified by the required attributes
Response: The created marketing object id
XML and JSON example


update - edits or updates data of marketing object

URL: "https://<subdomain>.zferral.com/api/<api_key>/marketing/<id>.<format>"
Method: PUT
Format: xml or json
Required Parameters: id and XML or JSON data, as specified by the required attributes
Response: The updated marketing id
XML and JSON example


delete - delete marketing object

URL: "https://<subdomain>.zferral.com/api/<api_key>/marketing/<id>.<format>"
Method: DELETE
Format: xml or json
Required Parameters: id
Response: The deleted marketing object id
XML and JSON example


get – retrieve marketing object data

URL: "https://<subdomain>.zferral.com/api/<api_key>/marketing/<id>.<format>"
Method: GET
Format: xml or json
Required Parameters: id
Optional Parameters: affiliate_id - to get banner, ad code or text link
Response: A single Marketing object
XML and JSON example


list – retrieve list of marketing objects

URL: "https://<subdomain>.zferral.com/api/<api_key>/marketings.<format>"
Method: GET
Format: xml or json
Optional Parameters: page, limit, affiliate_id - to get banner, ad code or text link
Response: An array of Marketing objects, up to 50 per page
XML and JSON example

create - Usage Example

Scenarios [examples]:

Requirements:

  • Give correct <api_key>
  • Returned data format <format>


  1. Scenario: Create marketing object


    Request

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

    a) XML 

          <?xml version="1.0" encoding="UTF-8" ?>
      <marketing>
        <type>social_ad</type>
        <campaign_id>1</campaign_id>
        <name>Tweet</name>
        <body>Check out this great new way to crowdsource your sales and marketing .:i zferral.com</body>
        <destination_url>http://zferral.com</destination_url>
      </marketing>

    b) JSON 

            {
          "marketing" : {
            "type"            : "social_ad"
            "campaign_id"     : "1",
            "name"            : "tweet"
            "destination_url" : "http://zferral.com"
            "body"            : "Check out this great new way to crowdsource your sales and marketing .:i zferral.com"
        }}


    Response (return status code "201 Created"):

    a) XML 

            <?xml version="1.0" encoding="UTF-8"?>
        <marketing>
          <id>1</id>
        </marketing>

    b) JSON 

            {
         "marketing" : {
            "id" : "1",
        }}

  2. Scenario: Create a marketing object (sending not all required parameters)


    Request

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

    a) XML 

            <?xml version="1.0" encoding="UTF-8"?>
        <marketing>
          <campaing_id>1</campaing_id>
        </marketing>

    b) JSON 

            {
         "marketing" : {
            "campaing_id"  : 1,
        }}


    Response (return status code "422 Unprocessable Entity"):

    a) XML 

            <?xml version="1.0" encoding="UTF-8"?>
        <errors>
            <type>Required.</type>
            <name>Required.</name>
            <body>Required.</body>
            <destination_url>Required.</destination_url>
        </errors>

    b) JSON 

            {
         "errors": {
            "type":"Required.",
            "name":"Required.",
            "body":"Required.",
            "destination_url":"Required."
        }}


update - Usage Example

Scenarios [examples]:

Requirements:

  • Give correct <api_key>
  • Returned data format <format>
  • Give <id>


  1. Scenario: Edit marketing object data

    Request

    a) XML 

          <?xml version="1.0" encoding="UTF-8" ?>
      <marketing>
        <campaign_id>1</campaign_id>
        <name>Tweet</name>
        <body>Check out this great new way to crowdsource your sales and marketing .:i zferral.com</body>
        <destination_url>http://zferral.com</destination_url>
      </marketing>

    b) JSON 

            {
          "marketing" : {
            "campaign_id"     : "1",
            "name"            : "tweet"
            "destination_url" : "http://zferral.com"
            "body"            : "Check out this great new way to crowdsource your sales and marketing .:i zferral.com"
        }}


    Response (return status code "200 OK"):

    a) XML 

            <?xml version="1.0" encoding="UTF-8"?>
        <commission>
          <id>1</id>
        </commission>

    b) JSON 

            {
         "commission" : {
            "id" : "1",
        }}


delete – Usage Example

Scenarios [examples]:

Requirements:

  • Give correct <api_key>
  • Returned data format <format>
  • Give <id>


  1. Scenario: Delete marketing object data


    Request

    URL: "https://subdomain.zferral.com/api/<api_key>/marketing/1.<format>"


    Response (return status code "200 OK"):

    a) XML 

            <?xml version="1.0" encoding="UTF-8"?>
        <marketing>
            <id>1</id>
        </marketing>

    b) JSON 

            {
          "marketing": {
            "id" : 1,
        }}


get – Usage Example

Scenarios [examples]:

Requirements:

  • Give correct <api_key>
  • Returned data format <format>
  • Give <id>


  1. Scenario: Retrieve marketing object data


    Request

    URL: "https://subdomain.zferral.com/api/<api_key>/marketing/1.<format>"


    Response (return status code "200 OK"):

    a) XML 

            <?xml version="1.0" encoding="UTF-8"?>
        <marketing>
            <id>1</id>
            <campaign_id>1</campaign_id>
            <name>Tweet</name>
            <type>social_ad</type>
            <body>Check out this great new way to crowdsource your sales and marketing .:i zferral.com</body>
            <destination_url>http://zferral.com</destination_url>
            <created_at>2010-06-09 00:36:02</created_at>
        </marketing>

    b) JSON 

            {
          "marketing": {
            "id"              : 1,
            "campaign_id"     : 1,
            "name"            : "Tweet",
            "type"            : "social_ad",
            "body"            : "Check out this great new way to crowdsource your sales and marketing .:i zferral.com",
            "destination_url" : "http://zferral.com",
            "created_at"      : "2010-03-25 09:22:14"
        }}


list – Usage Example

Scenarios [examples]:

Requirements:

  • Give correct <api_key>
  • Returned data format <format>


  1. Scenario: Retrieve list of marketing objects


    Request

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


    Response (return status code "200 OK"):

    a) XML 

            <?xml version="1.0" encoding="UTF-8"?>
        <marketings type="array">
            <marketing>
                <id>1</id>
                <campaign_id>1</campaign_id>
                <name>Tweet</name>
                <type>social_ad</type>
                <body>Check out this great new way to crowdsource your sales and marketing .:i zferral.com</body>
                <destination_url>http://zferral.com</destination_url>
                <created_at>2010-06-09 00:36:02</created_at>
            </marketing>
            <marketing>
                <id>2</id>
                <campaign_id>1</campaign_id>
                <name>Build Your Sales Network</name>
                <type>text_ad</type>
                <title>Build Your Sales Network</title>
                <body>Loyalty and customer acquisition platform for your business</body>
                <destination_url>http://zferral.com</destination_url>
                <created_at>2010-06-09 17:34:00</created_at>
            </marketing>
        </marketings>

    b) JSON 

            {
         "marketings" : {
            "marketing" : {
              (...)
            },
            "marketing" : {
              (...)
            },
            "marketing" : {
              (...)
            }
        }}