# 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 user: With permission to manage sourcing partners. (https://developer.lokta.ai/api/roles-permissions/)
- The agreement: The fee lines and the date they start. A partner cannot be activated without terms in force.
- The partner's documents: The checklist depends on the partner type.
- A loan to attribute: Only needed for the last step. (https://developer.lokta.ai/guides/quickstart/)

## 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.

```bash
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](https://developer.lokta.ai/api/sourcing-partners/retrieve-reference-data.md)

```bash
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](https://developer.lokta.ai/api/sourcing-partners/create-sourcing-partners.md)

```bash
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": "asha@example.com",
        "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](https://developer.lokta.ai/api/sourcing-partners/checklist.md)

```bash
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](https://developer.lokta.ai/api/sourcing-partners/revise.md)

```bash
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](https://developer.lokta.ai/api/sourcing-partners/activate.md)

```bash
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](https://developer.lokta.ai/api/loan-attribution/create-loan-attributions.md)

```bash
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](https://developer.lokta.ai/guides/partner-fees-and-invoices/)
- [Sourcing Partners reference](https://developer.lokta.ai/api/sourcing-partners/)