API reference

Test mode. Use your secret key on your server; live processing is currently disabled.

https://api.knoxapi.com

Send form-encoded requests with Authorization: Bearer sk_test_....

Complete OpenAPI specification · Integration guide

Operations and schemas are based on the pinned Stripe OpenAPI specification (MIT). Nested object definitions and enums are available in the complete specification.

GET /v1/identity/verification_reports

List VerificationReports

List all verification reports.

Request parameters

Parameter	Location	Type	Description
`client_reference_id`	query	string	A string to reference this user. This can be a customer ID, a session ID, or similar, and can be used to reconcile this verification with your internal systems.
`created`	query	one of multiple schemas	Only return VerificationReports that were created during the given date interval.
`ending_before`	query	string	A cursor for use in pagination. `ending_before` is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, starting with `obj_bar`, your subsequent call can include `ending_before=obj_bar` in order to fetch the previous page of the list.
`expand`	query	array of string	Specifies which fields in the response should be expanded.
`limit`	query	integer	A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 10.
`starting_after`	query	string	A cursor for use in pagination. `starting_after` is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, ending with `obj_foo`, your subsequent call can include `starting_after=obj_foo` in order to fetch the next page of the list.
`type`	query	string	Only return VerificationReports of this type
`verification_session`	query	string	Only return VerificationReports created by this VerificationSession ID. It is allowed to provide a VerificationIntent ID.

object. See the OpenAPI specification for the complete schema.

Responses

HTTP 200: Successful response.

Field	Type	Description
`data` required	array of identity.verification_report
`has_more` required	boolean	True if this list has another page of items after this one that can be fetched.
`object` required	string	String representing the object's type. Objects of the same type share the same value. Always has the value `list`.
`url` required	string	The URL where this list can be accessed.

HTTP default: Error response.

Field	Type	Description
`error` required	api_errors

GET /v1/identity/verification_sessions

List VerificationSessions

Returns a list of VerificationSessions

Request parameters

Parameter	Location	Type	Description
`client_reference_id`	query	string	A string to reference this user. This can be a customer ID, a session ID, or similar, and can be used to reconcile this verification with your internal systems.
`created`	query	one of multiple schemas	Only return VerificationSessions that were created during the given date interval.
`ending_before`	query	string	A cursor for use in pagination. `ending_before` is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, starting with `obj_bar`, your subsequent call can include `ending_before=obj_bar` in order to fetch the previous page of the list.
`expand`	query	array of string	Specifies which fields in the response should be expanded.
`limit`	query	integer	A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 10.
`related_customer`	query	string	Customer ID
`related_customer_account`	query	string	The ID of the Account representing a customer.
`starting_after`	query	string	A cursor for use in pagination. `starting_after` is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, ending with `obj_foo`, your subsequent call can include `starting_after=obj_foo` in order to fetch the next page of the list.
`status`	query	string	Only return VerificationSessions with this status. [Learn more about the lifecycle of sessions](https://docs.stripe.com/identity/how-sessions-work).

object. See the OpenAPI specification for the complete schema.

Responses

HTTP 200: Successful response.

Field	Type	Description
`data` required	array of identity.verification_session
`has_more` required	boolean	True if this list has another page of items after this one that can be fetched.
`object` required	string	String representing the object's type. Objects of the same type share the same value. Always has the value `list`.
`url` required	string	The URL where this list can be accessed.

HTTP default: Error response.

Field	Type	Description
`error` required	api_errors

POST /v1/identity/verification_sessions

Create a VerificationSession

Creates a VerificationSession object. After the VerificationSession is created, display a verification modal using the session client_secret or send your users to the session’s url. If your API key is in test mode, verification checks won’t actually process, though everything else will occur as if in live mode. Related guide: Verify your users’ identity documents

Request parameters

Field	Type	Description
`client_reference_id`	string	A string to reference this user. This can be a customer ID, a session ID, or similar, and can be used to reconcile this verification with your internal systems.
`expand`	array of string	Specifies which fields in the response should be expanded.
`metadata`	object	Set of [key-value pairs](https://docs.stripe.com/api/metadata) that you can attach to an object. This can be useful for storing additional information about the object in a structured format. Individual keys can be unset by posting an empty value to them. All keys can be unset by posting an empty value to `metadata`.
`options`	object	A set of options for the session’s verification checks.
`provided_details`	object	Details provided about the user being verified. These details might be shown to the user.
`related_customer`	string	Customer ID
`related_customer_account`	string	The ID of the Account representing a customer.
`related_person`	object	Tokens referencing a Person resource and its associated account.
`return_url`	string	The URL that the user will be redirected to upon completing the verification flow.
`type`	string	The type of [verification check](https://docs.stripe.com/identity/verification-checks) to be performed. You must provide a `type` if not passing `verification_flow`.
`verification_flow`	string	The ID of a verification flow from the Dashboard. See https://docs.stripe.com/identity/verification-flows.

Responses

HTTP 200: Successful response.

Field	Type	Description
`client_reference_id`	string	A string to reference this user. This can be a customer ID, a session ID, or similar, and can be used to reconcile this verification with your internal systems.
`client_secret`	string	The short-lived client secret used by Stripe.js to [show a verification modal](https://docs.stripe.com/js/identity/modal) inside your app. This client secret expires after 24 hours and can only be used once. Don’t store it, log it, embed it in a URL, or expose it to anyone other than the user. Make sure that you have TLS enabled on any page that includes the client secret. Refer to our docs on [passing the client secret to the frontend](https://docs.stripe.com/identity/verification-sessions#client-secret) to learn more.
`created` required	integer	Time at which the object was created. Measured in seconds since the Unix epoch.
`id` required	string	Unique identifier for the object.
`last_error`	one of multiple schemas	If present, this property tells you the last error encountered when processing the verification.
`last_verification_report`	one of multiple schemas	ID of the most recent VerificationReport. [Learn more about accessing detailed verification results.](https://docs.stripe.com/identity/verification-sessions#results)
`livemode` required	boolean	If the object exists in live mode, the value is `true`. If the object exists in test mode, the value is `false`.
`metadata` required	object	Set of [key-value pairs](https://docs.stripe.com/api/metadata) that you can attach to an object. This can be useful for storing additional information about the object in a structured format.
`object` required	string	String representing the object's type. Objects of the same type share the same value.
`options`	one of multiple schemas	A set of options for the session’s verification checks.
`provided_details`	one of multiple schemas	Details provided about the user being verified. These details may be shown to the user.
`redaction`	one of multiple schemas	Redaction status of this VerificationSession. If the VerificationSession is not redacted, this field will be null.
`related_customer`	string	Customer ID
`related_customer_account`	string	The ID of the Account representing a customer.
`related_person`	gelato_related_person
`status` required	string	Status of this VerificationSession. [Learn more about the lifecycle of sessions](https://docs.stripe.com/identity/how-sessions-work).
`type` required	string	The type of [verification check](https://docs.stripe.com/identity/verification-checks) to be performed.
`url`	string	The short-lived URL that you use to redirect a user to Stripe to submit their identity information. This URL expires after 48 hours and can only be used once. Don’t store it, log it, send it in emails or expose it to anyone other than the user. Refer to our docs on [verifying identity documents](https://docs.stripe.com/identity/verify-identity-documents?platform=web&type=redirect) to learn how to redirect users to Stripe.
`verification_flow`	string	The configuration token of a verification flow from the dashboard.
`verified_outputs`	one of multiple schemas	The user’s verified data.

HTTP default: Error response.

Field	Type	Description
`error` required	api_errors

GET /v1/identity/verification_reports/{report}

Retrieve a VerificationReport

Retrieves an existing VerificationReport

Request parameters

Parameter	Location	Type	Description
`expand`	query	array of string	Specifies which fields in the response should be expanded.
`report`	path	string

object. See the OpenAPI specification for the complete schema.

Responses

HTTP 200: Successful response.

Field	Type	Description
`client_reference_id`	string	A string to reference this user. This can be a customer ID, a session ID, or similar, and can be used to reconcile this verification with your internal systems.
`created` required	integer	Time at which the object was created. Measured in seconds since the Unix epoch.
`document`	gelato_document_report
`email`	gelato_email_report
`id` required	string	Unique identifier for the object.
`id_number`	gelato_id_number_report
`livemode` required	boolean	If the object exists in live mode, the value is `true`. If the object exists in test mode, the value is `false`.
`object` required	string	String representing the object's type. Objects of the same type share the same value.
`options`	gelato_verification_report_options
`phone`	gelato_phone_report
`selfie`	gelato_selfie_report
`type` required	string	Type of report.
`verification_flow`	string	The configuration token of a verification flow from the dashboard.
`verification_session`	string	ID of the VerificationSession that created this report.

HTTP default: Error response.

Field	Type	Description
`error` required	api_errors

GET /v1/identity/verification_sessions/{session}

Retrieve a VerificationSession

Retrieves the details of a VerificationSession that was previously created. When the session status is requires_input, you can use this method to retrieve a valid client_secret or url to allow re-submission.

Request parameters

Parameter	Location	Type	Description
`expand`	query	array of string	Specifies which fields in the response should be expanded.
`session`	path	string

object. See the OpenAPI specification for the complete schema.

Responses

HTTP 200: Successful response.

Field	Type	Description
`client_reference_id`	string	A string to reference this user. This can be a customer ID, a session ID, or similar, and can be used to reconcile this verification with your internal systems.
`client_secret`	string	The short-lived client secret used by Stripe.js to [show a verification modal](https://docs.stripe.com/js/identity/modal) inside your app. This client secret expires after 24 hours and can only be used once. Don’t store it, log it, embed it in a URL, or expose it to anyone other than the user. Make sure that you have TLS enabled on any page that includes the client secret. Refer to our docs on [passing the client secret to the frontend](https://docs.stripe.com/identity/verification-sessions#client-secret) to learn more.
`created` required	integer	Time at which the object was created. Measured in seconds since the Unix epoch.
`id` required	string	Unique identifier for the object.
`last_error`	one of multiple schemas	If present, this property tells you the last error encountered when processing the verification.
`last_verification_report`	one of multiple schemas	ID of the most recent VerificationReport. [Learn more about accessing detailed verification results.](https://docs.stripe.com/identity/verification-sessions#results)
`livemode` required	boolean	If the object exists in live mode, the value is `true`. If the object exists in test mode, the value is `false`.
`metadata` required	object	Set of [key-value pairs](https://docs.stripe.com/api/metadata) that you can attach to an object. This can be useful for storing additional information about the object in a structured format.
`object` required	string	String representing the object's type. Objects of the same type share the same value.
`options`	one of multiple schemas	A set of options for the session’s verification checks.
`provided_details`	one of multiple schemas	Details provided about the user being verified. These details may be shown to the user.
`redaction`	one of multiple schemas	Redaction status of this VerificationSession. If the VerificationSession is not redacted, this field will be null.
`related_customer`	string	Customer ID
`related_customer_account`	string	The ID of the Account representing a customer.
`related_person`	gelato_related_person
`status` required	string	Status of this VerificationSession. [Learn more about the lifecycle of sessions](https://docs.stripe.com/identity/how-sessions-work).
`type` required	string	The type of [verification check](https://docs.stripe.com/identity/verification-checks) to be performed.
`url`	string	The short-lived URL that you use to redirect a user to Stripe to submit their identity information. This URL expires after 48 hours and can only be used once. Don’t store it, log it, send it in emails or expose it to anyone other than the user. Refer to our docs on [verifying identity documents](https://docs.stripe.com/identity/verify-identity-documents?platform=web&type=redirect) to learn how to redirect users to Stripe.
`verification_flow`	string	The configuration token of a verification flow from the dashboard.
`verified_outputs`	one of multiple schemas	The user’s verified data.

HTTP default: Error response.

Field	Type	Description
`error` required	api_errors

POST /v1/identity/verification_sessions/{session}

Update a VerificationSession

Updates a VerificationSession object. When the session status is requires_input, you can use this method to update the verification check and options.

Request parameters

Parameter	Location	Type	Description
`session`	path	string

Field	Type	Description
`expand`	array of string	Specifies which fields in the response should be expanded.
`metadata`	object	Set of [key-value pairs](https://docs.stripe.com/api/metadata) that you can attach to an object. This can be useful for storing additional information about the object in a structured format. Individual keys can be unset by posting an empty value to them. All keys can be unset by posting an empty value to `metadata`.
`options`	object	A set of options for the session’s verification checks.
`provided_details`	object	Details provided about the user being verified. These details may be shown to the user.
`type`	string	The type of [verification check](https://docs.stripe.com/identity/verification-checks) to be performed.

Responses

HTTP 200: Successful response.

Field	Type	Description
`client_reference_id`	string	A string to reference this user. This can be a customer ID, a session ID, or similar, and can be used to reconcile this verification with your internal systems.
`client_secret`	string	The short-lived client secret used by Stripe.js to [show a verification modal](https://docs.stripe.com/js/identity/modal) inside your app. This client secret expires after 24 hours and can only be used once. Don’t store it, log it, embed it in a URL, or expose it to anyone other than the user. Make sure that you have TLS enabled on any page that includes the client secret. Refer to our docs on [passing the client secret to the frontend](https://docs.stripe.com/identity/verification-sessions#client-secret) to learn more.
`created` required	integer	Time at which the object was created. Measured in seconds since the Unix epoch.
`id` required	string	Unique identifier for the object.
`last_error`	one of multiple schemas	If present, this property tells you the last error encountered when processing the verification.
`last_verification_report`	one of multiple schemas	ID of the most recent VerificationReport. [Learn more about accessing detailed verification results.](https://docs.stripe.com/identity/verification-sessions#results)
`livemode` required	boolean	If the object exists in live mode, the value is `true`. If the object exists in test mode, the value is `false`.
`metadata` required	object	Set of [key-value pairs](https://docs.stripe.com/api/metadata) that you can attach to an object. This can be useful for storing additional information about the object in a structured format.
`object` required	string	String representing the object's type. Objects of the same type share the same value.
`options`	one of multiple schemas	A set of options for the session’s verification checks.
`provided_details`	one of multiple schemas	Details provided about the user being verified. These details may be shown to the user.
`redaction`	one of multiple schemas	Redaction status of this VerificationSession. If the VerificationSession is not redacted, this field will be null.
`related_customer`	string	Customer ID
`related_customer_account`	string	The ID of the Account representing a customer.
`related_person`	gelato_related_person
`status` required	string	Status of this VerificationSession. [Learn more about the lifecycle of sessions](https://docs.stripe.com/identity/how-sessions-work).
`type` required	string	The type of [verification check](https://docs.stripe.com/identity/verification-checks) to be performed.
`url`	string	The short-lived URL that you use to redirect a user to Stripe to submit their identity information. This URL expires after 48 hours and can only be used once. Don’t store it, log it, send it in emails or expose it to anyone other than the user. Refer to our docs on [verifying identity documents](https://docs.stripe.com/identity/verify-identity-documents?platform=web&type=redirect) to learn how to redirect users to Stripe.
`verification_flow`	string	The configuration token of a verification flow from the dashboard.
`verified_outputs`	one of multiple schemas	The user’s verified data.

HTTP default: Error response.

Field	Type	Description
`error` required	api_errors

POST /v1/identity/verification_sessions/{session}/cancel

Cancel a VerificationSession

A VerificationSession object can be canceled when it is in requires_input status. Once canceled, future submission attempts are disabled. This cannot be undone. Learn more.

Request parameters

Parameter	Location	Type	Description
`session`	path	string

Field	Type	Description
`expand`	array of string	Specifies which fields in the response should be expanded.

Responses

HTTP 200: Successful response.

Field	Type	Description
`client_reference_id`	string	A string to reference this user. This can be a customer ID, a session ID, or similar, and can be used to reconcile this verification with your internal systems.
`client_secret`	string	The short-lived client secret used by Stripe.js to [show a verification modal](https://docs.stripe.com/js/identity/modal) inside your app. This client secret expires after 24 hours and can only be used once. Don’t store it, log it, embed it in a URL, or expose it to anyone other than the user. Make sure that you have TLS enabled on any page that includes the client secret. Refer to our docs on [passing the client secret to the frontend](https://docs.stripe.com/identity/verification-sessions#client-secret) to learn more.
`created` required	integer	Time at which the object was created. Measured in seconds since the Unix epoch.
`id` required	string	Unique identifier for the object.
`last_error`	one of multiple schemas	If present, this property tells you the last error encountered when processing the verification.
`last_verification_report`	one of multiple schemas	ID of the most recent VerificationReport. [Learn more about accessing detailed verification results.](https://docs.stripe.com/identity/verification-sessions#results)
`livemode` required	boolean	If the object exists in live mode, the value is `true`. If the object exists in test mode, the value is `false`.
`metadata` required	object	Set of [key-value pairs](https://docs.stripe.com/api/metadata) that you can attach to an object. This can be useful for storing additional information about the object in a structured format.
`object` required	string	String representing the object's type. Objects of the same type share the same value.
`options`	one of multiple schemas	A set of options for the session’s verification checks.
`provided_details`	one of multiple schemas	Details provided about the user being verified. These details may be shown to the user.
`redaction`	one of multiple schemas	Redaction status of this VerificationSession. If the VerificationSession is not redacted, this field will be null.
`related_customer`	string	Customer ID
`related_customer_account`	string	The ID of the Account representing a customer.
`related_person`	gelato_related_person
`status` required	string	Status of this VerificationSession. [Learn more about the lifecycle of sessions](https://docs.stripe.com/identity/how-sessions-work).
`type` required	string	The type of [verification check](https://docs.stripe.com/identity/verification-checks) to be performed.
`url`	string	The short-lived URL that you use to redirect a user to Stripe to submit their identity information. This URL expires after 48 hours and can only be used once. Don’t store it, log it, send it in emails or expose it to anyone other than the user. Refer to our docs on [verifying identity documents](https://docs.stripe.com/identity/verify-identity-documents?platform=web&type=redirect) to learn how to redirect users to Stripe.
`verification_flow`	string	The configuration token of a verification flow from the dashboard.
`verified_outputs`	one of multiple schemas	The user’s verified data.

HTTP default: Error response.

Field	Type	Description
`error` required	api_errors

POST /v1/identity/verification_sessions/{session}/redact

Redact a VerificationSession

Redact a VerificationSession to remove all collected information from Stripe. This will redact the VerificationSession and all objects related to it, including VerificationReports, Events, request logs, etc. A VerificationSession object can be redacted when it is in requires_input or verified status. Redacting a VerificationSession in requires_action state will automatically cancel it. The redaction process may take up to four days. When the redaction process is in progress, the VerificationSession’s redaction.status field will be set to processing; when the process is finished, it will change to redacted and an identity.verification_session.redacted event will be emitted. Redaction is irreversible. Redacted objects are still accessible in the Stripe API, but all the fields that contain personal data will be replaced by the string [redacted] or a similar placeholder. The metadata field will also be erased. Redacted objects cannot be updated or used for any purpose. Learn more.

Request parameters

Parameter	Location	Type	Description
`session`	path	string

Field	Type	Description
`expand`	array of string	Specifies which fields in the response should be expanded.

Responses

HTTP 200: Successful response.

Field	Type	Description
`client_reference_id`	string	A string to reference this user. This can be a customer ID, a session ID, or similar, and can be used to reconcile this verification with your internal systems.
`client_secret`	string	The short-lived client secret used by Stripe.js to [show a verification modal](https://docs.stripe.com/js/identity/modal) inside your app. This client secret expires after 24 hours and can only be used once. Don’t store it, log it, embed it in a URL, or expose it to anyone other than the user. Make sure that you have TLS enabled on any page that includes the client secret. Refer to our docs on [passing the client secret to the frontend](https://docs.stripe.com/identity/verification-sessions#client-secret) to learn more.
`created` required	integer	Time at which the object was created. Measured in seconds since the Unix epoch.
`id` required	string	Unique identifier for the object.
`last_error`	one of multiple schemas	If present, this property tells you the last error encountered when processing the verification.
`last_verification_report`	one of multiple schemas	ID of the most recent VerificationReport. [Learn more about accessing detailed verification results.](https://docs.stripe.com/identity/verification-sessions#results)
`livemode` required	boolean	If the object exists in live mode, the value is `true`. If the object exists in test mode, the value is `false`.
`metadata` required	object	Set of [key-value pairs](https://docs.stripe.com/api/metadata) that you can attach to an object. This can be useful for storing additional information about the object in a structured format.
`object` required	string	String representing the object's type. Objects of the same type share the same value.
`options`	one of multiple schemas	A set of options for the session’s verification checks.
`provided_details`	one of multiple schemas	Details provided about the user being verified. These details may be shown to the user.
`redaction`	one of multiple schemas	Redaction status of this VerificationSession. If the VerificationSession is not redacted, this field will be null.
`related_customer`	string	Customer ID
`related_customer_account`	string	The ID of the Account representing a customer.
`related_person`	gelato_related_person
`status` required	string	Status of this VerificationSession. [Learn more about the lifecycle of sessions](https://docs.stripe.com/identity/how-sessions-work).
`type` required	string	The type of [verification check](https://docs.stripe.com/identity/verification-checks) to be performed.
`url`	string	The short-lived URL that you use to redirect a user to Stripe to submit their identity information. This URL expires after 48 hours and can only be used once. Don’t store it, log it, send it in emails or expose it to anyone other than the user. Refer to our docs on [verifying identity documents](https://docs.stripe.com/identity/verify-identity-documents?platform=web&type=redirect) to learn how to redirect users to Stripe.
`verification_flow`	string	The configuration token of a verification flow from the dashboard.
`verified_outputs`	one of multiple schemas	The user’s verified data.

HTTP default: Error response.

Field	Type	Description
`error` required	api_errors