---
title: "Redeem referral"
method: POST
path: "/v1/referral-redemptions"
tags: ["Referrals"]
---

# Redeem referral

`POST /v1/referral-redemptions`

Redeem a referral code into a new application.

Referral redemption is asynchronous. The response includes a redemption ID and processing status. Poll `GET /v1/referral-redemptions/{redemptionId}` until the redemption status is `completed` or `failed`. The completed response includes the new application ID.

## Request body

- CreateReferralRedemptionParams
  - `code` string, required — A referral code using the format `AK_` followed by 10 uppercase alphanumeric characters.
  - `reference` string — Optional reference to use for the application created in the redeeming organisation. Defaults to the referral reference.

## Response `200`

Success

- union — A redemption of a referral code into a new application owned by the authenticated organisation.
  - ReferralRedemptionProcessing
    - `_id` string, required — The unique ID of the referral redemption.
    - `referrer` ReferralOrgDetails, required — Details for an organisation involved in a referral.
      - `name` string, required
      - `logo` string — A URL referencing the org's logo in PNG format.
    - `created_at` string, date-time, required
    - `updated_at` string, date-time, required
    - `status` 'processing', required
  - ReferralRedemptionCompleted
    - `_id` string, required — The unique ID of the referral redemption.
    - `referrer` ReferralOrgDetails, required — Details for an organisation involved in a referral.
      - `name` string, required
      - `logo` string — A URL referencing the org's logo in PNG format.
    - `created_at` string, date-time, required
    - `updated_at` string, date-time, required
    - `_application` string, required — The ID of the new application created. Only present when `status` is `completed`.
    - `status` 'completed', required
  - ReferralRedemptionFailed
    - `_id` string, required — The unique ID of the referral redemption.
    - `referrer` ReferralOrgDetails, required — Details for an organisation involved in a referral.
      - `name` string, required
      - `logo` string — A URL referencing the org's logo in PNG format.
    - `created_at` string, date-time, required
    - `updated_at` string, date-time, required
    - `status` 'failed', required
    - `failure_reason` ReferralRedemptionFailureReason, required — If a referral redemption has failed, this field provides additional information about what went wrong.
      - `code` 'document_unavailable' | 'internal_error', required — The reason for a referral redemption's failure: - `document_unavailable` One or more referral snapshot artifacts are no longer available. - `internal_error` An unhandled internal error prevented the redemption from completing.
      - `message` string

## Other responses

- `400` — Bad Request
- `401` — Unauthorized
- `403` — Forbidden
- `404` — Not Found
- `429` — Too Many Requests
- `500` — Internal Server Error

---

[API](https://skmtc.dev/akahu/apis/akahu-enduring-api.md) · [All operations](https://skmtc.dev/akahu/apis/akahu-enduring-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/akahu/akahu-enduring-api/revisions/b2de9915920d/schema)