--- title: "Step-Up and Additional Checks" url: "https://developer.incode.com/general-reference/step-up-and-additional-checks/" section: "general-reference" group: "Migrations and Deprecations" version: "v1.1" status: "live" --- # Step-Up and Additional Checks A **step-up** runs an additional check, or collects another document, for a person who has already been verified. Examples include a signature, a proof of address document, and a tier upgrade. Integrations have usually done this by restarting the original session, because that is where the earlier data lives. Restarts are being retired, as described in [Migration Guide: Moving Off Session Restarts](/general-reference/moving-off-session-restarts/). This page covers the replacement paths for step-ups. ## At a glance | | | | -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Enforcement date** | Dependent on case. | | **What's changing** | Reopening a completed session by calling `omni/start` API or SDK again, in order to run an extra check or collect another document. | | **Who's affected** | Any integration that restarts an existing session to add a signature, document, module, or acceptance after the original onboarding. | | **How to check** | Search your integration for call sites where `omni/start` is passed an existing `interviewId` or `externalId` and is followed by a module, upload, or signature call. For each one, work through [Find your scenario](#find-your-scenario). | | **Grace period** | None. See [Enforcement](/general-reference/moving-off-session-restarts/#enforcement). | ## What is changing | | What it is | Status | | --------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- | -------------------------------- | | **Reopen the original session** | Restarting a completed session to run a step-up there, because that is where the earlier data lives. | Being retired | | **New session, linked to the identity** | Starting a new session, proving it is the same person, and supplying any data the check needs. Incode writes the result back to the identity. | The supported path going forward | None of the replacement paths reopen the original session. Most follow the same shape, with two exceptions: [Scenario 2](#scenario-2-expired-document-update) needs no step-up session, and [Scenario 5](#scenario-5-retroactive-module-runs) is not supported. ### Key concepts - **Identity**: The record Incode keeps for a person across sessions. It is created when an onboarding session is approved, and it is what allows a later session to be recognized as the same person. Results such as a signature or a proof of address are written to it. Raw images are never stored on the identity. - **Proving it is the same person**: Where a case requires it, run Incode face authentication at the start of the new session. This links the new session to the existing identity. There is no backend-to-backend alternative today. - **Supplying raw data**: There is no mechanism to move data from one session into another. Where a check needs the ID images and the selfie, upload them into the new session. You can get them in two ways: keep your own copy from the original onboarding, or retrieve them from the original session with an admin token. See [Scenario 4](#scenario-4-government-record-verification-and-video-selfie). - **The 48-hour window**: A session lasts 48 hours from the `omni/start` call that created it. This applies to every case below that creates a new session. Everything you intend to do in that session must happen inside the window. ## Find your scenario Identify every scenario that describes what your integration does. Most integrations have more than one. Handle each separately. | # | Applies when | Replacement | | ------------------------------------------------------------ | ------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------- | | [1](#scenario-1-document-signature) | A document is signed using the signature captured during an earlier onboarding. | New session linked to the identity by face authentication. The signature is read from the identity. | | [2](#scenario-2-expired-document-update) | An ID, selfie, or proof of address has expired and needs replacing. | Read the expiry with an **admin token**, then run a new onboarding when it lapses. | | [3](#scenario-3-non-scoring-additions) | Something is collected that needs nothing from the earlier session: terms acceptance, an additional proof of address, or a tier upgrade. | New session linked to the identity by face authentication. Collect the item there. | | [4](#scenario-4-government-record-verification-and-video-selfie) | A module is run that needs images or data captured in an earlier session. | Get the original images, upload them into a **new session**, and run the module there. | | [5](#scenario-5-retroactive-module-runs) | A module bought after the original onboarding is run over old sessions. | Not supported. | | — | Session data is read to make a decision or for an audit, and nothing is run. | Not a step-up. See [Scenario 1: Reading session data](/general-reference/moving-off-session-restarts/#scenario-1-reading-session-data). | | — | A module failed and needs re-running. | Not a step-up. See [Migration Guide: Moving Off Session Restarts](/general-reference/moving-off-session-restarts/). | | — | None of the above. | Contact your Incode representative or use the customer portal. | ## Scenario 1: Document signature **Applies when:** a document is signed using a signature that was captured during an earlier onboarding. **What to do instead:** start a new session linked to the person's identity through face authentication. The signature endpoints read the default signature from the identity. **Prerequisites:** - An identity for the person. It is created when the onboarding session that captured the default signature is approved. - Face authentication, to link the new session to that identity. - For batch signing only: an admin token. See [these scenario 1 prerequisites](/general-reference/moving-off-session-restarts/#scenario-1-reading-session-data). ### Flow A: One document at a time 1. During onboarding, upload the default signature and approve the session. Approval creates the identity and copies the signature to it. 2. Run face authentication. This creates a new session linked to the identity. 3. Upload the contract and any additional signatures to the new session. 4. Call Attach Signature on Annotation. It takes the contract and additional signatures from the session, and the default signature from the identity. ### Flow B: Batch signing 1. The user authenticates with face authentication. This creates a session linked to their identity. Create one session per authentication event per day. 2. Upload documents to that session throughout the day, using an admin token. 3. Apply the signatures in your nightly job. Call the endpoint with the admin token, passing `interviewId` and each contract ID in turn. A single day of documents fits inside the 48-hour session window. Start a new session the next day. :::warning Do not create a session per document. Attach all of a day's documents to a single session. ::: ### The endpoints you'll call | What | Call | | ----------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- | | Upload the default signature | [`POST /omni/add/document/v2?type=signature`](/api-reference/add-document-v2/) | | Upload a contract | [`POST /omni/add/document/v2?type=contract&title=`](/api-reference/add-document-v2/) | | Apply the signature | [`POST /omni/attach-signature-on-annotation`](/api-reference/attach-signature-on-annotation/) | | Apply to several PDFs at once | [`POST /omni/attach-signature-to-pdf/v2`](/api-reference/attach-signature-to-pdf-v2/) | The file goes in the request body as either `base64Image` or `imageUrl`. All calls take the `x-api-key`, `X-Incode-Hardware-Id`, and `api-version: 1.0` headers. ### Where the signature comes from When you call Attach Signature on Annotation or Add Signature to PDF v2, Incode looks for the default signature in this order: - **The identity**: This is used if the session is linked to an identity that has a signature. - **The session**: This is used if there is no identity link, or the identity has no signature. This is how the endpoints work today, so existing integrations keep working. Only the default signature is stored on the identity. That is the one the user draws during onboarding. It is saved once and never overwritten by later sessions. Additional signatures stay on the session. These are any others you collect live, such as from a surgeon, patient, or witness. ### Existing users The signature is copied to the identity when a session is approved, so the flows above work for people onboarded after this change. For people onboarded before it, Incode runs a one-time backfill per account that copies the signature across. No action is required on your side. Until the backfill has run for your account, use these flows for newly onboarded users and keep your current integration for everyone else. Contact your Incode representative to confirm the backfill status for your account. ### Advanced and qualified electronic signatures AES and QES are not yet available on this path. ### After migration: remove the old path Remove any code path that calls `omni/start` with an existing `interviewId` or `externalId` in order to sign a document. ## Scenario 2: Expired document update **Applies when:** an ID, selfie, or proof of address has expired and needs replacing. **What to do instead:** read the document's expiry from the original session with an admin token. When it lapses, run a new onboarding for that person. No step-up session, identity, or face authentication is required. **Prerequisites:** - An admin token. See [these scenario 1 prerequisites](/general-reference/moving-off-session-restarts/#scenario-1-reading-session-data). ### What the change looks like 1. Read the expiry date from the original session with [`GET /omni/get/ocr-data?id=`](/api-reference/get-ocr-data/). 2. When the document lapses, run a new onboarding for that person. ```bash curl -X GET 'https:///omni/get/ocr-data?id=' \ --header 'x-api-key: ' \ --header 'x-incode-hardware-id: ' \ --header 'api-version: 1.0' ``` If identity is enabled for your account, you can query the identity for a validity flag instead of reading raw OCR data. The replacement document is captured in the new session and Incode writes it back to the identity, so the record stays linked. Identity makes this case simpler but is not required to migrate. ### After migration: Remove the old path Remove any code path that restarts the original session to capture a replacement document. ## Scenario 3: Non-scoring additions **Applies when:** something is collected that needs nothing from the earlier session: a terms acceptance, an additional proof of address, or a tier upgrade. **What to do instead:** start a new session, authenticate the user against the existing identity, and collect the new item in that session. **Prerequisites:** - An identity for the person. - Face authentication, to link the new session to that identity. ### What the change looks like 1. Create a new session. 2. Authenticate the user against the existing identity with face authentication. 3. Collect the new item in that session. For a proof of address, call [`POST /omni/add/document/v2?type=document&format=pdf`](/api-reference/add-document-v2/). 4. Incode attaches the result to the identity where it qualifies as a credential. Terms and conditions acceptance and watchlist results stay on the session and are not written to the identity. Without face authentication, you can still collect the item in a new session, but it is not attached to the person's identity. There is no way to link a session to an existing identity without face authentication today. ### After migration: Remove the old path Remove any code path that restarts a completed session to collect an additional document or acceptance. ## Scenario 4: Government Record Verification and Video Selfie **Applies when:** an additional module is run that needs images or data captured in an earlier session, such as [Government Record Verification](/features-and-modules/government-record-verification/) or [Video Selfie](/features-and-modules/video-selfie/). **What to do instead:** get the ID images and selfie from the original onboarding, upload them into a new session, and run the module there. **Prerequisites:** - The ID images and selfie from the original onboarding. You can get them in two ways: - **Keep your own copy**: Store the ID images and selfie when you capture them at onboarding. - **Retrieve them from the original session**: Use an admin token and the original `interviewId`. The original session is not reopened, and no new session is required to read them. Use this option for users onboarded before you started keeping copies. See [these scenario 1 prerequisites](/general-reference/moving-off-session-restarts/#scenario-1-reading-session-data) for the admin token. :::warning Retrieval depends on your data retention settings. Images already removed under your retention policy cannot be retrieved, and only your own copy will work. Check how far back your retention reaches before you rely on this option for older sessions. ::: ### What the change looks like 1. Get the ID images and selfie from your own storage or from the original session. 2. Create a new session. 3. Upload the images into it. 4. Run the module in the new session. ### The endpoints you'll call Get the images from the original session. Pass the original session's `interviewId` as `id`. Without it, the endpoint reads the session from the token, which is not the session you want. | Data required | Call | | ------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- | | Images, as download links valid for one hour | [`POST /omni/get/images/v2?id=`](/api-reference/get-images-v2/) | | Second ID images | [`POST /omni/get/images-second-id/v2?id=`](/api-reference/get-images-second-id-v2/) | These endpoints return links instead of base64 in the response body, which matters when retrieving in volume. **Upload the images into the new session.** | What | Call | | ------------------------ | ---------------------------------------------------------------------------------------------------------- | | Front of the ID | [`POST /omni/add/front-id/v2`](/api-reference/add-front-id-v2/) | | Back of the ID | [`POST /omni/add/back-id/v2`](/api-reference/add-back-id-v2/) | | Process the ID | [`POST /omni/process-id`](/api-reference/process-id/) | | Selfie | [`POST /omni/add/face/third-party`](/api-reference/add-face-third-party/) | | Compare selfie to the ID | [`POST /omni/process-face`](/api-reference/process-face/) | Images go in the request body as either `base64Image` or `imageUrl`. Keep to this order: - Upload the front of the ID before the back. - Run `process-id` before `process-face`. - After `process-id` has finished, the ID upload calls cannot be repeated on that session. For selfies supplied by `imageUrl`, the domain must be allowlisted. The Video Selfie module uses the previously captured selfie and ID as inputs, but it performs a new face capture, which is where liveness is checked. It does not replay the old capture. ### After migration: Remove the old path Remove any code path that restarts the original session to run an additional module. ## Scenario 5: Retroactive module runs **Applies when:** a module such as [CURP Validation](/features-and-modules/curp-validation/), [Antifraud Check](/features-and-modules/antifraud-check/), or [Custom Watchlist](/features-and-modules/custom-watchlist/) is contracted after onboarding and needs to run over existing sessions. **Not supported.** A module runs only on sessions created after it is contracted. This is by design, and there is no migration path. **What to do instead:** run the module on new sessions going forward. Where an existing user needs it, create a new session and supply the data you already hold, as in [Scenario 4](#scenario-4-government-record-verification-and-video-selfie).