Download OpenAPI specification:Download
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.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.
| entrupy_id required | string |
| format_options__return_item_photos | boolean (Format Options Return Item Photos) Default: false Set to If |
| include_images | boolean (Include Images) Default: false Attach image URLs to the returned item.
This is distinct from |
{- "item": {
- "entrupy_id": "ENTPY12345",
- "timestamp": {
- "epoch": 1716465600,
- "display": "2024-05-23T12:00:00+00:00"
}, - "status": {
- "result": {
- "id": "authentic",
- "final": true,
- "display": "Authentic"
}, - "flag": null,
- "retake": {
- "retake_required": false,
- "display": "No Action Required"
}
}, - "activity": {
- "name": "authentication",
- "form_factor": "microscopic",
- "product_category": "luxury",
- "product_group": "bags"
}, - "properties": {
- "brand": {
- "id": "chanel",
- "display": "Chanel"
}, - "material": {
- "id": "lambskin",
- "display": "Lambskin"
}
}, - "owner": {
- "organization": {
- "name": "Example Reseller"
}, - "user": {
- "username": "authenticator@example.com"
}
}, - "certificate": {
}, - "text_fields": {
- "customer_item_id": "SKU9876",
- "identifier": "SN-4815162342"
}
}
}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.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.
| lookup_value required | string |
| format_options__return_item_photos | boolean (Format Options Return Item Photos) Default: false Set to If |
| include_images | boolean (Include Images) Default: false Attach image URLs to the returned item.
This is distinct from |
{- "item": {
- "entrupy_id": "ENTPYLKUP789",
- "timestamp": {
- "epoch": 1700058600,
- "display": "2023-11-15T14:30:00+00:00"
}, - "status": {
- "result": {
- "id": "authentic",
- "final": true,
- "display": "Authentic"
}, - "flag": null,
- "retake": {
- "retake_required": false,
- "display": "No Action Required"
}
}, - "activity": {
- "name": "authentication",
- "form_factor": "microscopic",
- "product_category": "luxury",
- "product_group": "bags"
}, - "properties": {
- "brand": {
- "id": "louis_vuitton",
- "display": "Louis Vuitton"
}, - "material": {
- "id": "monogram_canvas",
- "display": "Monogram Canvas"
}
}, - "owner": {
- "organization": {
- "name": "Example Reseller"
}, - "user": {
- "username": "authenticator@example.com"
}
}, - "certificate": {
}, - "text_fields": {
- "customer_item_id": "CUST_LOOKUP_001",
- "identifier": "DC-2023-11"
}
}
}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.format_options__return_item_photos.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.
| 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 This is a JSON object key, not the GET query flag |
object or null (TimestampRange) Default: null Time range filter to return entries within a given time interval. Both | |
| cursor | string or null (Cursor) Default: null Pagination cursor from a previous response's |
| include_images | boolean or null (Include Images) Default: false Attach image URLs to every matching item.
This is distinct from nested |
| property name* additional property | any |
{- "limit": 10,
- "filters": [
- {
- "key": "text_fields.customer_item_id",
- "value": "CUST_SEARCH_A001",
- "exclude": false
}
], - "include_images": false
}{- "items": [
- {
- "entrupy_id": "ENTPYSRCH001",
- "timestamp": {
- "epoch": 1700474400,
- "display": "2023-11-20T10:00:00+00:00"
}, - "status": {
- "result": {
- "id": "authentic",
- "final": true,
- "display": "Authentic"
}, - "flag": null,
- "retake": {
- "retake_required": false,
- "display": "No Action Required"
}
}, - "activity": {
- "name": "authentication",
- "form_factor": "microscopic",
- "product_category": "luxury",
- "product_group": "bags"
}, - "properties": {
- "brand": {
- "id": "chanel",
- "display": "Chanel"
}, - "material": {
- "id": "lambskin",
- "display": "Lambskin"
}
}, - "owner": {
- "organization": {
- "name": "Example Reseller"
}, - "user": {
- "username": "authenticator@example.com"
}
}, - "certificate": {
}, - "text_fields": {
- "customer_item_id": "CUST_SEARCH_A001"
}
}, - {
- "entrupy_id": "ENTPYSRCH002",
- "timestamp": {
- "epoch": 1696516200,
- "display": "2023-10-05T15:30:00+00:00"
}, - "status": {
- "result": {
- "id": "authentic",
- "final": true,
- "display": "Authentic"
}, - "flag": null,
- "retake": {
- "retake_required": false,
- "display": "No Action Required"
}
}, - "activity": {
- "name": "authentication",
- "form_factor": "microscopic",
- "product_category": "luxury",
- "product_group": "bags"
}, - "properties": {
- "brand": {
- "id": "gucci",
- "display": "Gucci"
}, - "material": {
- "id": "canvas",
- "display": "Canvas"
}
}, - "owner": {
- "organization": {
- "name": "Example Reseller"
}, - "user": {
- "username": "authenticator@example.com"
}
}, - "certificate": {
}, - "text_fields": {
- "customer_item_id": "CUST_SEARCH_B005",
- "identifier": "DC-2023-10"
}
}
], - "item_count": 2,
- "next_cursor": "CURSOR_FOR_NEXT_PAGE_ABC456"
}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.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.| entrupy_id required | string |
| format_options__return_item_photos | boolean (Format Options Return Item Photos) Default: false Set to If |
| include_images | boolean (Include Images) Default: false Attach image URLs to the returned item.
This is distinct from |
{- "item": {
- "entrupy_id": "ENTPYFP123",
- "timestamp": {
- "epoch": 1698314400,
- "display": "2023-10-26T10:00:00+00:00"
}, - "status": {
- "result": {
- "id": "registered",
- "final": true,
- "display": "Registered"
}, - "flag": null,
- "retake": {
- "retake_required": false,
- "display": "No Action Required"
}
}, - "activity": {
- "name": "fingerprint",
- "form_factor": "microscopic",
- "mode": "register"
}, - "owner": {
- "organization": {
- "name": "Example Reseller"
}, - "user": {
- "username": "authenticator@example.com"
}
}, - "text_fields": {
- "customer_item_id": "CUST_FP_ITEM_789"
}
}
}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.format_options__return_item_photos.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.| 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 This is a JSON object key, not the GET query flag |
object or null (TimestampRange) Default: null Time range filter to return entries within a given time interval. Both | |
| cursor | string or null (Cursor) Default: null Pagination cursor from a previous response's |
| include_images | boolean or null (Include Images) Default: false Attach image URLs to every matching item.
This is distinct from nested |
| property name* additional property | any |
{- "limit": 5,
- "filters": [
- {
- "key": "text_fields.customer_item_id",
- "value": "FP_ITEM_001",
- "exclude": false,
- "text_fields": "canonical"
}, - {
- "key": "activity.mode",
- "value": "register",
- "exclude": false
}
], - "include_images": false
}{- "items": [
- {
- "entrupy_id": "ENTPYFP456",
- "timestamp": {
- "epoch": 1701424800,
- "display": "2023-12-01T10:00:00+00:00"
}, - "status": {
- "result": {
- "id": "registered",
- "final": true,
- "display": "Registered"
}, - "flag": null,
- "retake": {
- "retake_required": false,
- "display": "No Action Required"
}
}, - "activity": {
- "name": "fingerprint",
- "form_factor": "microscopic",
- "mode": "register"
}, - "owner": {
- "organization": {
- "name": "Example Reseller"
}, - "user": {
- "username": "authenticator@example.com"
}
}, - "text_fields": {
- "customer_item_id": "FP_ITEM_001"
}
}
], - "item_count": 1,
- "next_cursor": "CURSOR_FOR_NEXT_PAGE_FP"
}Deprecated: use POST /v2/catalog/brands instead.
This legacy endpoint returns micro-product authentication capture options only (function_id authentication). It will not be available on future API versions.
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.
{- "config": {
- "brands": [
- {
- "brand_id": "louis_vuitton",
- "display": {
- "name": "Louis Vuitton"
}, - "materials": [
- {
- "material_id": "monogram_canvas",
- "display": {
- "name": "Monogram Canvas"
}, - "details": [
- {
- "field_alias": "identifier",
- "display": {
- "name": "Date Code"
}
}
]
}, - {
- "material_id": "damier_ebene",
- "display": {
- "name": "Damier Ebene"
}, - "details": [
- {
- "field_alias": "identifier",
- "display": {
- "name": "Date Code"
}
}
]
}
]
}, - {
- "brand_id": "chanel",
- "display": {
- "name": "Chanel"
}, - "materials": [
- {
- "material_id": "caviar_leather",
- "display": {
- "name": "Caviar Leather"
}, - "details": [
- {
- "field_alias": "identifier",
- "display": {
- "name": "Serial Number"
}
}
]
}
]
}
]
}, - "iat": 1678886400,
- "exp": 1678972800
}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.
| 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 |
{- "unique_user_id": "testuser123",
- "email": "testuser123@example.com",
- "first_name": "Test",
- "last_name": "User"
}{- "login_voucher": "<encrypted_voucher_string>",
- "username": "YourOrg-testuser123"
}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.
{- "categories": [
- {
- "product_category": "luxury",
- "customer_product_group": "bags",
- "display": {
- "product_category": "Luxury",
- "customer_product_group": "Bags"
}, - "brands": [
- {
- "brand_id": "louis_vuitton",
- "display": {
- "name": "Louis Vuitton"
}, - "materials": [
- {
- "material_id": "monogram_canvas",
- "display": {
- "name": "Monogram Canvas"
}
}, - {
- "material_id": "damier_ebene",
- "display": {
- "name": "Damier Ebene"
}
}
]
}, - {
- "brand_id": "chanel",
- "display": {
- "name": "Chanel"
}, - "materials": [
- {
- "material_id": "caviar_leather",
- "display": {
- "name": "Caviar Leather"
}
}
]
}
]
}
]
}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.
| limit | integer or null (Limit) Default: 20 Maximum number of results to return. Defaults to 20 when omitted. Values must be in |
| cursor | string or null (Cursor) Default: null |
| property name* additional property | any |
{- "limit": 10,
- "cursor": null
}{- "items": [
- {
- "create_time": {
- "display": "2017-05-15T14:06:58+00:00",
- "epoch": 1494857218
}, - "domain_name": "sample-endpoint.entrupy.com",
- "domain_owner": {
- "organization": {
- "name": "Example Reseller"
}, - "user": {
- "username": "authenticator@example.com"
}
}, - "domain_uuid": "b9b39947-8a16-483d-a7eb-2b961c41b2f7"
}
], - "item_count": 1,
- "next_cursor": null
}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 <path_prefix>/entrupy_url_registration/<verifier>), then call POST /v2/domains/finish_registration with the same domain_name, path_prefix and verifier.
Set path_prefix when you control only part of a shared host. The registration then covers only callback URLs whose path equals the prefix or continues it after a /. If your receiver can answer a POST but cannot serve a file, use POST /v2/domains/verify_endpoint instead.
Treat register_token as a capability secret; do not log it. Requires a token with webhooks enabled. Api-Version must be 2.0.
| domain_name required | string (Domain Name) Hostname to verify, such as |
| path_prefix | string or null (Path Prefix) Default: null Optional. Register only part of the host, such as |
| property name* additional property | any |
{- "domain_name": "hooks.acme.com",
- "path_prefix": null
}{- "domain_name": "hooks.acme.com",
- "path_prefix": null,
- "verifier": "abcdefghijklmnopqrstuvwxyz0123456789ABCDEFG",
- "register_token": "abcdefghijklmnopqrstuvwxyz0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789abc",
- "expires_at": "2026-09-18T15:04:05Z"
}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.
| domain_name required | string (Domain Name) Hostname to verify, such as |
| path_prefix | string or null (Path Prefix) Default: null The same |
| verifier required | string (Verifier)
|
| property name* additional property | any |
{- "domain_name": "hooks.acme.com",
- "path_prefix": null,
- "verifier": "abcdefghijklmnopqrstuvwxyz0123456789ABCDEFG"
}{- "create_time": {
- "display": "2017-05-15T14:06:58+00:00",
- "epoch": 1494857218
}, - "domain_name": "hooks.acme.com",
- "domain_owner": {
- "organization": {
- "name": "Example Reseller"
}, - "user": {
- "username": "authenticator@example.com"
}
}, - "domain_uuid": "b9b39947-8a16-483d-a7eb-2b961c41b2f7",
- "verifier": "abcdefghijklmnopqrstuvwxyz0123456789ABCDEFG"
}Verify a webhook callback URL directly, with no challenge file.
Entrupy immediately sends POST <url> with Content-Type: application/json and body {"type": "url_verification", "challenge": "<random string>"}. Your endpoint must respond 200 within 5 seconds, without redirecting, with a body that is exactly the challenge string or exactly {"challenge": "<the same string>"}.
On success the URL's host and path are registered to your organization (path_prefix is the URL path), so webhooks can target that URL or paths below it. Verifying https://<host>/ registers the whole host.
url must use https with no port, credentials, query string or fragment. Shares the finish_registration rate limit, so repeated failures may return 429. Requires a token with webhooks enabled. Api-Version must be 2.0.
| url required | string (Url) The webhook callback URL to verify, such as |
| property name* additional property | any |
{- "create_time": {
- "display": "2026-11-09T14:06:58+00:00",
- "epoch": 1794233218
}, - "domain_name": "api.example.com",
- "path_prefix": "/v1/tenants/acme/hooks/entrupy",
- "domain_owner": {
- "organization": {
- "name": "Example Reseller"
}, - "user": {
- "username": "authenticator@example.com"
}
}, - "domain_uuid": "0c1f6f0e-3d0b-4c55-9a43-6d0a8f9e2b17"
}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.
| domain_uuid required | string |
{- "status": "ok"
}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.409.Api-Version must be 2.0.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.
| endpoint required | object (Endpoint) Callback destination.
|
| 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 |
| filters required | Array of objects (Filters) Delivery filters. Must include a filter whose Optional keys:
Each filter needs |
| property name* additional property | any |
{- "secret_key": "ExampleSecretKey1234567890",
- "channel": null,
- "filters": [
- {
- "key": "activity.name",
- "value": "authentication"
}
]
}{- "channel": "default",
- "create_time": {
- "display": "2024-05-15T14:06:58+00:00",
- "epoch": 1715782018
}, - "filters": [
- {
- "key": "activity.name",
- "value": "authentication"
}
], - "format_options": {
- "api_version": "2.0",
- "locale": "en",
- "item_format_version": 5
}, - "webhook_owner": {
- "organization": {
- "name": "Example Reseller"
}, - "user": {
- "username": "authenticator@example.com"
}
}, - "webhook_uuid": "cff3fe0e-122a-4cb6-8b73-465c529d8b02"
}{- "channel": "default",
- "item_count": 1,
- "items": [
- {
- "entrupy_id": "ENTPY12345",
- "update_counter": 12,
- "status": {
- "result": {
- "id": "authentic",
- "final": true,
- "display": "Authentic"
}, - "flag": null,
- "retake": {
- "retake_required": false,
- "display": "No Action Required"
}
}, - "activity": {
- "name": "authentication",
- "form_factor": "microscopic",
- "product_category": "luxury",
- "product_group": "bags"
}, - "properties": {
- "brand": {
- "id": "chanel",
- "display": "Chanel"
}, - "material": {
- "id": "lambskin",
- "display": "Lambskin"
}
}, - "owner": {
- "organization": {
- "name": "Example Reseller"
}, - "user": {
- "username": "authenticator@example.com"
}
}, - "certificate": {
}, - "text_fields": {
- "customer_item_id": "SKU9876"
}
}
], - "webhook_uuid": "cff3fe0e-122a-4cb6-8b73-465c529d8b02"
}List active webhook configurations owned by your organization.
Use this to audit existing callback endpoints.
| limit | integer or null (Limit) Default: 20 Maximum number of results to return. Defaults to 20 when omitted. Values must be in |
| cursor | string or null (Cursor) Default: null |
| property name* additional property | any |
{- "limit": 10,
- "cursor": null
}{- "items": [
- {
- "channel": "default",
- "create_time": {
- "display": "2024-05-15T14:06:58+00:00",
- "epoch": 1715782018
}, - "filters": [
- {
- "key": "activity.name",
- "value": "authentication"
}
], - "format_options": {
- "api_version": "2.0",
- "locale": "en",
- "item_format_version": 5
}, - "webhook_owner": {
- "organization": {
- "name": "Example Reseller"
}, - "user": {
- "username": "authenticator@example.com"
}
}, - "webhook_uuid": "cff3fe0e-122a-4cb6-8b73-465c529d8b02"
}
], - "item_count": 1,
- "next_cursor": null
}Retrieve a webhook's configuration: filters, channel, endpoint, webhook_owner, create_time, and format_options.
This does not include delivery history or delivery status.
| webhook_uuid required | string |
{- "channel": "default",
- "create_time": {
- "display": "2024-05-15T14:06:58+00:00",
- "epoch": 1715782018
}, - "filters": [
- {
- "key": "activity.name",
- "value": "authentication"
}
], - "format_options": {
- "api_version": "2.0",
- "locale": "en",
- "item_format_version": 5
}, - "webhook_owner": {
- "organization": {
- "name": "Example Reseller"
}, - "user": {
- "username": "authenticator@example.com"
}
}, - "webhook_uuid": "cff3fe0e-122a-4cb6-8b73-465c529d8b02"
}