API reference

Identity

Knox answers these operations with the same requests and responses as Stripe's API. Authenticate with your secret key, Authorization: Bearer sk_test_..., from your server, and send form-encoded bodies. Test mode only: live processing is currently disabled.

List VerificationReports

GET/v1/identity/verification_reports

List all verification reports.

Query parameters

  • client_reference_idstring

    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.

  • createdobject | integer

    Only return VerificationReports that were created during the given date interval.

    Show 4 child parameters
    • gtinteger
    • gteinteger
    • ltinteger
    • lteinteger
  • ending_beforestring

    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.

  • expandarray of strings

    Specifies which fields in the response should be expanded.

  • limitinteger

    A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 10.

  • starting_afterstring

    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.

  • typestring

    Only return VerificationReports of this type

    Possible values
    • document
    • id_number
  • verification_sessionstring

    Only return VerificationReports created by this VerificationSession ID. It is allowed to provide a VerificationIntent ID.

Returns

A list of identity.verification_report objects.

GET /v1/identity/verification_reports
curl -G https://api.knoxapi.com/v1/identity/verification_reports \
  -H "Authorization: Bearer $KNOX_SECRET_KEY" \
  --data-urlencode limit=3
Response
{
  "object": "list",
  "url": "/v1/identity/verification_reports",
  "has_more": false,
  "data": [
    {
      "client_reference_id": null,
      "created": 1234567890,
      "document": {
        "address": {
          "city": "San Francisco",
          "country": "US",
          "line1": "1234 Main St.",
          "state": "CA",
          "line2": null,
          "postal_code": null
        },
        "error": {
          "code": null,
          "reason": null
        },
        "expiration_date": {
          "day": 1,
          "month": 12,
          "year": 2030
        },
        "files": [
          "file_QXhWG300bR0L1WbLXBqG1wQc",
          "file_QXhWi7GgxZg2M3XqN2Y0P4Q2"
        ],
        "first_name": "Jenny",
        "issued_date": {
          "day": 1,
          "month": 12,
          "year": 2020
        },
        "issuing_country": "US",
        "last_name": "Rosen",
        "status": "verified",
        "type": "driving_license"
      },
      "id": "vr_1Pgc76B7WZ01zgkWq9Rp33Dj",
      "livemode": false,
      "object": "identity.verification_report",
      "options": {
        "document": {},
        "id_number": {}
      },
      "type": "document",
      "verification_session": "vs_1Pgc76B7WZ01zgkW1uXbT3Y9"
    }
  ]
}

Create a VerificationSession

POST/v1/identity/verification_sessions

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

Body parameters

  • client_reference_idstring

    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.

  • expandarray of strings

    Specifies which fields in the response should be expanded.

  • metadataobject

    Set of key-value pairs 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.

  • optionsobject

    A set of options for the session’s verification checks.

    Show 1 child parameter
    • documentobject
      Show 4 child parameters
      • allowed_typesarray of strings
      • require_id_numberboolean
      • require_live_captureboolean
      • require_matching_selfieboolean
  • provided_detailsobject

    Details provided about the user being verified. These details might be shown to the user.

    Show 2 child parameters
    • emailstring
    • phonestring
  • related_customerstring

    Customer ID

  • related_customer_accountstring

    The ID of the Account representing a customer.

  • related_personobject

    Tokens referencing a Person resource and its associated account.

    Show 2 child parameters
    • accountstringRequired
    • personstringRequired
  • return_urlstring

    The URL that the user will be redirected to upon completing the verification flow.

  • typestring

    The type of verification check to be performed. You must provide a type if not passing verification_flow.

    Possible values
    • document
    • id_number
  • verification_flowstring

    The ID of a verification flow from the Dashboard. See https://docs.stripe.com/identity/verification-flows.

Returns

The identity.verification_session object.

POST /v1/identity/verification_sessions
curl -X POST https://api.knoxapi.com/v1/identity/verification_sessions \
  -H "Authorization: Bearer $KNOX_SECRET_KEY"
Response
{
  "client_reference_id": null,
  "client_secret": null,
  "created": 1234567890,
  "id": "vs_1Pgc76B7WZ01zgkWBdQi8PTU",
  "last_error": {
    "code": null,
    "reason": null
  },
  "last_verification_report": "vr_QXhW13B2hsHOm43JtUgs0f0w",
  "livemode": false,
  "metadata": {},
  "object": "identity.verification_session",
  "options": {
    "document": {
      "require_matching_selfie": true
    }
  },
  "redaction": {
    "status": "processing"
  },
  "status": "verified",
  "type": "document",
  "url": null,
  "related_customer": null,
  "related_customer_account": null
}

List VerificationSessions

GET/v1/identity/verification_sessions

Returns a list of VerificationSessions

Query parameters

  • client_reference_idstring

    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.

  • createdobject | integer

    Only return VerificationSessions that were created during the given date interval.

    Show 4 child parameters
    • gtinteger
    • gteinteger
    • ltinteger
    • lteinteger
  • ending_beforestring

    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.

  • expandarray of strings

    Specifies which fields in the response should be expanded.

  • limitinteger

    A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 10.

  • related_customerstring

    Customer ID

  • related_customer_accountstring

    The ID of the Account representing a customer.

  • starting_afterstring

    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.

  • statusstring

    Only return VerificationSessions with this status. Learn more about the lifecycle of sessions.

    Possible values
    • canceled
    • processing
    • requires_input
    • verified

Returns

A list of identity.verification_session objects.

GET /v1/identity/verification_sessions
curl -G https://api.knoxapi.com/v1/identity/verification_sessions \
  -H "Authorization: Bearer $KNOX_SECRET_KEY" \
  --data-urlencode limit=3
Response
{
  "object": "list",
  "url": "/v1/identity/verification_sessions",
  "has_more": false,
  "data": [
    {
      "client_reference_id": null,
      "client_secret": null,
      "created": 1234567890,
      "id": "vs_1Pgc76B7WZ01zgkWBdQi8PTU",
      "last_error": {
        "code": null,
        "reason": null
      },
      "last_verification_report": "vr_QXhW13B2hsHOm43JtUgs0f0w",
      "livemode": false,
      "metadata": {},
      "object": "identity.verification_session",
      "options": {
        "document": {
          "require_matching_selfie": true
        }
      },
      "redaction": {
        "status": "processing"
      },
      "status": "verified",
      "type": "document",
      "url": null,
      "related_customer": null,
      "related_customer_account": null
    }
  ]
}

Retrieve a VerificationReport

GET/v1/identity/verification_reports/{report}

Retrieves an existing VerificationReport

Path parameters

  • reportstringRequired

Query parameters

  • expandarray of strings

    Specifies which fields in the response should be expanded.

Returns

The identity.verification_report object.

GET /v1/identity/verification_reports/{report}
curl https://api.knoxapi.com/v1/identity/verification_reports/vr_1Pgc76B7WZ01zgkWq9Rp33Dj \
  -H "Authorization: Bearer $KNOX_SECRET_KEY"
Response
{
  "client_reference_id": null,
  "created": 1234567890,
  "document": {
    "address": {
      "city": "San Francisco",
      "country": "US",
      "line1": "1234 Main St.",
      "state": "CA",
      "line2": null,
      "postal_code": null
    },
    "error": {
      "code": null,
      "reason": null
    },
    "expiration_date": {
      "day": 1,
      "month": 12,
      "year": 2030
    },
    "files": [
      "file_QXhWG300bR0L1WbLXBqG1wQc",
      "file_QXhWi7GgxZg2M3XqN2Y0P4Q2"
    ],
    "first_name": "Jenny",
    "issued_date": {
      "day": 1,
      "month": 12,
      "year": 2020
    },
    "issuing_country": "US",
    "last_name": "Rosen",
    "status": "verified",
    "type": "driving_license"
  },
  "id": "vr_1Pgc76B7WZ01zgkWq9Rp33Dj",
  "livemode": false,
  "object": "identity.verification_report",
  "options": {
    "document": {},
    "id_number": {}
  },
  "type": "document",
  "verification_session": "vs_1Pgc76B7WZ01zgkW1uXbT3Y9"
}

Update a VerificationSession

POST/v1/identity/verification_sessions/{session}

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

Path parameters

  • sessionstringRequired

Body parameters

  • expandarray of strings

    Specifies which fields in the response should be expanded.

  • metadataobject

    Set of key-value pairs 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.

  • optionsobject

    A set of options for the session’s verification checks.

    Show 1 child parameter
    • documentobject
      Show 4 child parameters
      • allowed_typesarray of strings
      • require_id_numberboolean
      • require_live_captureboolean
      • require_matching_selfieboolean
  • provided_detailsobject

    Details provided about the user being verified. These details may be shown to the user.

    Show 2 child parameters
    • emailstring
    • phonestring
  • typestring

    The type of verification check to be performed.

    Possible values
    • document
    • id_number

Returns

The identity.verification_session object.

POST /v1/identity/verification_sessions/{session}
curl https://api.knoxapi.com/v1/identity/verification_sessions/vs_1Pgc76B7WZ01zgkWBdQi8PTU \
  -H "Authorization: Bearer $KNOX_SECRET_KEY" \
  -d "metadata[order_id]=6735"
Response
{
  "client_reference_id": null,
  "client_secret": null,
  "created": 1234567890,
  "id": "vs_1Pgc76B7WZ01zgkWBdQi8PTU",
  "last_error": {
    "code": null,
    "reason": null
  },
  "last_verification_report": "vr_QXhW13B2hsHOm43JtUgs0f0w",
  "livemode": false,
  "metadata": {},
  "object": "identity.verification_session",
  "options": {
    "document": {
      "require_matching_selfie": true
    }
  },
  "redaction": {
    "status": "processing"
  },
  "status": "verified",
  "type": "document",
  "url": null,
  "related_customer": null,
  "related_customer_account": null
}

Retrieve a VerificationSession

GET/v1/identity/verification_sessions/{session}

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.

Path parameters

  • sessionstringRequired

Query parameters

  • expandarray of strings

    Specifies which fields in the response should be expanded.

Returns

The identity.verification_session object.

GET /v1/identity/verification_sessions/{session}
curl https://api.knoxapi.com/v1/identity/verification_sessions/vs_1Pgc76B7WZ01zgkWBdQi8PTU \
  -H "Authorization: Bearer $KNOX_SECRET_KEY"
Response
{
  "client_reference_id": null,
  "client_secret": null,
  "created": 1234567890,
  "id": "vs_1Pgc76B7WZ01zgkWBdQi8PTU",
  "last_error": {
    "code": null,
    "reason": null
  },
  "last_verification_report": "vr_QXhW13B2hsHOm43JtUgs0f0w",
  "livemode": false,
  "metadata": {},
  "object": "identity.verification_session",
  "options": {
    "document": {
      "require_matching_selfie": true
    }
  },
  "redaction": {
    "status": "processing"
  },
  "status": "verified",
  "type": "document",
  "url": null,
  "related_customer": null,
  "related_customer_account": null
}

Cancel a VerificationSession

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

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.

Path parameters

  • sessionstringRequired

Body parameters

  • expandarray of strings

    Specifies which fields in the response should be expanded.

Returns

The identity.verification_session object.

POST /v1/identity/verification_sessions/{session}/cancel
curl -X POST https://api.knoxapi.com/v1/identity/verification_sessions/vs_1Pgc76B7WZ01zgkWBdQi8PTU/cancel \
  -H "Authorization: Bearer $KNOX_SECRET_KEY"
Response
{
  "client_reference_id": null,
  "client_secret": null,
  "created": 1234567890,
  "id": "vs_1Pgc76B7WZ01zgkWBdQi8PTU",
  "last_error": {
    "code": null,
    "reason": null
  },
  "last_verification_report": "vr_QXhW13B2hsHOm43JtUgs0f0w",
  "livemode": false,
  "metadata": {},
  "object": "identity.verification_session",
  "options": {
    "document": {
      "require_matching_selfie": true
    }
  },
  "redaction": {
    "status": "processing"
  },
  "status": "verified",
  "type": "document",
  "url": null,
  "related_customer": null,
  "related_customer_account": null
}

Redact a VerificationSession

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

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.

Path parameters

  • sessionstringRequired

Body parameters

  • expandarray of strings

    Specifies which fields in the response should be expanded.

Returns

The identity.verification_session object.

POST /v1/identity/verification_sessions/{session}/redact
curl -X POST https://api.knoxapi.com/v1/identity/verification_sessions/vs_1Pgc76B7WZ01zgkWBdQi8PTU/redact \
  -H "Authorization: Bearer $KNOX_SECRET_KEY"
Response
{
  "client_reference_id": null,
  "client_secret": null,
  "created": 1234567890,
  "id": "vs_1Pgc76B7WZ01zgkWBdQi8PTU",
  "last_error": {
    "code": null,
    "reason": null
  },
  "last_verification_report": "vr_QXhW13B2hsHOm43JtUgs0f0w",
  "livemode": false,
  "metadata": {},
  "object": "identity.verification_session",
  "options": {
    "document": {
      "require_matching_selfie": true
    }
  },
  "redaction": {
    "status": "processing"
  },
  "status": "verified",
  "type": "document",
  "url": null,
  "related_customer": null,
  "related_customer_account": null
}

Operations and schemas come from the pinned Stripe OpenAPI specification (MIT); response examples from its fixtures. Nested object definitions and enums are in the complete specification.