Verify API documentation

Introduction

The Verify API provides a programmatic interface to fingerprint assets.

Depending on your plan the API can be reached at specific region endpoints. Please note that each region endpoint requires a different API key. At the moment the following endpoints are available:

region United States, us-central1

https://fingerprint-ue1.joinverify.com/v1

region Europe, europe-west1

https://fingerprint-ew1.joinverify.com/v1

Authentication

To use the Verify API each request must be authenticated. Requests are authenticated by providing a key in the X-Api-Key HTTP header.

When signing up for access to the Verify API, each client is provided with a key. Besides the client and Verify, nobody else should have access to the key. In order to not expose the key requests should always be done server-side.

Example request


curl https://fingerprint-ew1.joinverify.com/v1/fingerprint \
-H "X-Api-Key: $VERIFY_API_KEY" \

Fingerprint

POST https://fingerprint-ew1.joinverify.com/v1/fingerprint/

Creates a fingerprinted image from the given image.

Example request


curl https://fingerprint-ew1.joinverify.com/v1/fingerprint \
-H "X-Api-Key: $VERIFY_API_KEY" \
-H "Content-Type: application/json" \
-d '{
    "url": "http://www.test.com/original-image.jpg", 
    "repeat_min": 2, 
    "repeat_max": 4
}'

Request body

url

string

Required

The URL of the asset. Supported formats are PNG, JPEG and WebP.

NOTE: maximum image dimension(s) is 6144 pixels. Maximum file size is 50 MB.

repeat_min

integer

Optional

The minimum number the fingerprint is repeated throughout the asset. Value range is 1 to 8, default value is 1. If there are less pixels available then repeat_min requires the request will fail.

repeat_max

integer

Optional

The maximum number the fingerprint is repeated throughout the asset. Value range is 1 to 8, default value is 4. If less than the required pixels are available repeat_max will be clamped to the maximum.

keep_metadata

boolean

Optional

Copies the metadata from the original asset over to the newly generated fingerprinted asset. Supported metadata types are EXIF, IPTC and XMP. Default value is false.

bypass_max_res

boolean

Optional

Bypasses the maximum dimension(s) limit for images.

NOTE: images risk undetectable fingerprints if scaled below 15%.

Return body

file

string

The fingerprinted asset as base64 data URI.

string

Uniquely generated ID which is placed inside the fingerprint.

num_repeat

integer

Number of times the fingerprint is repeated throughout the asset.

Response


{
    "file": "data:image/jpg;base64,...",
    "id": "303e392b",
    "num_repeat": 4,
}

Fingerprint detect

POST https://fingerprint-ew1.joinverify.com/v1/fingerprint/detect

Detect and read fingerprint from given image.

Example request


curl https://fingerprint-ew1.joinverify.com/v1/fingerprint/detect \
-H "X-Api-Key: $VERIFY_API_KEY" \
-H "Content-Type: application/json" \
-d '{
    "url": "http://www.test.com/fingerprinted.jpg", 
    "master": "http://www.test.com/original.jpg"
}'

Request body

url

string

Required

The URL of the fingerprinted asset. Supported formats are PNG, JPEG and WebP.

NOTE: maximum image dimension(s) is 6144 pixels. Maximum file size is 50 MB.

master

string

Required

The URL of the original asset. Supported formats are PNG, JPEG and WebP.

NOTE: maximum image dimension(s) is 6144 pixels. Maximum file size is 50 MB.

Return body

verified

boolean

Set to true if the fingerprint was verified with a cryptographic check.

certain

integer

Indicates the level of certainty a damaged fingerprint ID matches with a fingerprint ID from the Verify cloud. Value is a percentage in range between 0 to 100.

string

fingerprint ID which was read from the given image.

Response


{
    "verified": true,
    "certain": 100,
    "id": "303e392b",
}

Fingerprint remove

DELETE https://fingerprint-ew1.joinverify.com/v1/fingerprint/remove

Remove the given image and all associated fingerprints from the Verify cloud.

Example request


curl https://fingerprint-ew1.joinverify.com/v1/fingerprint/remove \
-X DELETE \
-H "X-Api-Key: $VERIFY_API_KEY" \
-H "Content-Type: application/json" \
-d '{
    "url": "http://www.test.com/fingerprinted.jpg"
}'

Request body

url

string

Required

The URL of the asset. Supported formats are PNG, JPEG and WebP.

NOTE: maximum image dimension(s) is 6144 pixels. Maximum file size is 50 MB.

Return body

Returns status code 200 if successfully removed.

Monitor results

POST https://fingerprint-ew1.joinverify.com/v1/monitor/results

Retrieves monitor results for given image.

Example request


curl https://fingerprint-ew1.joinverify.com/v1/monitor/results \
-H "X-Api-Key: $VERIFY_API_KEY" \
-H "Content-Type: application/json" \
-d '{
    "url": "http://www.test.com/fingerprinted.jpg", 
    "start": 10,
    "rows": 5,
}'

Request body

url

string

Optional

The URL of the asset. Supported formats are PNG, JPEG and WebP.

NOTE: If no URL is supplied matches for all images will be returned.

NOTE: maximum image dimension(s) is 6144 pixels. Maximum file size is 50 MB.

start

integer

Optional

Start index for rows.

rows

integer

Optional

Number of rows to be returned. Value range between 1 and 1000.

Return body

matches_count

integer

Number of matches found.

rows_count

integer

Number of rows returned.

matches

array

Match object

integer

ID of match in the monitor index.

page_url

string

URL of the website on the internet.

image_url

string

URL of the image on the internet.

date

string

Date match was added to the monitor index.

table

Print object

interactions

table

Interactions object

Print object

verified

boolean

Set to true if the fingerprint was verified with a cryptographic check.

certain

integer

Indicates the level of certainty a damaged fingerprint ID matches with a fingerprint ID from the Verify cloud. Value is a percentage in range between 0 to 100.

string

fingerprint ID which was read from the given image.

Interactions object

views_count

integer

Number of views video post received.

likes_count

integer

Number of likes post received.

shares_count

integer

Number of shares post received.

comments_count

integer

Number of comments post received.

sentiment_post

string

Sentiment of post description determined by AI. Value can be positive, neutral, negative or unkown.

sentiment_comments

string

Sentiment of comments determined by AI. Value can be positive, neutral, negative or unkown.

Response


{
"matches_count": 100,
"rows_count": 3,
    "matches": [
        {
            "page_url": "https://example.com/news/example.html",
            "image_url": "https://example.com/wp-content/uploads/2018/10/example.jpg",
            "date": "10-02-2022",
            "print": [
                "verified": true,
                "certain": 100,
                "id": "303e392b",
            ],
            "interactions": [
                "views_count": 15000,
                "likes_count": 1232,
                "shares_count": 54,
                "comments_count": 27,
                "sentiment_post": "positive",
                "sentiment_comments": "positive",
            ]
        },
        ...
    ]
}

Usage

GET https://fingerprint-ew1.joinverify.com/v1/usage/

Retrieves usage report.

Example request


curl https://fingerprint-ew1.joinverify.com/v1/usage \
-H "X-Api-Key: $VERIFY_API_KEY"

Return body

image_count

integer

Current number of images in the Verify cloud being monitored and billed.

image_quota

integer

Maximum number of images based on the current subscription.

renewal_subscription_date

string

Date when subscription gets renewed.

Response


{
    "image_count": 320,
    "image_quota": 2000,
    "renewal_subscription_date": "10-02-2025",
}