Back to Top

Card Reader

Overview

FullContact Card Reader API is a human based business card transcription service. The FullContact Card Reader API allows you to send images of business cards to FullContact, and you will receive back a response containing human transcribed structured contact data. The endpoint is a RESTful service where a developer can send front and back images of a business card to be transcribed and that data is returned back to you via a specified webhook callback URL.

Getting Started Resources

As you get started implementing the Card Reader API, there are a few resources that can help you out. Below we've listed a few libraries, services, and a sample app.

Libraries

  • Java Client for FullContact API (v2) by FullContact - A Java client to access most of FullContact's v2 API endpoints, including Person, Card Reader, Disposable Email, Name, and more.
  • Objective-C Library for FullContact API (v2) by FullContact - An Objective-C library to access FullContact's v2 API endpoints via iOS and Mac OS X. This is the same library we use in our own apps such as FullContact Card Reader.

Hello World Apps

Other Resources

  • RequestBin - RequestBin is a tool that collects requests made to it in a human friendly way. This is a great tool for inspecting and debugging webhook requests.

Upload Card

Use the Upload Card method to submit front and back photos of a business card for processing.

Requests

POST https://api.fullcontact.com/v2/cardReader?webhookUrl=xxxx&apiKey=xxxx

Required Parameter
Optional Parameter
copy
POST https://api.fullcontact.com/v2/cardReader?webhookUrl=myWebhookURL&apiKey=xxxx
POST https://api.fullcontact.com/v2/cardReader?format=xml&webhookUrl=myWebhookURL&apiKey=xxxx

Parameters

Name Description
apiKey This API key is assigned to you by FullContact. It is used to identify and authorize your request. Your API key should be kept private, and should never be displayed publicly.

For more information about our API, such as using an API key header vs query parameter, see our API Overview.
copy
POST https://api.fullcontact.com/v2/cardReader?webhookUrl=myWebhookURL&apiKey=xxxx
webhookUrl This is the URL that a request will be made to once the card has been processed. It must be URL Encoded:
copy
POST https://api.fullcontact.com/v2/cardReader?webhookUrl=myWebhookURL&apiKey=xxxx
http%3A%2F%2Fmydomain.com%2Fwebhook
Request Body You can either send in the files as a multipart/form-data request or as a JSON object with BASE64 encoded images:

(Back image is optional)

Note on image sizes: The minimum image size the POST will accept is 320px by 240px (smaller images will result in a 412 response code). Resolutions smaller than this tend to be difficult to transcribe. Also, please limit image sizes that you POST to the endpoint to be less than 6 MB (total of all images) as anything larger will be rejected with a 413 response code. We also recommend reducing sizes of larger images so that the longest dimension of either the height or width is 800px, while maintaining the aspect ratio on the other dimension.
copy
POST https://api.fullcontact.com/v2/cardReader?webhookUrl=myWebhookURL&apiKey=xxxx
{
    "front": "iVBORw0KGg...rQAAAAASUVORK5CYII=",
    "back": "iVBO...SUVORK5CYII="
}
Content-Disposition: form-data; name="front"; filename="front.png|jpg|gif"
Content-Type: image/png|jpg|gif
Content-Transfer-Encoding: binary

Content-Disposition: form-data; name="back"; filename="back.png|jpg|gif"
Content-Type: image/png|jpg|gif
Content-Transfer-Encoding: binary
                                
verified (optional)

Used to specify the quality of transcription. Calls to verified=medium|high require a FullContact premium account.

  • low (default if not specified) - a single human transcription is completed. On the pricing page this is the "Basic" level.
  • medium - human transcription plus single verification of each data element. On the pricing page this is the "Plus" level.
  • high - human transcription plus double verification of each data element. On the pricing page this is the "Premium" level.
copy
POST https://api.fullcontact.com/v2/cardReader?webhookUrl=myWebhookURL&verified=medium&apiKey=xxxx
returnedData (optional) A response can contain verified and unverified data, this parameter can be used to exclude unverified data from being returned in the response.

  • verifiedOnly - non-verified results will be excluded from the response payload.
copy
POST https://api.fullcontact.com/v2/cardReader?webhookUrl=myWebhookURL&returnedData=verifiedOnly&apiKey=xxxx
format (optional) Used to specify response in xml or json.
copy
POST https://api.fullcontact.com/v2/cardReader?format=json&webhookUrl=myWebhookURL&apiKey=xxxx
casing (optional) Card Reader can alter the casing of certain fields in the final results.
  • default - (default if not specified) - the data is not modified
  • uppercase - Affected fields are converted to UPPER CASE lettering
  • lowercase - Affected fields are converted to lower case lettering
  • titlecase - Affected fields are converted to Title Case lettering
Affected fields include name (given name, family name, and middle initial), organizations (title and name), and address fields.
copy
POST https://api.fullcontact.com/v2/cardReader?casing=titlecase&webhookUrl=myWebhookURL&apiKey=xxxx
sandbox (optional) Card Reader Sandbox is a free, quick response mode for testing and development.

Read Carefully on how each status option behaves, and what to expect while testing.
  • PROCESSING - The card will appear to be processing and never proceed to finish. There is no webhook.
  • CALLBACK_MADE - After a short delay a request will be sent to your webhook (If the webhook fails, it will become CALLBACK_FAILED).
  • CALLBACK_FAILED - There is no webhook, and the status is marked as CALLBACK_FAILED.
  • CALLBACK_MADE_NOT_PROCESSABLE - After a short delay, an unprocessable indication message will be sent to your webhook (If the webhook fails, it will become CALLBACK_FAILED_NOT_PROCESSABLE).
  • CALLBACK_FAILED_NOT_PROCESSABLE - There is no webhook, and the status is marked as CALLBACK_FAILED_NOT_PROCESSABLE.
copy
POST https://api.fullcontact.com/v2/cardReader?sandbox=CALLBACK_MADE&webhookUrl=myWebhookURL&apiKey=xxxx
  • Sandbox webhooks will look the exact same as the normal responses.
  • Sandbox uploads will have the same photos that you uploaded via POST.
  • Sandbox content will work and look the exact same as normal requests.
  • Other params such as returnedData, verified, format, etc... will work the same as normal requests.
  • Contact data for sandbox is predefined and always the same.
  • Sandbox cards will appear to be processing until a callback is made (if applicable).
  • The Sandbox 'short delay' before receiving a webhook ranges from 0 to 60 seconds.
URID (advanced - optional) URID stands for Unique Request Identifier.
  • If you pass in the URID parameter, we will make sure that the request you are referring to by this id is only processed once.
  • This can be useful in low connectivity environments where you might not get a response back, even though we've successfully handled your request.
  • By doing this, you can prevent duplicate or unknown webhooks to your application on retried requests.
To use this parameter, it is very important that your URID parameter is unique per image sent because any future requests with the given URID will simply point back to the first request with that URID.
copy
POST https://api.fullcontact.com/v2/cardReader?URID=12345-abcde-67890-vwxyz&webhookUrl=myWebhookURL&apiKey=xxxx
Example scenario to use this feature:
  • Mobile application sends a card, we receive it, we start processing it and send the application a 202 response.
  • The mobile application enters a low connectivity area and does not get a response.
  • The mobile application retries the request assuming it failed (however, it did not fail).
  • Without the URID parameter for this request, we start processing a new transcription and give you another 202.
  • This time the mobile application gets the response and is happy, but now also receives two webhooks, one being for a job that failed that has a different id.
Because both requests were for the same transcription, the mobile application could have created a URID for this request that is the same for both requests, and the second (retry) request would simply receive a 202 with the id for the first request and the second (retry) request is never processed and not duplicated.
Custom Params (advanced - optional) Card Reader has the ability to funnel your own custom params through requests.
These parameters will be passed back on every callback and GET response as the mapping key "params"
To use custom parameters, simply add any parameter that is not in the following list to your request.
(Note that the params below are stripped out of all requests - do not use!)
  • apiKey
  • webhookUrl
  • front
  • back
  • casing
  • format
  • verified
  • returnedData
  • sandbox
  • accessToken
  • controller
  • action
Note that all of the current optional and required params are in this list, and some of them do come back for your use but will not show up in the "params" list. The others are stripped out for security purposes.

Tips: Since it's always possible for us to release new features with optional parameters, we don't want custom parameters breaking your app.
To ensure your app will never conflict with our future updates, we suggest that you use a following strategy:
  • Prefix your custom parameters with a name and underscore. (Ex: For a custom field "lead": myapp_lead=mining)
  • Use the word custom to begin all your custom parameters. (Ex: customLead, custom_lead)
copy
POST https://api.fullcontact.com/v2/cardReader?myCustomParam=foobar&webhookUrl=myWebhookURL&apiKey=xxxx

Example Responses

The API responds with JSON or XML. The POST response will look like:

HTTP/1.1 202 ACCEPTED
Date: Wed Jul 30 19:12:36 UTC 2014 
Content-Type: application/json;charset=UTF-8
{
    "queued": true,
    "id": "xxxxxxxxxxxxxxx",
    "estimatedWaitTimeMinutes": 33,
    "status": 202
}
HTTP/1.1 202 ACCEPTED
Date: Wed Jul 30 19:12:36 UTC 2014 
Content-Type: text/xml;charset=UTF-8
<?xml version="1.0" encoding="UTF-8" ?>
<response>
  <queued>true</queued>
  <id>xxxxxxxxxxxxxxx</id>
  <estimatedWaitTimeMinutes>33</estimatedWaitTimeMinutes>
  <status>202</status>
</response>

An example post back response to the webhookUrl will look like:

HTTP/1.1 200 OK
Date: Wed Jul 30 19:12:36 UTC 2014 
Content-Type: application/json;charset=UTF-8
{
    "lastWebhookAttempt": "2013-02-05T00:37:38.000Z",
    "vCardUrl": "https://link-to-vcard.vcf",
    "id": "xxxxxxxxxxxxx",
    "webhookAttempts": 1,
    "webhookUrl": "http://link-to-webhook-server.com",
    "quality": "MEDIUM",
    "submitted": "2013-02-05T00:13:19.000Z",
    "contact": {
      "photos":
      [
        {
          "primary": false,
          "value": "https://link-to-image.jpg",
          "type": "BusinessCard"
        }
      ],
      "accounts":
      [
        {
          "username": "lorangb",
          "domain": "twitter.com",
          "urlString": "http://twitter.com/lorangb"
        }
      ],
      "organizations":
      [
        {
          "title": "CEO / Co-Founder",
          "isPrimary": false,
          "name": "FullContact"
        }
      ],
      "urls":
      [
        {
          "value": "www.fullcontact.com",
          "type": "other"
        }
      ],
      "name": {
        "familyName": "Lorang",
        "givenName": "Bart"
      },
      "phoneNumbers":
      [
        {
          "value": "(XXX) XXX-XXXX",
          "type": "work"
        }
      ],
      "emails":
      [
        {
          "value": "bart@fullcontact.com",
          "type": "work"
        }
      ]
    },
    "unverifiedFields": [
      "ims[0]"
    ],
    "unverifiedContact": {
      "photos":
      [
        {
          "primary": false,
          "value": "https://link-to-image.jpg",
          "type": "BusinessCard"
        }
      ],
      "accounts":
      [
        {
          "username": "lorangb",
          "domain": "twitter.com",
          "urlString": "http://twitter.com/lorangb"
        }
      ],
      "organizations":
      [
        {
          "title": "CEO / Co-Founder",
          "isPrimary": false,
          "name": "FullContact"
        }
      ],
      "urls":
      [
        {
          "value": "www.fullcontact.com",
          "type": "other"
        }
      ],
      "name": {
        "familyName": "Lorang",
        "givenName": "Bart"
      },
      "phoneNumbers":
      [
        {
          "value": "(XXX) XXX-XXXX",
          "type": "work"
        }
      ],
      "emails":
      [
        {
          "value": "bart@fullcontact.com",
          "type": "work"
        }
      ],
      "ims": 
      [
        {
          "value": "bart",
          "type": "skype"
        }
      ]
    },
  "unverifiedVCardUrl": "https://link-to-unverified-vcard.vcf"
}
HTTP/1.1 200 OK
Date: Wed Jul 30 19:12:36 UTC 2014 
Content-Type: text/xml;charset=UTF-8
<?xml version="1.0" encoding="UTF-8" ?>
<response>
	<lastWebhookAttempt>2013-02-05T00:37:38.000Z</lastWebhookAttempt>
	<webhookAttempts>1</webhookAttempts>
	<webhookUrl>http://link-to-webhook-server.com</webhookUrl>
	<quality>MEDIUM</quality>
	<submitted>2013-02-05T00:13:19.000Z</submitted>
	<vCardUrl>https://link-to-vcard.vcf</vCardUrl>
	<id>xxxxxxxxxxxxx</id>
	<contact>
		<photos>
			<photo>
				<primary>false</primary>
				<value>
				https://link-to-image.JPEG
				</value>
				<type>BusinessCard</type>
			</photo>
		</photos>
		<accounts>
			<account>
				<username>lorangb</username>
				<domain>twitter.com</domain>
				<urlString>http://twitter.com/lorangB</urlString>
			</account>
		</accounts>
		<organizations>
			<organization>
				<title>CEO / Co-Founder</title>
				<isPrimary>false</isPrimary>
				<name>FullContact</name>
			</organization>
		</organizations>
		<urls>
			<url>
				<value>www.fullcontact.com</value>
				<type>other</type>
			</url>
		</urls>
		<name>
			<familyName>Lorang</familyName>
			<givenName>Bart</givenName>
		</name>
		<phoneNumbers>
			<phoneNumber>
				<value>(XXX) XXX-XXXX</value>
				<type>work</type>
			</phoneNumber>
		</phoneNumbers>
		<emails>
			<email>
				<value>bart@fullcontact.com</value>
				<type>work</type>
			</email>
		</emails>
	</contact>
	<unverifiedFields>  
	    <unverifiedField>ims[0]</unverifiedField>	
	</unverifiedFields>
	<unverifiedContact>
		<photos>
			<photo>
				<primary>false</primary>
				<value>
				https://link-to-image.JPEG
				</value>
				<type>BusinessCard</type>
			</photo>
		</photos>
		<accounts>
			<account>
				<username>lorangb</username>
				<domain>twitter.com</domain>
				<urlString>http://twitter.com/lorangB</urlString>
			</account>
		</accounts>
		<organizations>
			<organization>
				<title>CEO / Co-Founder</title>
				<isPrimary>false</isPrimary>
				<name>FullContact</name>
			</organization>
		</organizations>
		<urls>
			<url>
				<value>www.fullcontact.com</value>
				<type>other</type>
			</url>
		</urls>
		<name>
			<familyName>Lorang</familyName>
			<givenName>Bart</givenName>
		</name>
		<phoneNumbers>
			<phoneNumber>
				<value>(XXX) XXX-XXXX</value>
				<type>work</type>
			</phoneNumber>
		</phoneNumbers>
		<emails>
			<email>
				<value>bart@fullcontact.com</value>
				<type>work</type>
			</email>
		</emails>
		<ims>
			<im>
				<value>bart</value>
				<type>skype</type>
			</im>
		</ims>
	</unverifiedContact>
	<unverifiedVCardUrl>https://link-to-unverified-vcard.vcf</unverifiedVCardUrl>
</response>

If a job is not processable the post back to the webhookUrl will contain the following response.

HTTP/1.1 400 Bad Request
Date: Wed Jul 30 19:12:36 UTC 2014 
Content-Type: application/json;charset=UTF-8
{
"status": 400,
"id": "xxxxxxxxxxxxxxx",
"message": "The image sent was not processable.  Please ensure the image contains clearly legible contact information."
}
HTTP/1.1 400 Bad Request
Date: Wed Jul 30 19:12:36 UTC 2014 
Content-Type: text/xml;charset=UTF-8
<?xml version="1.0" encoding="UTF-8" ?>
<response>
    <status>200</status>
    <id>xxxxxxxxxxxxxxx</id>
    <message>The image sent was not processable.  Please ensure the image contains clearly legible contact information.</message>
</response>

Response Schema

The callback will have a response schema as below.

HTTP/1.1 200 Success
Date: Wed Jul 30 19:12:36 UTC 2014 
Content-Type: application/json;charset=UTF-8
{
    "lastWebhookAttempt": {"type":"string"}, // UTC Time in ISO 8601 format - JSON null if 0 attempts have been made
    "webhookAttempts": {"type":"number"},
    "webhookUrl": {"type":"string"}, 
    "quality":  {"type":"string"}, // "LOW", "MEDIUM", or "HIGH"
    "submitted": {"type":"string"}, // UTC Time in ISO 8601 format
    "contact": {
        "addresses": [
            {
                "country": {"type":"string"},
                "type": {"type":"string"},   // currently always "work"
                "locality": {"type":"string"},
                "extendedAddress": {"type":"string"},  // currently always null
                "postalCode": {"type":"string"},
                "formatted": {"type":"string"},  // currently always null
                "region": {"type":"string"},
                "streetAddress": {"type":"string"}  // pipe delimited for up to 4 lines of address "address line 1 | address line 2 | etc."
            }
        ],
        "emails": [
            {
                "type": {"type":"string"},  // currently always "work"
                "value": {"type":"string"}
            }
        ],
        "phoneNumbers": [
            {
                "type": {"type":"string"},  // currently supporting "home", "pager", "other", "work fax", "mobile", "main", or "work"
                "value": {"type":"string"}
            }
        ],
        "name": {
            "honorificSuffix": {"type":"string"},  // currently always null
            "givenName": {"type":"string"},
            "familyName": {"type":"string"},
            "honorificPrefix": {"type":"string"},  // currently always null
            "middleName": {"type":"string"}
        },
        "urls": [
            {
                "type": {"type":"string"},  // currently either "company" or up to three results of type "other"
                "value": {"type":"string"}
            }
        ],
        "organizations": [
            {
                "name": {"type":"string"},
                "isPrimary": {"type":"boolean"},
                "title": {"type":"string"}
            }
        ],
        "ims": [
            {
                "type": {"type":"string"},
                "value": {"type":"string"}
            }
        ],
        "accounts": [
            {
                "urlString": {"type":"string"},
                "domain": {"type":"string"},
                "userid": {"type":"string"},
                "username": {"type":"string"}
            }
        ],
        "photos": [
            {
                "type": {"type":"string"},  // currently always "BusinessCard"
                "value": {"type":"string"},
                "primary": {"type":"boolean"}
            }
        ]
    },
    "id": {"type":"string"},
    "vCardUrl": {"type":"string"},
    "unverifiedContact":{
        "addresses": [
            {
                "country": {"type":"string"},
                "type": {"type":"string"},   // currently always "work"
                "locality": {"type":"string"},
                "extendedAddress": {"type":"string"},  // currently always null
                "postalCode": {"type":"string"},
                "formatted": {"type":"string"},  // currently always null
                "region": {"type":"string"},
                "streetAddress": {"type":"string"}  // pipe delimited for up to 4 lines of address "address line 1 | address line 2 | etc."
            }
        ],
        "emails": [
            {
                "type": {"type":"string"},  // currently always "work"
                "value": {"type":"string"}
            }
        ],
        "phoneNumbers": [
            {
                "type": {"type":"string"},  // currently supporting "home", "pager", "other", "work fax", "mobile", "main", or "work"
                "value": {"type":"string"}
            }
        ],
        "name": {
            "honorificSuffix": {"type":"string"},  // currently always null
            "givenName": {"type":"string"},
            "familyName": {"type":"string"},
            "honorificPrefix": {"type":"string"},  // currently always null
            "middleName": {"type":"string"}
        },
        "urls": [
            {
                "type": {"type":"string"},  // currently either "company" or up to three results of type "other"
                "value": {"type":"string"}
            }
        ],
        "organizations": [
            {
                "name": {"type":"string"},
                "isPrimary": {"type":"boolean"},
                "title": {"type":"string"}
            }
        ],
        "ims": [
            {
                "type": {"type":"string"},
                "value": {"type":"string"}
            }
        ],
        "accounts": [
            {
                "urlString": {"type":"string"},
                "domain": {"type":"string"},
                "userid": {"type":"string"},
                "username": {"type":"string"}
            }
        ],
        "photos": [
            {
                "type": {"type":"string"},  // currently always "BusinessCard"
                "value": {"type":"string"},
                "primary": {"type":"boolean"}
            }
        ]
    },
    "unverifiedVCardUrl": {"type":"string"},
    "unverifiedFields": [
    	{"type":"string"}  //  examples include "ims[0]", "emails[2]" or "familyName" etc.
    ]
}

View Single Request

Use the view single request method to view a specific transcription.

Requests

GET https://api.fullcontact.com/v2/cardReader/xxxxx?apiKey=xxxx

Required Parameter
Optional Parameter
copy
GET https://api.fullcontact.com/v2/cardReader/xxx?apiKey=xxxx
GET https://api.fullcontact.com/v2/cardReader/xxx?format=xml&apiKey=xxxx

Parameters

Name Description
apiKey This API key is assigned to you by FullContact. It is used to identify and authorize your request. Your API key should be kept private, and should never be displayed publicly.

For more information about our API, such as using an API key header vs query parameter, see our API Overview.
copy
GET https://api.fullcontact.com/v2/cardReader/xxx?apiKey=xxxx
id The id of a specific request.
copy
GET https://api.fullcontact.com/v2/cardReader/xxx?apiKey=xxxx
returnedData (optional) A response can contain verified and unverified data, this parameter can be used to exclude unverified data from being returned in the response.

verifiedOnly - non-verified results will be excluded from the response payload.
copy
GET https://api.fullcontact.com/v2/cardReader/xxx?returnedData=verifiedOnly&apiKey=xxxx
format (optional) Used to specify response in xml or json.
copy
GET https://api.fullcontact.com/v2/cardReader/xxx?format=json&apiKey=xxxx
diagnostics (optional) With this parameter you can see what the response from your own server was when we sent out your webhook.
copy
GET https://api.fullcontact.com/v2/cardReader/xxx?diagnostics=true&apiKey=xxxx
This parameter will conditionally add the following key-values to the response of your view requests that include:
  • clientServerResponseCode - The most recent integer response code your server returned.
  • clientServerResponseBody - The most recent response body your server returned as a string.
Important Notes:
  • These keys will only show up if data is present - so you will not see this information until we make at least one webhook attempt even if you include the diagnostics parameter in your request.
  • The clientServerResponseBody is limited to 512 characters.
  • If your server return status is 200, clientServerResponseBody will not be present.
  • This parameter will only add these key-values on transcriptions with webhooks made after May 29th, 2013.

Example Responses

The API responds with JSON or XML.

HTTP/1.1 200 OK
Date: Wed Jul 30 19:12:36 UTC 2014 
Content-Type: application/json;charset=UTF-8
{
    "lastWebhookAttempt": "2013-02-05T00:37:38.000Z",
    "webhookAttempts": 1,
    "webhookUrl": "http://link-to-webhook-server.com",
    "quality": "MEDIUM",
    "submitted": "2013-02-05T00:13:19.000Z",							
    "vCardUrl": "https://link-to-vcard.vcf",
    "status": "CALLBACK_MADE",
    "clientServerResponseCode": 200,
    "id": "xxxxxxxxxxxxx",
    "contact": {
      "photos":
      [
        {
          "primary": false,
          "value": "https://link-to-image.jpg",
          "type": "BusinessCard"
        }
      ],
      "accounts":
      [
        {
          "username": "lorangb",
          "domain": "twitter.com",
          "urlString": "http://twitter.com/lorangb"
        }
      ],
      "organizations":
      [
        {
          "title": "CEO / Co-Founder",
          "isPrimary": false,
          "name": "FullContact"
        }
      ],
      "urls":
      [
        {
          "value": "www.fullcontact.com",
          "type": "other"
        }
      ],
      "name": {
        "familyName": "Lorang",
        "givenName": "Bart"
      },
      "phoneNumbers":
      [
        {
          "value": "(XXX) XXX-XXXX",
          "type": "work"
        }
      ],
      "emails":
      [
        {
          "value": "bart@fullcontact.com",
          "type": "work"
        }
      ]
    },
    "params": { "my-custom-param": "xxxxx" }
  }
HTTP/1.1 200 OK
Date: Wed Jul 30 19:12:36 UTC 2014 
Content-Type: text/xml;charset=UTF-8
<?xml version="1.0" encoding="UTF-8" ?>
<response>
    <lastWebhookAttempt>2013-02-05T00:37:38.000Z</lastWebhookAttempt>
    <webhookAttempts>1</webhookAttempts>
    <webhookUrl>http://link-to-webhook-server.com</webhookUrl>
    <quality>MEDIUM</quality>
    <submitted>2013-02-05T00:13:19.000Z</submitted>
    <vCardUrl>https://link-to-vcard.vcf</vCardUrl>
    <status>CALLBACK_MADE</status>
    <clientServerResponseCode>200</clientServerResponseCode>
    <id>xxxxxxxxxxxxx</id>
    <contact>
        <photos>
            <photo>
                <primary>false</primary>
                <value>
                https://link-to-image.JPEG
                </value>
                <type>BusinessCard</type>
            </photo>
        </photos>
        <accounts>
            <account>
                <username>lorangb</username>
                <domain>twitter.com</domain>
                <urlString>http://twitter.com/lorangB</urlString>
            </account>
        </accounts>
        <organizations>
            <organization>
                <title>CEO / Co-Founder</title>
                <isPrimary>false</isPrimary>
                <name>FullContact</name>
            </organization>
        </organizations>
        <urls>
            <url>
                <value>www.fullcontact.com</value>
                <type>other</type>
            </url>
        </urls>
        <name>
            <familyName>Lorang</familyName>
            <givenName>Bart</givenName>
        </name>
        <phoneNumbers>
            <phoneNumber>
                <value>(XXX) XXX-XXXX</value>
                <type>work</type>
            </phoneNumber>
        </phoneNumbers>
        <emails>
            <email>
                <value>bart@fullcontact.com</value>
                <type>work</type>
            </email>
        </emails>
    </contact>
    <params>
    	<my-custom-param>xxxxxxx</my-custom-param>	
    </params>
</response>
HTTP/1.1 404 File Not Found
Date: Wed Jul 30 19:12:36 UTC 2014 
Content-Type: application/json;charset=UTF-8
{
  "response": "Request failed, job was not found",
  "status": 404
}
HTTP/1.1 404 File Not Found
Date: Wed Jul 30 19:12:36 UTC 2014 
Content-Type: text/xml;charset=UTF-8
<?xml version="1.0" encoding="UTF-8" ?>
<response>
	<response>Request failed, job was not found</response>
	<status>404</status>
</response>

View Requests

Use the view requests method to view a paged history of your transcriptions.

Requests

GET https://api.fullcontact.com/v2/cardReader?page=0&apiKey=xxxx

Required Parameter
Optional Parameter
copy
GET https://api.fullcontact.com/v2/cardReader?page=0&apiKey=xxxx
GET https://api.fullcontact.com/v2/cardReader?format=xml&page=0&apiKey=xxxx

Parameters

Name Description
apiKey This API key is assigned to you by FullContact. It is used to identify and authorize your request. Your API key should be kept private, and should never be displayed publicly.

For more information about our API, such as using an API key header vs query parameter, see our API Overview.
copy
GET https://api.fullcontact.com/v2/cardReader?apiKey=xxxx
page (optional) Used to page through the results. If not specified, it defaults to the first page (0).
copy
GET https://api.fullcontact.com/v2/cardReader?page=0&apiKey=xxxx
returnedData (optional) A response can contain verified and unverified data, this parameter can be used to exclude unverified data from being returned in the response.

verifiedOnly - non-verified results will be excluded from the response payload.
copy
GET https://api.fullcontact.com/v2/cardReader?returnedData=verifiedOnly&apiKey=xxxx
format (optional) Used to specify response in xml or json.
copy
GET https://api.fullcontact.com/v2/cardReader?format=json&apiKey=xxxx
diagnostics (optional) With this parameter you can see what the response from your own server was when we sent out your webhook.
copy
GET https://api.fullcontact.com/v2/cardShark?diagnostics=true&apiKey=xxxx
This parameter will conditionally add the following key-values to the response of your view requests that include:
  • clientServerResponseCode - The most recent integer response code your server returned.
  • clientServerResponseBody - The most recent response body your server returned as a string.
Important Notes:
  • These keys will only show up if data is present - so you will not see this information until we make at least one webhook attempt even if you include the diagnostics parameter in your request.
  • The clientServerResponseBody is limited to 512 characters.
  • If your server return status is 200, clientServerResponseBody will not be present.
  • This parameter will only add these key-values on transcriptions with webhooks made after May 29th, 2013.

Example Responses

The API responds with JSON or XML.

HTTP/1.1 200 OK
Date: Wed Jul 30 19:12:36 UTC 2014 
Content-Type: application/json;charset=UTF-8
{
  "status": 200,
  "currentPage":0,
  "totalPages":11,
  "totalRecords":208,
  "count":20,  
  "results": [
  {
      "lastWebhookAttempt": null,
      "id": "xxxxxxxxxxxxx",
      "webhookAttempts": 0,
      "status": "PROCESSING",
      "webhookUrl": "http://link-to-webhook-server.com",
      "quality": "LOW",
      "submitted": "2013-02-05T20:19:19.000Z",
      "params": { "my-custom-param": "xxxxx" }
  },
  {
    "lastWebhookAttempt": "2013-02-05T00:37:38.000Z",
    "webhookAttempts": 1,
    "webhookUrl": "http://link-to-webhook-server.com",
    "quality": "MEDIUM",
    "submitted": "2013-02-05T00:13:19.000Z",							
    "vCardUrl": "https://link-to-vcard.vcf",
    "status": "CALLBACK_MADE",
    "clientServerResponseCode": 200,
    "id": "xxxxxxxxxxxxx",
    "contact": {
      "photos":
      [
        {
          "primary": false,
          "value": "https://link-to-image.jpg",
          "type": "BusinessCard"
        }
      ],
      "accounts":
      [
        {
          "username": "lorangb",
          "domain": "twitter.com",
          "urlString": "http://twitter.com/lorangb"
        }
      ],
      "organizations":
      [
        {
          "title": "CEO / Co-Founder",
          "isPrimary": false,
          "name": "FullContact"
        }
      ],
      "urls":
      [
        {
          "value": "www.fullcontact.com",
          "type": "other"
        }
      ],
      "name": {
        "familyName": "Lorang",
        "givenName": "Bart"
      },
      "phoneNumbers":
      [
        {
          "value": "(XXX) XXX-XXXX",
          "type": "work"
        }
      ],
      "emails":
      [
        {
          "value": "bart@fullcontact.com",
          "type": "work"
        }
      ]
    }
  }]
}
HTTP/1.1 200 OK
Date: Wed Jul 30 19:12:36 UTC 2014 
Content-Type: text/xml;charset=UTF-8
<?xml version="1.0" encoding="UTF-8" ?>
<response>
    <results>
        <lastWebhookAttempt></lastWebhookAttempt>
        <webhookAttempts>0</webhookAttempts>
        <webhookUrl>http://link-to-webhook-server.com</webhookUrl>
        <quality>LOW</quality>
        <submitted>2013-02-05T20:19:19.000Z</submitted>
        <vCardUrl>https://link-to-vcard.vcf</vCardUrl>
        <id>xxxxxxxxxxxxx</id>
        <status>PROCESSING</status>
        <params>
            <my-custom-param>xxxxxxx</my-custom-param>	
        </params>
    </results>
    <results>
        <lastWebhookAttempt>2013-02-05T00:37:38.000Z</lastWebhookAttempt>
        <webhookAttempts>1</webhookAttempts>
        <webhookUrl>http://link-to-webhook-server.com</webhookUrl>
        <quality>MEDIUM</quality>
        <submitted>2013-02-05T00:13:19.000Z</submitted>
        <vCardUrl>https://link-to-vcard.vcf</vCardUrl>
        <id>xxxxxxxxxxxxx</id>
        <status>CALLBACK_MADE</status>
        <clientServerResponseCode>200</clientServerResponseCode>
        <contact>
            <photos>
                <photo>
                    <primary>false</primary>
                    <value>
                    https://link-to-image.JPEG
                    </value>
                    <type>BusinessCard</type>
                </photo>
            </photos>
            <accounts>
                <account>
                    <username>lorangb</username>
                    <domain>twitter.com</domain>
                    <urlString>http://twitter.com/lorangB</urlString>
                </account>
            </accounts>
            <organizations>
                <organization>
                    <title>CEO / Co-Founder</title>
                    <isPrimary>false</isPrimary>
                    <name>FullContact</name>
                </organization>
            </organizations>
            <urls>
                <url>
                    <value>www.fullcontact.com</value>
                    <type>other</type>
                </url>
            </urls>
            <name>
                <familyName>Lorang</familyName>
                <givenName>Bart</givenName>
            </name>
            <phoneNumbers>
                <phoneNumber>
                    <value>(XXX) XXX-XXXX</value>
                    <type>work</type>
                </phoneNumber>
            </phoneNumbers>
            <emails>
                <email>
                    <value>bart@fullcontact.com</value>
                    <type>work</type>
                </email>
            </emails>
        </contact>
    </results>
    <count>20</count>
    <status>200</status>
    <totalRecords>208</totalRecords>
    <currentPage>0</currentPage>
    <totalPages>11</totalPages>
</response>

Repost Webhook (Debugging)

When transcriptions finish, we send webhooks to your specified webhookUrl. Use this to re-fire them.

Requests

POST https://api.fullcontact.com/v2/cardReader/xxxxx/repostWebhook?apiKey=xxxx

Required Parameter
Optional Parameter
copy
POST https://api.fullcontact.com/v2/cardReader/xxx/repostWebhook?apiKey=xxxx
POST https://api.fullcontact.com/v2/cardReader/xxx/repostWebhook?format=xml&apiKey=xxxx

Parameters

Name Description
apiKey This API key is assigned to you by FullContact. It is used to identify and authorize your request. Your API key should be kept private, and should never be displayed publicly.

For more information about our API, such as using an API key header vs query parameter, see our API Overview.
copy
POST https://api.fullcontact.com/v2/cardReader/xxx/repostWebhook?apiKey=xxxx
id The id of a specific request.
copy
POST https://api.fullcontact.com/v2/cardReader/xxx/repostWebhook?apiKey=xxxx
format (optional) Used to specify response in xml or json. This will NOT change the response format of the webhook, only the response format of this particular request
copy
POST https://api.fullcontact.com/v2/cardReader/xxx/repostWebhook?format=json&apiKey=xxxx

Example Responses

The API responds with JSON or XML.

HTTP/1.1 200 OK
Date: Wed Jul 30 19:12:36 UTC 2014 
Content-Type: application/json;charset=UTF-8
{
    "message": "Successfully reposted webhook for id xxxxxx. Webhook should POST shortly...",
    "status": 200
}
HTTP/1.1 200 OK
Date: Wed Jul 30 19:12:36 UTC 2014 
Content-Type: text/xml;charset=UTF-8
<?xml version="1.0" encoding="UTF-8" ?>
<response>
  <message>Successfully reposted webhook for id xxxxxx. Webhook should POST shortly...</message>
  <status>200</status>
</response>
HTTP/1.1 400 Bad Request
Date: Wed Jul 30 19:12:36 UTC 2014 
Content-Type: application/json;charset=UTF-8
{
    "message": "Request failed, you cannot retry a webhook until the job has finished processing completely.",
    "status": 400
}
HTTP/1.1 400 Bad Request
Date: Wed Jul 30 19:12:36 UTC 2014 
Content-Type: text/xml;charset=UTF-8
<?xml version="1.0" encoding="UTF-8" ?>
<response>
  <message>Request failed, you cannot retry a webhook until the job has finished processing completely.</message>
  <status>400</status>
</response>
HTTP/1.1 404 File Not Found
Date: Wed Jul 30 19:12:36 UTC 2014 
Content-Type: application/json;charset=UTF-8
{
  "response": "Request failed, job was not found",
  "status": 404
}
HTTP/1.1 404 File Not Found
Date: Wed Jul 30 19:12:36 UTC 2014 
Content-Type: text/xml;charset=UTF-8
<?xml version="1.0" encoding="UTF-8" ?>
<response>
  <message>Request failed, job was not found</message>
  <status>404</status>
</response>

Statuses

Status Description
PROCESSING The job request for the image(s) is processing.
CALLBACK_MADE A successful http POST response callback has been made to the webhook URL. No further action will be completed for the job request.
CALLBACK_FAILED The http POST attempt was made to the webhook URL but the recipient server did not respond or responded with error. The request will be retried up to 5 times at 1 minute retry intervals.
CALLBACK_MADE_NOT_PROCESSABLE A successful http POST response callback has been made to the webhook URL. The job request could not be completed. This could be due to a number of issues such as illegible image(s), images that don't contain contact information, etc.
CALLBACK_FAILED_NOT_PROCESSABLE The http POST attempt was made to the webhook URL but the recipient server did not respond or responded with error. The request will be retried up to 5 times at 1 minute retry intervals. The job request could not be completed. This could be due to a number of issues such as illegible image(s), images that don't contain contact information, etc.

Card Reader API Diagram

Last modified: May 09 2014 13:10:49