single_buy

Updated on December 22nd, 2013

This method performs a single automated purchase and returns an alphanumeric code that can be used to download the content being purchased.

Codes can be sent directly to an intended recipient as a download link via email or SMS message. Once the link is clicked, the download process will begin.

This method returns a "request_id" which can be used to lookup the status of a request after it's been made.

Note: You do not need to timeout your script. We will automatically do that for you after 30 seconds if no response is returned.

Resource URL

https://api.given.to/rests/single_buy

Parameters

campaign_id required

The numeric ID of the campaign this purchase is associated with. You can view a list of your existing campaigns and the ID of each here

Example Value: 123456

app_id required

The iTunes App ID of the app being purchased. Use the App ID Search Tool to find the ID of the app you want to send.

option required

Download codes that are generated using this API method will be returned in the response when it is set to generate. The "generate" option is available for clients that prefer to deliver the link on their own and will return the original apple url. When this parameter is set to send, Given.to will send the code directly to the recipient using the values you've provided in the send_format and send_to parameters.

Example Values: send or generate

Default message for sms send: You've just received a free copy of {App Name} from {Company Name}. Click here to download, ((given url))

send_format optional

The send_format tells us what type of information you are sending in your request to identify the intended recipient. Currently this parameter can be set to either "email" (to send the download link to an email address) or "phone" (to send the download link to a phone number via SMS). This field is required if the option parameter is set to "send".

Example Value: email

Example Value: phone

send_to optional

The email address or phone number of the intended recipient. Currently, only US phone numbers can be used. The country code is not necessary. Dashes are not necessary.

Example Value: email@example.com

Example Value: 5555555555

Example

Sample Request: Buy an App with PHP & cURL

<?php

        $url = 'https://api.given.to/rests/single_buy'; 
        
        $ch = curl_init($url);
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
        curl_setopt($ch, CURLOPT_POST, 1);

        $json_hold['option'] = 'send';
        $json_hold['send_format'] = 'number';
        $json_hold['send_to'] = '5555555555';
        $json_hold['app_id'] = '412789267';
        $json_hold['campaign_id'] = 4;
        $json = json_encode($json_hold);

        $data = array(
            'auth_key' => "YOUR_KEY", 
            'auth_secret' => "YOUR_SECRET", 
            'data' => $json
        );

        curl_setopt($ch, CURLOPT_POSTFIELDS, $data);
        $response = curl_exec($ch);
        curl_close($ch);
	
	echo "<pre>";
	print_r($response);
	echo "</pre>";

?>
				

Response

request_id

ID of the request

status

Either of the following values:

  • SUCCESS - The request has been generated or sent successfully
  • FAILURE - The request has failed
  • PENDING - The request is taking longer than expected to generate or send. We'll continue processing it for up to an hour. If the request cannot be generated or sent within 1 hour, it will be considered failed. You can use a "Webhook URL" to be notified of request status changes.
message

A detailed message offering more information regarding the current status

Note: Currently, the redeem link is returned in this field for "generate" requests. Please rely on the "redeem_link" value for redeem links. This field will be repurposed in the near future.

redeem_link

The direct redeem link generated for this request.

This value appears in responses for "generate" requests only.

Note: These "redeem_link" URLs are provided for the convenience of clients who rely on their own reporting. Given.to cannot track clickthroughs and redemption metrics when these links are used. For accurate reporting through your Given.to API dashboard, please use "redeem_redirect" URLs.

redeem_redirect

A "given.to" URL that redirects to the redeem link generated for this request.

This value appears in responses for "generate" requests only.

Note: Given.to cannot track clickthroughs and redemption metrics unless these links are used. We do not track any metrics when direct "redeem_link" URLs are used. For accurate reporting through your Given.to API dashboard, please use "redeem_redirect" URLs.

Sample Response (Successful - Send)

{
	"status":"SUCCESS",
	"message":"Sms send Success",
	"request_id":"123456",
}
				

Sample Response (Successful - Generate)

{
	"status":"SUCCESS",
	"message":"Link generated",
	"redeem_link":"http://buy.itunes.apple.com/WebObjects/MZFinance.woa/wa/com.apple.jingle.app.finance.DirectAction/freeProductCodeWizard?code=XXXXXX&mt=8",
	"redeem_redirect":"http://api.given.to/a/XXXXXX",
	"request_id":"123456",
}
				

Sample Response (Failed)

{
	"status":"FAILURE",
	"message":"Required field, \"app_id\", missing",
	"request_id":"123456",
}