Wern Ancheta

Adventures in Web Development.

Stalking the Programmer Way With Clearbit's Person API

| Comments

In this tutorial, I’ll be showing you can programatically find out information about any person using their email. You can do that by using the Clearbit Person API.

In order to use the Person API, you first have to create your Clearbit account. After creating your account, you’ll be assigned with an API key which you can use for making requests to their API.

If you’re on Ruby, Node or Python you can search for the Clearbit client for each of those platforms from their Github page. Just search for ‘clearbit-’ followed by the platform. So if you’re on Ruby, then you search for ‘clearbit-ruby’. You can then install the client on your machine and follow the examples provided in the official documentation.

At the time of writing of this article, there’s still no client available for PHP. But you can use Guzzle to easily make requests to their API. You can install Guzzle via Composer by executing the following command.

1

composer require guzzlehttp/guzzle:~6.0

Once that’s done, you can include the vendor autoload file in your test file and then create a new instance of the Guzzle client. Use http://person.clearbit.com/v1/ as the base for all your requests.

1
2
3
4
5

<?php
require_once 'vendor/autoload.php';

$client = new GuzzleHttp\Client(array('base_uri' => 'http://person.clearbit.com/v1/'));
?>

To request the data of a specific person, you can pass their email after the people/email endpoint. Here’s an example.

1
2
3
4
5
6
7
8
9

<?php
$response = $client->get('people/email/ancheta.wern@gmail.com', array('auth' => array(
        'YOUR-CLEARBIT-API-KEY', ''
    )));
$res = json_decode($response->getBody(), true);
?>
<pre>
    <?php print_r($res); ?>
</pre>

Clearbit uses basic authentication. The API key acts as the username so the password should be left blank.

It would then return the following output.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147

Array
(
[id] => c29c2e9f-d082-4525-8dd3-1291835bf834
[name] => Array
    (
        [fullName] => Wern Ancheta
        [givenName] => Wern
        [familyName] => Ancheta
    )

[email] => ancheta.wern@gmail.com
[gender] => 
[location] => Philippines
[geo] => Array
    (
        [city] => 
        [state] => 
        [country] => PH
        [lat] => 12.879721
        [lng] => 121.774017
    )

[bio] => JavaScripter, PHP Junkie, Anime Fanatic, Pokemon Master, Supernatural Enthusiast
[site] => http://wern-ancheta.com
[avatar] => https://d1ts43dypk8bqh.cloudfront.net/v1/avatars/c29c2e9f-d082-4525-8dd3-1291835bf834
[employment] => Array
    (
        [name] => 
        [title] => 
        [domain] => 
    )

[facebook] => Array
    (
        [handle] => vern.ancheta
    )

[github] => Array
    (
        [handle] => 
        [id] => 
        [avatar] => 
        [company] => 
        [blog] => 
        [followers] => 
        [following] => 
    )

[twitter] => Array
    (
        [handle] => Wern_Ancheta
        [id] => 283769265
        [bio] => JavaScripter, PHP Junkie, Anime Fanatic, Pokemon Master, Supernatural Enthusiast
        [followers] => 330
        [following] => 961
        [statuses] => 7402
        [favorites] => 356
        [location] => Philippines
        [site] => http://wern-ancheta.com
        [avatar] => https://pbs.twimg.com/profile_images/2585189311/7q7dmz2h78lv32f8tw78.jpeg
    )

[linkedin] => Array
    (
        [handle] => 
    )

[googleplus] => Array
    (
        [handle] => 
    )

[angellist] => Array
    (
        [handle] => 
        [id] => 
        [bio] => 
        [blog] => 
        [site] => 
        [followers] => 
        [avatar] => 
    )

[klout] => Array
    (
        [handle] => 
        [score] => 
    )

[foursquare] => Array
    (
        [handle] => 
    )

[aboutme] => Array
    (
        [handle] => 
        [bio] => 
        [avatar] => 
    )

[gravatar] => Array
    (
        [handle] => zenonn
        [urls] => Array
            (
                [0] => Array
                    (
                        [value] => http://kyokasuigetsu25.wordpress.com
                        [title] => Data Integrated Entity Blog
                    )

                [1] => Array
                    (
                        [value] => http://wernancheta.wordpress.com
                        [title] => Wern Ancheta Web Development Blog
                    )

                [2] => Array
                    (
                        [value] => http://wernancheta.carbonmade.com
                        [title] => Wern Ancheta Portfolio
                    )

            )

        [avatar] => http://2.gravatar.com/avatar/717bcde740783a83a168468df0dbbb75
        [avatars] => Array
            (
                [0] => Array
                    (
                        [url] => http://2.gravatar.com/avatar/717bcde740783a83a168468df0dbbb75
                        [type] => thumbnail
                    )

                [1] => Array
                    (
                        [url] => http://0.gravatar.com/userimage/29616243/2e8d74c1260a1c180328ea6317ebb8e0
                        [type] => 
                    )

            )

    )

[fuzzy] => 
)

As you can see, it’s not very complete. It has left out my Github, LinkedIn, GooglePlus and FourSquare profiles. It doesn’t have one for Instagram as well. Nevertheless, this API proves to be a good resource if you want to get data about a specific person.

If you want to update your own data, extract the ID that clearbit has assigned to your profile and then use it on your request. Here’s an example.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

<?php
$client = new GuzzleHttp\Client(['base_uri' => 'http://person.clearbit.com/v1/']);
$response = $client->post('people/YOUR-CLEARBIT-ID/flag',
            array('auth' => array(
                'YOUR-CLEARBIT-API-KEY', ''
            ),
            'form_params' => array(
                'foursquare' => array('handle' => 'wern_ancheta'),
                'googleplus' => array('handle' => '+WernAncheta'),
                'github' => array(
                    'handle' => 'anchetaWern'
                ),
                'gender' => 'male',
                'linkedin' => array('handle' => 'wernr'),
                'gravatar' => array('handle' => 'vernancheta')
            )
        )
);
$res = json_decode($response->getBody(), true);
echo $response->getStatusCode(); //200
?>

Note that your data won’t be immediately update. This is good since the update must be reviewed by an actual human so that not just anyone can mess with your data.

Comments