Entrupy API (2.0.0)

Download OpenAPI specification:Download

Authentication Data

Get authentication by Entrupy ID

Returns status, result, certificate, catalog, and image information for a specific authentication session.

path Parameters

entrupy_id

required

string

Responses

Response samples

200
404

Content type

application/json

Example

Default Response (No Optional Data)

{"item": {"entrupy_id": "ENTPY12345",
"timestamp": {"created_at": "2025-05-23T10:00:00Z"
},
"status": {"result": {"id": "authentic",
"final": true,
"display": null
},
"initial_result": {"id": "authentic",
"final": false,
"display": null
},
"flag": "reviewed_ok",
"retake": {"retake_required": false,
"display": ""
}
},
"activity": {"form_factor": "free_camera",
"name": "authentication",
"product_category": "luxury",
"mode": null
},
"properties": {"customer_item_id": "SKU9876",
"brand": "Chanel"
},
"owner": {"organization_id": "ORG_ABC",
"user_id": "USER_XYZ"
},
"certificate": {"certificate_id": "CERT_123",
"url": "https://example.com/certificate/ENTPY12345"
},
"text_fields": {"notes_to_buyer": "Handle with care."
},
"images": null,
"catalog": null
}
}

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.

path Parameters

lookup_value

required

string

Responses

Response samples

200
404

Content type

application/json

{"item": {"entrupy_id": "ENTPYLKUP789",
"timestamp": {"created_at": "2023-11-15T14:30:00Z",
"last_updated_at": "2023-11-15T14:35:00Z"
},
"status": {"result": {"id": "authentic",
"final": true
},
"initial_result": {"id": "authentic",
"final": false
},
"flag": null
},
"activity": {"form_factor": "microscopic",
"name": "authentication",
"product_category": "luxury",
"mode": null
},
"properties": {"customer_item_id": "CUST_LOOKUP_001",
"brand": "Louis Vuitton"
},
"owner": {"organization_id": "ORG_ABC",
"user_id": "USER_456"
},
"certificate": {"certificate_id": "CERT_LKUP_101",
"url": "https://example.com/certificate/ENTPYLKUP789"
},
"text_fields": {"notes_for_certificate": "Purchased from trusted reseller."
},
"images": {"main_image": {"url": "https://example.com/auth/ENTPYLKUP789_main.jpg"
},
"close_up_logo": {"url": "https://example.com/auth/ENTPYLKUP789_logo_cu.jpg"
}
},
"fingerprint_parent": null
}
}

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.

Request Body schema: application/json
required

	Limit (integer) or Limit (null) (Limit) Default: 10 Maximum number of results to return (max 25).
	Array of Filters (objects) or Filters (null) (Filters) Default: null List of filters to apply to the search results.
	Format Options (object) or Format Options (null) (Format Options) Default: null Advanced formatting options for results.
	TimestampRange (object) or null Default: null Time range filter to return entries within a given time interval. Both start and end are optional.
property name* additional property	any

Responses

Request samples

Payload

Content type

application/json

Example

Simple Search by Customer Item ID

{"limit": 10,
"filters": [{"key": "text_fields.customer_item_id",
"value": "CUST_SEARCH_A001",
"values": null,
"exclude": false,
"text_fields": null
}
],
"format_options": null,
"range": null
}

Response samples

200

Content type

application/json

Example

Successful Search with Results

{"items": [{"entrupy_id": "ENTPYSRCH001",
"timestamp": {"created_at": "2023-11-20T10:00:00Z"
},
"status": {"result": {"id": "authentic",
"final": true
},
"initial_result": null,
"flag": null
},
"activity": {"form_factor": "microscopic",
"name": "authentication",
"product_category": "luxury",
"mode": null
},
"properties": {"customer_item_id": "CUST_SEARCH_A001",
"brand": "Chanel"
},
"owner": null,
"certificate": {"url": "https://example.com/certificate/ENTPYSRCH001"
},
"text_fields": null,
"images": null,
"fingerprint_parent": null
},
{"entrupy_id": "ENTPYSRCH002",
"timestamp": {"created_at": "2023-10-05T15:30:00Z"
},
"status": {"result": {"id": "authentic",
"final": true
},
"initial_result": null,
"flag": null
},
"activity": {"form_factor": "microscopic",
"name": "authentication",
"product_category": "luxury",
"mode": null
},
"properties": {"customer_item_id": "CUST_SEARCH_B005",
"brand": "Gucci"
},
"owner": null,
"certificate": null,
"text_fields": {"notes": "From Fall 2023 collection"
},
"images": null,
"fingerprint_parent": null
}
],
"item_count": 2,
"next_cursor": "CURSOR_FOR_NEXT_PAGE_ABC456"
}

Fingerprint Data

Get fingerprint by Entrupy ID

Return the fingerprint record for an item. Use this endpoint when verifying that a new submission matches the original fingerprint stored by Entrupy.

path Parameters

entrupy_id

required

string

Responses

Response samples

200
404

Content type

application/json

{"item": {"entrupy_id": "ENTPYFP123",
"timestamp": {"created_at": "2023-10-26T10:00:00Z",
"last_updated_at": "2023-10-26T10:05:00Z"
},
"status": {"result": {"id": "verified",
"final": true
},
"initial_result": null,
"flag": null
},
"activity": {"form_factor": "microscopic",
"name": "fingerprint",
"product_category": null,
"mode": "register"
},
"properties": {"customer_item_id": "CUST_FP_ITEM_789",
"device_id": "DEVICE_ABC",
"app_version": "1.5.0"
},
"owner": {"organization_id": "ORG_XYZ",
"user_id": "USER_123"
},
"certificate": null,
"text_fields": {"internal_notes": "Fingerprint captured for archival.",
"location_captured": "Warehouse A"
},
"images": {"microscopic_close_up": {"url": "https://example.com/fp/ENTPYFP123_mc1.jpg",
"metadata": {"zoom_level": "100x"
}
},
"overview_image": {"url": "https://example.com/fp/ENTPYFP123_ov1.jpg"
}
},
"fingerprint_parent": {"entrupy_id": "ENTPYAUTHPARENT456",
"relationship_type": "derived_from_authentication"
}
}
}

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.

Request Body schema: application/json
required

	Limit (integer) or Limit (null) (Limit) Default: 10 Maximum number of results to return (max 25).
	Array of Filters (objects) or Filters (null) (Filters) Default: null List of filters to apply to the search results.
	Format Options (object) or Format Options (null) (Format Options) Default: null Advanced formatting options for results.
	TimestampRange (object) or null Default: null Time range filter to return entries within a given time interval. Both start and end are optional.
property name* additional property	any

Responses

Request samples

Payload

Content type

application/json

{"limit": 5,
"filters": [{"key": "properties.brand.id",
"value": "some_brand_id",
"values": null,
"exclude": false,
"text_fields": null
},
{"key": "text_fields.customer_item_id",
"value": "FP_ITEM_001",
"values": null,
"exclude": false,
"text_fields": "canonical"
}
],
"format_options": null,
"range": null
}

Response samples

200

Content type

application/json

Example

Successful Fingerprint Search with Results

{"items": [{"entrupy_id": "ENTPYFP456",
"timestamp": {"created_at": "2023-12-01T10:00:00Z",
"last_updated_at": "2023-12-01T10:05:00Z"
},
"status": {"result": {"id": "verified",
"final": true
},
"initial_result": null,
"flag": null
},
"activity": {"form_factor": "microscopic",
"name": "fingerprint",
"product_category": null,
"mode": "registration"
},
"properties": {"customer_item_id": "FP_ITEM_001",
"brand": {"id": "some_brand_id",
"name": "Example Brand"
},
"device_id": "DEVICE_XYZ",
"app_version": "1.6.0"
},
"owner": {"organization_id": "ORG_123",
"user_id": "USER_ABC"
},
"certificate": null,
"text_fields": {"internal_notes": "Archival fingerprint."
},
"images": {"microscopic_close_up": {"url": "https://example.com/fp/ENTPYFP456_mc1.jpg"
},
"overview_image": {"url": "https://example.com/fp/ENTPYFP456_ov1.jpg"
}
},
"fingerprint_parent": null
}
],
"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

200

Content type

application/json

{"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
}

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 First Name (null) (First Name) Default: null The user's first name.
	Last Name (string) or Last Name (null) (Last Name) Default: null The user's last name.
property name* additional property	any

Responses

Request samples

Payload

Content type

application/json

{"unique_user_id": "testuser123",
"email": "testuser123@example.com",
"first_name": "Test",
"last_name": "User"
}

Response samples

200
400
409

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 First Name (null) (First Name) Default: null The user's first name.
	Last Name (string) or Last Name (null) (Last Name) Default: null The user's last name.
property name* additional property	any

Responses

Request samples

Payload

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

200
400
403

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. Returns 503 when catalog data is temporarily unavailable; clients should retry.

Responses

Response samples

200
503

Content type

application/json

{"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"
}
}
]
}
]
}
]
}

Webhooks

Search registered domains

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

Request Body schema: application/json
required

	Limit (integer) or Limit (null) (Limit) Default: 25
	Cursor (string) or Cursor (null) (Cursor) Default: null
property name* additional property	any

Responses

Request samples

Payload

Content type

application/json

{"limit": 10,
"cursor": null
}

Response samples

200

Content type

application/json

{"items": [{"create_timestamp": null,
"domain_name": "sample-endpoint.entrupy.com",
"domain_owner": null,
"domain_uuid": "b9b39947-8a16-483d-a7eb-2b961c41b2f7"
}
],
"item_count": 1,
"next_cursor": null
}

Create webhook

Register a webhook endpoint to receive real-time notifications such as session completion or support messages. The target URL must be on a registered domain and payloads are signed with your secret key.

Request Body schema: application/json
required

endpoint required	object (Endpoint)
secret_key required	string (Secret Key)
	Channel (string) or Channel (null) (Channel) Default: null
	Array of Filters (objects) or Filters (null) (Filters) Default: null
property name* additional property	any

Responses

Request samples

Payload

Content type

application/json

{"endpoint": {"type": "url",
"value": "https://sample-endpoint.entrupy.com/notifications"
},
"secret_key": "ExampleSecretKey1234567890",
"channel": null,
"filters": [{"key": "activity.name",
"value": "authentication"
}
]
}

Response samples

200

Content type

application/json

{"channel": "default",
"create_timestamp": null,
"endpoint": {"type": "url",
"value": "https://sample-endpoint.entrupy.com/notifications"
},
"filters": [{"key": "activity.name",
"value": "authentication"
}
],
"webhook_owner": null,
"webhook_uuid": "cff3fe0e-122a-4cb6-8b73-465c529d8b02"
}

Search webhooks

List active webhook configurations owned by your organization. Use this to audit or manage existing callback endpoints.

Request Body schema: application/json
required

	Limit (integer) or Limit (null) (Limit) Default: 25
	Cursor (string) or Cursor (null) (Cursor) Default: null
property name* additional property	any

Responses

Request samples

Payload

Content type

application/json

{"limit": 10,
"cursor": null
}

Response samples

200

Content type

application/json

{"items": [{"channel": "default",
"create_timestamp": null,
"endpoint": {"type": "url",
"value": "https://sample-endpoint.entrupy.com/notifications"
},
"filters": [{"key": "activity.name",
"value": "authentication"
}
],
"webhook_owner": null,
"webhook_uuid": "cff3fe0e-122a-4cb6-8b73-465c529d8b02"
}
],
"item_count": 1,
"next_cursor": null
}

Get webhook

Retrieve details about a specific webhook, including its filters, channel, and current delivery status.

path Parameters

webhook_uuid

required

string

Responses

Response samples

200

Content type

application/json

{"channel": "default",
"create_timestamp": null,
"endpoint": {"type": "url",
"value": "https://sample-endpoint.entrupy.com/notifications"
},
"filters": [{"key": "activity.name",
"value": "authentication"
}
],
"webhook_owner": null,
"webhook_uuid": "cff3fe0e-122a-4cb6-8b73-465c529d8b02"
}

Deactivate webhook

Disable a webhook so that no further events are delivered. The webhook remains in the system and can be reactivated or inspected later.

path Parameters

webhook_uuid

required

string

Responses

Response samples

200

Content type

application/json

{"status": "ok"
}

Entrupy API (2.0.0)

Authentication Data

Get authentication by Entrupy ID

path Parameters

Responses

Response samples

Lookup authentication by Customer ID

path Parameters

Responses

Response samples

Search authentications

Request Body schema: application/jsonrequired

Responses

Request samples

Response samples

Fingerprint Data

Get fingerprint by Entrupy ID

path Parameters

Responses

Response samples

Search fingerprints

Request Body schema: application/jsonrequired

Responses

Request samples

Response samples

Integrations

Authentication config

Responses

Response samples

Create login voucher

Request Body schema: application/jsonrequired

Responses

Request samples

Response samples

Authorize user

Request Body schema: application/jsonrequired

Responses

Request samples

Response samples

Supported brands and categories

Responses

Response samples

Webhooks

Search registered domains

Request Body schema: application/jsonrequired

Responses

Request samples

Response samples

Create webhook

Request Body schema: application/jsonrequired

Responses

Request samples

Response samples

Search webhooks

Request Body schema: application/jsonrequired

Responses

Request samples

Response samples

Get webhook

path Parameters

Responses

Response samples

Deactivate webhook

path Parameters

Responses

Response samples

Request Body schema: application/json
required

Request Body schema: application/json
required

Request Body schema: application/json
required

Request Body schema: application/json
required

Request Body schema: application/json
required

Request Body schema: application/json
required

Request Body schema: application/json
required