Introduction
CloudVCard API Documentation
CloudVCard is a ContactInformation as a Service (CIaaS) platform that acts as a single source of truth for contact information.
This contact information is provided by the owners of the contact information themselves who sign up to our service. Where we can validate the contact information (like phonenumber, email address and social networking sites), we will. But more important is the way we allow people to search for this information without giving up privacy of contact information during the search. By using a method that we call fingerprinting of contacts, users are able to search for these contacts without having to share this contact information with us. We only need the fingerprint to find a match, not the actually contact information.
Example code available for cUrl, PHP, Python and NodeJS/Javascript
How does our algorithm work?
Contact information goes through our fingerprinting algorithm which in result, returns a list of irreversible hashes that can be used by the platform to identify an end user. By running this algorithm on your devices/clients/servers, the privacy of your contacts is guaranteed because the contact information itself will never leave the device. Only the irreversible hashes are transferred to our platform to try to match them with a CloudVCard id. Guaranteeing the privacy of the contact information and the end user.
How can I use the API?
Our API documentation explains how developers can easily integrate our platform with their scripts, products, services, webshop, CRM, billing or any other system. We do this by providing detailed examples on how to request and interact with our API and what to expect as result. These codes examples are available for cUrl, Python and javascript but can easily be used in any other language.
All our API’s are designed to work independently or in combination with eachother. Our API’s are organized around REST and are designed to have predictable, resource-oriented URLs that use HTTP response codes to indicate API errors.
Authenticate
Request API access
CloudVCard uses JWT Tokens to authenticate to the API. Requesting such a token can be done by scanning the QR code below with the CloudVCard APP. In the background, we use CloudVCards campaign system to handle the workflow for these requests. If you are viewing this documentation on a device with CloudVCard installed, you can also click here: CloudVCard API Request
Usage
<?php
require('CloudVCard');
$api = new CloudVCard('1');
$api.APIClient.authorize('<API Token>');
import CloudVCard
CloudVCard.version('1')
api = CloudVCard.authorize('<API Token>')
curl "https://api.cloudvcard.com/v1/system/checkToken"
-H "Authorization: <API Token>"
var cvc = require('CloudVCard');
cvc.version('1')
let api = cvc.authorize('<API Token>');
Using our API is easy. You can select your preferred scripting language at the top right corner of your screen. This will make sure you get the code examples in your prefered scripting language. Next step is to make sure you have a valid API authentication token. You can request your own by scanning the QR code above with the CloudVCard app or by following the link on a device with CloudVCard installed. Processing your request can take up to 24h, but this delay will be removed in the near future. Currently you can use the limited set of API calls that are mentioned below, but we are working hard to make all functionality you have in the app available via API.
VCards
Retrieve VCards (Public Info)
<?php
require('CloudVCard');
$api = new CloudVCard('1');
$api.APIClient.authorize('<API Token>');
$vcard = $api.VCards.getPublic(["<ID>"]); # Replace <ID> with the vcard id you want to request.
import CloudVCard
CloudVCard.version('1')
api = CloudVCardv1.authorize('<API Token>')
api.vcards.getPublic("<ID>") # Replace <ID> with the vcard id you want to request.
curl "https://api.cloudvcard.com/v1/vcards/getPublic?ids[]=<ID>"
-H "Authorization: Bearer <API Token>"
var cvc = require('CloudVCard');
cvc.version('1')
let api = cvc.authorize('<API Token>');
let vcards = api.cvc.vcards.getPublic(["<ID>"]); # Replace <ID> with the vcard id you want to request.
The above code returns:
{
"result": [
{
"found": true,
"ispublic": false,
"id": "fdc2274c-2edf-4d73-9e88-e52e8ee9f90d",
"isdefault": true,
"type": "work",
"lastupdated": 1483662108,
"creationdate": 1483662108,
"name": "Lucas",
"firstname": "Jonathan",
"title": "Project Manager",
"photo": "https://cdn.cloudvcard.com/photo/ddc2274c-2edf-4d73-9e88-e52e8ee9f90d.png",
"companyname": "Some Company"
}
],
"transactionid": "--SJy!qIe5l--"
}
This endpoint retrieves vcards information that is publicly available. If you wish to receive all information (which will only return more information if you have an active connection with the vcard), you can use the get request instead.
HTTP Request
GET https://api.cloudvcard.com/v1/vcard/getPublic?ids[]=<ID>
Query Parameters
Parameter | Default | Description |
---|---|---|
ids | A list of vcard ids for which to retrieve the public information from (limit: 20) |
Retrieve VCards
<?php
require('CloudVCard');
$api = new CloudVCard('1');
$api.APIClient.authorize('<API Token>');
$vcard = $api.VCard.get(["<uuid>"]); # Replace <uuid> with the vcard id you want to request.
import CloudVCard
CloudVCard.version('1')
api = CloudVCardv1.authorize('<API Token>')
api.vcard.get(["<uuid>"]) # Replace <uuid> with the vcard id you want to request.
curl "https://api.cloudvcard.com/v1/vcard/get?ids[]=<ID>"
-H "Authorization: Bearer <API Token>"
var cvc = require('CloudVCard');
cvc.version('1')
let api = cvc.authorize('<API Token>');
let vcard = api.cvc.vcards.get(["<ID>"]); # Replace <ID> with the vcard id you want to request.
The above code returns:
{
"result": [
{
"found": true,
"ispublic": false,
"id": "fdc2274c-2edf-4d73-9e88-e52e8ee9f90d",
"isdefault": true,
"type": "work",
"lastupdated": 1483662108,
"creationdate": 1483662108,
"numbers": [
{
"numbertype": "cell",
"number": "+33 00 00 00",
"isconfirmed": false,
"isdefault": true
}
],
"emails": [
{
"email": "info@example.com",
"isconfirmed": true,
"isdefault": true
}
],
"addresses": [
{
"street": "Street 123",
"mailbox": "",
"city": "City",
"zipcode": "2599",
"countrycode": "BE",
"country": "Belgium",
"isconfirmed": false,
"isdefault": true
}
],
"name": "Lucas",
"firstname": "Jonathan",
"title": "Project Manager",
"photo": "https://cdn.cloudvcard.com/photo/ddc2274c-2edf-4d73-9e88-e52e8ee9f90d.png",
"companyname": "Some Company"
}
],
"transactionid": "--SJy!qIe5l--"
}
This endpoint retrieves an array of vcards. Response can be either the complete vcard (in case a connection exists or in case of a public vcard) or the minimal information which is the same as getPublic. In order to retrieve all contact information, an active connection is required.
HTTP Request
GET https://api.cloudvcard.com/v1/vcards/get?ids[]=<ID>
Query Parameters
Parameter | Default | Description |
---|---|---|
ids | A list of vcard ids for which to receive the contact information (limit: 20) |
Search fingerprints
<?php
require('CloudVCard');
$api = new CloudVCard('1');
$api.APIClient.authorize('<API Token>');
$vcard = $api.VCards.search("<fingerprints>"); # Replace <fingerprints> with an array of fingerprints you want to search for.
import CloudVCard
CloudVCard.version('1')
api = CloudVCardv1.authorize('<API Token>')
api.vcards.search("<fingerprints>") # Replace <uuid> with the vcard id you want to request.
curl "https://api.cloudvcard.com/v1/vcards/search"
-H "Authorization: Bearer <API Token>"
-H "Accept: application/json"
-X POST
-d '{"fingerprints":[<ID>]}'
const cvc = require('CloudVCard');
cvc.version('1')
let contacts = [{
firstname: 'Demo',
lastname: 'User',
emails: ['demouser@example.com'],
phoneNumbers: ['+33 00 00 00']
}]
let fingerprints = cvc.generateFingerprints(contacts);
let api = cvc.authorize('<API Token>');
let vcard = api.cvc.vcards.search("<fingerprints>"); // Replace <fingerprints> with the vcard id you want to request.
The above code returns:
{
"result": [
{
"fingerprint": "NAME:da2a5890bf308fa4;SURNAME:f97ffd0373f5f6e3;BIRTHDAY:eef6b1edfec14b9f;MAIL:2927a259c0253af6",
"found": false
},
{
"fingerprint": "NAME:da2a5890bf308fa4;SURNAME:f97ffd0373f5f6e3;BIRTHDAY:eef6b1edfec14b9f;MAIL:2927a259c0253af6",
"found": true,
"vcardid": "uuid",
"score": 98
}
],
"transactionid": "--3!5g7u4my--"
}
This endpoint allows you to search vcards based on fingerprints of the contact information of your contacts.
HTTP Request
POST https://api.cloudvcard.com/v1/vcards/search
Query Parameters
Parameter | Default | Description |
---|---|---|
fingerprints | Provide an array of fingerprints |
Error Codes
The CloudVCard API uses the following error codes:
Error Code | Meaning |
---|---|
400 | Bad Request – Invalid request |
401 | Unauthorized – Forgot your API key or API key is invalid, see error message |
403 | Forbidden – You are not allowed to perform this request |
404 | Not Found – The requested resource could not be found |
406 | Not Acceptable – You requested a format that isn’t json |
418 | I’m a teapot – Some things you just can’t miss. |
422 | Unprocessable Entity – The parameters you provided are invalid |
429 | Too Many Requests – You’re requesting too many resources! Slow down! |
500 | Internal Server Error – We had a problem with our server. Try again later. |
503 | Service Unavailable – We’re temporarily offline for maintenance. Please try again later. |