Image Validation API

The Image Validation API is no longer supported for new integrations.

Image Validation objects allow a customer to submit images such as receipt captures for validation or photographs. Using this API, receipt capture images can be tracked through the validation process. The number of images per image validation record is configurable. SessionM can work with a variety of partners to validate receipts, but the API is validation provider agnostic.

Consider the following image format requirements:

Image can be submitted base64 encoded or binary.
Image needs to be under 10MB in file size.
Supported formats include JPG, PNG, TIFF, PDF and GIF.

Note that some setup and configuration is required before this API can be utilized. For more information, please contact your Customer Success representative for assistance.

API Contingencies and Combinations:

Since image validations exist to validate receipts and images from customers, you must create the customers that engage in this process. Use the Standard Profile API to create customers and specify the attributes for their standard profiles.
Image validation records are often tied to campaigns, which are created in advance by via the SessionM UI. Campaign identifiers can then be passed in with request object from the Image Validation API. Campaign IDs determine how SessionM analyzes the image and awards specific incentives accordingly. For example, people submit receipts and images of themselves. Image validation logic considers if the receipts are tied to specific retailers.

This API provides the following methods:

Create a new image validation record
Create a new image in an image validation record
Retrieve an image validation record

Create a New Image Validation Record

Adds a new image validation record. This method allows customers to submit a receipt.

Endpoints

This method offers the following endpoints:

Copy

REST Endpoints

POST /priv/v1/apps/:api_key/image_validations?auth_token=xxxx-yyyy-zzzz
POST /priv/v1/apps/:api_key/users/:user_id/image_validations
POST /priv/v1/apps/:api_key/external/users/:external_id/image_validations

For more information on how to specify an endpoint as part of an actual URL, see Before You Begin. The procedure in this section includes a sample URL for a customer transaction.

Endpoint Parameters

The following parameters are available when specifying the endpoint for this method:

Endpoint Parameter	Description
api_key	Supplied by the SessionM Platform, the API key is necessary to authenticate any HTTP request to a SessionM API. This key is associated to an API secret, which ties the authentication to a specific application or web site within the organization. The platform maintains each application or site as a digital property, something that can be configured using the SessionM UI.
user_id	Internal identifier for the customer within the SessionM Platform.
external_id	Identifier for a customer in an external system integrating with the SessionM Platform.
auth_token	Specified authorization token. For example: auth_token=xxxx-yyyy-zzzz.

Request Object

When this method runs, it passes in a request object that contains an image_validation object, which is shown below:

Copy

JSON Request

{
  "image_validation": {
    "validation_type": "receipt",
    "campaign_permalink": "my-receipt-campaign",
    "placement_id" : 54321,
    "external_id" : "my-tracking-id",
    "images" : [
        { "id" : "100", "base64_data"  : "....", "mime_type" : "image/jpg" },
        { "id" : "101", "base64_data"  : "....", "mime_type" : "image/png" }
    ],
    "data" : {
    }
  }
}

This object is detailed in the following table:

Request Attributes for Image Validation

Attribute	Type Required/Optional	Description
validation_type	string required	Specifies validation type. Use "receipt" to explicitly specify a receipt capture and validation. Use “image" for regular image validation.
campaign_permalink	string required	SessionM campaign identifier for the image. Each campaign has a defined set of rules and desired customer actions.
placement_id	string optional	Your placement ID. Format: placement_id=your-placement-id.
external_id	string optional	Use for local tracking.
image_count	integer optional	Used for uploading one image at a time through the /images route.
images	array required	Must be at least length 1.
data	object optional	Free form hash.

Note too that every image accepts an optional, client-defined ID for tracking purposes; these IDs are returned in the response.

Response Object

In addition to a status value-pair for the transaction, the response object returned by the method contains an image_validation object, which is shown below:

Copy

JSON Response

{
  "status": "ok",
  "image_validation": {
    "id": 111111,
    "validation_type": "receipt",
    "campaign_id" : 12345,
    "campaign_permalink" : "my-receipt-campaign",
    "placement_id" : 54321,
    "external_id" : "my-tracking-id",
    "user_id": "xxxxx",
    "status": "pending",
    "created_at": "2015-01-20 13:04:45",
    "updated_at": "2015-01-21 13:04:45",
    "image_count": 2,
    "images": [
        { "id" : "100", "url" : "https://content.sessionm.com/images/12345/example/54321/image1.jpg", "mime_type" : "image/jpg" },
        { "id" : "101", "url": "https://content.sessionm.com/images/12345/example/54321/image2.png", "mime_type" : "image/png" },
    ],
    "data" : {
    }
  }
}

The following table documents this object:

Response Attributes for Image Validation

Attribute	Type	Description
id	integer	Image validation ID.
validation_type	string	Shows validation type: receipt to explicitly specify a receipt capture and validation; image for regular image validation.
campaign_id	integer	SessionM campaign identifier for the image. Each campaign has a defined set of rules and actions.
campaign_permalink	string	SessionM campaign identifier for the image. Each campaign has a defined set of rules and desired customer actions.
placement_id	string	Your placement ID. Format: placement_id=your-placement-id.
external_id	string	Use for local tracking.
user_id	string	SessionM customer identifier.
status	string	One of pending, valid, invalid, incomplete.
created_at	string	Image validation creation UTC date time.
updated_at	string	Image validation last updated UTC date time.
image_count	integer	Used for uploading one image at a time through the /images route.
images	array	List of image objects attached to the image validation with URLs.
data	object	Free form hash.

Statuses and Errors

When this method makes a successful call to the platform, it returns a 200-level status code. When the string returned with a 200-level status code is ok, the transaction did process. But, if the string returned is error, you need to discover what type of error occurred.

Returned errors can be either method-specific or generic. The platform returns the following error messages for this method:

Code	Reason
missing_data	Required parameter is missing.
campaign_unavailable	The campaign identifier sent in could not be found.
campaign_unavailable	The customer is ineligible for this campaign or has hit the cap.
validation	Customer has exceeded daily limit.

For information on the generic statuses and errors returned for any object, see the associated section in Generic Statuses and Errors.

Create a New Image in an Image Validation Record

Adds a new image to an image validation record.

In more technical terms, it adds an image to an image validation record with a status of incomplete. It then returns an updated image validation object. Image validation objects with a status of incomplete change to pending once the initial image_count is reached.

Endpoints

This method offers the following endpoints:

Copy

REST Endpoints

POST /api/v1/apps/:api_key/image_validations/:image_validation_id/images?auth_token=xxxx-yyyy-zzzz
POST /priv/v1/apps/:api_key/users/:user_id/image_validations/:image_validation_id/images
POST /priv/v1/apps/:api_key/external/users/:external_id/image_validations/:image_validation_id/images

For more information on how to specify an endpoint as part of an actual URL, see Before You Begin. The procedure in this section includes a sample URL for a customer transaction.

Endpoint Parameters

Endpoint Parameter	Description
api_key	Supplied by the SessionM Platform, the API key is necessary to authenticate any HTTP request to a SessionM API. This key is associated to an API secret, which ties the authentication to a specific application or web site within the organization. The platform maintains each application or site as a digital property, something that can be configured using the SessionM UI.
user_id	Internal identifier for the customer within the SessionM Platform.
external_id	Identifier for a customer in an external system integrating with the SessionM Platform.
auth_token	Specified authorization token. For example: auth_token=xxxx-yyyy-zzzz.

Request Object

When this method runs, it passes in a request object that contains an image object, which is shown below:

Copy

JSON Request

{
  "image" : {
    "id" : "101",
    "base64_data"  : "....",
    "mime_type" : "image/jpg"
  }
}

This object is detailed in the following table:

Request Attributes for Image

Attribute	Type Required/Optional	Description
id	string optional	Use for local tracking.
base64_data	string required	Base64 encoded image data.
mime_type	string optional	Mime type of the image.

Response Object

This object is identical to the response object returned for the method that creates a new validation record, as shown below:

Copy

JSON Response

{
  "status": "ok",
  "image_validation": {
    "id": 111111,
    "validation_type": "receipt",
    "campaign_id" : 12345,
    "campaign_permalink" : "example",
    "placement_id" : 54321,
    "user_id": "xxxxx",
    "status": "pending",
    "created_at": "2015-01-20 13:04:45",
    "updated_at": "2015-01-21 13:04:45",
    "image_count": 2,
    "images": [
        { "id" : "100", "url" : "https://content.sessionm.com/images/12345/example/54321/image1.jpg", "mime_type" : "image/jpg" },
        { "id" : "101", "url": "https://content.sessionm.com/images/12345/example/54321/image2.png", "mime_type" : "image/png" },
    ],
    "data" : {
    }
  }
}

For more information, see the image_validation object.

Statuses and Errors

Returned errors can be either method-specific or generic. The platform returns the following error messages for this method:

Code	Reason
validation	Invalid image data sent in.
image_not_found	No image data sent in.
validation	Too many images passed in.
validation	An image passed in is over 10MB.

For information on the generic statuses and errors returned for any object, see the associated section in Generic Statuses and Errors.

Retrieve an Image Validation Record

Retrieves an image validation record.

Endpoints

This method offers the following endpoints:

Copy

REST Endpoints

GET /api/v1/apps/:api_key/image_validations?auth_token=xxxx-yyyy-zzzz
GET /priv/v1/apps/:api_key/users/:user_id/image_validations
GET /priv/v1/apps/:api_key/external/users/:external_id/image_validations

For more information on how to specify an endpoint as part of an actual URL, see Before You Begin. The procedure in this section includes a sample URL for a customer transaction.

Endpoint Parameters

Endpoint Parameter	Description
api_key	Supplied by the SessionM Platform, the API key is necessary to authenticate any HTTP request to a SessionM API. This key is associated to an API secret, which ties the authentication to a specific application or web site within the organization. The platform maintains each application or site as a digital property, something that can be configured using the SessionM UI.
user_id	Internal identifier for the customer within the SessionM Platform.
external_id	Identifier for a customer in an external system integrating with the SessionM Platform.
auth_token	Specified authorization token. For example: auth_token=xxxx-yyyy-zzzz.
limit	Default is 100.
page	Default is 1.

Request Object

Not applicable.

Response Object

In addition to a status value-pair for the transaction, the response object returned by the method contains an image_validations array, which is shown below:

Copy

JSON Response

{
  "image_validations": [
    {
      "id": 111111,
      "validation_type": "receipt",
      "campaign_id" : 12345,
      "campaign_permalink" : "example",
      "placement_id" : 54321,
      "user_id" : "xxxxx",
      "status": "pending",
      "created_at": "2015-01-20 13:04:45",
      "updated_at": "2015-01-21 13:04:45",
      "image_count" : 2,
      "images": [
        { "id" : "100", "url" : "https://content.sessionm.com/images/12345/example/54321/image1.jpg", "mime_type" : "image/jpg" },
        { "id" : "101", "url" : "https://content.sessionm.com/images/12345/example/54321/image2.png", "mime_type" : "image/png" },
      ],
      "data" : {
      }
    },
    {
      "id":111112,
      "validation_type":"receipt",
      "campaign_id":12345,
      "campaign_permalink" : "example",
      "placement_id" : 54321,
      "user_id":"xxxxx",
      "status":"valid",
      "store_name":"ACME Pharmacy",
      "receipt_date":"2016-02-16 14:21:10",
      "created_at":"2016-02-11 06:48:23",
      "updated_at":"2016-02-16 14:21:10",
      "image_count":1,
      "images":[
         { "id" : "200", "url" : "https://content.sessionm.com/images/12345/example/54321/image1.jpg", "mime_type" : "image/jpg" }
      ],
      "data":{
      },
      "results":[
        {
          "id" : "111112-1",
          "name" : "3600000001",
          "description" : "example",
          "price" : 1.05,
          "quantity" : 2,
          "points" : 10
        },
        {
          "id" : "111112-2",
          "name" : "3600000002",
          "description" : "example 2",
          "price" : 2.50,
          "quantity" : 1,
          "points" : 10
        }
      ]
    },
    {
      "id":111113,
      "validation_type":"receipt",
      "campaign_id":12345,
      "campaign_permalink" : "example",
      "placement_id" : 54321,
      "user_id":"xxxxx",
      "status":"invalid",
      "invalid_code":1,
      "invalid_reason":"We cannot read your receipt clearly. Please make sure to take the picture with ample lighting showing your qualifying purchase.",
      "created_at":"2016-02-11 06:49:23",
      "updated_at":"2016-02-16 14:22:59",
      "image_count":1,
      "images":[
         { "id" : "300", "url" : "https://content.sessionm.com/images/12345/example/54321/image1.jpg", "mime_type" : "image/jpg" }
      ],
      "data":{
      }
    }
  ]
}

The following tables document this array:

Response Attributes for Image Validation

Attribute	Type	Description
id	integer	Image Validation ID.
validation_type	string	Shows validation type: receipt to explicitly specify a receipt capture and validation; image for regular image validation.
campaign_id	integer	SessionM campaign identifier for the image. Each campaign has a defined set of rules and actions.
campaign_permalink	string	SessionM campaign identifier for the image. Each campaign has a defined set of rules and desired customer actions.
placement_id	string	Your placement ID. Format: placement_id=your-placement-id.
user_id	string	SessionM customer identifier.
status	string	Statuses include: incomplete, pending, valid and invalid. Note that invalid validations include the invalid_code and the invalid_reason keys.
invalid_code	integer	For a list of invalid image codes, see the table in Invalid Image Codes.
invalid_reason	string	For a list of invalid image code reasons, see the table in Invalid Image Codes.
created_at	string	Image validation creation UTC date time.
updated_at	string	Image validation last updated UTC date time.
image_count	integer	Used for uploading one image at a time through the /images route.
images	array	List of image objects attached to the image validation with URLs.
data	object	Free form hash.
results	array	For more information on the objects in the results array, see table below.

Response Attributes for Results

Attribute	Type	Description
id	string	Image Validation ID and a result identifier combined with a hyphen.
name	string	UPC / SKU code or product name.
description	string	Product description.
price	float	Price payed for the receipt line item.
quantity	integer	Number of products purchased.
points	integer	Number of points earned for the receipt line item.

Invalid Image codes

The following table details the codes for invalid images:

Invalid Image Codes

Code	Description
0	Unknown
1	Receipt cannot be read clearly
2	Receipt is cropped
3	Receipt submitted twice
4	Receipt submitted outside of campaign dates
5	Image is not a receipt
6	No valid purchases found
7	Purchases are from a non-qualifying store
8	Image cannot be read clearly
9	Image is unrelated to campaign
10	Image submitted twice
11	Image submitted outside of campaign dates
12	Image has no valid purchases found, similar to 6
13	Multiple submissions not allowed for this campaign
14	Required fields missing from the receipt
15	Loyalty card linked to same retailer
16	Award limit reached
17	Image appears to have been altered.
18	Non-participating region

Statuses and Errors

Returned errors can be either method-specific or generic. No error messages are defined for this method except for the generic statuses and errors returned for any object. For more information, see the associated section in Generic Statuses and Errors.