Onboard a sourcing partner

A sourcing partner is a party that brings loans to the lender and is paid a fee for them. Onboarding happens in steps. A partner cannot be attributed a loan until it is active, and it cannot be activated without an agreement in force.

Creating the partner and adding terms each require an Idempotency-Key, and reusing a key with a different body returns 409 rather than replaying the first response. Activation and attribution accept a key too.

Before you start

A userWith permission to manage sourcing partners. Open the reference
The agreementThe fee lines and the date they start. A partner cannot be activated without terms in force.
The partner's documentsThe checklist depends on the partner type.
A loan to attributeOnly needed for the last step. Open the guide

Set your environment

Every request authenticates with HTTP Basic and names its tenant in a header. Set these once and the commands below work as written.

export LOKTA_API="https://default.lokta.tech"
export LOKTA_USER="your-username"
export LOKTA_PASS="your-password"

1. Read the reference data

Lookups such as document types arrive as codes. Read them once so you send values the API accepts.

GET/v1/sourcing-partner-reference-data

curl -X GET "$LOKTA_API/lokta-lms/api/v1/sourcing-partner-reference-data" \
  -u "$LOKTA_USER:$LOKTA_PASS" \
  -H "Tenant-Identifier: default"

2. Create the partner

The partner starts as pending. The details and the contacts can ride the same call, so onboarding can be one request. If contacts are supplied and none is marked primary, the first becomes primary.

details

Optional. The partner's legal details.

contacts

Optional. The partner's contacts.

This is an example body. The reference does not list every field of this request yet, so treat the field names as placeholders and confirm them before you build.

POST/v1/sourcing-partners

curl -X POST "$LOKTA_API/lokta-lms/api/v1/sourcing-partners" \
  -u "$LOKTA_USER:$LOKTA_PASS" \
  -H "Tenant-Identifier: default" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "name": "Example Finserv",
    "external_id": "PARTNER-001",
    "partner_type": "DSA",
    "details": {
      "legal_name": "Example Finserv Private Limited",
      "pan": "AAAAA0000A",
      "gstin": "29AAAAA0000A1Z5"
    },
    "contacts": [
      {
        "name": "Asha Rao",
        "role": "Finance head",
        "purpose": "Invoices",
        "email": "[email protected]",
        "phone": "+91 00000 00000"
      }
    ]
  }'

The response carries the partner id. The next steps call it $PARTNER_ID.

3. Track the document checklist

The checklist has one row per requirement for the partner's type, with its status. Upload a file against a document type, then verify or reject it.

GET/v1/sourcing-partners/{partnerId}/document-checklist

curl -X GET "$LOKTA_API/lokta-lms/api/v1/sourcing-partners/$PARTNER_ID/document-checklist" \
  -u "$LOKTA_USER:$LOKTA_PASS" \
  -H "Tenant-Identifier: default"

4. Add the agreement

Terms are versioned. A new version starts on a date and closes the one before it, and there is no way to edit a version in place.

Activation is refused with 422 sourcing/partner_has_no_active_terms until an agreement is in force.

product_id

The loan product the agreement covers. Null is the partner's default agreement.

effective_from

The date the version starts. It must be after the version it supersedes.

method, accrual_frequency

The fee method and how often fees accrue. Accepted in either case.

lines

The fee lines, numbered from their order in the array. Each has a basis code, such as DISBURSED_PRINCIPAL, and may have slabs ordered by from_principal.

guarantee

A single object or null. Its form is a code, such as CASH_DEPOSIT.

This is an example body. The reference does not list every field of this request yet, so treat the field names as placeholders and confirm them before you build.

POST/v1/sourcing-partners/{partnerId}/terms

curl -X POST "$LOKTA_API/lokta-lms/api/v1/sourcing-partners/$PARTNER_ID/terms" \
  -u "$LOKTA_USER:$LOKTA_PASS" \
  -H "Tenant-Identifier: default" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "product_id": null,
    "effective_from": "2026-09-01",
    "method": "percentage",
    "accrual_frequency": "monthly",
    "lines": [
      {
        "basis": "DISBURSED_PRINCIPAL",
        "rate_pct": "1.50"
      }
    ],
    "guarantee": null
  }'

5. Activate the partner

This closes onboarding. Once the partner is active, loans can be attributed to it.

POST/v1/sourcing-partners/{partnerId}/activation

curl -X POST "$LOKTA_API/lokta-lms/api/v1/sourcing-partners/$PARTNER_ID/activation" \
  -u "$LOKTA_USER:$LOKTA_PASS" \
  -H "Tenant-Identifier: default" \
  -H "Idempotency-Key: $(uuidgen)"

6. Attribute a loan

A loan has one partner. A second attribution returns 409, so correct the existing one instead. The source defaults to at_origination, and a backfill has to be stated deliberately.

For a Direct loan, do not call this at all.

source

Optional. at_origination by default, or backfill.

This is an example body. The reference does not list every field of this request yet, so treat the field names as placeholders and confirm them before you build.

POST/v1/loan-attributions

curl -X POST "$LOKTA_API/lokta-lms/api/v1/loan-attributions" \
  -u "$LOKTA_USER:$LOKTA_PASS" \
  -H "Tenant-Identifier: default" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "loan_id": 1,
    "partner_id": "your-partner-id",
    "source": "at_origination"
  }'

Where to go next

Run partner fees and record a payment Sourcing Partners reference

Every request authenticates with HTTP Basic and carries a Tenant-Identifier header. See the conventions. Read this guide as Markdown.

This is the API reference for Lokta, the agentic loan servicing platform. Go to lokta.ai