Leads

Attach a reward to a referral

Attaches a bonus, SPIFF or revenue share to a single referral, on top of whatever the partner's reward plan already pays. Use it when the rule that decides which referrals qualify lives in your own systems: your integration evaluates the rule and attaches the reward.

external_identifier is required and is your own idempotency key. Posting the same one twice updates the existing reward instead of creating a second, so a retried delivery cannot pay the bonus twice. Three shapes are supported: a fixed sum on qualification, a fixed sum on closed-won, and a flat percentage of revenue on closed-won. Banded rates (over time or over revenue) and payout caps stay with the reward plan, and are rejected here rather than accepted and ignored.

The request is refused, with a code naming the reason, when it would not do what you asked:

codewhat happened
plan_rewards_not_appliedThe referral has not yet been given the rewards its reward plan owes it. Move the referral forward first, then retry.
milestone_passedThe referral has already passed the point at which this reward type pays. Send force: true to attach it anyway and raise its invoice immediately.
referral_not_invoiceableThe referral is rejected, churned or expired, so the reward cannot be paid.
unsupported_reward_typereward_type is ONE_TIME_PAYOUT or not a known reward type.
period_months_requiredThe term must be a positive number of months.
reward_type_immutableThe external_identifier already names a reward of a different type. Remove it and add a new one.
payee_immutableThe external_identifier already names a reward paying a different payee. Remove it and add a new one.
invoice_lockedThe reward has a finalized or paid invoice, so its amount can no longer be changed. Void or reverse the invoice first.
invoice_amount_stampedThe reward is a QUALIFIED_LEAD_FIXED reward that has already invoiced. That invoice keeps the amount it was raised with, so remove the reward and add a new one at the new amount.
term_change_invoicedThe revenue share has already invoiced, so its period_months can no longer be changed. Remove it and add a new one with the new term.

Repricing a CLOSED_WON_FIXED or CLOSED_WON_PERCENTAGE reward whose invoices are still draft or payment-ready recalculates those invoices on the same call.

Malformed input is a 400 naming the field: a missing name, amount, external_identifier or (for CLOSED_WON_PERCENTAGE) period_months; period_months sent with a fixed type; an unsupported currency; an invalid payee_type, or a named contact that is not an active contact at the referral's partner; or a band or cap field (periods, revenue_conditions, percentage_rate_type, max_payout_amount), which belong on a reward plan.

Requires payment_write permission.

post/leads/{lead_identifier}/rewards

Request

  • Base URL: https://api.lassotech.com/api/v1/rest
  • URL: https://api.lassotech.com/api/v1/rest/leads/{lead_identifier}/rewards
  • Auth: API key in header x-lasso-access-token

Path parameters

lead_identifierstring required

Referral identifier (slug by default, or value matching by param)

Query parameters

by'slug' | 'id' | 'email' | 'company_name' | 'external'

How to read the referral identifier in the path. See Resource Lookup.

external_system_typestring

Required when by=external. e.g. HUBSPOT, SALESFORCE, PIPEDRIVE

external_object_typestring

Required when by=external (optional for a Salesforce partner). e.g. company, deal, opportunity, account

Request body

namestring required

Shown to the partner alongside the reward.

amountnumber float required

The payout sum for a fixed reward, or the rate (greater than 0, at most 100) for CLOSED_WON_PERCENTAGE.

reward_type'QUALIFIED_LEAD_FIXED' | 'CLOSED_WON_FIXED' | 'CLOSED_WON_PERCENTAGE' required

When the reward pays, and whether amount is a sum or a rate. QUALIFIED_LEAD_FIXED and CLOSED_WON_FIXED pay a fixed sum; CLOSED_WON_PERCENTAGE pays amount percent of revenue and requires period_months.

period_monthsinteger

Required for CLOSED_WON_PERCENTAGE, and rejected for the fixed types. How long the revenue share runs, in months. Any positive term is accepted.

external_identifierstring required

Your own identifier for this reward. Required, and unique per referral.

currencystring

ISO currency code. Must be one of your account's supported base currencies. Defaults to the referral's currency.

payee_type'partner' | 'partner_user'

Pay the partner organization or a contact. Defaults to the partner where the referral has one, and to partner_user when a contact is named below. Sending partner alongside a named contact is refused as contradictory. partner_user with no contact named pays the referral's own contact. Fixed when the reward is created: sending a different payee for an existing external_identifier is refused with payee_immutable.

partner_user_slugstring

Pay this contact rather than the referral's own contact. Must be an active contact at the referral's partner. Mutually exclusive with partner_user_email.

partner_user_emailstring

Pay the contact with this email rather than the referral's own contact. Must be an active contact at the referral's partner. Mutually exclusive with partner_user_slug.

forceboolean

Attach the reward even though the referral has already passed the point at which it pays, and raise its invoice now.

visible_to_partnersboolean
external_titlestring nullable
external_descriptionstring nullable
internal_descriptionstring nullable

Example request

{
  "name": "Tier 1 Call Held Bonus",
  "amount": 1000,
  "period_months": 12,
  "external_identifier": "hs-deal-4242-tier1",
  "currency": "USD",
  "partner_user_slug": "PC-1A2B3C",
  "partner_user_email": "finance@acme.com"
}

Response

A reward with this external_identifier already existed and was updated

Example response

{
  "lead_reward": {
    "name": "Tier 1 Call Held Bonus",
    "invoices": [
      {
        "status": "draft"
      }
    ]
  }
}

Changes

No recorded changes to this operation across all 1 revision of this API.