API Documentation

zferral API

Introduction

Affiliate

Methods:

create
update
delete
get
list

Examples:

create
update
delete
get
list

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

Parameters:

id (Read Only) The unique identifier for this affiliate
password (Optional) Password - is randomly generated by default
email (Required) Email address
is_blocked (Optional) Whether affiliate is blocked
is_active (Optional) Whether affiliate account is activated (default: 'true')
timezone (Optional) Timezone
first_name (Optional) Name
last_name (Optional) Last name
send_user_email (Optional - get only) Whether to send login details to affiliate email + url to affiliate panel (default: false). Parameter used only with creating Affiliate. Allow true values: 'true', 't', 'yes', 'y', 'on', '1'
registration_link (Optional) Registration link
registered_at (Optional) Registration date
mobile (Optional) Mobile
fax (Optional) Fax
tax_id (Optional) Tax Id
misc (Optional) Additional information
remote_id (Optional) The unique identifier used within your own application for this affiliate
parent_affiliate_id (Optional) Id of affiliate that referred this affiliate
created_at (Read Only) The creation date for this affiliate
updated_at (Read Only) The date of last update for this affiliate
paypal_email (Optional) PayPal email
get_tiers (Only Get action) Whether to retrieve all tiers of this affiliate. Allow true values: 'true', 't', 'yes', 'y', 'on', '1'

Referrals parameters (tiers)

<tier1><id> (Optional) referral Id
<tier2><id> (Optional) referral Id
... etc.

Home/Company address

p_street1 (Optional) Street 1
p_street2 (Optional) Street 2
p_city (Optional) City
p_state (Optional) State
p_country (Optional) Country
p_code (Optional) Postcode

Additional address

s_street1 (Optional) Street 1
s_street2 (Optional) Street 2
s_city (Optional) City
s_state (Optional) State
s_country (Optional) Country
s_code (Optional) Postcode

Methods

create - creates a new Affiliate

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

update - updates Affiliate data

URL: "https://<subdomain>.zferral.com/api/<api_key>/affiliate/<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 Affiliate
XML and JSON example

delete – removes Affiliate

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

get – retrieves Affiliate data

URL: "https://<subdomain>.zferral.com/api/<api_key>/affiliate/<id>.<format>"
Method: GET
Format: xml or json
Optional Parameters: get_tiers
Required Parameters: id
Response: A single Affiliate
XML and JSON example

list – retrieves list of Affiliates

URL: "https://<subdomain>.zferral.com/api/<api_key>/affiliates.<format>"
Method: GET
Format: xml or json
Optional Parameters: is_active, get_tiers, page, limit
Response: An array of Affiliates, default up to 50 per page
XML and JSON example

create - Usage Example

Scenarios [examples]:

Requirements:

Correct <api_key>
Returned data format <format>

Scenario: Create Affiliate (send all the required parameters + optional parameter send_user_email)

Request

a) XML

        <?xml version="1.0" encoding="UTF-8"?>
        <affiliate>
          <email>john@example.com</email>
          <send_user_email>1</send_user_email>
        </affiliate>

b) JSON

        {
         "affiliate" : {
            "email"           : "john@example.com",
            "send_user_email" : "1"
        }}

Response (return status code "201 Created"):

a) XML

        <?xml version="1.0" encoding="UTF-8"?>
        <affiliate>
          <id>134</id>
        </affiliate>

b) JSON

        {
         "affiliate" : {
            "id" : "134",
        }}

Scenario: Create Affiliate (not send all the required parameters)

Request

a) XML

        <?xml version="1.0" encoding="UTF-8"?>
        <affiliate>
          <first_name>John</first_name>
          <last_name>Clarck</last_name>
        </affiliate>

b) JSON

        {
         "affiliate" : {
            "first_name" : "John",
            "last_name"  : "Clarck",
        }}

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

a) XML

        <?xml version="1.0" encoding="UTF-8"?>
        <errors>
          <email>Required.</email>
        </errors>

b) JSON

        {
         "errors" : {
            "email" : "Required."
        }}

Scenario: Create Affiliate (send invalid parameters: 'param1', 'param2')

Request

a) XML

        <?xml version="1.0" encoding="UTF-8"?>
        <affiliate>
          <first_name>John</first_name>
          <last_name>Clarck</last_name>
          <email>john@example.com</email>
          <param1>paramValue</param1>
          <param2>890</param2>
        </affiliate>

b) JSON

        {
         "affiliate" : {
            "first_name" : "John",
            "last_name"  : "Clarck",
            "email"      : "john@example.com",
            "param1"     : "paramValue",
            "param2"     : "param2"
        }}

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

a) XML

        <?xml version="1.0" encoding="UTF-8"?>
        <errors>
          <error>Unexpected extra form field named "param1".</error>
          <error>Unexpected extra form field named "param2".</error>
        </errors>

b) JSON

        {
          "errors": [
            "Unexpected extra form field named \"param1\".",
            "Unexpected extra form field named \"param2\"."
        ]}

Scenario: Affiliate create another method than POST (method: UPDATE)

Request (method: UPDATE) a) XML

        <?xml version="1.0" encoding="UTF-8"?>
        <affiliate>
          <first_name>John</first_name>
          <last_name>Clarck</last_name>
          <email>john@example.com</email>
          <param1>paramValue</param1>
          <param2>890</param2>
        </affiliate>

b) JSON

        {
         "affiliate" : {
            "first_name" : "John",
            "last_name"  : "Clarck",
            "email"      : "john@example.com",
            "param1"     : "paramValue",
            "param2"     : "param2"
        }}

Response (return status code "404 Not Found"):

a) XML

        <?xml version="1.0" encoding="UTF-8" ?>
        <error code="404" message="Not Found">

b) JSON

        {
          "error": {
            "code"    : "404",
            "message" : "Not Found"
        }}

update - Usage Example

Scenarios [examples]:

Requirements:

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

Scenario: Updates Affiliate data (sending correct parameters: first_name, email)

Request

a) XML

        <?xml version="1.0" encoding="UTF-8"?>
        <affiliate>
          <first_name>Tomy</first_name>
          <email>tomy@example.com</email>
        </affiliate>

b) JSON

        {
         "affiliate" : {
            "first_name" : "Tomy",
            "email"      : "tomy@example.com"
        }}

Response (return status code "200 OK"):

a) XML

        <?xml version="1.0" encoding="UTF-8"?>
        <affiliate>
          <id>134</id>
        </affiliate>

b) JSON

        {
         "affiliate" : {
            "id" : "134",
        }}

Scenario: Updates Affiliate data (sending correct parameters: first_name, email) + Correct listy tiers

Request

a) XML

        <?xml version="1.0" encoding="UTF-8"?>
        <affiliate>
          <first_name>Tomy</first_name>
          <email>tomy@example.com</email>
          <tier1>
            <id>45</id>
          </tier1>
          <tier2>
            <id>68</id>
          </tier2>
          <tier3>
            <id>94</id>
          </tier3>
        </affiliate>

b) JSON

        {
         "affiliate" : {
            "first_name" : "Tomy",
            "email"      : "tomy@example.com",
            "tier1" : {
              id" : "45"
            },
            "tier2" : {
              id" : "68"
            },
            "tier3" : {
              id" : "94"
            }
        }}

Response (return status code "200 OK"):

a) XML

        <?xml version="1.0" encoding="UTF-8"?>
        <affiliate>
          <id>134</id>
        </affiliate>

b) JSON

        {
         "affiliate" : {
            "id" : "134",
        }}

Scenario: Updates Affiliate data (sending incorrect parameters: email, tier1)

Request

a) XML

        <?xml version="1.0" encoding="UTF-8"?>
        <affiliate>
          <first_name>Tomy</first_name>
          <email>tomy@example.com</email>
          <tier1>
            <id1>3</id1>
          </tier1>
        </affiliate>

b) JSON

        {
         "affiliate" : {
            "email" : "tomy@example.com",
            "tier1" : {
              "id" : "mickey"
            }
        }}

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

a) XML

        <?xml version="1.0" encoding="UTF-8"?>
        <errors>
          <email>The email address is not valid.</email>
          <tier1>Invalid.</tier1>
        </errors>

b) JSON

        {
          "errors" : {
            "email" : "The email address is not valid.",
            "tier1" : "Invalid."
          }
        }

Scenario: Updates Affiliate data (Give id of non-existing affiliate: id)

Response (return status code "404 Not Found"):

delete – Usage Example

Scenarios [examples]:

Requirements:

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

Scenario: Delete affiliate

Request

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

Response (return status code "200 OK"):

a) XML

        <?xml version="1.0" encoding="UTF-8"?>
        <affiliate>
          <id>134</id>
        </affiliate>

b) JSON

        {
         "affiliate" : {
            "id" : "134",
        }}

Scenario: Delete affiliate that belong to other company

Request

URL: "https://other-subdomain.zferral.com/api/<api_key>/affiliate/10.<format>"

Response (return status code "403 Forbidden"):

a) XML

        <?xml version="1.0" encoding="UTF-8"?>
        <errors>
          <error>Removing forbidden.</error>
        </errors>

b) JSON

        {
         "errors" : [
            "Removing forbidden",
        ]}

get – Usage Example

Scenarios [examples]:

Requirements:

Correct <api_key>
Returned data format <format>

Correct <id>

Scenario: Retrieves Affiliate data

Request

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

Response (return status code "200 OK"):

a) XML

        <?xml version="1.0" encoding="UTF-8"?>
        <affiliate>
          <id>10</id>
          <is_active>1</is_active>
          <email>tony.simpson@example.com</email>
          <first_name>Tony</first_name>
          <last_name>Simpson</last_name>
          <registration_link>tonytony</registration_link>
          <registered_at>2010-03-01 00:00:00</registered_at>
          <mobile>111-222-3334</mobile>
          <fax>987-765-4321</fax>
          <misc>note...</misc>
          <remote_id>
          <parent_affiliate_id>
          <created_at>2010-01-01 00:00:00</created_at>
          <updated_at>2010-02-13 14:34:11</updated_at>
          <p_street1>Zephyrhills</p_street1>
          <p_street2>
          <p_city>New York</p_city>
          <p_state>New York</p_state>
          <p_country>USA</p_country>
          <p_code>10002</p_code>
          <s_street1>
          <s_street2>
          <s_city>
          <s_state>
          <s_country>
          <s_code>
        </affiliate>

b) JSON

        {
         "affiliate" : {
            "id"                  : "10",
            "is_active"           : "1"
            "email"               : "tony.simpson@example.com",
            "first_name"          : "Tony",
            "last_name"           : "Simpson",
            "registration_link"   : "tonytony",
            "registered_at"       : "2010-03-01 00:00:00"
            "mobile"              : "111-222-3334",
            "fax"                 : "987-765-4321",
            "misc"               : "note...",
            "remote_id"           : "",
            "parent_affiliate_id" : "",
            "created_at"          : "2010-01-01 00:00:00",
            "updated_at"          : "2010-02-13 14:34:11"
            "p_street1"           : "Zephyrhills",
            "p_street2"           : "",
            "p_city"              : "New York",
            "p_state"             : "New York",
            "p_country"           : "USA",
            "p_code"              : "10002",
            "s_street1"           : "",
            "s_street2"           : "",
            "s_city"              : "",
            "s_state"             : "",
            "s_country"           : "",
            "s_code"              : "",
        }}

Scenario: Retrieves Affiliate data with optional filter parameter get_tiers

Request

URL: "https://subdomain.zferral.com/api/<api_key>/affiliate/10.<format>?get_tiers=true"

Response (return status code "200 OK"):

a) XML

        <?xml version="1.0" encoding="UTF-8"?>
        <affiliate>
          <id>10</id>
          <is_active>1</is_active>
          <email>tony.simpson@example.com</email>
          <first_name>Tony</first_name>
          <last_name>Simpson</last_name>
          <registration_link>tonytony</registration_link>
          <registered_at>2010-03-01 00:00:00</registered_at>
          <mobile>111-222-3334</mobile>
          <fax>987-765-4321</fax>
          <misc>note...</misc>
          <remote_id>
          <parent_affiliate_id>
          <tiers>
            <tier1>
              <id>105</id>
            </tier1>
            <tier2>
              <id>106</id>
            </tier2>
            <tier3>
              <id>154</id>
            </tier3>
          </tiers>
          <created_at>2010-01-01 00:00:00</created_at>
          <updated_at>2010-02-13 14:34:11</updated_at>
          <p_street1>Zephyrhills</p_street1>
          <p_street2>
          <p_city>New York</p_city>
          <p_state>New York</p_state>
          <p_country>USA</p_country>
          <p_code>10002</p_code>
          <s_street1>
          <s_street2>
          <s_city>
          <s_state>
          <s_country>
          <s_code>
        </affiliate>

b) JSON

        {
         "affiliate" : {
            "id"                  : "10",
            "is_active"           : "1"
            "email"               : "tony.simpson@example.com",
            "first_name"          : "Tony",
            "last_name"           : "Simpson",
            "registration_link"   : "tonytony",
            "registered_at"       : "2010-03-01 00:00:00"
            "mobile"              : "111-222-3334",
            "fax"                 : "987-765-4321",
            "misc"               : "note...",
            "remote_id"           : "",
            "parent_affiliate_id" : "",
            "tries"             : {
              "tier1" : {
                id" : "105"
              },
              "tier2" : {
                id" : "106"
              },
              "tier3" : {
                id" : "154"
              }
            },
            "created_at"          : "2010-01-01 00:00:00",
            "updated_at"          : "2010-02-13 14:34:11"
            "p_street1"           : "Zephyrhills",
            "p_street2"           : "",
            "p_city"              : "New York",
            "p_state"             : "New York",
            "p_country"           : "USA",
            "p_code"              : "10002",
            "s_street1"           : "",
            "s_street2"           : "",
            "s_city"              : "",
            "s_state"             : "",
            "s_country"           : "",
            "s_code"              : "",
        }}

Scenario: Retrieves Affiliate data (Give id of non-existing affiliate: id)

Request

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

Response (return status code "404 Not Found"):

list – Usage Example

Scenarios [examples]:

Requirements:

Correct <api_key>
Returned data format <format>

Scenario: Retrieves list of Affiliates

Request

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

Response (return status code "200 OK"):

a) XML

        <?xml version="1.0" encoding="UTF-8"?>
        <affiliates type="array">
          <affiliate>
            <id>1</id>
            <is_active>1</is_active>
            <password>
            <email>tony.simpson@example.com</email>
            <first_name>Tony</first_name>
            <last_name>Simpson</last_name>
            <registration_link>
            <registered_at>2010-03-01 00:00:00</registered_at>
            <mobile>111-222-3334</mobile>
            <fax>987-765-4321</fax>
            <misc>note...</misc>
            <remote_id>
            <parent_affiliate_id>
            <created_at>2010-03-01 15:45:59</created_at>
            <updated_at>2010-03-01 15:45:59</updated_at>
            <p_street1>Zephyrhills</p_street1>
            <p_street2>
            <p_city>New York</p_city>
            <p_state>New York</p_state>
            <p_country>USA</p_country>
            <p_code>10002</p_code>
            <s_street1>
            <s_street2>
            <s_city>
            <s_state>
            <s_country>
            <s_code>
          </affiliate>
          <affiliate>
            <id>2</id>
            <is_active>1</is_active>
            <password>
            <email>john.crow@example.com</email>
            <first_name>John</first_name>
            <last_name>Crow</last_name>
            <registration_link>
            <registered_at>2010-03-05 00:00:00</registered_at>
            <mobile>111-222-3334</mobile>
            <fax>987-765-4321</fax>
            <misc>note...</misc>
            <remote_id>
            <parent_affiliate_id>1</parent_affiliate_id>
            <created_at>2010-03-01 15:45:59</created_at>
            <updated_at>2010-03-01 15:45:59</updated_at>
            <p_street1>Wall street</p_street1>
            <p_street2>
            <p_city>New York</p_city>
            <p_state>New York</p_state>
            <p_country>USA</p_country>
            <p_code>10002</p_code>
            <s_street1>
            <s_street2>
            <s_city>
            <s_state>
            <s_country>
            <s_code>
          </affiliate>
          <affiliate>
            <id>3</id>
            <is_active>1</is_active>
            <password>
            <email>jack.sparr@example.com</email>
            <first_name>Jack</first_name>
            <last_name>Sparr</last_name>
            <registration_link>
            <registered_at>2010-03-14 00:00:00</registered_at>
            <mobile>111-222-3334</mobile>
            <fax>987-765-4321</fax>
            <misc>note...</misc>
            <remote_id>
            <parent_affiliate_id>1</parent_affiliate_id>
            <created_at>2010-03-01 15:45:59</created_at>
            <updated_at>2010-03-01 15:45:59</updated_at>
            <p_street1>13 Wall Street</p_street1>
            <p_street2>
            <p_city>New York</p_city>
            <p_state>New York</p_state>
            <p_country>USA</p_country>
            <p_code>10002</p_code>
            <s_street1>
            <s_street2>
            <s_city>
            <s_state>
            <s_country>
            <s_code>
          </affiliate>
        </affiliates>

b) JSON

        {
         "affiliates" : {
            "affiliate" : {
              (...)
            },
            "affiliate" : {
              (...)
            },
            "affiliate" : {
              (...)
            }
        }}

Scenario: Retrieves 3 pages (page) from list of active affiliates (is_active) with limit of 2 records (limit) + retrieves Tiers (get_tiers)

Request

URL: "https://<subdomain>.zferral.com/api/<api_key>/affiliates.<format>?page=3&is_active=true&limit=2&get_tiers=true"

Response (return status code "200 OK"):

a) XML

        <?xml version="1.0" encoding="UTF-8"?>
        <affiliates type="array">
          <affiliate>
            <id>9</id>
            <password>123123123123</password>
            <email>albert.aliston@example.com</email>
            <first_name>Tony</first_name>
            <last_name>Aliston</last_name>
            <registration_link></registration_link>
            <registered_at>2010-03-01 00:00:00</registered_at>
            <mobile>111-222-3334</mobile>
            <fax>987-765-4321</fax>
            <misc>note...</misc>
            <remote_id>
            <parent_affiliate_id></parent_affiliate_id>
            <tiers>
              <tier_1>
                <id>134</id>
              </tier_1>
            </tiers>
            <created_at>2010-03-24 16:17:42</created_at>
            <updated_at>2010-03-24 16:17:42</updated_at>
            <p_street1>Zephyrhills</p_street1>
            <p_street2></p_street2>
            <p_city>New York</p_city>
            <p_state>New York</p_state>
            <p_country>USA</p_country>
            <p_code>10002</p_code>
            <s_street1></s_street1>
            <s_street2></s_street2>
            <s_city></s_city>
            <s_state></s_state>
            <s_country></s_country>
            <s_code></s_code>
          </affiliate>
          <affiliate>
            <id>14</id>
            <password>123123123123</password>
            <email>tony.kent@example.com</email>
            <first_name>Lucas</first_name>
            <last_name>Kent</last_name>
            <registration_link></registration_link>
            <registered_at>2010-03-01 00:00:00</registered_at>
            <mobile>111-222-3334</mobile>
            <fax>987-765-4321</fax>
            <misc>note...</misc>
            <remote_id>
            <parent_affiliate_id></parent_affiliate_id>
            <tiers>
              <tier_1>
                <id>112</id>
              </tier_1>
              <tier_2>
                <id>143</id>
              </tier_2>
              <tier_3>
                <id>233</id>
              </tier_3>
            </tiers>
            <created_at>2010-03-24 16:17:42</created_at>
            <updated_at>2010-03-24 16:17:42</updated_at>
            <p_street1>Zephyrhills</p_street1>
            <p_street2></p_street2>
            <p_city>New York</p_city>
            <p_state>New York</p_state>
            <p_country>USA</p_country>
            <p_code>10002</p_code>
            <s_street1></s_street1>
            <s_street2></s_street2>
            <s_city></s_city>
            <s_state></s_state>
            <s_country></s_country>
            <s_code></s_code>
          </affiliate>
        </affiliates>

b) JSON

        {
          "affiliates" : [
            {
              "id"                  : 9,
              "password"            : "123123123123",
              "email"               : "albert.aliston@example.com",
              "first_name"          : "Tony",
              "last_name"           : "Aliston",
              "registration_link"   : null,
              "registered_at"       : "2010-03-01 00:00:00",
              "mobile"              : "111-222-3334",
              "fax"                 : "987-765-4321",
              "misc"               : "note...",
              "remote_id"           : null,
              "parent_affiliate_id" : null,
              "tiers" : {
                "tier_1" : {
                  "id" : 134
                }
              },
              "created_at"          : "2010-03-24 16:17:42",
              "updated_at"          : "2010-03-24 16:17:42",
              "p_street1"           : "Zephyrhills",
              "p_street2"           : null,
              "p_city"              : "New York",
              "p_state"             : "New York",
              "p_country"           : "USA",
              "p_code"              : 10002,
              "s_street1"           : null,
              "s_street2"           : null,
              "s_city"              : null,
              "s_state"             : null,
              "s_country"           : null,
              "s_code"              : null
            },
            {
              "id"                  : 14,
              "password"            : "123123123123",
              "email"               : "tony.kent@example.com",
              "first_name"          : "Lucas",
              "last_name"           : "Kent",
              "registration_link"   : null,
              "registered_at"       : "2010-03-01 00:00:00",
              "mobile"              : "111-222-3334",
              "fax"                 : "987-765-4321",
              "misc"               : "note...",
              "remote_id"           : null,
              "parent_affiliate_id" : null,
              "tiers" : {
                "tier_1" : {
                  "id" : 112
                },
                "tier_2" : {
                  "id" : 143
                },
                "tier_3" : {
                  "id" : 233
                }
              },
              "created_at"          : "2010-03-24 16:17:42",
              "updated_at"          : "2010-03-24 16:17:42",
              "p_street1"           : "Zephyrhills",
              "p_street2"           : null,
              "p_city"              : "New York",
              "p_state"             : "New York",
              "p_country"           : "USA",
              "p_code"              : 10002,
              "s_street1"           : null,
              "s_street2"           : null,
              "s_city"              : null,
              "s_state"             : null,
              "s_country"           : null,
              "s_code"              : null
            }
          ]
        }

Scenario: Retrieves list of Affiliates with optional filter parameter get_tiers

Request

URL: "https://<subdomain>.zferral.com/api/<api_key>/affiliates.<format>?get_tiers=true"

Response (return status code "200 OK"):

a) XML

        <?xml version="1.0" encoding="UTF-8"?>
        <affiliates type="array">
          <affiliate>
            <id>1</id>
            <is_active>1</is_active>
            <password>
            <email>tony.simpson@example.com</email>
            <first_name>Tony</first_name>
            <last_name>Simpson</last_name>
            <registration_link>
            <registered_at>2010-03-01 00:00:00</registered_at>
            <mobile>111-222-3334</mobile>
            <fax>987-765-4321</fax>
            <misc>note...</misc>
            <remote_id>
            <parent_affiliate_id>
            <tiers>
              <tier1>
                <id>2</id>
              </tier1>
              <tier2>
                <id>3</id>
              </tier2>
            </tiers>
            <created_at>2010-03-01 15:45:59</created_at>
            <updated_at>2010-03-01 15:45:59</updated_at>
            <p_street1>Zephyrhills</p_street1>
            <p_street2>
            <p_city>New York</p_city>
            <p_state>New York</p_state>
            <p_country>USA</p_country>
            <p_code>10002</p_code>
            <s_street1>
            <s_street2>
            <s_city>
            <s_state>
            <s_country>
            <s_code>
          </affiliate>
          <affiliate>
            <id>2</id>
            <is_active>1</is_active>
            <password>
            <email>john.crow@example.com</email>
            <first_name>John</first_name>
            <last_name>Crow</last_name>
            <registration_link>
            <registered_at>2010-03-05 00:00:00</registered_at>
            <mobile>111-222-3334</mobile>
            <fax>987-765-4321</fax>
            <misc>note...</misc>
            <remote_id>
            <parent_affiliate_id>1</parent_affiliate_id>
            <tiers></tiers>
            <created_at>2010-03-01 15:45:59</created_at>
            <updated_at>2010-03-01 15:45:59</updated_at>
            <p_street1>Wall street</p_street1>
            <p_street2>
            <p_city>New York</p_city>
            <p_state>New York</p_state>
            <p_country>USA</p_country>
            <p_code>10002</p_code>
            <s_street1>
            <s_street2>
            <s_city>
            <s_state>
            <s_country>
            <s_code>
          </affiliate>
          <affiliate>
            <id>3</id>
            <is_active>1</is_active>
            <password>
            <email>jack.sparr@example.com</email>
            <first_name>Jack</first_name>
            <last_name>Sparr</last_name>
            <registration_link>
            <registered_at>2010-03-14 00:00:00</registered_at>
            <mobile>111-222-3334</mobile>
            <fax>987-765-4321</fax>
            <misc>note...</misc>
            <remote_id>
            <parent_affiliate_id>1</parent_affiliate_id>
            <tiers></tiers>
            <created_at>2010-03-01 15:45:59</created_at>
            <updated_at>2010-03-01 15:45:59</updated_at>
            <p_street1>13 Wall Street</p_street1>
            <p_street2>
            <p_city>New York</p_city>
            <p_state>New York</p_state>
            <p_country>USA</p_country>
            <p_code>10002</p_code>
            <s_street1>
            <s_street2>
            <s_city>
            <s_state>
            <s_country>
            <s_code>
          </affiliate>
        </affiliates>

b) JSON

        {
         "affiliates" : {
            "affiliate1" : {
              (...)
            },
            "affiliate2" : {
              (...)
            },
            "affiliate3" : {
              (...)
            }
        }}

Scenario: Retrieves 2 pages of Affiliates list (optional parameter page)

Request

URL: "https://<subdomain>.zferral.com/api/<api_key>/affiliates.<format>?page=2"

Response (return status code "200 OK"):

a) XML

        <?xml version="1.0" encoding="UTF-8"?>
        <affiliates type="array">
          <affiliate>
            <id>51</id>
            <is_active>1</is_active>
            <password></password>
            <email>tony.bennet@example.com</email>
            <first_name>Tony</first_name>
            <last_name>Aliston</last_name>
            <registration_link></registration_link>
            <registered_at>2010-03-01 00:00:00</registered_at>
            <mobile>111-222-3334</mobile>
            <fax>987-765-4321</fax>
            <misc>note...</misc>
            <remote_id>
            <parent_affiliate_id></parent_affiliate_id>
            <created_at>2010-03-02 11:21:16</created_at>
            <updated_at>2010-03-02 11:21:16</updated_at>
            <p_street1>Zephyrhills</p_street1>
            <p_street2></p_street2>
            <p_city>New York</p_city>
            <p_state>New York</p_state>
            <p_country>USA</p_country>
            <p_code>10002</p_code>
            <s_street1></s_street1>
            <s_street2></s_street2>
            <s_city></s_city>
            <s_state></s_state>
            <s_country></s_country>
            <s_code></s_code>
          </affiliate>
          <affiliate>
            <id>52</id>
            <is_active>1</is_active>
            <password></password>
            <email>tony.aliston@example.com</email>
            <first_name>Tomy</first_name>
            <last_name>Aliston</last_name>
            <registration_link></registration_link>
            <registered_at>2010-03-01 00:00:00</registered_at>
            <mobile>111-222-3334</mobile>
            <fax>987-765-4321</fax>
            <misc>note...</misc>
            <remote_id>
            <parent_affiliate_id></parent_affiliate_id>
            <created_at>2010-03-02 11:21:16</created_at>
            <updated_at>2010-03-02 11:21:16</updated_at>
            <p_street1>Zephyrhills</p_street1>
            <p_street2></p_street2>
            <p_city>New York</p_city>
            <p_state>New York</p_state>
            <p_country>USA</p_country>
            <p_code>10002</p_code>
            <s_street1></s_street1>
            <s_street2></s_street2>
            <s_city></s_city>
            <s_state></s_state>
            <s_country></s_country>
            <s_code></s_code>
          </affiliate>
          <affiliate>
            <id>53</id>
            <is_active>1</is_active>
            <password></password>
            <email>john.stock@example.com</email>
            <first_name>Clark</first_name>
            <last_name>Olson</last_name>
            <registration_link></registration_link>
            <registered_at>2010-03-01 00:00:00</registered_at>
            <mobile>111-222-3334</mobile>
            <fax>987-765-4321</fax>
            <misc>note...</misc>
            <remote_id>
            <parent_affiliate_id></parent_affiliate_id>
            <created_at>2010-03-02 11:21:16</created_at>
            <updated_at>2010-03-02 11:21:16</updated_at>
            <p_street1>Zephyrhills</p_street1>
            <p_street2></p_street2>
            <p_city>New York</p_city>
            <p_state>New York</p_state>
            <p_country>USA</p_country>
            <p_code>10002</p_code>
            <s_street1></s_street1>
            <s_street2></s_street2>
            <s_city></s_city>
            <s_state></s_state>
            <s_country></s_country>
            <s_code></s_code>
          </affiliate>
          ...
          <affiliate>
            <id>99</id>
            <is_active>1</is_active>
            <password></password>
            <email>albert@example.com</email>
            <first_name>Clark</first_name>
            <last_name></last_name>
            <registration_link></registration_link>
            <registered_at>2010-03-01 00:00:00</registered_at>
            <mobile>111-222-3334</mobile>
            <fax>987-765-4321</fax>
            <misc>note...</misc>
            <remote_id>
            <parent_affiliate_id></parent_affiliate_id>
            <created_at>2010-03-02 11:21:16</created_at>
            <updated_at>2010-03-02 11:21:16</updated_at>
            <p_street1>Zephyrhills</p_street1>
            <p_street2></p_street2>
            <p_city>New York</p_city>
            <p_state>New York</p_state>
            <p_country>USA</p_country>
            <p_code>10002</p_code>
            <s_street1></s_street1>
            <s_street2></s_street2>
            <s_city></s_city>
            <s_state></s_state>
            <s_country></s_country>
            <s_code></s_code>
          </affiliate>
          <affiliate>
            <id>100</id>
            <is_active>1</is_active>
            <password></password>
            <email>tomy@example.com</email>
            <first_name>Tony</first_name>
            <last_name>Aliston</last_name>
            <registration_link></registration_link>
            <registered_at>2010-03-01 00:00:00</registered_at>
            <mobile>111-222-3334</mobile>
            <fax>987-765-4321</fax>
            <misc>note...</misc>
            <remote_id>
            <parent_affiliate_id></parent_affiliate_id>
            <created_at>2010-03-02 11:21:16</created_at>
            <updated_at>2010-03-02 11:21:16</updated_at>
            <p_street1>Zephyrhills</p_street1>
            <p_street2></p_street2>
            <p_city>New York</p_city>
            <p_state>New York</p_state>
            <p_country>USA</p_country>
            <p_code>10002</p_code>
            <s_street1></s_street1>
            <s_street2></s_street2>
            <s_city></s_city>
            <s_state></s_state>
            <s_country></s_country>
            <s_code></s_code>
          </affiliate>
        </affiliates>

b) JSON

        {
         "affiliates" : {
            "affiliate1" : {
              (...)
            },
            "affiliate2" : {
              (...)
            },
            "affiliate3" : {
              (...)
            },
        }}

Scenario: Retrieves 2 pages of affiliates list (optional parameter page) with limit = 48 records (optional parameter limit)

Request

URL: "https://<subdomain>.zferral.com/api/<api_key>/affiliates.<format>?page=2&limit=48"

Response (return status code "200 OK"):

a) XML

        <?xml version="1.0" encoding="UTF-8"?>
        <affiliates type="array">
          <affiliate>
              <id>51</id>
              <is_active>1</is_active>
              <password>123123123123</password>
              <email>tony.olson@example.com</email>
              <first_name>Lucas</first_name>
              <last_name>Bennet</last_name>
              <registration_link></registration_link>
              <registered_at>2010-03-01 00:00:00</registered_at>
              <mobile>111-222-3334</mobile>
              <fax>987-765-4321</fax>
              <misc>note...</misc>
              <remote_id>
              <parent_affiliate_id></parent_affiliate_id>
              <created_at>2010-03-18 13:37:03</created_at>
              <updated_at>2010-03-18 13:37:03</updated_at>
              <p_street1>Zephyrhills</p_street1>
              <p_street2></p_street2>
              <p_city>New York</p_city>
              <p_state>New York</p_state>
              <p_country>USA</p_country>
              <p_code>10002</p_code>
              <s_street1></s_street1>
              <s_street2></s_street2>
              <s_city></s_city>
              <s_state></s_state>
              <s_country></s_country>
              <s_code></s_code>
          </affiliate>
          ...
          <affiliate>
              <id>98</id>
              <is_active>1</is_active>
              <password>123123123123</password>
              <email>tony.bennet@example.com</email>
              <first_name>Celvin</first_name>
              <last_name>Kent</last_name>
              <registration_link></registration_link>
              <registered_at>2010-03-01 00:00:00</registered_at>
              <mobile>111-222-3334</mobile>
              <fax>987-765-4321</fax>
              <misc>note...</misc>
              <remote_id>
              <parent_affiliate_id></parent_affiliate_id>
              <created_at>2010-03-18 13:37:03</created_at>
              <updated_at>2010-03-18 13:37:03</updated_at>
              <p_street1>Zephyrhills</p_street1>
              <p_street2></p_street2>
              <p_city>New York</p_city>
              <p_state>New York</p_state>
              <p_country>USA</p_country>
              <p_code>10002</p_code>
              <s_street1></s_street1>
              <s_street2></s_street2>
              <s_city></s_city>
              <s_state></s_state>
              <s_country></s_country>
              <s_code></s_code>
          </affiliate>
        </affiliates>

b) JSON

        {
          "affiliates" : [{
            "id"                  : 51,
            "is_active"           : true,
            "password"            : "123123123123",
            "email"               : "tony.olson@example.com",
            "first_name"          : "Lucas",
            "last_name"           : "Bennet",
            "registration_link"   : null,
            "registered_at"       : "2010-03-01 00:00:00",
            "mobile"              : "111-222-3334",
            "fax"                 : "987-765-4321",
            "misc"               : "note...",
            "remote_id"           : null,
            "parent_affiliate_id" : null,
            "created_at"          : "2010-03-18 13:37:03",
            "updated_at"          : "2010-03-18 13:37:03",
            "p_street1"           : "Zephyrhills",
            "p_street2"           : null,
            "p_city"              : "New York",
            "p_state"             : "New York",
            "p_country"           : "USA",
            "p_code"              : 10002,
            "s_street1"           : null,
            "s_street2"           : null,
            "s_city"              : null,
            "s_state"             : null,
            "s_country"           : null,
            "s_code"              : null
          },
          ...
          {
            "id"                  : 98,
            "is_active"           : true,
            "password"            : "mypassword",
            "email"               : "john.bennet@example.com",
            "first_name"          : "Celvin",
            "last_name"           : "Kent",
            "registration_link"   : null,
            "registered_at"       : "2010-03-01 00:00:00",
            "mobile"              : "111-421-3334",
            "fax"                 : "987-765-4321",
            "misc"               : "note...",
            "remote_id"           : null,
            "parent_affiliate_id" : null,
            "created_at"          : "2010-03-18 13:37:03",
            "updated_at"          : "2010-03-18 13:37:03",
            "p_street1"           : "Zephyrhills",
            "p_street2"           : null,
            "p_city"              : "New York",
            "p_state"             : "New York",
            "p_country"           : "USA",
            "p_code"              : 10002,
            "s_street1"           : "Zephyrhills2",
            "s_street2"           : null,
            "s_city"              : "New York",
            "s_state"             : "New York",
            "s_country"           : "USA",
            "s_code"              : 50022
          }]
        }

Scenario: Retrieves 3 (non-existing) pages of affiliates list (optional parameter <page>). No results.

Request

URL: "https://<subdomain>.zferral.com/api/<api_key>/affiliates.<format>?page=3"

Response (return status code "200 OK"):

a) XML
```
        <?xml version="1.0" encoding="UTF-8"?>
        <affiliates type="array"></affiliates>
      
```
b) JSON
```
        {
         "affiliates" : []
        }
      
```

zferral API

Authentication of affiliates

API Objects

Affiliate

Methods:

Examples:

Parameters:

Methods

create - creates a new Affiliate

update - updates Affiliate data

delete – removes Affiliate

get – retrieves Affiliate data

list – retrieves list of Affiliates

create - Usage Example

update - Usage Example

delete – Usage Example

get – Usage Example

list – Usage Example