Skip to main content

API Reference 1.4

note

All new applications should use the v2 API (release date: 2025 Q3). If you are maintaining an application that uses an older version, see the migration guides and the version history for details on upgrading.

Welcome to the Entrupy API!

Getting Started​

The Entrupy API serves all requests over HTTPS from api.entrupy.com.

An authorization token is required. Authorize your requests with the header Authorization: Token 01234567, replacing 01234567 with your token.

When making your requests, specify the desired API Version with the required header; for the v1.4 API use Api-Version: 1.4.

Specify what language should be used for display strings using the header Accept-Language: en. Currently this supports en for English, and ja for Japanese (Default: en).

For more information on the format of individual items, see the v1.4 data model.

Rate Limiting​

The API has a rate limit of ~10 requests per second. Requests exceeding this limit will receive the response code 429 Too Many Requests with a Retry-After header, set to the number of seconds to wait before retry. (See RFC6585#section-4)

You can test your credentials and check service health by making a request to the following path:

GET /v1/health​

Basic check to test credentials and view server status.

Example request:

GET /v1/health HTTP/1.1
Host: api.entrupy.com
Api-Version: 1.4
Authorization: Token [valid_token]

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "status": "ok"
}
  • Request Headers:
    • Api-Version: 1.4
    • Authorization: required token
  • Status Codes:
    • 200 OK: Authorized, service ok
    • 400 Bad Request: Incorrect headers
    • 401 Unauthorized: Route is unauthorized (token was invalid or not provided)
    • 429 Too Many Requests: Rate limit has been exceeded. The Retry-After header will contain the number of seconds to wait before retry.

API Versioning Policy​

We may make changes to the output of the routes described below without an API version bump as long as they are not considered breaking changes. All code processing API responses and webhook payloads should be written flexibly enough to handle these changes (Such as new keys added to dictionaries or new elements added to arrays). For details about what kinds of changes will be made without an API version bump in the future, please see the API versioning documentation.

API Routes​

Authentications API​

Users use the Entrupy app to create new authentications and modify certain fields. The authentications API allows read-only access to authentication status and history.

Retrieve Authentication Sessions by Entrupy ID​

GET /v1/authentications/{entrupy_id}​

Information and status for the authentication session {entrupy_id}.

This route only returns information for authentications owned by the requester. Invalid IDs or IDs owned by someone else will return a 403.

Example request A:

GET /v1/authentications/1SALEFYH HTTP/1.1
Host: api.entrupy.com
Accept-Language: en
Api-Version: 1.4
Authorization: Token [valid_token]

Example response A:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "item": {
    "activity": {
      "form_factor": "microscopic",
      "name": "authentication",
      "product_category": "luxury"
    },
    "certificate": {
      "preview": "https://cert.entrupy.com/1SALEFYH?format=sharable",
      "site": "https://cert.entrupy.com/1SALEFYH"
    },
    "entrupy_id": "1SALEFYH",
    "owner": {
      "organization": {
        "name": "EntrupyOrganization"
      },
      "user": {
        "username": "EntrupyUser"
      }
    },
    "properties": {
      "brand": {
        "display": "Louis Vuitton",
        "id": "louis_vuitton"
      },
      "material": {
        "display": "Damier Azur Canvas",
        "id": "damier_azur_canvas"
      }
    },
    "status": {
      "flag": null,
      "result": {
        "display": "Authentic",
        "final": true,
        "id": "authentic"
      }
    },
    "text_fields": {
      "customer_item_id": "8492068",
      "identifier": "9970303"
    },
    "timestamp": {
      "display": "2019-08-27T04:14:28.342735+00:00Z",
      "epoch": 1566879268.342735
    }
  }
}
  • Path Parameters:
    • entrupy_id (string): The Entrupy ID of the authentication session.
  • Query Parameters:
    • format_options__return_item_photos (boolean): Format option flag. Boolean that determines whether or not image URLs for each session's photo (macro) regions are returned. If set to true, a list of regions and image URLs will be returned at .images.photos. These image URLs are temporary and expire after one hour. Default: false.
  • Request Headers:
    • Accept-Language: en
    • Api-Version: 1.4
    • Authorization: required token
  • Status Codes:
    • 200 OK: Session exists, no error
    • 400 Bad Request: Incorrect headers
    • 401 Unauthorized: Route is unauthorized (token was invalid or not provided)
    • 403 Forbidden: Either the authentication with the provided ID does not exist, or you do not have access to it
    • 429 Too Many Requests: Rate limit has been exceeded. The Retry-After header will contain the number of seconds to wait before retry.

Retrieve Authentication Sessions by Customer Item ID (Order ID/SKU)​

GET /v1/lookup/authentications/{lookup_value}​

Information and status for the authentication that best matches the provided lookup value.

The default behavior is to lookup a matching Customer Item ID (Order ID / SKU). If there is an authentication with a final result, the first one is returned. Otherwise, the latest in-progress or non-final authentication is returned.

This route only returns information for authentications owned by the requester. Invalid IDs or IDs owned by someone else will return a 403.

Example request:

This returns the best match for Customer Item ID 5416322.

GET /v1/lookup/authentications/5416322 HTTP/1.1
Host: api.entrupy.com
Accept-Language: en
Api-Version: 1.4
Authorization: Token [valid_token]

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "item": {
    "activity": {
      "form_factor": "microscopic",
      "name": "authentication",
      "product_category": "luxury"
    },
    "certificate": {
      "preview": "https://cert.entrupy.com/E5F1LFYN?format=sharable",
      "site": "https://cert.entrupy.com/E5F1LFYN"
    },
    "entrupy_id": "E5F1LFYN",
    "owner": {
      "organization": {
        "name": "EntrupyOrganization"
      },
      "user": {
        "username": "EntrupyUser"
      }
    },
    "properties": {
      "brand": {
        "display": "Gucci",
        "id": "gucci"
      },
      "material": {
        "display": "GG Canvas",
        "id": "gg_canvas"
      }
    },
    "status": {
      "flag": null,
      "result": {
        "display": "Authentic",
        "final": true,
        "id": "authentic"
      }
    },
    "text_fields": {
      "customer_item_id": "5416322",
      "identifier": "8529268"
    },
    "timestamp": {
      "display": "2019-08-19T17:38:54.083790+00:00Z",
      "epoch": 1566236334.08379
    }
  }
}
  • Path Parameters:
    • lookup_value (string): The value to look up (e.g., Customer Item ID).
  • Query Parameters:
    • format_options__return_item_photos (boolean): Format option flag. Boolean that determines whether or not image URLs for each session's photo (macro) regions are returned. If set to true, a list of regions and image URLs will be returned at .images.photos. These image URLs are temporary and expire after one hour. Default: false.
  • Request Headers:
    • Accept-Language: en
    • Api-Version: 1.4
    • Authorization: required token
  • Status Codes:
    • 200 OK: Authentication exists, no error
    • 400 Bad Request: Incorrect headers
    • 401 Unauthorized: Route is unauthorized (token was invalid or not provided)
    • 403 Forbidden: Either the authentication with the provided ID does not exist, or you do not have access to it
    • 429 Too Many Requests: Rate limit has been exceeded. The Retry-After header will contain the number of seconds to wait before retry.

Search Authentication Sessions​

POST /v1/search/authentications​

Search for authentication sessions matching provided key/value filters.

This route only returns sessions owned by the requester.

Example request A:

This requests authentication sessions with Customer Item ID 5416322.

POST /v1/search/authentications HTTP/1.1
Host: api.entrupy.com
Accept-Language: en
Api-Version: 1.4
Authorization: Token [valid_token]
Content-Type: application/json

{
  "filters": [
    {
      "key": "text_fields.customer_item_id",
      "value": "5416322"
    }
  ]
}

Example response A:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "item_count": 1,
  "items": [
    {
      "activity": {
        "form_factor": "microscopic",
        "name": "authentication",
        "product_category": "luxury"
      },
      "certificate": {
        "preview": "https://cert.entrupy.com/E5F1LFYN?format=sharable",
        "site": "https://cert.entrupy.com/E5F1LFYN"
      },
      "entrupy_id": "E5F1LFYN",
      "owner": {
        "organization": {
          "name": "EntrupyOrganization"
        },
        "user": {
          "username": "EntrupyUser"
        }
      },
      "properties": {
        "brand": {
          "display": "Gucci",
          "id": "gucci"
        },
        "material": {
          "display": "GG Canvas",
          "id": "gg_canvas"
        }
      },
      "status": {
        "flag": null,
        "result": {
          "display": "Authentic",
          "final": true,
          "id": "authentic"
        }
      },
      "text_fields": {
        "customer_item_id": "5416322",
        "identifier": "8529268"
      },
      "timestamp": {
        "display": "2019-08-19T17:38:54.083790+00:00Z",
        "epoch": 1566236334.08379
      }
    }
  ],
  "next_cursor": null
}

Example request B:

This requests the two latest authentications with a brand id of louis_vuitton and an authentic or unidentified result.

POST /v1/search/authentications HTTP/1.1
Host: api.entrupy.com
Accept-Language: en
Api-Version: 1.4
Authorization: Token [valid_token]
Content-Type: application/json

{
  "filters": [
    {
      "key": "properties.brand.id",
      "value": "louis_vuitton"
    },
    {
      "key": "status.result.id",
      "values": ["authentic", "unidentified"]
    }
  ],
  "limit": 2
}

Example response B:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "item_count": 2,
  "items": [
    {
      "activity": {
        "form_factor": "microscopic",
        "name": "authentication",
        "product_category": "luxury"
      },
      "certificate": {
        "preview": "https://cert.entrupy.com/AF5FSFF6?format=sharable",
        "site": "https://cert.entrupy.com/AF5FSFF6"
      },
      "entrupy_id": "AF5FSFF6",
      "owner": {
        "organization": {
          "name": "EntrupyOrganization"
        },
        "user": {
          "username": "EntrupyUser"
        }
      },
      "properties": {
        "brand": {
          "display": "Louis Vuitton",
          "id": "louis_vuitton"
        },
        "material": {
          "display": "Damier Azur Canvas",
          "id": "damier_azur_canvas"
        }
      },
      "status": {
        "flag": null,
        "result": {
          "display": "Authentic",
          "final": true,
          "id": "authentic"
        }
      },
      "text_fields": {
        "customer_item_id": "8492068",
        "identifier": "2661081"
      },
      "timestamp": {
        "display": "2022-01-25T06:17:45.868821+00:00Z",
        "epoch": 1643091465.868821
      }
    },
    {
      "activity": {
        "form_factor": "microscopic",
        "name": "authentication",
        "product_category": "luxury"
      },
      "certificate": {
        "preview": "https://cert.entrupy.com/E5A1ZFDZ?format=sharable",
        "site": "https://cert.entrupy.com/E5A1ZFDZ"
      },
      "entrupy_id": "E5A1ZFDZ",
      "owner": {
        "organization": {
          "name": "EntrupyOrganization"
        },
        "user": {
          "username": "EntrupyUser"
        }
      },
      "properties": {
        "brand": {
          "display": "Louis Vuitton",
          "id": "louis_vuitton"
        },
        "material": {
          "display": "Monogram Canvas",
          "id": "monogram_canvas"
        }
      },
      "status": {
        "flag": null,
        "result": {
          "display": "Authentic",
          "final": true,
          "id": "authentic"
        }
      },
      "text_fields": {
        "customer_item_id": "8492068",
        "identifier": "6695155"
      },
      "timestamp": {
        "display": "2022-01-17T17:53:31.816675+00:00Z",
        "epoch": 1642442011.816675
      }
    }
  ],
  "next_cursor": "a215a2tueWFtbHdzZGZ6YnFtYmNtcHRyZ3pzcWx2emlxbWVpcnBkbQ=="
}

Since next_cursor is not null, more results exist. To get the next set of values, set cursor to "a215a2tueWFtbHdzZGZ6YnFtYmNtcHRyZ3pzcWx2emlxbWVpcnBkbQ==" on the next request. When next_cursor is null, the end of the search results have been reached.

Example request C:

This requests the latest 5 authentication Entrupy IDs.

POST /v1/search/authentications HTTP/1.1
Host: api.entrupy.com
Accept-Language: en
Api-Version: 1.4
Authorization: Token [valid_token]
Content-Type: application/json

{
  "limit": 5,
  "return": "entrupy_ids"
}

Example response C:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "entrupy_id_count": 5,
  "entrupy_ids": [
    "EZZNZF6W",
    "EZUZEFEZ",
    "UEUZLF9F",
    "LSLFAFML",
    "AF5FSFF6"
  ],
  "next_cursor": "bnlvd21ybmVwd2dodHhka3BsYnVoYndtYWhsbWxkcWltbmJidmpiaw=="
}

Example request D:

This requests the latest microscopic authentication session. See the data model document for a list of all form factors.

POST /v1/search/authentications HTTP/1.1
Host: api.entrupy.com
Accept-Language: en
Api-Version: 1.4
Authorization: Token [valid_token]
Content-Type: application/json

{
  "filters": [
    {
      "key": "activity.form_factor",
      "value": "microscopic"
    }
  ],
  "limit": 1
}

Example response D:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "item_count": 1,
  "items": [
    {
      "activity": {
        "form_factor": "microscopic",
        "name": "authentication",
        "product_category": "luxury"
      },
      "certificate": {
        "preview": "https://cert.entrupy.com/AF5FSFF6?format=sharable",
        "site": "https://cert.entrupy.com/AF5FSFF6"
      },
      "entrupy_id": "AF5FSFF6",
      "owner": {
        "organization": {
          "name": "EntrupyOrganization"
        },
        "user": {
          "username": "EntrupyUser"
        }
      },
      "properties": {
        "brand": {
          "display": "Louis Vuitton",
          "id": "louis_vuitton"
        },
        "material": {
          "display": "Damier Azur Canvas",
          "id": "damier_azur_canvas"
        }
      },
      "status": {
        "flag": null,
        "result": {
          "display": "Authentic",
          "final": true,
          "id": "authentic"
        }
      },
      "text_fields": {
        "customer_item_id": "8492068",
        "identifier": "2661081"
      },
      "timestamp": {
        "display": "2022-01-25T06:17:45.868821+00:00Z",
        "epoch": 1643091465.868821
      }
    }
  ],
  "next_cursor": "bnlvd21ybmVwd2dodHhka3BsYnVoYndtYWhsbWxkcWltbmJidmpiaw=="
}
  • Query Parameters:
    • filters (array): A list of filters used to narrow the result set. Default: null.
      • key (string): One of the following:
        • activity.form_factor
        • owner.organization.name
        • owner.user.username
        • properties.brand.id
        • properties.material.id
        • status.flag
        • status.result.id
        • text_fields.customer_item_id
        • text_fields.identifier
        • text_fields.style_code
        • text_fields.us_size
      • Note that when using a filter for text_fields.identifier you must also filter by properties.brand.id
      • value (string): A string that will be matched. Exactly one of value or values is required.
      • values (array): A list of strings that will be matched. Exactly one of value or values is required.
      • exclude (boolean): Boolean that determines whether the filter will be used to exclude matching values instead of returning matching values. Default: false.
      • text_fields (string): For text fields, determines which lookup method is used. Valid values are "canonical" or "verbatim". "canonical" returns all values with the same alphanumeric characters, case-insensitive. "verbatim" returns exact matches. Default: "canonical".
    • return (string): Determines whether to return full session information or Entrupy IDs only. Valid values are "items" and "entrupy_ids". Default: "items".
    • limit (integer): The maximum number of sessions or Entrupy IDs to be returned. Default: 25. Maximum: 25.
    • cursor (string): Used for pagination. Set this value to the previous request's next_cursor field to get the next set of results. Default: null.
    • range (object): Used to return entries in a given time interval. Default: null.
      • start (integer): Start date (earliest date), in unix epoch, or null.
      • end (integer): End date (latest date), in unix epoch, or null.
    • format_options (object): Optional flags that control per-session fields returned. Default: null.
      • return_item_photos (boolean): Boolean that determines whether or not image URLs for each session's photo (macro) regions are returned. If set to true, a list of regions and image URLs will be returned at .images.photos. These image URLs are temporary and expire after one hour. Default: false.
  • Request Headers:
    • Accept-Language: en
    • Api-Version: 1.4
    • Authorization: required token
    • Content-Type: application/json
  • Status Codes:
    • 200 OK: Valid request, result returned
    • 400 Bad Request: Incorrect headers or malformed request body
    • 401 Unauthorized: Route is unauthorized (token was invalid or not provided)
    • 429 Too Many Requests: Rate limit has been exceeded. The Retry-After header will contain the number of seconds to wait before retry.

Fingerprints API​

The Fingerprints API allows read-only access to fingerprint session status and history.

Retrieve Fingerprint Sessions by Entrupy ID​

GET /v1/fingerprints/{entrupy_id}​

Information and status for the fingerprint session {entrupy_id}.

This route only returns information for fingerprint sessions owned by the requester. Invalid IDs or IDs owned by someone else will return a 403.

Example request A:

GET /v1/fingerprints/ZS5NUFU7 HTTP/1.1
Host: api.entrupy.com
Accept-Language: en
Api-Version: 1.4
Authorization: Token [valid_token]

Example response A:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "item": {
    "activity": {
      "form_factor": "microscopic",
      "mode": "compare",
      "name": "fingerprint"
    },
    "entrupy_id": "ZS5NUFU7",
    "fingerprint_parent": {
      "activity": {
        "form_factor": "microscopic",
        "mode": "register",
        "name": "fingerprint"
      },
      "entrupy_id": "5PF5SFKS",
      "text_fields": {
        "customer_item_id": "9146416"
      },
      "url": "https://api.entrupy.com/v1/fingerprints/5PF5SFKS"
    },
    "owner": {
      "organization": {
        "name": "EntrupyOrganization"
      },
      "user": {
        "username": "EntrupyUser"
      }
    },
    "status": {
      "flag": null,
      "result": {
        "display": "Match",
        "final": true,
        "id": "match"
      }
    },
    "text_fields": {
      "customer_item_id": "9146416"
    },
    "timestamp": {
      "display": "2019-08-20T14:23:17.380397+00:00Z",
      "epoch": 1566310997.380397
    }
  }
}

In rare situations, some information from the item is not available even if you have permission to request the main item. For instance, if the fingerprint parent item is no longer registered to your account you will be missing the fingerprint_parent fields. In this case, in addition to the item key there will be a warnings key with more information. For example:

Example request B:

GET /v1/fingerprints/EL51EFHE HTTP/1.1
Host: api.entrupy.com
Accept-Language: en
Api-Version: 1.4
Authorization: Token [valid_token]

Example response B:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "item": {
    "activity": {
      "form_factor": "microscopic",
      "mode": "compare",
      "name": "fingerprint"
    },
    "entrupy_id": "EL51EFHE",
    "fingerprint_parent": {},
    "owner": {
      "organization": {
        "name": "EntrupyOrganization"
      },
      "user": {
        "username": "EntrupyUser"
      }
    },
    "status": {
      "flag": null,
      "result": {
        "display": "Match",
        "final": true,
        "id": "match"
      }
    },
    "text_fields": {
      "customer_item_id": "2266901"
    },
    "timestamp": {
      "display": "2019-06-18T13:35:14.363279+00:00Z",
      "epoch": 1560864914.363279
    }
  },
  "warnings": [
    {
      "code": "fingerprint_parent_not_authorized",
      "message": "Not authorized to access fingerprint parent"
    }
  ]
}
  • Path Parameters:
    • entrupy_id (string): The Entrupy ID of the fingerprint session.
  • Request Headers:
    • Accept-Language: en
    • Api-Version: 1.4
    • Authorization: required token
  • Status Codes:
    • 200 OK: Session exists, no error
    • 400 Bad Request: Incorrect headers
    • 401 Unauthorized: Route is unauthorized (token was invalid or not provided)
    • 403 Forbidden: Either the session with the provided ID does not exist, or you do not have access to it
    • 429 Too Many Requests: Rate limit has been exceeded. The Retry-After header will contain the number of seconds to wait before retry.

Search Fingerprint Sessions​

POST /v1/search/fingerprints​

Search for fingerprint sessions matching provided key/value filters.

This route only returns sessions owned by the requester.

Example request A:

This requests all fingerprint sessions where the fingerprint parent has Customer Item ID "8942625".

POST /v1/search/fingerprints HTTP/1.1
Host: api.entrupy.com
Accept-Language: en
Api-Version: 1.4
Authorization: Token [valid_token]
Content-Type: application/json

{
  "filters": [
    {
      "key": "fingerprint_parent.customer_item_id",
      "value": "8942625"
    }
  ]
}

Example response A:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "item_count": 1,
  "items": [
    {
      "activity": {
        "form_factor": "microscopic",
        "mode": "compare",
        "name": "fingerprint"
      },
      "entrupy_id": "5A1EAFSN",
      "fingerprint_parent": {
        "activity": {
          "form_factor": "microscopic",
          "mode": "register",
          "name": "fingerprint"
        },
        "entrupy_id": "UNEE5FAR",
        "text_fields": {
          "customer_item_id": "8942625"
        },
        "url": "https://api.entrupy.com/v1/fingerprints/UNEE5FAR"
      },
      "owner": {
        "organization": {
          "name": "EntrupyOrganization"
        },
        "user": {
          "username": "EntrupyUser"
        }
      },
      "status": {
        "flag": null,
        "result": {
          "display": "Match",
          "final": true,
          "id": "match"
        }
      },
      "text_fields": {
        "customer_item_id": "8942625"
      },
      "timestamp": {
        "display": "2021-09-24T15:01:58.420058+00:00Z",
        "epoch": 1632495718.420058
      }
    }
  ],
  "next_cursor": null
}

Example request B:

This searches for the last fingerprint comparison session with Customer Item ID "3144065".

POST /v1/search/fingerprints HTTP/1.1
Host: api.entrupy.com
Accept-Language: en
Api-Version: 1.4
Authorization: Token [valid_token]
Content-Type: application/json

{
  "filters": [
    {
      "key": "activity.mode",
      "value": "compare"
    },
    {
      "key": "text_fields.customer_item_id",
      "value": "3144065"
    }
  ],
  "limit": 1
}

Example response B:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "item_count": 1,
  "items": [
    {
      "activity": {
        "form_factor": "microscopic",
        "mode": "compare",
        "name": "fingerprint"
      },
      "entrupy_id": "PFP5NFEF",
      "fingerprint_parent": {
        "activity": {
          "form_factor": "microscopic",
          "mode": "register",
          "name": "fingerprint"
        },
        "entrupy_id": "LPULLFQN",
        "text_fields": {
          "customer_item_id": "3144065"
        },
        "url": "https://api.entrupy.com/v1/fingerprints/LPULLFQN"
      },
      "owner": {
        "organization": {
          "name": "EntrupyOrganization"
        },
        "user": {
          "username": "EntrupyUser"
        }
      },
      "status": {
        "flag": null,
        "result": {
          "display": "Match",
          "final": true,
          "id": "match"
        }
      },
      "text_fields": {
        "customer_item_id": "3144065"
      },
      "timestamp": {
        "display": "2021-09-17T13:29:55.654808+00:00Z",
        "epoch": 1631885395.654808
      }
    }
  ],
  "next_cursor": null
}

Example request C:

This searches for the last fingerprint registration session.

POST /v1/search/fingerprints HTTP/1.1
Host: api.entrupy.com
Accept-Language: en
Api-Version: 1.4
Authorization: Token [valid_token]
Content-Type: application/json

{
  "filters": [
    {
      "key": "activity.mode",
      "value": "register"
    }
  ],
  "limit": 1
}

Example response C:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "item_count": 1,
  "items": [
    {
      "activity": {
        "form_factor": "microscopic",
        "mode": "register",
        "name": "fingerprint"
      },
      "entrupy_id": "ZALZEFDN",
      "owner": {
        "organization": {
          "name": "EntrupyOrganization"
        },
        "user": {
          "username": "EntrupyUser"
        }
      },
      "status": {
        "flag": null,
        "result": {
          "display": "Registered",
          "final": true,
          "id": "registered"
        }
      },
      "text_fields": {
        "customer_item_id": "2529778"
      },
      "timestamp": {
        "display": "2022-01-18T16:05:36.973939+00:00Z",
        "epoch": 1642521936.973939
      }
    }
  ],
  "next_cursor": "aW92bGdpbGZ0b2xrc2R0bmhxcWFiemJzbmFud3Nscm5jYmt1cWtiaw=="
}

Since next_cursor is not null, more results exist. To get the next set of values, set cursor to aW92bGdpbGZ0b2xrc2R0bmhxcWFiemJzbmFud3Nscm5jYmt1cWtiaw== on the next request. When next_cursor is null, the end of the search results have been reached.

Example request D:

This requests the latest 5 fingerprint Entrupy IDs.

POST /v1/search/fingerprints HTTP/1.1
Host: api.entrupy.com
Accept-Language: en
Api-Version: 1.4
Authorization: Token [valid_token]
Content-Type: application/json

{
  "limit": 5,
  "return": "entrupy_ids"
}

Example response D:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "entrupy_id_count": 5,
  "entrupy_ids": [
    "NAUZEFXR",
    "ZFA5UFSE",
    "SESZ5FVC",
    "SNLSPFDD",
    "UNEEAFXS"
  ],
  "next_cursor": "eHNqZHNpZmpzZ29venFwYnNicHduc29hbXl0cHJyaGF5bGt6bXVsZg=="
}
  • Query Parameters:
    • filters (array): A list of filters used to narrow the result set. Default: null.
      • key (string): One of the following:
        • activity.mode
        • fingerprint_parent.entrupy_id
        • fingerprint_parent.customer_item_id
        • owner.organization.name
        • owner.user.username
        • status.flag
        • status.result.id
        • text_fields.customer_item_id
      • value (string): A string that will be matched. Exactly one of value or values is required.
      • values (array): A list of strings that will be matched. Exactly one of value or values is required.
      • exclude (boolean): Boolean that determines whether the filter will be used to exclude matching values instead of returning matching values. Default: false.
      • text_fields (string): For text fields, determines which lookup method is used. Valid values are "canonical" or "verbatim". "canonical" returns all values with the same alphanumeric characters, case-insensitive. "verbatim" returns exact matches. Default: "canonical".
    • return (string): Determines whether to return full session information or Entrupy IDs only. Valid values are "items" and "entrupy_ids". Default: "items".
    • limit (integer): The maximum number of items or Entrupy IDs to be returned. Default: 25. Maximum: 25.
    • cursor (string): Used for pagination. Set this value to the previous request's next_cursor field to get the next set of results. Default: null.
    • range (object): Used to return entries in a given time interval. Default: null.
      • start (integer): Start date (earliest date), in unix epoch, or null.
      • end (integer): End date (latest date), in unix epoch, or null.
  • Request Headers:
    • Accept-Language: en
    • Api-Version: 1.4
    • Authorization: required token
    • Content-Type: application/json
  • Status Codes:
    • 200 OK: Valid request, result returned
    • 400 Bad Request: Incorrect headers or malformed request body
    • 401 Unauthorized: Route is unauthorized (token was invalid or not provided)
    • 429 Too Many Requests: Rate limit has been exceeded. The Retry-After header will contain the number of seconds to wait before retry.

Webhooks​

For details on how to implement and use webhooks, see the Webhooks guide.