API function 'Create Callback'

back to API Documentation (up a level)

API Call: Summary table

Summary API call URL Example
URL Model http://callmyapp.com/api/1.0/create/?api_key=[api_key]&callback_url=[callback_url]&callback_time=[callback_time]
Example URL http://callmyapp.com/api/1.0/create/?api_key=123abc&callback_url=http://apihouse.com/demo-callback-endpoint&callback_time=2010-11-28T19:55:00%2B01:00
Example URL with repeat callback every 30 minutes http://callmyapp.com/api/1.0/create/?api_key=123abc&callback_url=http://apihouse.com/demo-callback-endpoint&callback_time=2010-11-28T19:55:00%2B01:00&callback_repeat=1&callback_repeat_interval_unit=minutes&callback_repeat_interval=30

API Call: Parameter table

URL Parameter Specification Value/Content
api_key Mandatory? : Yes This value of 'api_key' should be exactly the same as the 'api key' associated to your account. You can find your 'api key' in the account page after you have signed in.
callback_url Mandatory? : Yes
'URL Encoded'		 'callback_url' is the URL the CallMyApp will send the callback notification. The URL may contain parameters and must be accessible by CallMyApp at 'callback_time'.
callback_time Mandatory? : Yes
'URL Encoded'
Format : 'ISO 8601' (W3C "Date and Time Formats" page), including time zone designator.		 'callback_time' is the time at which the callback should be triggered.
callback_repeat Mandatory? : No
Permitted values : [ "0" | "1" ]		 'callback_repeat' should be set to "1" if callback repeating required.
callback_repeat_type Mandatory? : Yes if 'callback_repeat' set to "1".
Permitted values : [ "interval" | "immediate" ]		 "interval" repeat will repeat the callback continuously at the specified interval. "immediate" will repat the callback as soon as the previous callback has completed.
callback_repeat_interval_unit Mandatory? : Yes if 'callback_repeat' set to "1".
Permitted values : [ "seconds" | "minutes" | "hours" | "days" | "months" | "years" ]		 'callback_repeat_interval_unit' is the time unit used with 'callback_repeat_interval' to define the callback repeat frequency.
callback_repeat_interval Mandatory? : Yes if 'callback_repeat' set to "1".
Format : A positive integer.		 'callback_repeat_interval' is the multiplier of the time unit to define when repeated callback is fired.
response_format Mandatory? : No
Permitted values : [ "json" | "xml" ]
default value: "json"
Case sensitive? : Yes		 'response_format' specifies in which data format the response should be sent.

API Call: Response table

response format response type description
JSON success 
{
	"success":1,
	"api_function":"create",
	"api_call_parameters":{"key1":"value1","key2":"value2" ...},
	"callback_id":[unique callback 'id', should not be assumed numeric]
}
JSON error 
{
	"success":0,
	"error":[see Error code table for possible values]
}
XML success 
<?xml version="1.0" encoding="UTF-8"?>
<response>
    <api_function>create</api_function>
    <success>1</success>
    <api_call_parameters>
        <parameter>
            <key>key1</key>
            <value>value1</value>
        </parameter>
        <parameter>
            <key>key2</key>
            <value>value2</value>
        </parameter>
        ...
    </api_call_parameters>
    <callback_id>[unique callback 'id', should not be assumed numeric]</callback_id>
</response>
XML error 
<?xml version="1.0" encoding="UTF-8"?>
<response>
    <success>0</success>
    <error>[see Error code table for possible values]</error>
</response>

API Call: Error code table

In addition to the following API function specific error codes, the response may also include the error codes defined in the Common error code table.

Error Key Significance
callback_url_absent The mandatory 'callback_url' parameter was missing from the API call URL
callback_time_absent The mandatory 'callback_time' parameter was missing from the API call URL
callback_time_expired The value for 'callback_time' supplied in the API call URL represents a time in the past, therefore a callback can not be created. Due to 'network lag' and server load, you should create callbacks for at least 20 seconds in advance.
callback_already_exists A constraint exists to prevent duplicate callbacks with the same time and same callback URL for a given user account. This error is returned when a callback already exists with the specified time and callback url.