Skip to main content
API docs by Redocly

Entrupy API (2.0.0)

Download OpenAPI specification:Download

Authentication Data

Get authentication by Entrupy ID

Return status, result, certificate, and owner information for a specific authentication session.

Images

  • include_images=true returns item.images as [{type, url}], where type is thumbnail or high_resolution.
  • format_options__return_item_photos=true returns region-keyed photos under item.images.photos.
  • With both flags, include_images wins and item.images is the [{type, url}] list. When neither image flag is set, standard tokens omit item.images; tokens configured with presign_camera_url still get a legacy images.camera object. That setting is not a request parameter.

Note: this payload does not include MarketEdge data (product details, condition, or marketplace listings). MarketEdge is not available on the public REST API.

path Parameters
entrupy_id
required
string
query Parameters
format_options__return_item_photos
boolean (Format Options Return Item Photos)
Default: false

Set to true to include region-keyed item photos under item.images.photos.

If include_images is also true, include_images wins and item.images is the [{type, url}] list instead.

include_images
boolean (Include Images)
Default: false

Attach image URLs to the returned item.

  • true: item.images is a list of {type, url} objects, where type is thumbnail or high_resolution.
  • false or omitted: item.images is left off the item unless format_options__return_item_photos is true.

This is distinct from format_options__return_item_photos, which returns region-keyed photos under item.images.photos. If both flags are true, include_images wins and item.images is the [{type, url}] list. When neither image flag is set, standard tokens omit item.images; tokens configured with presign_camera_url still get a legacy images.camera object. That setting is not a request parameter.

Responses

Response samples

Content type
application/json
Example
{
  • "item": {
    }
}

Lookup authentication by Customer ID

Retrieve the latest authentication for an item using your own customer_item_id. This helps correlate Entrupy results with records in your inventory system.

Images

  • include_images=true returns item.images as [{type, url}], where type is thumbnail or high_resolution.
  • format_options__return_item_photos=true returns region-keyed photos under item.images.photos.
  • With both flags, include_images wins and item.images is the [{type, url}] list. When neither image flag is set, standard tokens omit item.images; tokens configured with presign_camera_url still get a legacy images.camera object. That setting is not a request parameter.

Note: this payload does not include MarketEdge data (product details, condition, or marketplace listings). MarketEdge is not available on the public REST API.

path Parameters
lookup_value
required
string
query Parameters
format_options__return_item_photos
boolean (Format Options Return Item Photos)
Default: false

Set to true to include region-keyed item photos under item.images.photos.

If include_images is also true, include_images wins and item.images is the [{type, url}] list instead.

include_images
boolean (Include Images)
Default: false

Attach image URLs to the returned item.

  • true: item.images is a list of {type, url} objects, where type is thumbnail or high_resolution.
  • false or omitted: item.images is left off the item unless format_options__return_item_photos is true.

This is distinct from format_options__return_item_photos, which returns region-keyed photos under item.images.photos. If both flags are true, include_images wins and item.images is the [{type, url}] list. When neither image flag is set, standard tokens omit item.images; tokens configured with presign_camera_url still get a legacy images.camera object. That setting is not a request parameter.

Responses

Response samples

Content type
application/json
Example
{
  • "item": {
    }
}

Search authentications

Search your organization's authentication history using flexible filters. This endpoint powers dashboards and reporting without requiring you to store all results locally.

Images

  • include_images=true in the JSON body returns item.images as [{type, url}], where type is thumbnail or high_resolution.
  • format_options.return_item_photos=true in the JSON body returns region-keyed photos under item.images.photos.
  • Search does not read the GET query flag format_options__return_item_photos.
  • With both flags, include_images wins and item.images is the [{type, url}] list. When neither image flag is set, standard tokens omit item.images; tokens configured with presign_camera_url still get a legacy images.camera object. That setting is not a request parameter.

Note: this payload does not include MarketEdge data (product details, condition, or marketplace listings). MarketEdge is not available on the public REST API.

Request Body schema: application/json
required
limit
integer or null (Limit)
Default: 25

Maximum number of results to return. Defaults to 25 when omitted; values above 25 are capped at 25.

Array of objects or null (Filters)
Default: null

List of filters to apply to the search results.

format_options
object or null (Format Options)
Default: null

Nested formatting options. Set return_item_photos to true for region-keyed photos under item.images.photos.

This is a JSON object key, not the GET query flag format_options__return_item_photos. If include_images is also true, include_images wins.

object or null (TimestampRange)
Default: null

Time range filter to return entries within a given time interval. Both start and end are optional.

cursor
string or null (Cursor)
Default: null

Pagination cursor from a previous response's next_cursor field.

include_images
boolean or null (Include Images)
Default: false

Attach image URLs to every matching item.

  • true: item.images is a list of {type, url} objects, where type is thumbnail or high_resolution.
  • false or omitted: item.images is left off the item unless the JSON body sets format_options.return_item_photos to true.

This is distinct from nested format_options.return_item_photos, which returns region-keyed photos under item.images.photos. Search reads JSON body keys only: it does not read the GET query flag format_options__return_item_photos. If both body flags are true, include_images wins and item.images is the [{type, url}] list. When neither image flag is set, standard tokens omit item.images; tokens configured with presign_camera_url still get a legacy images.camera object. That setting is not a request parameter.

property name*
additional property
any

Responses

Request samples

Content type
application/json
Example
{
  • "limit": 10,
  • "filters": [
    ],
  • "include_images": false
}

Response samples

Content type
application/json
Example
{
  • "items": [
    ],
  • "item_count": 2,
  • "next_cursor": "CURSOR_FOR_NEXT_PAGE_ABC456"
}

Fingerprint Data

Get fingerprint by Entrupy ID

Return the fingerprint record for an Entrupy ID. Register and compare items both use this route: fingerprint_parent is present only on compare items, and register items omit it.

Images

  • include_images=true returns item.images as [{type, url}], where type is thumbnail or high_resolution.
  • format_options__return_item_photos=true returns region-keyed photos under item.images.photos.
  • With both flags, include_images wins and item.images is the [{type, url}] list. When neither image flag is set, standard tokens omit item.images; tokens configured with presign_camera_url still get a legacy images.camera object. That setting is not a request parameter.
path Parameters
entrupy_id
required
string
query Parameters
format_options__return_item_photos
boolean (Format Options Return Item Photos)
Default: false

Set to true to include region-keyed item photos under item.images.photos.

If include_images is also true, include_images wins and item.images is the [{type, url}] list instead.

include_images
boolean (Include Images)
Default: false

Attach image URLs to the returned item.

  • true: item.images is a list of {type, url} objects, where type is thumbnail or high_resolution.
  • false or omitted: item.images is left off the item unless format_options__return_item_photos is true.

This is distinct from format_options__return_item_photos, which returns region-keyed photos under item.images.photos. If both flags are true, include_images wins and item.images is the [{type, url}] list. When neither image flag is set, standard tokens omit item.images; tokens configured with presign_camera_url still get a legacy images.camera object. That setting is not a request parameter.

Responses

Response samples

Content type
application/json
Example
{
  • "item": {
    }
}

Search fingerprints

Search fingerprint records to track items that have been registered for identity verification. Filters let you narrow results to specific users or metadata.

Images

  • include_images=true in the JSON body returns item.images as [{type, url}], where type is thumbnail or high_resolution.
  • format_options.return_item_photos=true in the JSON body returns region-keyed photos under item.images.photos.
  • Search does not read the GET query flag format_options__return_item_photos.
  • With both flags, include_images wins and item.images is the [{type, url}] list. When neither image flag is set, standard tokens omit item.images; tokens configured with presign_camera_url still get a legacy images.camera object. That setting is not a request parameter.
Request Body schema: application/json
required
limit
integer or null (Limit)
Default: 25

Maximum number of results to return. Defaults to 25 when omitted; values above 25 are capped at 25.

Array of objects or null (Filters)
Default: null

List of filters to apply to the search results.

format_options
object or null (Format Options)
Default: null

Nested formatting options. Set return_item_photos to true for region-keyed photos under item.images.photos.

This is a JSON object key, not the GET query flag format_options__return_item_photos. If include_images is also true, include_images wins.

object or null (TimestampRange)
Default: null

Time range filter to return entries within a given time interval. Both start and end are optional.

cursor
string or null (Cursor)
Default: null

Pagination cursor from a previous response's next_cursor field.

include_images
boolean or null (Include Images)
Default: false

Attach image URLs to every matching item.

  • true: item.images is a list of {type, url} objects, where type is thumbnail or high_resolution.
  • false or omitted: item.images is left off the item unless the JSON body sets format_options.return_item_photos to true.

This is distinct from nested format_options.return_item_photos, which returns region-keyed photos under item.images.photos. Search reads JSON body keys only: it does not read the GET query flag format_options__return_item_photos. If both body flags are true, include_images wins and item.images is the [{type, url}] list. When neither image flag is set, standard tokens omit item.images; tokens configured with presign_camera_url still get a legacy images.camera object. That setting is not a request parameter.

property name*
additional property
any

Responses

Request samples

Content type
application/json
Example
{
  • "limit": 5,
  • "filters": [
    ],
  • "include_images": false
}

Response samples

Content type
application/json
Example
{
  • "items": [
    ],
  • "item_count": 1,
  • "next_cursor": "CURSOR_FOR_NEXT_PAGE_FP"
}

Integrations

Authentication config

Return brand and material options your token can access. Use this data to populate capture forms in your app and ensure requests use valid values.

Responses

Response samples

Content type
application/json
{
  • "config": {
    },
  • "iat": 1678886400,
  • "exp": 1678972800
}

Create login voucher

Generate an encrypted login voucher for the mobile app. This legacy flow allows a user to sign in to Entrupy before the authorize-user method was introduced.

Request Body schema: application/json
required
unique_user_id
required
string (Unique User Id)

A unique identifier for the user within your system.

email
required
string (Email)

The user's email address.

first_name
string or null (First Name)
Default: null

The user's first name.

last_name
string or null (Last Name)
Default: null

The user's last name.

property name*
additional property
any

Responses

Request samples

Content type
application/json
{
  • "unique_user_id": "testuser123",
  • "email": "testuser123@example.com",
  • "first_name": "Test",
  • "last_name": "User"
}

Response samples

Content type
application/json
{
  • "login_voucher": "<encrypted_voucher_string>",
  • "username": "YourOrg-testuser123"
}

Authorize user

Sign an authorization request from your mobile client so the SDK can obtain a session token from Entrupy. This is the preferred workflow for new integrations.

Request Body schema: application/json
required
unique_user_id
required
string (Unique User Id)

A unique identifier for the user within your system.

email
required
string (Email)

The user's email address.

sdk_authorization_request
required
string (Sdk Authorization Request)

The authorization request string generated by the Entrupy SDK.

first_name
string or null (First Name)
Default: null

The user's first name.

last_name
string or null (Last Name)
Default: null

The user's last name.

property name*
additional property
any

Responses

Request samples

Content type
application/json
{
  • "unique_user_id": "test-sdk-user-789",
  • "email": "test-sdk-user-789@example.com",
  • "sdk_authorization_request": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c",
  • "first_name": "SDKTest",
  • "last_name": "User"
}

Response samples

Content type
application/json
{
  • "signed_authorization_request": "<signed_sdk_authorization_request_payload>",
  • "username": "YourOrg-test-sdk-user-789"
}

Supported brands and categories

Return the supported brand, material, and product-category options maintained in Entrupy's CMS. Use this endpoint to keep capture forms in sync as supported options change, without hardcoding values locally.

This is a capture-form taxonomy of supported options, not MarketEdge and not product details for a specific authentication.

Returns 503 when these options are temporarily unavailable; clients should retry.

Responses

Response samples

Content type
application/json
{
  • "categories": [
    ]
}

Webhooks

Search registered domains

List domain names that have been verified for use with webhook callbacks. Webhooks can only target these domains.

Register a new hostname with POST /v2/domains/start_registration then POST /v2/domains/finish_registration. Remove one with POST /v2/domains/<domain_uuid>/deactivate after its webhooks are deactivated.

Request Body schema: application/json
required
limit
integer or null (Limit)
Default: 20

Maximum number of results to return. Defaults to 20 when omitted. Values must be in 1–20; values outside that range are rejected.

cursor
string or null (Cursor)
Default: null
property name*
additional property
any

Responses

Request samples

Content type
application/json
{
  • "limit": 10,
  • "cursor": null
}

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "item_count": 1,
  • "next_cursor": null
}

Start domain registration

Begin verifying that you control a hostname for webhook callbacks.

The response includes url, verifier, and register_token. Serve register_token as the body of GET url (path /entrupy_url_registration/<verifier>), then call POST /v2/domains/finish_registration with the same domain_name and verifier.

Treat register_token as a capability secret; do not log it. Requires a token with webhooks enabled. Api-Version must be 2.0.

Request Body schema: application/json
required
domain_name
required
string (Domain Name)

Hostname to verify, such as hooks.example.com. Do not include a scheme, path, or trailing slash.

property name*
additional property
any

Responses

Request samples

Content type
application/json
{
  • "domain_name": "hooks.acme.com"
}

Response samples

Content type
application/json
{}

Finish domain registration

Complete hostname verification after the challenge file is published.

Send the verifier from start_registration. On success the domain is registered to your organization and can be used as a webhook callback host. The response echoes verifier alongside the registered domain.

Finish is idempotent for an already-registered domain. Repeated failures may return 429. Requires a token with webhooks enabled. Api-Version must be 2.0.

Request Body schema: application/json
required
domain_name
required
string (Domain Name)

Hostname to verify, such as hooks.example.com. Do not include a scheme, path, or trailing slash.

verifier
required
string (Verifier)

verifier from the start_registration response (also the last path segment of url).

property name*
additional property
any

Responses

Request samples

Content type
application/json
{
  • "domain_name": "hooks.acme.com",
  • "verifier": "abcdefghijklmnopqrstuvwxyz0123456789ABCDEFG"
}

Response samples

Content type
application/json
{
  • "create_time": {
    },
  • "domain_name": "hooks.acme.com",
  • "domain_owner": {
    },
  • "domain_uuid": "b9b39947-8a16-483d-a7eb-2b961c41b2f7",
  • "verifier": "abcdefghijklmnopqrstuvwxyz0123456789ABCDEFG"
}

Deactivate domain

Remove a verified hostname so it can no longer be used as a webhook callback host.

Refused with 409 while any active webhook still targets this domain. Deactivate those webhooks first with POST /v2/webhooks/<webhook_uuid>/deactivate.

This does not cascade-delete webhooks. A second deactivate of an already removed domain returns 400. Requires a token with webhooks enabled. Api-Version must be 2.0.

path Parameters
domain_uuid
required
string

Responses

Response samples

Content type
application/json
{
  • "status": "ok"
}

Create webhook

Register an HTTPS callback that receives item snapshots when a matching authentication or fingerprint record changes. There are no named event types such as session.completed or support.message.

Requirements

  • endpoint.value must be an HTTPS URL on a domain already registered to your organization. List those domains with POST /v2/search/domains.
  • secret_key must be 16-256 characters. It is used to HMAC-SHA256 the raw JSON body, and every delivery carries the header Entrupy-Signature: SHA256:<base64>.
  • filters must include an activity.name filter set to exactly one value, authentication or fingerprint. Other optional filters may be added alongside it.
  • An organization may have at most 10 active webhooks. Creating one more returns 409.
  • Api-Version must be 2.0.
  • Set Accept-Language to en or ja. If omitted, en is used.

Delivery payload

The body Entrupy POSTs to endpoint.value is documented as the itemDelivery callback on this operation. WebhookDeliveryPayloadV2 contains channel, item_count, items, and webhook_uuid.

Each item matches a GET item except that it adds update_counter and omits timestamp and fingerprint_parent. Unlike a v2 GET item, webhook items omit status.flag_reason_id, status.flag_reason_display, and status.flag_message. They still include status.retake.

Request Body schema: application/json
required
endpoint
required
object (Endpoint)

Callback destination.

  • type must be url.
  • value must be an HTTPS URL on a domain registered to your organization, with no query, fragment, or params.
secret_key
required
string (Secret Key) [ 16 .. 256 ] characters

HMAC secret used to sign delivery payloads. Must be 16-256 characters.

channel
string or null (Channel)
Default: null

Opaque string echoed on every delivery so multiple webhooks can share a URL. Defaults to default.

filters
required
Array of objects (Filters)

Delivery filters. Must include a filter whose key is activity.name and whose value or values is exactly one of authentication or fingerprint.

Optional keys:

  • activity.form_factor: lightbox, microscopic, or free_camera.
  • owner.user.username: any username in your organization.

Each filter needs value or values; if both are sent, value is used.

property name*
additional property
any

Responses

Callbacks

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{
  • "channel": "default",
  • "create_time": {
    },
  • "endpoint": {},
  • "filters": [
    ],
  • "format_options": {
    },
  • "webhook_owner": {
    },
  • "webhook_uuid": "cff3fe0e-122a-4cb6-8b73-465c529d8b02"
}

Callback payload samples

Callback
POST: Item snapshot delivery
Content type
application/json
{
  • "channel": "default",
  • "item_count": 1,
  • "items": [
    ],
  • "webhook_uuid": "cff3fe0e-122a-4cb6-8b73-465c529d8b02"
}

Search webhooks

List active webhook configurations owned by your organization.

Use this to audit existing callback endpoints.

Request Body schema: application/json
required
limit
integer or null (Limit)
Default: 20

Maximum number of results to return. Defaults to 20 when omitted. Values must be in 1–20; values outside that range are rejected.

cursor
string or null (Cursor)
Default: null
property name*
additional property
any

Responses

Request samples

Content type
application/json
{
  • "limit": 10,
  • "cursor": null
}

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "item_count": 1,
  • "next_cursor": null
}

Get webhook

Retrieve a webhook's configuration: filters, channel, endpoint, webhook_owner, create_time, and format_options.

This does not include delivery history or delivery status.

path Parameters
webhook_uuid
required
string

Responses

Response samples

Content type
application/json
{
  • "channel": "default",
  • "create_time": {
    },
  • "endpoint": {},
  • "filters": [
    ],
  • "format_options": {
    },
  • "webhook_owner": {
    },
  • "webhook_uuid": "cff3fe0e-122a-4cb6-8b73-465c529d8b02"
}

Deactivate webhook

Disable a webhook so no further deliveries are sent.

There is no public reactivate route; create a new webhook to resume deliveries.

path Parameters
webhook_uuid
required
string

Responses

Response samples

Content type
application/json
{
  • "status": "ok"
}