Using Incode in Tines Stories

• Introduction
• Collecting information from Incode
• Adding credentials to Tines
• Setting up Tines actions
  • Authenticate with Incode
  • Generate a verification link
  • Deliver the verification link
  • Set up the Incode webhook
  • Validate the webhook in Tines
  • Use the verification result
• Summary

Introduction

Tines is a security and workflow automation platform that uses a straightforward graphical design process to automate tasks.

Incode is an AI-powered identity verification platform that uses government-issued photo IDs and biometric matching to verify a person's identity over the Internet — built for workforce, financial, and enterprise use cases.

Tines' ability to work with APIs combined with the Incode Workforce API is the simplest way to add automated, biometric identity verification to your security workflows, HR pipelines, or customer onboarding processes.

This article assumes you have some familiarity with Tines and no familiarity with Incode. For a nice introduction to Tines, see the content in Tines University.

Collecting information from Incode

You will need three things from Incode to configure Tines:

• an API key (*API_KEY*)
• a Workforce integration ID (*INTEGRATION_ID*)
• a Workforce integration secret (*INTEGRATION_SECRET*)

Go to the Incode Dashboard and sign in.

To get your API key, navigate to Settings → API Keys in the left sidebar. Select Create new API key, give it a descriptive name such as tines-integration, and copy the generated key. This is your *API_KEY*.

To get your integration ID and secret, navigate to Integrations in the left sidebar. Select the integration you want to use (or create a new one). From the integration detail page, copy the Integration ID and Integration Secret. These are your *INTEGRATION_ID* and *INTEGRATION_SECRET*.

Note: If you are using Incode's sandbox environment, your API base URL will be https://demo-api-incode-id.incodesmile.com. For production, use the base URL provided by your Incode account manager.

Adding credentials to Tines

Go to Tines and navigate to Credentials in the left sidebar.

Add *API_KEY* as a Text Credential named incode_x_api_key. Add incodesmile.com in the Domains field.

Add *INTEGRATION_ID* as a Text Credential named incode_workforce_integrationid. Leave Domains blank.

Add *INTEGRATION_SECRET* as a Text Credential named incode_workforce_secret. Leave Domains blank.

All three credentials are entered as Text credentials and will look like this in the Tines Credentials panel:

Setting up Tines actions

The high-level steps we'll configure in Tines are:

1. Authenticate with the Incode API to get a session token.
2. Generate a personalized verification link for the end-user.
3. Deliver that link to the end-user.
4. Wait for a webhook from Incode when the user completes verification.
5. Validate the webhook and use the result.

Authenticate with Incode

Before you can generate a verification link, the Incode API requires a short-lived session token obtained via a server-side authentication call. This token is used as the x-auth-token header in subsequent requests.

Drag the HTTP Request action into your story from the sidebar and configure it as follows:

• Name: GetIncodeToken
• URL: https://demo-api-incode-id.incodesmile.com/v1/integration/authorize/server
• Content type: JSON
• Method: POST
• Headers:

  x-api-key: <<CREDENTIAL.incode_x_api_key>>

• Payload:
  JSON

  {
    "integrationId": "<<CREDENTIAL.incode_workforce_integrationid>>",
    "secret": "<<CREDENTIAL.incode_workforce_secret>>"
  }

In the Editor view on the right side of the Tines workspace, this looks like:

{
  "url": "https://demo-api-incode-id.incodesmile.com/v1/integration/authorize/server",
  "content_type": "application_json",
  "method": "post",
  "headers": {
    "x-api-key": "<<CREDENTIAL.incode_x_api_key>>"
  },
  "payload": {
    "integrationId": "<<CREDENTIAL.incode_workforce_integrationid>>",
    "secret": "<<CREDENTIAL.incode_workforce_secret>>"
  }
}

Select Play on this action. The events window should show a successful response from Incode:

{
  "token": "eyJhbGci....",
  "expiresAt": 1714512000
}

The token field is the session token. It is short-lived, so this action should run at the beginning of each story run — not stored for reuse across separate executions.

Generate a verification link

Now that you have a session token, you can generate a personalized, time-limited verification link for the end-user.

Drag another HTTP Request action into your story and configure it as follows:

• Name: GenerateVerificationLink
• URL: https://demo-api-incode-id.incodesmile.com/v1/workforce/verification/candidate/generate-verification-link
• Content type: JSON
• Method: POST
• Headers:

  x-auth-token: <<GetIncodeToken.body.token>>

• Payload:
  JSON

  {
    "integrationID": "<<CREDENTIAL.incode_workforce_integrationid>>",
    "secret": "<<CREDENTIAL.incode_workforce_secret>>",
    "loginHint": "<<user_email>>",
    "loginHintType": "EMAIL",
    "validityMinutes": 4320,
    "redirectUrl": "https://your-company.com",
    "givenNames": "<<user_first_name>>",
    "lastName": "<<user_last_name>>"
  }

Replace <<user_email>>, <<user_first_name>>, and <<user_last_name>> with the Tines variables from wherever you collect or receive the user's information earlier in your story — for example from a web form, a webhook payload, or a previous API call.

The validityMinutes field controls how long the verification link stays active. 4320 equals 72 hours, which is a sensible default for most workflows. Adjust this to suit your use case.

In the Editor view, this looks like:

{
  "url": "https://demo-api-incode-id.incodesmile.com/v1/workforce/verification/candidate/generate-verification-link",
  "content_type": "application_json",
  "method": "post",
  "headers": {
    "x-auth-token": "<<GetIncodeToken.body.token>>"
  },
  "payload": {
    "integrationID": "<<CREDENTIAL.incode_workforce_integrationid>>",
    "secret": "<<CREDENTIAL.incode_workforce_secret>>",
    "loginHint": "<<user_email>>",
    "loginHintType": "EMAIL",
    "validityMinutes": 4320,
    "redirectUrl": "https://your-company.com",
    "givenNames": "<<user_first_name>>",
    "lastName": "<<user_last_name>>"
  }
}

Select Play on this action. The response from Incode will look like:

{
  "verificationLink": "https://verify.incode.com/x/acme/abcd1234xyz",
  "verificationTraceId": "f78ee334-79a8-4a5e-be4a-d728e226df64"
}

The two key fields are:

• verificationLink — the URL you will send to the end-user so they can complete biometric verification.
• verificationTraceId — a unique identifier for this verification session. Store this value — you will use it later to match the Incode webhook callback back to this specific verification request.

Deliver the verification link

Tines offers many methods to deliver data to end-users. Any of them will work for delivering this link — email, Slack, SMS, or even a redirect from a Tines page.

To demonstrate the flow, we'll use email delivery. If your story has already collected the user's email address from a form or upstream system, you can skip the form step.

Optional — collect the user's email via a Tines Page

If you need to collect the user's details first, select + / Tools on the left of your Tines workspace and drag a Page object onto your workspace. Name the page Request Identity Verification and add input fields for the user's email address, first name, and last name.

Send the email

Drag the Send Email action from the sidebar onto your workspace and configure it as follows:

• Recipients: <<user_email>> (or <<request_identity_verification.body.email>> if using a Tines form)

• Reply to: your team's support email address

• Sender name: your company or team name

• Subject: Your identity verification request from *COMPANY*

• Body: Write a message explaining the purpose of the verification. Include the link using the Tines variable <<GenerateVerificationLink.body.verificationLink>>. For example:

  Hi <<user_first_name>>,
  
  Please complete your identity verification by clicking the link below.
  The process takes less than 5 minutes and requires a government-issued
  photo ID and a quick facial scan.
  
  Verify your identity: <<GenerateVerificationLink.body.verificationLink>>
  
  This link expires in 72 hours. If you have any questions, reply to
  this email and our team will be happy to help.

Connect the actions in your story so they run in this order: GetIncodeToken → GenerateVerificationLink → Send Email.

To test the flow, run the story and confirm the email arrives with a working verification link.

Set up the Incode webhook

Incode can POST a signed message to a pre-defined HTTP endpoint when an end-user completes (or fails) verification. This is how you receive the result back into your Tines story.

Create the webhook action in Tines

Go to your Tines story and drag a Webhook Action into your workspace. Select it to edit. Set Allowed verbs to POST only. Select Copy next to the Webhook URL to copy it. This is the *DELIVERY_URL* you will register in Incode.

Register the webhook in Incode

Go to the Incode Dashboard and navigate to Configuration → Webhooks. Select your integration and open the Webhooks tab.

Select Add Webhook and configure it as follows:

Save the webhook. Incode will now POST an event to your Tines story each time a user completes or fails a verification session on this integration.

Name the webhook action

Back in Tines, rename the Webhook Action to IncodeStatusWebhook to make it easy to reference in downstream actions.

Validate the webhook in Tines

When Incode posts a verification result to your Tines story, the webhook body will look like this:

{
  "event_type": "verification.succeeded",
  "data": {
    "verification_trace_id": "f78ee334-79a8-4a5e-be4a-d728e226df64",
    "failure_reason": null,
    "ip": "203.0.113.42",
    "user_name": "Jane Smith",
    "latitude": 37.7749,
    "longitude": -122.4194
  }
}

The verification_trace_id in the callback matches the verificationTraceId you received when you generated the link. This is how you confirm that this callback belongs to the verification session you initiated.

Create a Trigger Action

Drag a Trigger Action into your story. Configure a rule that checks the incoming event_type and only passes events for successfully completed verifications:

{
  "rules": [
    {
      "type": "field==value",
      "value": "verification.succeeded",
      "path": "<<IncodeStatusWebhook.body.event_type>>"
    }
  ]
}

This ensures that the rest of your story only runs when verification succeeds. If you want to handle failures separately, add a second Trigger Action with "value": "verification.failed" and connect it to a different branch of your story.

Optionally verify the trace ID

If your story initiated the verification session and stored the verificationTraceId, you can add a second Trigger Action to confirm the callback matches the session you expect:

{
  "rules": [
    {
      "type": "field==value",
      "value": "<<GenerateVerificationLink.body.verificationTraceId>>",
      "path": "<<IncodeStatusWebhook.body.data.verification_trace_id>>"
    }
  ]
}

Note: In asynchronous workflows where the verification link is sent and the result arrives in a separate story run, use Tines Records to store the verificationTraceId alongside any relevant identifiers (such as a user ID or opportunity ID) when the link is generated, then look up that record using the incoming verification_trace_id when the callback arrives. See Tines Records documentation for details.

Use the verification result

Now that you have a validated verification result from Incode, you can use the data in your workflow. The data object in the webhook payload contains:

Here are some examples of how you might use this in Tines:

• ATS integration — use an HTTP Request action to add a biometric-verified tag and post a note to the candidate's profile in your applicant tracking system (e.g., Lever, Greenhouse, Workday).
• IT provisioning — trigger an account creation or password reset workflow once identity is confirmed, combining the verified name with a lookup in your corporate directory.
• Access control — update a record in your IAM or HRIS system to reflect that this person has completed biometric verification.
• Helpdesk escalation — send the verified identity details to a Slack channel or a support ticket so a human agent can take over with confidence.
• Audit log — write the verification_trace_id, verified name, IP, and timestamp to a Tines Record or external data store for compliance purposes.

To display the result for demonstration purposes, drag a Page object onto your workspace, set the Page behavior to Show success message, and set the success message to:

Identity verification complete.

Verified name: <<IncodeStatusWebhook.body.data.user_name>>
Trace ID: <<IncodeStatusWebhook.body.data.verification_trace_id>>
Processed: <<DATE("now")>>

Summary

At the end of these steps, your Tines story will consist of two connected flows:

Flow 1 — Send verification

[Collect user details] → [GetIncodeToken] → [GenerateVerificationLink] → [Send Email]

Flow 2 — Receive result

[IncodeStatusWebhook] → [Check event_type] → [Use verified data]

This story shows how you can use the Incode Workforce API in Tines to verify the identity of any user — whether a job candidate, a new hire, a customer, or an employee requesting elevated access — and feed the result back into any downstream system Tines can reach.