API Examples

The following page details a complete API example of using PHP.

Authenticate using User Credentials

The first step of any API request is to authenticate. This example uses the User Credentials authentication method.

// The grant type and Simplelists login credentials
$auth = array(
    "grant_type" =>  "password",
    "username"   =>  "apiuser",
    "password"   =>  "secret"
);

// The API authentication credentials (available from Support)
$client_credentials = "testclient:testpass";

// Set cURL parameters and call API
$curl = curl_init();
curl_setopt($curl, CURLOPT_URL, "https://www.simplelists.com/api/token.php");
curl_setopt($curl, CURLOPT_POST, true);
curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
curl_setopt($curl, CURLOPT_POSTFIELDS, $auth);
curl_setopt($curl, CURLOPT_HTTPAUTH, CURLAUTH_BASIC);
curl_setopt($curl, CURLOPT_USERPWD, $client_credentials);
$return = curl_exec($curl);
curl_close($curl);

// Decode API return to get access token
$decoded = json_decode($return, true);
$token = $decoded["access_token"];

Retrieve contacts

You can now use the access token to make calls directly to the API:

// Set up API request parameters
$request = array(
    "entity" => "contact",
    "action" => "get",
    "params" => array(
        "match"      => "all",
	"conditions" => array(
	    array(
		"field" => "surname",
		"value" => "smith"
	    )
        )
    )
);

// JSON encode the request
$encoded = json_encode($request);

// Set required HTTP headers
$headers = array(
    "Content-Type: application/json",
    "Content-Length: " . strlen($encoded),
    "Authorization: Bearer $code"
);

// Make the call
$curl = curl_init("https://www.simplelists.com/api/api.php");
curl_setopt($curl, CURLOPT_CUSTOMREQUEST, "POST");
curl_setopt($curl, CURLOPT_POSTFIELDS, $encoded);
curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
curl_setopt($curl, CURLOPT_HTTPHEADER, $headers);
$result = curl_exec($curl);

// Print the output
print_r(json_decode($result));

Obtaining a new access token

Access tokens expire after 1 hour, after which a new one needs to be obtained. This can be done by either logging in again using one of the above authentication methods, or by using the Refresh Token authentication method. To use the Refresh Token authenication method, send the refresh token (obtained in the initial authentication), after which a new access token will be received.

// The grant type and Simplelists login credentials
$auth = array(
    "grant_type"    =>  "refresh_token",
    "refresh_token" => "d4cc8dbca4489385959ea3a76ca2174f2983f622"
);

// The API authentication credentials (available from Support)
$client_credentials = "testclient:testpass";

// Set cURL parameters and call API
$curl = curl_init();
curl_setopt($curl, CURLOPT_URL, "https://www.simplelists.com/api/token.php");
curl_setopt($curl, CURLOPT_POST, true);
curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
curl_setopt($curl, CURLOPT_POSTFIELDS, $auth);
curl_setopt($curl, CURLOPT_HTTPAUTH, CURLAUTH_BASIC);
curl_setopt($curl, CURLOPT_USERPWD, $client_credentials);
$return = curl_exec($curl);
curl_close($curl);

// Decode API return to get access token
$decoded = json_decode($return, true);
$token = $decoded["access_token"];