Cloud Iris API

Iris recognition as a REST service. Enrol a person with left and right eye images, then find them among everyone enrolled (1:N) or confirm a claimed identity (1:1). Each customer is a tenant with its own isolated database.

Base URL:

https://api.iriscan.net

Authentication

Every request carries the tenant's API key in the Api-Key header.

curl https://api.iriscan.net/persons/query?page=0&pageSize=20 \
  -H "Api-Key: $IRISCAN_API_KEY"

API keys are issued per tenant together with the monthly plan. To get one, contact us with the expected number of enrolments and identifications per month; on-premise deployment with the Edge service is arranged the same way.

How matching works

When a person is enrolled, each eye image is segmented, the iris ring is unwrapped and encoded into a binary iris code with a mask of unusable bits (eyelids, lashes, reflections). The response returns both, plus blackPercentage, the share of the iris hidden by occlusion. A high value means too little texture was visible, and the image is worth retaking.

find compares a probe eye against every enrolled template of the tenant and returns the best match, or 404 when nobody matches. verify compares the probe only against the given person and returns 412 when it does not match. Images are sent as base64 strings; near-infrared images from dedicated iris scanners give the best results.

Errors

Status	Meaning
`400`	Malformed request or image
`401`	Missing or invalid `Api-Key`
`404`	Person not found, or no match for `find`
`412`	`verify`: the eye does not match the person
`422`	Validation failed; `errors` lists the fields

Error bodies have the same shape:

{
  "timestamp": "2021-03-02T10:15:30Z",
  "status": "UNPROCESSABLE_ENTITY",
  "message": "Validation failed",
  "errors": ["name: must not be blank"]
}

Reference

POST/persons

Add a new person to the database

Request body

Field	Type	Description
`name`	string	Display name of the person
`leftEye`	string (base64 image)	Left eye image, base64 (PNG or JPEG)
`rightEye`	string (base64 image)	Right eye image, base64 (PNG or JPEG)
`metadata`	object	Any JSON object stored with the person, returned as is

Example

curl -X POST "https://api.iriscan.net/persons" \
  -H "Api-Key: $IRISCAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Jane Doe",
  "leftEye": "<base64 image>",
  "rightEye": "<base64 image>",
  "metadata": {
    "employeeId": "E-1042"
  }
}'

Response 200

{
  "id": "6041f3a2c1e8",
  "tenantId": "5f9b1c7e2a44",
  "iris": {
    "leftEye": {
      "raw": "<base64>",
      "code": "<base64 iris code>",
      "mask": "<base64 mask>",
      "blackPercentage": 0.12
    },
    "rightEye": {
      "raw": "<base64>",
      "code": "<base64 iris code>",
      "mask": "<base64 mask>",
      "blackPercentage": 0.09
    }
  },
  "metadata": {
    "employeeId": "E-1042"
  }
}

Responses

200Success401Unauthorized422Validation failed

PUT/persons/{id}

Edit person from the database

Parameters

Name	Where	Description
`id`	path, string, required	Person ID

Request body

Field	Type	Description
`name`	string	Display name of the person
`metadata`	object	Any JSON object stored with the person, returned as is

Example

curl -X PUT "https://api.iriscan.net/persons/6041f3a2c1e8" \
  -H "Api-Key: $IRISCAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Jane A. Doe",
  "metadata": {
    "employeeId": "E-1042",
    "site": "Tallinn"
  }
}'

Response 200

{
  "id": "6041f3a2c1e8",
  "tenantId": "5f9b1c7e2a44",
  "iris": {
    "leftEye": {
      "raw": "<base64>",
      "code": "<base64 iris code>",
      "mask": "<base64 mask>",
      "blackPercentage": 0.12
    },
    "rightEye": {
      "raw": "<base64>",
      "code": "<base64 iris code>",
      "mask": "<base64 mask>",
      "blackPercentage": 0.09
    }
  },
  "metadata": {
    "employeeId": "E-1042"
  }
}

Responses

200Success401Unauthorized404Not found422Validation failed

DELETE/persons/{id}

Delete person from the database

Parameters

Name	Where	Description
`id`	path, string, required	Person ID

Example

curl -X DELETE "https://api.iriscan.net/persons/6041f3a2c1e8" \
  -H "Api-Key: $IRISCAN_API_KEY"

Response 200

{
  "id": "6041f3a2c1e8",
  "tenantId": "5f9b1c7e2a44",
  "iris": {
    "leftEye": {
      "raw": "<base64>",
      "code": "<base64 iris code>",
      "mask": "<base64 mask>",
      "blackPercentage": 0.12
    },
    "rightEye": {
      "raw": "<base64>",
      "code": "<base64 iris code>",
      "mask": "<base64 mask>",
      "blackPercentage": 0.09
    }
  },
  "metadata": {
    "employeeId": "E-1042"
  }
}

Responses

200Success401Unauthorized404Not found

GET/persons/query

Query persons from database

Parameters

Name	Where	Description
`term`	query, string	Text to search
`page`	query, number, required	Zero-based page index
`pageSize`	query, number, required	The size of the page to be returned
`sort`	query, string	Sort result format - property,(asc,desc)

Example

curl -X GET "https://api.iriscan.net/persons/query?term=doe&page=0&pageSize=20&sort=name,asc" \
  -H "Api-Key: $IRISCAN_API_KEY"

Response 200

{
  "numberOfElements": 1,
  "totalElements": 1,
  "totalPages": 1,
  "content": [
    {
      "id": "6041f3a2c1e8",
      "tenantId": "5f9b1c7e2a44",
      "iris": {
        "leftEye": {
          "raw": "<base64>",
          "code": "<base64 iris code>",
          "mask": "<base64 mask>",
          "blackPercentage": 0.12
        },
        "rightEye": {
          "raw": "<base64>",
          "code": "<base64 iris code>",
          "mask": "<base64 mask>",
          "blackPercentage": 0.09
        }
      },
      "metadata": {
        "employeeId": "E-1042"
      }
    }
  ]
}

Responses

200Success400Invalid input401Unauthorized

POST/persons/find

Find person in database

Request body

Field	Type	Description
`eye`	string	Probe eye image, base64 (PNG or JPEG)

Example

curl -X POST "https://api.iriscan.net/persons/find" \
  -H "Api-Key: $IRISCAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "eye": "<base64 image>"
}'

Response 200

{
  "id": "6041f3a2c1e8",
  "tenantId": "5f9b1c7e2a44",
  "iris": {
    "leftEye": {
      "raw": "<base64>",
      "code": "<base64 iris code>",
      "mask": "<base64 mask>",
      "blackPercentage": 0.12
    },
    "rightEye": {
      "raw": "<base64>",
      "code": "<base64 iris code>",
      "mask": "<base64 mask>",
      "blackPercentage": 0.09
    }
  },
  "metadata": {
    "employeeId": "E-1042"
  }
}

Responses

200Success400Invalid input401Unauthorized404Not found422Validation failed

POST/persons/{id}/verify

Verify person from database

Parameters

Name	Where	Description
`id`	path, string, required	person id to verify with

Request body

Field	Type	Description
`eye`	string	Probe eye image, base64 (PNG or JPEG)

Example

curl -X POST "https://api.iriscan.net/persons/6041f3a2c1e8/verify" \
  -H "Api-Key: $IRISCAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "eye": "<base64 image>"
}'

Response 200

{
  "id": "6041f3a2c1e8",
  "tenantId": "5f9b1c7e2a44",
  "iris": {
    "leftEye": {
      "raw": "<base64>",
      "code": "<base64 iris code>",
      "mask": "<base64 mask>",
      "blackPercentage": 0.12
    },
    "rightEye": {
      "raw": "<base64>",
      "code": "<base64 iris code>",
      "mask": "<base64 mask>",
      "blackPercentage": 0.09
    }
  },
  "metadata": {
    "employeeId": "E-1042"
  }
}

Responses

200Success400Invalid input401Unauthorized404Not found412Verify failed422Validation failed

Schemas

Person

Field	Type	Description
`id`	string	Person ID
`tenantId`	string	Tenant ID
`iris`	IrisData	Templates for both eyes
`metadata`	object	Any JSON object stored with the person, returned as is

PersonPage

Field	Type	Description
`numberOfElements`	number (int64)	Persons on this page
`totalElements`	number (int64)	Persons matching the query
`totalPages`	number (int64)	Number of pages
`content`	array of Person	Persons on this page

IrisData

Field	Type	Description
`leftEye`	Eye	Left eye image, base64 (PNG or JPEG)
`rightEye`	Eye	Right eye image, base64 (PNG or JPEG)

Eye

Field	Type	Description
`raw`	string	Normalised iris texture, base64
`code`	string	Binary iris code, base64
`mask`	string	Mask of unusable bits for the code, base64
`blackPercentage`	number (double)	Share of the iris hidden by eyelids, lashes or reflections (0–1)

ErrorResponse

Field	Type	Description
`timestamp`	string (date-time)	Time of the error
`status`	string	HTTP status name
`message`	string	Human-readable error

ValidationErrorResponse

Field	Type	Description
`timestamp`	string (date-time)	Time of the error
`status`	string	HTTP status name
`message`	string	Human-readable error
`errors`	array of string	Validation messages, one per field