Toggle navigation

Integration Support

Version 1.0.0

How to integrate with our onboarding journey:


  • Profiles for users are created using our Create Profile APIs. The response of this API contains a link (capture link). Redirect your customer to the capture link to start their journey. Once the journey is complete, you have the option to redirect your customer back to your application. You can view the integration data flow here.
  • After the customer has completed their journey on the IDfy platform you can retrieve the information through our Get Profile API. Additionally, you can configure a URL (webhook) and the IDfy platform will call to send you the customer profile information.
  • The customer journey configuration can be customized to your needs.
  • If your team will be accessing the IDfy platform from within your corporate network to perform the video journey, review profile information, test the product, or access documentation. Please refer to the whitelisting section (Network Configuration Document) to whitelist the relevant IPs.

You need to understand the following steps to integrate our APIs:

Configure the Workflow

Our platform allows you to customize your user’s journey. You can configure all the data capture, verification checks, and video journey details, and also white label the journey with your logo and brand colors. Please contact the Integration SPOC assigned to your account and they will assist you with the same. 

Setup an Account

You can use the custom authorization headers that are configured with IDfy to integrate seamlessly. This is done after you send the mail to any of our SPOCs and ask them to create an account for you. After your account is set up in the Idfy database, you will get a unique account-id and api-key to access our APIs. 

Create a Profile

Profiles for users are created using our Create Profile APIs. The response of this API contains a link (capture link). Redirect your customer to this link to start their journey. Add the user’s basic information (text/image inputs) in the request body of Create Profile API, based on your journey configuration. 

There are two modes by which a profile link can be generated:

Profile Creation – Synchronous and Asynchronous

Integration of Webhooks

There are four kinds of webhooks sent from Profiles Gateway.

  • Session Update: Session Update: This webhook is triggered after a successful or unsuccessful user session (the user being the client’s customer).
  • Profile Status Update: This webhook is triggered when the status of the profile changes.

Here is a diagrammatic explanation for the profile status changes:

Click here for more details on profile state

You can embed a link to the “Initiate KYC” button of your KYC page or application screen by the steps below.

  • Fetch the capture link returned in the response of the Create Profile API:
  • Add the redirect_uri as a query parameter. (redirect_uri is used to specify URLs the users have to be directed to once they complete a video session with the agent or if the call is dropped.)
  • Add the exit_url as a query parameter. (exit_url is used to specify URLs the users have to be directed to when they cancel the session on IDfy capture link)

Here’s an example for your reference 

Best practices for redirect_uri

  1. Do not include ‘#’ character (browser strips this character from the URL)
  2. Make the URL user and session-specific (i.e. on completion of IDfy’s journey, users should be able to continue with their previous activity on their UI).
  3. Always use “https”
  4. Do not provide direct access to your session (when opened in isolation, should not have access to users profile)
  5. No PII data should be contained in the URL
  6. Always specify an expiry to the session.
  7. URI encode the redirect link after adding the redirect_uri or exit_url

Following are the links to API and Data Transmission Documentations:

  1. Standard REST API Documentations and Response Samples
  2. Payload / Response Encryptions


IDfy supports SAML-based SSO integration with client ADFS to provide seamless identity and access management.

Steps in SSO Integration

  1. Please share the below details with us
    1. Client SAML XML Metadata file
    2. Sign in URL
  2. IDfy will configure these in the demo account and share back the below details
    1. IDfy SAML metadata file
    2. IDfy sign-in URL and IP address to open firewall ports to destination server from client ADFS [Active directory Federation Service] server. (optional)
    3. Claim rules detail which client will create for relying party configuration.
  3. The client can configure the same in their ADFS
  4. Testing the SSO integration on the Demo account
  5. Then we can apply the same configuration to the live account

User Roles

  1. Maker – Agent who accepts only video calls
  2. Checker – Agent who can create profiles from the dashboard and review the profiles after the video call is completed successfully (verified or rejected by maker)
  3. External Auditor – Third-party entity who can only view the profiles
  4. Link Creator – Agent who can create profiles, view the profiles created by him/her, and copy the capture links.

The Integration process follows the data flow and transmission according to the given structure:

Data Flow and Data Transmission Diagrams

Following are some of the best practices while integrating with our Products. Please refer to these guidelines to have optimal performance and minimize scope for errors or future rework:

The Lead Reference ID should be IDfy Specific

The Reference ID establishes a unique connection between our system and yours. We strongly recommend that you avoid keeping your internal Lead ID the same as your IDfy Reference ID. Instead, we advise that you maintain a mapping between the Customer Reference ID and your Lead ID to ensure the integration remains compatible irrespective of any changes to your business logic in the future.

IDfy may add new keys to the JSON response of the APIs

The JSON response from the IDfy APIs which are consumed by you should be agnostic to any new keys added to the response of any and all APIs. From time to time, we may add new keys to the JSON response as we enhance our solutions. These amendments may be done without any intimation to you. Please ensure that new keys added to the API response do not break the integration. 

Support UDP Protocols for Video Calls

There are two main protocols for data transmission in Video Calls – TCP and UDP. Our systems support both protocols, but UDP is probably better in terms of call stability and reduced packet loss. We have seen significantly better performance on the UDP protocol, and strongly recommend that you open the ports for UDP for the best Video Calling experience. 

Ensure all Image URLs are accessible to IDfy and have an expiration time.

If you are sending images or videos in the ‘Create Profile’ API, then it can be sent via a URL or a base 64 string. If you are using URLs, then they should be accessible to IDfy APIs. The best practice is to use signed URLs with a time out. With the time out you can ensure that the URLs cannot be misused by external entities.

Usage of sync and async create profile APIs

The Asynchronous mode is used when more than 2 resources (image/text/video) are sent in a profile create request. 

The Synchronous mode is used when 2 or less than 2 resources (image/text/video) are sent in a profile create request.

Following are the network-related best practices to follow while integrating with our APIs:


Video calling is a bandwidth-intensive activity. To ensure a smooth experience, please follow these network-related best practices:

  • Use a dedicated network for video calling
  • Ideal bandwidth for every agent -500kbps
  • Minimum bandwidth for every agent -300kpbs


  • Use Google Chrome – latest version (minimum version 76)
  • Ensure you have not opened another tab while taking the video call which might be consuming a lot of bandwidth or might be accessing your camera

Device and Operation System

  • Use Windows 10 and above
  • Ensure your device is not running something in the background that may be using your bandwidth or accessing your camera/microphone
  1. Please follow the given links to check the Infrastructure and Network Requirements Documentations:
    1. Network Configuration Requirements For Assisted Video KYC
    2. Network Troubleshooting

Please refer to the following  Multi-Tenant Architecture Diagram and Single-Tenant Architecture Diagram and of the IDfy Platform:


Single Tenant Setup

Multi-Tenant Setup


The sequence diagram for integrating standard endpoints, and sequence diagram for integrating encrypted endpoints can be found in the links below:


For Standard Endpoints

For Payload Encryption Endpoints

Following is the list of operations that are out of scope of the current API integration solution:


IDfy provides a simple API to create a customer profile that will return alike for your end customer.  For a seamless customer experience,  render the link returned in the API response either as a review on your application, or you can redirect the user to the provided link. Once the user completes the IDfy leg of his/her journey, they can be redirected back to your platform. Our links cannot be rendered or embedded directly in an I-Frame within your website.

Adapters and SFTP

Any data about the video call details including profile status will be provided in this way only. Any change in the mechanism of transfer of format of the data will require custom adapter development for transferring data, and is not included in the standard setup support process. If you need this, please fill in the Custom Requests form and we will get back to you.

The IDfy platform does not support Single File Transfer Protocol (SFTP)

Agent Portal & Dashboards optimized only for Desktop / Laptop

The best experience for the IDfy agent portal, performing video calls and reviewing profiles etc is rendered when they are using desktops and laptops. We recommend agents use the latest version of Google Chrome. Please ensure you are using  Chrome 92.0.4515.131 or higher.


Storage & DMS integrations

We do not store end-user data beyond our standard purging policy unless mutually agreed in writing. If you need us to store data on your behalf, please speak with our Sales team



IDfy provides a web-based customer journey across multiple devices and browsers, and as such our product is Operating System agnostic. We do not offer an SDK for Android or iOS or any other platform.

We do not handle external API calls during the IDfy journey

IDfy does not have the facility to call your APIs while the end-user is on our platform. As such, any internal verification checks need to be completed before or after directing the customer to the IDfy journey. 

Custom Features

We have provided a set of standard features of our product offerings. If you need anything beyond these, please get in touch with your integration SPOC for such requirements and we’ll get back to you.  

SMS will always go from IDfy’s handle

Under TRAI guidelines, IDfy systems cannot integrate with external communications engines. If our communication engine is being used for triggering SMS, the SMS will go from IDfy’s domain. If you wish to send SMS from your domain, we can inform you of any changes in the status of your customer’s journey via a webhook, which can be used as a trigger for sending further communication.

User Access Management (UAM)

To provide control for creating, deleting, and managing users and roles, we have a user access management portal where you can manage the roles of your agents. The UAM module is an independent, premium offering and if you would like to enable that for your account, please speak with your Sales representative.

If there are any specific support needed, please mail the query on

Go to the Security Support Page