Skip to main content

Overview

A loan integration with EASYCRED consists of two core steps:
  1. Initiate the Journey: Submit the applicant’s profile and choose between Headless (API_HEADLESS) or Hosted (API_HOSTED) mode.
  2. Drive the Journey: Poll state and handle required actions (Headless) or direct the user to the EASYCRED screen (Hosted).

Base URLs

Production

https://api.easycred.co.in

Development / UAT

https://dev.easycred.co.in

Step 1: Initiate a Loan Journey

Start an application by calling the initiate endpoint with customer data and your selected mode:
Required Scope: leads:create
Headers: x-api-key, x-timestamp, x-nonce, x-signature, Content-Type: application/json

Request Body Parameters

customer Object Schema

Note on Loan Amount: loanAmount is not mandatory at initiation. Borrowers are evaluated by lenders for their maximum eligible sanctioned credit limit. When selecting an offer (SELECT_OFFER in Headless or on the hosted UI), specifying the desired loanAmount within the approved range is mandatory.

Example cURL — Initiate Journey

goldLoanDetails Object (Gold Loans Only)


Initiate Responses

Store journeySession. Pass it as the X-Journey-Session header on all subsequent calls for this journey.

Step 2 (Option A): Drive Headless Journeys

In Headless mode, your backend manages the borrower experience by polling state and submitting user actions.

1. Poll Journey State

Headers: Include X-Journey-Session: <token> in addition to your standard HMAC auth headers.

2. Action Categories

Branch your code according to currentNextAction.category:

3. Submit User Actions (COLLECT)

When category is COLLECT, post the user’s choice:
Required Scope: offers:select
Payload Format: { "kind": "<ActionKind>", "payload": { ... } }

Supported Action Kinds

  • Select Loan Offer (SELECT_OFFER):
  • Select Gold Loan Branch (SELECT_GOLD_LOAN_BRANCH):
  • Submit Bank Account (SUBMIT_BANK_ACCOUNT):

4. Handle Verification Redirects (REDIRECT)

When category is REDIRECT, open currentNextAction.url in a browser or WebView for the borrower (for KYC verification, e-NACH mandate registration, or digital loan agreement signing). Once the borrower completes the verification and returns to your application, inform EASYCRED:
Payload:
(Use "KYC", "MANDATE", or "ESIGN" depending on the completed step). Resume the GET /journey/{journeyId} poll loop immediately after signalling return.

5. Referral Offers (e.g. Apollo Finvest)

When credit evaluations are completed or when alternative options exist, EASYCRED returns secondary referral offers in the journey state inside data.referralOffers[]:
  • Hosted Journeys (API_HOSTED): The EASYCRED hosted page automatically displays the Apollo Finvest referral card with a dedicated CTA that securely routes the applicant through /r/<code>.
  • Headless Journeys (API_HEADLESS): EASYCRED does not send automated SMS messages in headless mode. Your application must inspect data.referralOffers[], render the referral options in your custom UI, and provide the user with the corresponding redirectUrl.

Step 2 (Option B): Hosted Journey Tracking

When using API_HOSTED, EASYCRED manages the entire borrower experience on hosted web screens. Your backend does not make step-by-step action calls. Track journey progress using any of these methods:
  1. Check Journey Status by journeyId: Call GET /api/v1/partner/journey/{journeyId} using standard HMAC headers (x-api-key, x-signature, x-timestamp, x-nonce) to retrieve real-time progress, active step, and terminal outcome.
  2. Webhooks (Recommended): Configure an HTTPS endpoint via POST /api/v1/partner/webhooks. EASYCRED automatically sends signed real-time events (journey.updated, journey.completed, journey.rejected, journey.failed) carrying data.journeyId as the applicant progresses through hosted screens. See the Webhooks Guide.
  3. List & Poll Applications by applicationId: Retrieve all applications originated by your account via GET /api/v1/partner/leads?page=1&limit=20 to obtain applicationId, or check status via GET /api/v1/partner/leads/{applicationId}/status.

Journey Terminal Outcomes

When category is TERMINAL, the journey is complete. Read data.outcome: