versium/reach-api-php-sdk

A PHP client library for accessing the Versium REACH APIs.

v0.4.0 2023-06-20 17:40 UTC

Requires

• php: >=7.2
• ext-curl: *
• ext-json: *

Requires (Dev)

• phpunit/phpunit: ^9.5

BSD-3-Clause

• Ryan Watson
• Bryan Kotjan

README

A simplified PHP interface for accessing the Versium Reach APIs

Installation

From the root of your project, use composer to install the SDK from packagist.

composer require versium/reach-api-php-sdk

Usage

1. Use ReachClient

use Versium\Reach\ReachClient;

1. Create a ReachClient instance, with your API Key, an optional callback function for logging, and an optional queries-per-second rate limit.

$loggingFunction = function($msg) {
    //print out message for dev
    echo $msg;
};
$client = new ReachClient('you-api-key', $loggingFunction);

Note: remember to update the $qps value if Versium customer services increases your rate limit.

1. For adding data to a set of inputs, use the append function. This function returns a Generator that yields arrays containing API responses. Check the API documentation for which data tools and output types are available.

//call the contact API to append phones and emails 
$inputs = [
    [
        'first' => 'john',
        'last' => 'doe',
        'address' => '123 Trinity St',
        'city' => 'Redmond',
        'state' => 'WA',
        'zip' => '98052',
    ]
];

foreach ($client->append('contact', $inputs, ['email', 'phone']) as $results) {
    //filter out failed queries for processing later
    $failedResults = array_filter($results, function ($result) {
        return !$result->success;
    });
    
    //merge successful matches with inputs
    foreach ($results as $idx => $result) {
        if ($result->matchFound) {
            $inputs[$idx]['appendResults'] = $result->body->versium->results;
        }        
    }
}

1. For retrieving a list of records, use the listgen function. This function returns a single APIResponse object. This object contains the getRecordsFunc property for iterating through the returned records. Check the API documentation for which data tools and output types are available.

$result = $client->listgen('abm', ['domain' => ['versium.com']], ['abm_email', 'abm_online_audience']);

if ($result->success) {
    foreach (($result->getRecordsFunc)() as $record) {
        var_dump($record);
    }
}

Returned Results

Both the append and listgen functions return one or more APIResponse objects. See the comments in the class for descriptions of its properties.

Things to keep in mind

• The default rate limit for Reach APIs is 20 queries per second
• You must have a provisioned API key for this function to work. If you are unsure where to find your API key, look at our API key documentation