### Signature Calculation Steps

Source: https://referralcandy.com/api

A step-by-step example of generating an MD5 signature for API authentication.

```text
["timestamp=1296664909", "accessID=acihijaklscj", "name=john"]
```

```text
["accessID=acihijaklscj", "name=john", "timestamp=1296664909"]
```

```text
"accessID=acihijaklscjname=johntimestamp=1296664909"
```

```text
"APISECRETKEYaccessID=acihijaklscjname=johntimestamp=1296664909"
```

```text
signature = MD5("APISECRETKEYaccessID=acihijaklscjname=johntimestamp=1296664909") = "04535fe455e9f77a90c06e81d7888569"
```

--------------------------------

### Signature Calculation Example Params

Source: https://referralcandy.com/api

Initial parameters used for signature calculation.

```json
{email: "abc@xyz.com", name: "john & jane"}
```

--------------------------------

### Authentication Response Example

Source: https://referralcandy.com/api

A sample JSON response showing a successful authentication or data retrieval.

```json
{"message":"Success","referrals":[{"referral_email":"referral1@example.com","referral_timestamp":1329738979,"referring_email":"customer@example.com","campaignID":321},{"referral_email":"referral2@example.com","referral_timestamp":1329738984,"referring_email":"customer@example.com","campaignID":123}],"period_from":1329738679,"period_to":1329739284}
```

--------------------------------

### Sample Result for POST Rewards

Source: https://referralcandy.com/api

Example of a successful response from the POST rewards endpoint.

```json
{:message=>"Success", :reward=>{:advocate_email=>"john@example.com", :advocate_name=>"John Smith", :created_at=>1442584289, :description=>"20% discount", :id=>3938282, :status=>"delivered", :type=>"custom"}}
```

--------------------------------

### Get Rewards Method Sample Result

Source: https://referralcandy.com/api

The Ruby hash-style response returned after a successful GET request to the rewards endpoint.

```ruby
{:message=>"Success", :rewards=>[{:advocate_email=>"john@example.com", :advocate_name=>"John Smith", :created_at=>1442584289, :description=>"20% discount", :id=>2, :status=>"delivered", :type=>"custom"}, {:advocate_email=>"alice@example.com", :advocate_name=>"Alice Bob", :created_at=>1442584426, :description=>"20% discount", :id=>3, :status=>"pending_fulfilment", :type=>"custom"}], :since_id=>1}
```

--------------------------------

### Referrer Method GET Sample Result

Source: https://referralcandy.com/api

The JSON response returned when querying for the referrer of a specific customer.

```json
{"message":"Success","referrer":"referrer@example.com", "campaignId": 123}
```

--------------------------------

### Purchase Method Sample Result

Source: https://referralcandy.com/api

Example JSON response returned after a successful POST request to the purchase endpoint.

```json
{"message":"Success","status":"true","referralcorner_urls":[{"campaignId":123,"url":"//refcandy.referralcandy.com/share/BW299X"}]}
```

--------------------------------

### GET /api/v2.2/referrer.json

Source: https://referralcandy.com/api

Queries for the referrer of a particular customer.

```APIDOC
## GET /api/v2.2/referrer.json

### Description
This method lets you query for the referrer of a particular customer. This method is not available when the account is suspended.

### Method
GET

### Endpoint
https://my.referralcandy.com/api/v2.2/referrer.json

### Parameters
#### Query Parameters
- **customer_email** (string) - Required - Customer email address.
- **timestamp** (integer) - Required - UNIX timestamp of API call.
- **accessID** (string) - Required - API Access ID.
- **signature** (string) - Required - Calculated signature.

### Response
#### Success Response (200)
- **referrer** (string) - Email address of referring customer if one exists, null otherwise.
- **message** (string) - A message indicating the outcome of the API call.
- **campaignId** (integer) - Campaign the referral belongs to.

### Response Example
{
  "message": "Success",
  "referrer": "referrer@example.com",
  "campaignId": 123
}
```

--------------------------------

### GET /campaigns.json

Source: https://referralcandy.com/api

Returns a list of campaigns for your account. Each campaign includes its ID, name, join URL, and state.

```APIDOC
## GET /campaigns.json

### Description
This method returns a list of campaigns for your account.

### Method
GET

### Endpoint
https://my.referralcandy.com/api/v2.2/campaigns.json

### Parameters
#### Query Parameters
- **timestamp** (string) - Required - UNIX timestamp of API call.
- **accessID** (string) - Required - API Access ID.
- **signature** (string) - Required - Calculated signature.

### Response
#### Success Response (200)
- **campaigns** (array) - Array of campaigns in your account.
  - **campaign_id** (integer) - Unique identifier for the campaign that can be used for querying other api.
  - **campaign_name** (string) - Name of the campaign.
  - **join_url** (string) - Public URL customers can visit to join the campaign.
  - **campaign_state** (string) - Possible values: ACTIVE | PAUSED | STOPPED.
- **message** (string) - A message indicating the outcome of the API call.

#### Response Example
{"message": "Success", "campaigns": [{"campaign_id": 123, "campaign_name": "Summer Referral Campaign", "join_url": "https://abc.refr.cc/join/summer-campaign","campaign_state": "ACTIVE"}]}
```

--------------------------------

### GET /verify.json

Source: https://referralcandy.com/api

Verifies that authentication for API calls is set up correctly. Returns a message indicating the outcome. Not available when the account is suspended, returning HTTP 403.

```APIDOC
## GET /verify.json

### Description
This method lets you verify that authentication for your API calls is set up correctly. This method is not available when the account is suspended and will return a HTTP 403 Forbidden status code.

### Method
GET

### Endpoint
https://my.referralcandy.com/api/v2.2/verify.json

### Parameters
#### Query Parameters
- **timestamp** (string) - Required - UNIX timestamp of API call.
- **accessID** (string) - Required - API Access ID.
- **signature** (string) - Required - Calculated signature.

### Response
#### Success Response (200)
- **message** (string) - A message indicating the outcome of the API call.
- **reason** (string) - Further information provided about the response. This field is returned only in certain cases.

#### Response Example
{"message":"Verification Ok"}
```

--------------------------------

### Reward Purchases Method Sample Result

Source: https://referralcandy.com/api

The JSON response returned after a successful GET request to the reward_purchases endpoint.

```json
{"message":"Success", "referred_purchases":[{"id":1, "external_reference_id":"ORDER_1", "purchaser_email":"john@example.com"},{"id":2, "external_reference_id":"ORDER_2", "purchaser_email":"alice@example.com"}]}
```

--------------------------------

### GET rewards.json

Source: https://referralcandy.com/api

Queries for rewards matching specified criteria. Returns HTTP 403 if the account is suspended.

```APIDOC
## GET /api/v2.2/rewards.json

### Description
This method lets you query for rewards which match some criteria. This method is not available when the account is suspended and will return a HTTP 403 Forbidden status code.

### Method
GET

### Endpoint
https://my.referralcandy.com/api/v2.2/rewards.json

### Parameters
#### Query Parameters
- **email** (string) - Optional - When given, the result only contains rewards from the advocate with this email address.
- **since_id** (integer) - Optional - When given, the result starts from the next matching reward earned after the specified reward ID. Otherwise, the result starts with the first matching reward.
- **status** (string) - Optional - When specified, the result contains rewards with the matching status. Otherwise, the result contains rewards matching all statuses. Accepted values are pending_fulfillment, delivered.
- **type** (string) - Optional - When specified, the result contains rewards with the matching type. Otherwise, the result contains rewards matching all types. Accepted values are cash, coupon, custom, none.
- **timestamp** (integer) - Required - UNIX timestamp of API call.
- **accessID** (string) - Required - API Access ID.
- **signature** (string) - Required - Calculated signature.
- **campaignId** (string) - Optional - campaignId

### Response
#### Success Response (200)
- **message** (string) - A message indicating the outcome of the API call.
- **rewards** (array) - The first 200 matching rewards.
- **since_id** (integer) - The value specified in the request if available.
- **status** (string) - The value specified in the request if available.
- **type** (string) - The value specified in the request if available.
- **coupon_code** (string) - The value specified in the request if available.
- **coupon_code_expiry_timestamp** (integer) - The value specified in the request if available.
- **coupon_code_data** (object) - The value specified in the request if available.
- **coupon_used** (boolean) - Indicates whether this coupon has been used (true) or remains unused (false) in Shopify. Only available for Shopify merchants and only when Shopify can provide usage data.

#### Response Example
{:message=>"Success", :rewards=>[{:advocate_email=>"john@example.com", :advocate_name=>"John Smith", :created_at=>1442584289, :description=>"20% discount", :id=>2, :status=>"delivered", :type=>"custom"}, {:advocate_email=>"alice@example.com", :advocate_name=>"Alice Bob", :created_at=>1442584426, :description=>"20% discount", :id=>3, :status=>"pending_fulfilment", :type=>"custom"}], :since_id=>1}
```

--------------------------------

### Sample JSON response for GET contacts

Source: https://referralcandy.com/api

A sample JSON response returned by the contacts endpoint, showing a successful query with two contacts and their associated purchase data.

```json
{"message":"Success","total_count":2,"contacts":[{"id":800,"first_name":"Contact","last_name":"One","email":"contact1@example.com","purchase_made":true,"purchases":[{"purchased_at":1329738679,"amount":97.0,"currency":"USD"}],"unsubscribed":false},{"id":1250,"first_name":"Contact","last_name":"Two","email":"contact2@example.com","purchase_made":false,"purchases":[],"unsubscribed":false}],"campaignId":123,"limit":100}
```

--------------------------------

### GET reward_purchases.json

Source: https://referralcandy.com/api

Queries for referred purchases associated with a reward. Returns HTTP 403 if the account is suspended.

```APIDOC
## GET /api/v2.2/reward_purchases.json

### Description
This method lets you query for the referred purchases that are associated with a reward. This method is not available when the account is suspended and will return a HTTP 403 Forbidden status code.

### Method
GET

### Endpoint
https://my.referralcandy.com/api/v2.2/reward_purchases.json

### Parameters
#### Query Parameters
- **reward_id** (integer) - Required - The ID of the reward.
- **timestamp** (integer) - Required - UNIX timestamp of API call.
- **accessID** (string) - Required - API Access ID.
- **signature** (string) - Required - Calculated signature.

### Response
#### Success Response (200)
- **message** (string) - A message indicating the outcome of the API call.
- **reason** (string) - Further information provided about the response. This field is returned only in certain cases.
- **referred_purchases** (array) - The list of the referred purchases that is associated with the reward.

#### Response Example
{"message":"Success", "referred_purchases":[{"id":1, "external_reference_id":"ORDER_1", "purchaser_email":"john@example.com"},{"id":2, "external_reference_id":"ORDER_2", "purchaser_email":"alice@example.com"}]}
```

--------------------------------

### GET /api/v2.2/contacts.json

Source: https://referralcandy.com/api

Queries for contacts enrolled in a campaign. Returns a list of contacts with details such as name, email, purchase history, and subscription status.

```APIDOC
## GET /api/v2.2/contacts.json

### Description
This method lets you query for contacts currently enrolled in your campaign. This method is not available when the account is suspended and will return a HTTP 403 Forbidden status code.

### Method
GET

### Endpoint
https://my.referralcandy.com/api/v2.2/contacts.json

### Parameters
#### Query Parameters
- **id** (integer) - Optional - Lowest id of contact returned by query. Defaults to 1.
- **limit** (integer) - Optional - Number of contacts to return. Defaults to 100. Capped at 100.
- **email** (string) - Optional - When given, only the contact with this exact email address is returned.
- **timestamp** (integer) - Required - UNIX timestamp of API call.
- **accessID** (string) - Required - API Access ID.
- **signature** (string) - Required - Calculated signature.
- **campaignId** (string) - Optional - Filter by campaign. Fallback to first campaign if not provided.

### Request Example
GET https://my.referralcandy.com/api/v2.2/contacts.json?id=50&limit=100

### Response
#### Success Response (200)
- **contacts** (array) - Array of contacts.
  - **id** (integer) - Unique identifier of contact.
  - **first_name** (string) - First name of contact.
  - **last_name** (string) - Last name of contact.
  - **email** (string) - Email address of contact.
  - **purchase_made** (boolean) - Whether contact made a purchase at the store (true/false).
  - **purchases** (array) - Array of purchases made by contact.
    - **purchased_at** (integer) - UNIX timestamp of purchase.
    - **amount** (number) - Invoice amount of purchase.
    - **currency** (string) - ISO 4217 currency code of the purchase.
  - **unsubscribed** (boolean) - Whether contact is unsubscribed (true/false).
- **total_count** (integer) - Number of contacts returned in this response.
- **campaignId** (integer) - ID of the campaign the contacts were read from. Confirms which campaign's contacts are being returned when campaignId was omitted from the request.
- **limit** (integer) - Number of contacts returned in this response. May be less than the requested limit if fewer contacts are available.
- **message** (string) - A message indicating the outcome of the API call.
- **reason** (string) - Further information provided about the response. This field is returned only in certain cases.

#### Response Example
{"message":"Success","total_count":2,"contacts":[{"id":800,"first_name":"Contact","last_name":"One","email":"contact1@example.com","purchase_made":true,"purchases":[{"purchased_at":1329738679,"amount":97.0,"currency":"USD"}],"unsubscribed":false},{"id":1250,"first_name":"Contact","last_name":"Two","email":"contact2@example.com","purchase_made":false,"purchases":[],"unsubscribed":false}],"campaignId":123,"limit":100}
```

--------------------------------

### GET /api/v2.2/referrals.json

Source: https://referralcandy.com/api

Queries for referred purchases made over some period of time. This method is not available when the account is suspended and will return a HTTP 403 Forbidden status code.

```APIDOC
## GET /api/v2.2/referrals.json

### Description
Queries for referred purchases made over some period of time. This method is not available when the account is suspended and will return a HTTP 403 Forbidden status code.

### Method
GET

### Endpoint
https://my.referralcandy.com/api/v2.2/referrals.json

### Parameters
#### Query Parameters
- **period_from** (integer) - Required - UNIX timestamp of start of query period.
- **period_to** (integer) - Optional - UNIX timestamp of end of query period. Defaults to most recent timestamp.
- **customer_email** (string) - Optional - Advocate's email address. Return referred purchases made by advocate if set. Return all referred purchases if not set.
- **pending_review_only** (boolean) - Optional - Whether to only return referred purchases that are pending the review period (true/false). Defaults to false - this returns referred purchases regardless of review period status.
- **timestamp** (integer) - Required - UNIX timestamp of API call.
- **accessID** (string) - Required - API Access ID.
- **signature** (string) - Required - Calculated signature.

### Response
#### Success Response (200)
- **referrals** (array) - Array of referred customers and referral timestamps.
  - **referral_email** (string) - Email address of referred customer.
  - **referral_timestamp** (integer) - UNIX timestamp when referral purchase was made.
  - **referring_email** (string) - Email address of advocate who made the referral.
  - **review_period_over** (boolean) - Whether the review period for this referred purchase is over.
  - **external_reference_id** (string) - An ID that can be used to track this referred purchase externally.
  - **campaignID** (integer) - Campaign ID that is associated to the referral.
- **period_from** (integer) - UNIX timestamp of start of query period.
- **period_to** (integer) - UNIX timestamp of end of query period of the results returned. This might not be the same as the period_to value requested since successful referrals can only be detected up till a couple of minutes before the current time.
- **message** (string) - A message indicating the outcome of the API call.
- **reason** (string) - Further information provided about the response. This field is returned only in certain cases.
```

--------------------------------

### Signup Method Sample Result

Source: https://referralcandy.com/api

The JSON response structure for a successful signup request, showing enrollment details across multiple campaigns.

```json
{
  "message": "Success",
  "referralcorner_url": "http://refcandy.referralcandy.com/BW299X",
  "referral_link": "http://refcandy.refr.cc/ABCDEF",
  "invite_code": "BW299X",
  "enrollments": [
    {
      "campaignId": 101,
      "enrolled": true,
      "primary": true,
      "referralcorner_url": "http://refcandy.referralcandy.com/BW299X",
      "referral_link": "http://refcandy.refr.cc/ABCDEF",
      "invite_code": "BW299X"
    },
    {
      "campaignId": 102,
      "enrolled": true,
      "primary": false,
      "referralcorner_url": "http://refcandy.referralcandy.com/CX300Y",
      "referral_link": "http://refcandy.refr.cc/GHIJKL",
      "invite_code": "CX300Y"
    }
  ]
}
```

--------------------------------

### Invite Method Sample Result

Source: https://referralcandy.com/api

The JSON response structure for a successful invite request.

```json
{"message":"Success","invites":500}
```

--------------------------------

### POST /api/v2.2/signup.json

Source: https://referralcandy.com/api

Adds a contact to the ReferralCandy system and attempts enrollment across all campaigns. Returns per-campaign enrollment results, including referral links and portal sharing page URLs.

```APIDOC
## POST /api/v2.2/signup.json

### Description
Adds a contact to the ReferralCandy system and attempts enrollment across all campaigns. If the advocate is enrolled, returns the referral link and Portal Sharing Page address for the primary campaign.

### Method
POST

### Endpoint
https://my.referralcandy.com/api/v2.2/signup.json

### Parameters
#### Input Parameters
- **first_name** (string) - Required - Advocate's first name.
- **last_name** (string) - Required - Advocate's last name.
- **email** (string) - Required - Advocate's email address.
- **timestamp** (integer) - Required - UNIX timestamp of API call.
- **accessID** (string) - Required - API Access ID.
- **signature** (string) - Required - Calculated signature.
- **campaignId** (integer) - Optional - Sets the primary campaign in the response. Fallback to first campaign if not provided. Enrollment is attempted across all campaigns regardless.
- **segment_id** (string) - Optional - ID of a static segment to assign the contact to. Retrieve it from the dashboard. To enroll a contact in the given campaign, the segment must be set as the campaign's target audience. Regardless of whether segment_id is present, the contact will be automatically added to any dynamic segment they fit the criteria for (e.g., LTV > 0).

### Response
#### Success Response (200)
- **message** (string) - A message indicating the outcome of the API call.
- **reason** (string) - Further information provided about the response. This field is returned only in certain cases.
- **referralcorner_url** (string) - URL of the advocate's Portal Sharing Page of the primary campaign enrollment. Empty/null if the primary campaign enrollment failed.
- **referral_link** (string) - URL of the advocate's unique referral link of the primary campaign enrollment. Empty/null if the primary campaign enrollment failed.
- **invite_code** (string) - The latest invite code (AIC) of the advocate of the primary campaign enrollment. Empty/null if the primary campaign enrollment failed.
- **segment** (object) - Segment assignment details in JSON (only included when segment_id is provided). Contains: segmentId (number), assigned (boolean), and optionally reason (string) if assignment failed.
- **enrollments** (array) - Array of enrollment results for each campaign. Each object contains: campaignId (number), enrolled (boolean), primary (boolean, indicates the primary campaign). When enrolled is true, includes referralcorner_url (string), referral_link (string or null), and invite_code (string or null). When enrolled is false, includes an error object with code (one of CAMPAIGN_PAUSED, CAMPAIGN_STOPPED, SEGMENT_MISMATCH, NOT_ENROLLED) and message (string).

#### Response Example
{
  "message": "Success",
  "referralcorner_url": "http://refcandy.referralcandy.com/BW299X",
  "referral_link": "http://refcandy.refr.cc/ABCDEF",
  "invite_code": "BW299X",
  "enrollments": [
    {
      "campaignId": 101,
      "enrolled": true,
      "primary": true,
      "referralcorner_url": "http://refcandy.referralcandy.com/BW299X",
      "referral_link": "http://refcandy.refr.cc/ABCDEF",
      "invite_code": "BW299X"
    },
    {
      "campaignId": 102,
      "enrolled": true,
      "primary": false,
      "referralcorner_url": "http://refcandy.referralcandy.com/CX300Y",
      "referral_link": "http://refcandy.refr.cc/GHIJKL",
      "invite_code": "CX300Y"
    }
  ]
}

### Error Handling
- HTTP 200: All campaigns enrolled successfully.
- HTTP 207: Partially enrolled.
- HTTP 422: No campaigns enrolled.
```

--------------------------------

### Verify Method Sample Result

Source: https://referralcandy.com/api

The JSON response returned by the verify method.

```json
{"message":"Verification Ok"}
```

--------------------------------

### Campaigns Method Sample Result

Source: https://referralcandy.com/api

The JSON response returned by the campaigns method, containing a list of account campaigns.

```json
{"message": "Success", "campaigns": [{"campaign_id": 123, "campaign_name": "Summer Referral Campaign", "join_url": "https://abc.refr.cc/join/summer-campaign","campaign_state": "ACTIVE"}]}
```

--------------------------------

### Referral Method POST Sample Result

Source: https://referralcandy.com/api

The JSON response returned after successfully updating a referral status.

```json
{"message":"Success","customer_email":"customer@example.com","returned":true}
```

--------------------------------

### POST /api/v2.2/invite.json

Source: https://referralcandy.com/api

Sends a welcome email to a contact for a targeted campaign if the contact is enrolled. Returns a 403 Forbidden status if the campaign is paused or stopped.

```APIDOC
## POST /api/v2.2/invite.json

### Description
Sends a welcome email to a contact for your targeted campaign if the contact is enrolled in it. This method is not available when the targeted campaign is paused or stopped.

### Method
POST

### Endpoint
https://my.referralcandy.com/api/v2.2/invite.json

### Parameters
#### Input Parameters
- **email** (string) - Required - Contact's email address.
- **timestamp** (integer) - Required - UNIX timestamp of API call.
- **accessID** (string) - Required - API Access ID.
- **signature** (string) - Required - Calculated signature.
- **campaignId** (integer) - Optional - Send invite to the campaign if the contact is enrolled to the campaign. No invite will be sent if contact is not enrolled to the campaign. Fallback to first campaign if not provided.

### Response
#### Success Response (200)
- **message** (string) - A message indicating the outcome of the API call.
- **reason** (string) - Further information provided about the response. This field is returned only in certain cases.

#### Response Example
{"message":"Success","invites":500}

### Error Handling
- HTTP 403: Forbidden - The targeted campaign is paused or stopped.
```

--------------------------------

### API Base URL Format

Source: https://referralcandy.com/api

The base URL structure for making API calls to specific methods.

```text
https://my.referralcandy.com/api/v2.2/**_some-method_**.json
```

--------------------------------

### POST /api/v2.2/purchase.json

Source: https://referralcandy.com/api

Registers a new purchase at the store. This method is not available when the account is suspended and will return a HTTP 403 Forbidden status code.

```APIDOC
## POST /api/v2.2/purchase.json

### Description
Registers a new purchase at the store. This method is not available when the account is suspended and will return a HTTP 403 Forbidden status code.

### Method
POST

### Endpoint
https://my.referralcandy.com/api/v2.2/purchase.json

### Parameters
#### Request Body
- **first_name** (string) - Required - Customer's first name.
- **last_name** (string) - Optional - Customer's last name.
- **email** (string) - Required - Customer's email address.
- **locale** (string) - Optional - Customer's preferred language. Defaults to campaign's default language if it is not set or not available to the campaign. Valid values (ISO 639-1 language code): en, fr, de, es, it, ja, nl, ru, zh-CN, zh-HK, zh-TW, da, no, sv, pt-BR.
- **discount_code** (string) - Required if discount code was used - Discount code used in the order. Blank if no discount code was used.
- **accepts_marketing** (boolean) - Optional - Whether the customer opted in to marketing (true/false). Defaults to true.
- **order_timestamp** (integer) - Required - UNIX timestamp of order.
- **browser_ip** (string) - Required - IP address of customer when making the purchase.
- **user_agent** (string) - Required - User agent string of the customer's web browser.
- **invoice_amount** (number) - Required - Total invoice amount for this purchase.
- **currency_code** (string) - Required - ISO 4217 currency code used in order invoice (e.g. USD, GBP, INR).
- **external_reference_id** (string) - Optional - An ID that can be used to track this purchase externally.
- **referrer_id** (string) - Optional - An optional referrer identifier you can add to identify the referrer of this purchase. This is usually the AIC parameter ReferralCandy appends when a new customer clicks a referral link to get to the merchants store. The referrer_id will be used to help identify who referred this purchase.
- **timestamp** (integer) - Required - UNIX timestamp of API call.
- **accessID** (string) - Required - API Access ID.
- **signature** (string) - Required - Calculated signature.

### Response
#### Success Response (200)
- **message** (string) - A message indicating the outcome of the API call.
- **reason** (string) - Further information provided about the response. This field is returned only in certain cases.
- **status** (string) - Success indicator, returned as the string 'true'. Retained for backward compatibility.
- **referralcorner_urls** (array) - An array containing the customer's Portal Sharing Pages for all campaigns they are enrolled in. Each entry is an object with campaignId (number) and url (string), and corresponds to a different campaign where the customer has been successfully enrolled. If the customer is not enrolled in any campaigns, this will return an empty array.

#### Response Example
{"message":"Success","status":"true","referralcorner_urls":[{"campaignId":123,"url":"//refcandy.referralcandy.com/share/BW299X"}]}
```

--------------------------------

### Unsubscribed Method Sample Result

Source: https://referralcandy.com/api

The JSON response returned after a successful PUT request to the unsubscribed endpoint.

```json
{"message":"Success","email":"contact1@example.com","unsubscribed":true}
```

--------------------------------

### Literal String MD5 Calculation

Source: https://referralcandy.com/api

The correct format for computing the MD5 signature using the literal string instead of the URI encoded version.

```text
MD5("...email=abc@xyz.comname=john & jane...")
```

--------------------------------

### POST /api/v2.2/referral.json

Source: https://referralcandy.com/api

Updates the purchase status of a referred customer, allowing for the marking of returns and optional notification of the referrer.

```APIDOC
## POST /api/v2.2/referral.json

### Description
This method lets you update the purchase status of a referred customer. By default, an email is sent out to the customer who made the referral to inform him/her that he/she is not eligible for a recent referral reward. This method is not available when the account is suspended.

### Method
POST

### Endpoint
https://my.referralcandy.com/api/v2.2/referral.json

### Parameters
#### Query Parameters
- **customer_email** (string) - Required - Email address of customer who made the referred purchase.
- **notify** (boolean) - Optional - Whether to notify customer who referred customer specified above that the referral has been disregarded. Defaults to true.
- **returned** (boolean) - Required - Whether customer has returned his/her purchase. If set to true, the referral will be disregarded.
- **timestamp** (integer) - Required - UNIX timestamp of API call.
- **accessID** (string) - Required - API Access ID.
- **signature** (string) - Required - Calculated signature.

### Response
#### Success Response (200)
- **message** (string) - A message indicating the outcome of the API call.
- **customer_email** (string) - Customer email address.
- **returned** (boolean) - Whether customer has returned his/her purchase.

### Response Example
{
  "message": "Success",
  "customer_email": "customer@example.com",
  "returned": true
}
```

--------------------------------

### POST /api/v2.2/rewards.json

Source: https://referralcandy.com/api

Updates a custom reward. This method is not available when the campaign is stopped and will return a HTTP 403 Forbidden status code.

```APIDOC
## POST /api/v2.2/rewards.json

### Description
Updates a custom reward. This method is not available when the campaign is stopped and will return a HTTP 403 Forbidden status code.

### Method
POST

### Endpoint
https://my.referralcandy.com/api/v2.2/rewards.json

### Parameters
#### Input Parameters
- **id** (string) - Required - The ID of the reward.
- **status** (string) - Required - The status of the reward. Accepted values are pending_fulfillment, delivered.
- **timestamp** (integer) - Required - UNIX timestamp of API call.
- **accessID** (string) - Required - API Access ID.
- **signature** (string) - Required - Calculated signature.

### Output Parameters
- **message** (string) - A message indicating the outcome of the API call if available.
- **reason** (string) - Further details provided to help understand the response. This field is returned only in certain cases.
- **messages** (array) - A list of messages indicating the outcome of the API call if available.
- **reward** (object) - The updated reward.

### Sample Result
```
{:message=>"Success", :reward=>{:advocate_email=>"john@example.com", :advocate_name=>"John Smith", :created_at=>1442584289, :description=>"20% discount", :id=>3938282, :status=>"delivered", :type=>"custom"}}
```
```

--------------------------------

### PUT unsubscribed.json

Source: https://referralcandy.com/api

Unsubscribes or resubscribes a contact in the referral program. Returns HTTP 403 if the campaign is stopped.

```APIDOC
## PUT /api/v2.2/unsubscribed.json

### Description
This method lets you unsubscribe and resubscribe a contact in your referral program. This method is not available when the campaign is stopped and will return a HTTP 403 Forbidden status code.

### Method
PUT

### Endpoint
https://my.referralcandy.com/api/v2.2/unsubscribed.json

### Parameters
#### Query Parameters
- **email** (string) - Required - Contact's email address.
- **unsubscribed** (boolean) - Required - Whether to unsubscribe or resubscribe contact (true/false).
- **timestamp** (integer) - Required - UNIX timestamp of API call.
- **accessID** (string) - Required - API Access ID.
- **signature** (string) - Required - Calculated signature.

### Response
#### Success Response (200)
- **message** (string) - A message indicating the outcome of the API call.
- **reason** (string) - Further information provided about the response. This field is returned only in certain cases.
- **email** (string) - Customer email address.
- **unsubscribed** (boolean) - Whether customer is unsubscribed.

#### Response Example
{"message":"Success","email":"contact1@example.com","unsubscribed":true}
```

--------------------------------

### URI Encoded POST Body

Source: https://referralcandy.com/api

The URI encoded version of the parameters for the POST request body.

```text
email=abc%40xyz.com&name=john+%26+jane
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.