NAV Navbar
Logo

cUrl
PHP
Python
JS

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?

How does it 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

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.