---
title: "Attach a reward to a referral"
method: POST
path: "/leads/{lead_identifier}/rewards"
tags: ["Leads"]
---

# Attach a reward to a referral

`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`

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:

| code | what happened |
|------|---------------|
| `plan_rewards_not_applied` | The referral has not yet been given the rewards its reward plan owes it. Move the referral forward first, then retry. |
| `milestone_passed` | The 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_invoiceable` | The referral is rejected, churned or expired, so the reward cannot be paid. |
| `unsupported_reward_type` | `reward_type` is `ONE_TIME_PAYOUT` or not a known reward type. |
| `period_months_required` | The term must be a positive number of months. |
| `reward_type_immutable` | The `external_identifier` already names a reward of a different type. Remove it and add a new one. |
| `payee_immutable` | The `external_identifier` already names a reward paying a different payee. Remove it and add a new one. |
| `invoice_locked` | The reward has a finalized or paid invoice, so its amount can no longer be changed. Void or reverse the invoice first. |
| `invoice_amount_stamped` | The 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_invoiced` | The 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.

## Path parameters

- `lead_identifier` string, required

## Query parameters

- `by` 'slug' | 'id' | 'email' | 'company_name' | 'external'
- `external_system_type` string
- `external_object_type` string

## Request body

- object
  - `name` string, required: Shown to the partner alongside the reward.
  - `amount` number, 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_months` integer: 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_identifier` string, required: Your own identifier for this reward. Required, and unique per referral.
  - `currency` string: 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_slug` string: 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_email` string: 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`.
  - `force` boolean: Attach the reward even though the referral has already passed the point at which it pays, and raise its invoice now.
  - `visible_to_partners` boolean
  - `external_title` string, nullable
  - `external_description` string, nullable
  - `internal_description` string, nullable

## Response `200`

A reward with this external_identifier already existed and was updated

- object
  - `lead_reward` LeadReward
    - `id` integer
    - `name` string
    - `reward_type` 'QUALIFIED_LEAD_FIXED' | 'CLOSED_WON_FIXED' | 'CLOSED_WON_PERCENTAGE' | 'ONE_TIME_PAYOUT': Rewards created through this API are QUALIFIED_LEAD_FIXED, CLOSED_WON_FIXED or CLOSED_WON_PERCENTAGE; ONE_TIME_PAYOUT only appears on rewards that came from elsewhere.
    - `amount` number, float
    - `amount_type` 'fixed_amount' | 'percentage'
    - `period_months` integer, nullable: How long a revenue share runs. Null for fixed-amount rewards, which bill once.
    - `currency` string
    - `external_identifier` string, nullable: The identifier you created the reward with. Null for rewards copied from a reward plan or added in the Lasso admin.
    - `source` 'reward_plan' | 'ad_hoc': Whether the reward came from the partner's reward plan or was attached to this referral alone.
    - `reward_plan` object, nullable
      - `segment_reward_id` integer
      - `segment_slug` string
      - `segment_name` string
    - `payee` object: Who the reward pays. A reward pays either the partner organization or one partner contact, never both.
      - `type` 'partner' | 'partner_user'
      - `partner_slug` string, nullable
      - `partner_name` string, nullable
      - `partner_user_slug` string, nullable
      - `email` string, nullable
    - `external_title` string, nullable
    - `external_description` string, nullable
    - `internal_description` string, nullable
    - `visible_to_partners` boolean
    - `invoices` LeadRewardInvoice[]: Every invoice raised against this reward, voided ones included.
      - `slug` string
      - `status` 'draft' | 'payment_ready' | 'finalized' | 'paid' | 'voided': The invoice's current status. A reward with a finalized or paid invoice can no longer be removed.
      - `amount` number, float
      - `currency` string
      - `invoice_on` string, date
      - `due_on` string, date
      - `paid_at` string, date-time, nullable
    - `removable` boolean: False once one of the reward's invoices is finalized or paid. Removing it then is refused.
    - `removal_blocked_reason` string, nullable
    - `created_at` string, date-time
    - `updated_at` string, date-time

## Other responses

- `201`: Reward attached
- `400`: Missing or malformed parameter
- `401`: Missing or invalid API key
- `403`: API key lacks required permission
- `404`: Resource not found
- `422`: The reward was refused, with a code naming the reason
- `429`: Rate limit exceeded. Wait the number of seconds in `Retry-After`, then retry.

---

[API](https://skmtc.dev/onelasso/apis/lasso-rest-api.md) · [All operations](https://skmtc.dev/onelasso/apis/lasso-rest-api/llms.txt) · [OpenAPI document](https://skmtc.dev/onelasso/apis/lasso-rest-api/revisions/bbc328f5e2d1?raw)