Overview
A loan integration with EASYCRED consists of two core steps:- Initiate the Journey: Submit the applicant’s profile and choose between Headless (
API_HEADLESS) or Hosted (API_HOSTED) mode. - 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.inDevelopment / UAT
https://dev.easycred.co.inStep 1: Initiate a Loan Journey
Start an application by calling the initiate endpoint with customer data and your selected mode:leads:createHeaders:
x-api-key, x-timestamp, x-nonce, x-signature, Content-Type: application/json
Request Body Parameters
customer Object Schema
Note on Loan Amount:loanAmountis not mandatory at initiation. Borrowers are evaluated by lenders for their maximum eligible sanctioned credit limit. When selecting an offer (SELECT_OFFERin Headless or on the hosted UI), specifying the desiredloanAmountwithin the approved range is mandatory.
Example cURL — Initiate Journey
goldLoanDetails Object (Gold Loans Only)
Initiate Responses
- Headless Mode (API_HEADLESS)
- Hosted Mode (API_HOSTED)
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
X-Journey-Session: <token> in addition to your standard HMAC auth headers.
2. Action Categories
Branch your code according tocurrentNextAction.category:
3. Submit User Actions (COLLECT)
When category is COLLECT, post the user’s choice:
offers:selectPayload 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:
"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 insidedata.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 inspectdata.referralOffers[], render the referral options in your custom UI, and provide the user with the correspondingredirectUrl.
Step 2 (Option B): Hosted Journey Tracking
When usingAPI_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:
- Check Journey Status by
journeyId: CallGET /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. - 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) carryingdata.journeyIdas the applicant progresses through hosted screens. See the Webhooks Guide. - List & Poll Applications by
applicationId: Retrieve all applications originated by your account viaGET /api/v1/partner/leads?page=1&limit=20to obtainapplicationId, or check status viaGET /api/v1/partner/leads/{applicationId}/status.
Journey Terminal Outcomes
Whencategory is TERMINAL, the journey is complete. Read data.outcome: