Partner API

Submit student leads for the colleges granted to you and follow each lead to its outcome. Server-to-server, JSON over HTTPS, additive versioning: clients must ignore unknown fields.

Quickstart

Create a test key in the portal (Developers → Keys), send a lead to the sandbox, watch it move through its states, then read it back. Live keys are issued when CollegePucho approves go-live.

POST https://collegepucho.onrender.com/partner/v1/leads
X-API-Key: pk_live_…
Idempotency-Key: 7c1f…
Content-Type: application/json

{
  "name": "Riya Sharma",
  "mobile": "9811112222",
  "email": "riya@example.com",
  "college": "ims-ghaziabad",
  "course": "MBA",
  "state": "Delhi",
  "city": "New Delhi",
  "external_ref": "CRM-55821",
  "campaign": "oct-fair",
  "consent": {
    "version": "v1-en",
    "at": "2026-10-02T09:10:00+05:30",
    "channel": "web",
    "scope": [
      "counselling_calls",
      "share_with_college"
    ]
  }
}

{
  "id": 918223,
  "submission_id": 1,
  "external_ref": "CRM-55821",
  "state": "under_review",
  "review_due_at": "2026-10-02T13:10:00+05:30",
  "warnings": [],
  "quota": {
    "day_left": 39,
    "month_left": 1811
  }
}

const res = await fetch("https://collegepucho.onrender.com/partner/v1/leads", {
  method: "POST",
  headers: { "X-API-Key": process.env.CP_KEY, "Idempotency-Key": crypto.randomUUID(), "Content-Type": "application/json" },
  body: JSON.stringify(lead),
});
const data = await res.json(); // data.state === "under_review"

import os, uuid, requests
r = requests.post("https://collegepucho.onrender.com/partner/v1/leads",
    headers={"X-API-Key": os.environ["CP_KEY"], "Idempotency-Key": str(uuid.uuid4())},
    json=lead, timeout=10)
print(r.status_code, r.json()["state"])

$ch = curl_init("https://collegepucho.onrender.com/partner/v1/leads");
curl_setopt_array($ch, [CURLOPT_POST => true, CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => ["X-API-Key: " . getenv("CP_KEY"), "Idempotency-Key: " . bin2hex(random_bytes(16)), "Content-Type: application/json"],
  CURLOPT_POSTFIELDS => json_encode($lead)]);
$data = json_decode(curl_exec($ch), true); // $data["state"] === "under_review"

Authentication & keys

Rotating a key keeps the old one working for 24 hours; responses then carry X-CP-Key-Deprecated: true. Keys are shown once at creation and never stored in readable form. Live keys may be restricted to an IP allow-list (403 ip_blocked otherwise); test keys are not restricted.

The API is server-to-server. Browser requests with live or test keys are refused by CORS by design — use a publishable key, bound to your origins, for embedded forms (it can only POST /leads and GET /scope).

Rate limits & headers

Request headers

• X-API-Key
• Idempotency-Key (optional, POST /leads)
• X-Request-Id (optional, echoed)
• X-CP-Sandbox-Scenario (test keys only)

Response headers

• X-Request-Id
• X-RateLimit-Limit
• X-RateLimit-Remaining
• X-RateLimit-Reset
• Retry-After (429)
• Idempotent-Replayed
• X-CP-Key-Deprecated

Idempotency & external_ref

Send Idempotency-Key with POST /leads: the same key with the same body returns the stored response (200, Idempotent-Replayed: true); the same key with a different body is 409 idempotency_mismatch. external_ref is independent: a repeated external_ref also replays.

Endpoints

“Try it” is intentionally absent: keys are server-side secrets. Download the OpenAPI document to generate a client.

Validation

States

Flow: under_review (or hold when a correction is needed) → approved_waiting → delivered → contacted / interested → application → admission. Terminal states: rejected, duplicate, withdrawn, expired, not_accepted, returned. What you see after delivery depends on your feedback mode (none, stages, full).

Reason codes

Rejection

Held (approved, waiting for the college)

Returns by the college

Errors

Every error body is { code, message, hint?, errors?[] }; 422 bodies list field errors as { field, code, message }.

Consent

Every lead carries the student's consent: consent: { version, at, channel, scope[], language? }. scope normally holds contact and share_with_college. A student under 18 (is_minor or dob) needs guardian: { name, relation }. Keep your own record of the notice text shown for each version; the notice is available in English and Hindi.

Webhooks

Configure a URL in the portal (Developers → Webhook). https only; a public hostname (no IPs, no private networks); no redirects; the endpoint must answer 2xx to a webhook.test ping when saved.

Events

lead.receivedlead.approvedlead.rejectedlead.holdlead.withdrawnlead.expiredlead.editedlead.deliveredlead.heldlead.not_acceptedlead.stagelead.returnedlead.supersededlead.erasedlead.consent_withdrawndispute.openeddispute.updateddispute.resolvedconversion.applicationconversion.admissionpayout.accruedpayout.payablepayout.reversedpayout.clawbackrun.statement_readypayout.paidbatch.completedscope.changedgrant.pausedgrant.resumedrate_card.changedkey.expiringkey.rotatedpartner.lifecyclewebhook.disabledwebhook.test

Headers

• X-CP-Event
• X-CP-Delivery (uuid — dedupe on it)
• X-CP-Timestamp (unix seconds)
• X-CP-Signature: v1=HMAC-SHA256(secret, timestamp + "." + rawBody) — may list two signatures while a rotated secret overlaps
• X-CP-Env (live | test)

Payload

{
  "schema_version": 1,
  "event": "lead.delivered",
  "env": "live",
  "occurred_at": "2026-10-03T09:10:00.000Z",
  "data": {
    "…": "event-specific ids, refs, codes, amounts — never student details"
  },
  "submission": {
    "id": 918223,
    "submission_id": 1,
    "external_ref": "CRM-55821",
    "state": "delivered",
    "reason_code": null,
    "held_reason": null,
    "college_code": "ims-ghaziabad"
  }
}

Verify the signature

Recompute HMAC-SHA256 over `${X-CP-Timestamp}.${raw request body}` with your signing secret, compare constant-time to any listed v1 value, and reject timestamps older than 300 seconds.

const crypto = require("crypto");
function verify(rawBody, headers, secret) {
  const ts = headers["x-cp-timestamp"];
  if (Math.abs(Date.now() / 1000 - Number(ts)) > 300) return false;
  const expected = crypto.createHmac("sha256", secret).update(ts + "." + rawBody).digest("hex");
  return String(headers["x-cp-signature"]).split(",").some((s) => {
    const v = s.trim().replace(/^v1=/, "");
    return v.length === expected.length && crypto.timingSafeEqual(Buffer.from(v), Buffer.from(expected));
  });
}

import hmac, hashlib, time
def verify(raw_body: bytes, headers, secret: str) -> bool:
    ts = headers["X-CP-Timestamp"]
    if abs(time.time() - int(ts)) > 300: return False
    expected = hmac.new(secret.encode(), f"{ts}.".encode() + raw_body, hashlib.sha256).hexdigest()
    return any(hmac.compare_digest(s.strip().removeprefix("v1="), expected) for s in headers["X-CP-Signature"].split(","))

function verify(string $rawBody, array $headers, string $secret): bool {
  $ts = $headers["X-CP-Timestamp"];
  if (abs(time() - (int)$ts) > 300) return false;
  $expected = hash_hmac("sha256", $ts . "." . $rawBody, $secret);
  foreach (explode(",", $headers["X-CP-Signature"]) as $s) if (hash_equals($expected, preg_replace("/^v1=/", "", trim($s)))) return true;
  return false;
}

Retries, ordering, replay

Non-2xx or no answer within 8 s → retried after 1 min, 5 min, 30 min, 2 h and 12 h, then marked failed. 25 consecutive failures disable the endpoint (owners are emailed; re-enable from the portal). Order is not guaranteed; dedupe on X-CP-Delivery. Past deliveries can be replayed from the portal (10 per hour).

Sandbox

Use a pk_test_ key. Leads go to a sandbox book with a scripted journey chosen by the mobile number below or the X-CP-Sandbox-Scenario header; webhooks fire with env test.

Scope & capacity

GET /scope lists the colleges granted to you with their codes, allowed courses and states, and a cap_state of open, tight or full. Approved leads are delivered when the college has capacity; CollegePucho's own leads are served first and a per-college reserve is kept for partner leads. A held lead shows a held reason (for example capacity_day) until it is delivered, returned or expires after the hold window.

How you get paid

1. Rate card — per college, course and state, for the events lead, application and admission (GET /rate-card). Decreases are announced at least 7 days ahead.
2. Items — a lead payout accrues on delivery and is on hold until the return window closes; application and admission payouts become payable when the college confirms (GET /payouts).
3. Statement — generated on the 8th for the previous month; approved by the 10th; PDF and JSON with a sha256 hash (GET /runs/:id).
4. Invoice — GST-registered partners raise a tax invoice for the statement amount (SAC 9983); unregistered partners do not add GST.
5. TDS — deducted under section 194H on the taxable amount; 20% when no valid PAN is on file; Form 16A each quarter.
6. Payment — within 30 days (45 for MSME) by bank transfer to the verified account; the UTR appears on the statement.

Changelog & deprecation

Versioning is additive: new fields and events may appear at any time; removals are announced here at least 90 days ahead and signalled with X-CP-Deprecated-Endpoint or X-CP-Key-Deprecated headers. Status page: status.collegepucho.com.