Introduction

Verifeyed provides a programming interface to verify the originality of digital images, PDF files, and photo-documentations. The API is very easy to integrate and independent of your operating system, database system or development language.

Libraries and language bindings to support REST and JSON are available in all major languages and platforms. Using API is very simple and is based on sending a GET or a POST request to our servers with your encoded authentication information included.

Note: In code samples in this documentation, “\” indicates the line is wrapped onto the next line, without any breaks. “\” is not a part of the line content.

UTF-8 encoding

For compatibility reasons, every URL passed to Verifeyed API needs to be UTF-8 encoded. All strings returned by Verifeyed API are also UTF-8 encoded.

Request Formats

The image can be uploaded using a POST request to our API directly or a publicly accessible URL of the image has to be provided in a GET request.

POST Request for image verification

When using post request, the image should be directly uploaded to the API site.

http://www.verifeyed.com/api.php
api_key [api_key]
api_sig [api_sig]
date [datetime]
nonce [nonce]
image_upload Content-Type: multipart/form-data; [upload file]

GET Request for Images Verification

This is a request format to use when you have your image located at a publicly accessible URL.

http://www.verifeyed.com/api.php?api_key=[api_key] \
&api_sig=[api_sig]&nonce=[nonce]&date=[datetime]&image_URL=[imageURL]

Description of Request Parameters

  • [api_key] Your API key. You can use this key publicly in requests. The key is used to identify which user sent the request. This code can be found in your API account page once you have signed up for API.
  • [api_sig] API signature calculated based on several parameters. See next section for details on how to calculate your api_sig. This parameter is used for authentication.
  • [datetime] The Unix time (timestamp) at which the request is sent (number of seconds that have elapsed since the January 1, 1970 GMT). This parameter must be sent as a 10 digit UTC format string (e.g., 1304655527).
  • [nonce] Any random value that should not be repeated and must be at least 8 character long. This value is used in calculation of api_sig.
  • [image_URL] Publicly accessible URL of the image (so that our server can open it directly) in standard URL format (e.g., http://www.verifeyed.com/testimage.jpg). Note that the URL should only open the image directly and not an html page with text and image(s).
  • [image_upload] Image uploaded directly from a web upload form. You may use the standard html upload button with the variable named as this.
  • [private_key] Must be kept secret. THIS IS NOT A PART OF ANY REQUEST IN ORIGINAL FORMAT. Private_key is only and only used to generate a SIG each time a request is sent. Sharing this key can mean that your account can be misused by other users.

Calculation of API_SIG value

Api_sig is used for authentication based on the values sent in the request. The calculation of the signature value is a 3 step process.

  1. The variables The following variables are to be used in the sig value. These variables are part of the request to be sent except the privatekey. [privatekey]: Can be found in your API account page once you are logged in and have access to the API. API access must be requested and approved manually to have a private key (see API information). [HTTPVerb]: The value can either be “get” or “post” (without quotes) based on the type of request sent. [image_upload] is null in case of GET requests and is the URL encoded value of the file uploaded in case of post request [date]: The unix timestamp in standard format. [nonce]: The nonce value sent in the request [apisite]: the URL of api site , value is “http://www.verifeyed.com/” without quotes (do not skip the / in the end) [others]: This variable should contain the image_URL in format ” image_URL=http://u.r/l.jpg “without quotes. This variable is null (empty) in case of POST request or status requests.
  2. The String Join the variables to form a continuous string (without spaces) , ie string = [privatekey][HTTPVerb][image_upload][date][nonce][apisite][others] convert this string to lowercase values. A sample string is given below with random values for each variable (for get request).
  3. SHA1 Hash The api_sig is the SHA1 hash of this string (to protect your private key from normal users). MD5 string calculation algorithms can be easily found for your favorite programming language online.

Format of Result for Single Image

The result returned for the request is JSON formatted. Following is a sample output.

{
    "code": 200,
    "message": "",
    "result": {
        "filename": "…",
        results…  
    }
}

Description of Result Parameters

  • code: The returned result code. In case of a successful request this is 200 and a result part is visible.
  • message: If some error occurs, this parameter contains more detailed information about the error.
  • result: This section contains results.

Remaining parameters are general information or specifications about the tested file.

Constraints on requests

  • Unique Nonce: Nonce must not be repeated, as a general guideline not within 2 hours. This is to prevent repeat requests or people copying your request and resending it.
  • Time Skew: Request time cannot be more than 15 minutes offset from Unix time. This is part of the security features to disallow repetition of requests.
  • API_SIG Calculation: API signature must be calculated using updated variables of each request each time the request is sent. The value cannot be programmed to be a fixed value.
  • Private Key is Secret: DO NOT share your private key. Design your application in such a way that this key is not visible to a common user in any way. Only the resulting hash in API_SIG can be visible.

API Error Codes

Error codes generated by the API are in the range from 200 through 999.

  • 200: OK,
  • 400: Arguments api_key, api_sig, date and nonce are mandatory,
  • 401: Identical Nonce Found,
  • 402: No file to upload or no operation required,
  • 404: Error while downloading file ,
  • 500: Request time is too skewed from the server,
  • 601: Error in authorization. Bad api_sig,
  • 602: API key is invalid length,
  • 603: Wrong API key provided,
  • 604: Error in authorization, Member not allowed to use API,
  • 605: Nonce is too short! Minimum length is 8 characters ,
  • 900: Non-defined API error occurred

 

Download PHP sample code here.

Download JAVA sample code here.