# Mint a referral code

Mint a referral/promo code owned by the caller's organisation.
The owner is derived from the credential and is never taken from the request
body. `organisation` may be supplied to state the intended owner explicitly; if
it names any organisation other than the one the credential resolves to the
request is refused with `403`.
Omit `code` and one is generated from an unambiguous alphabet. A supplied code
must match `[A-Za-z0-9]{2,16}` — the driver-facing redemption surface silently
discards anything else, so a hyphenated or over-long code would mint here and
then fail to attribute in the field.

Endpoint: POST /referral_codes
Version: 2.0
Security: oauth2

## Header parameters:

  - `EvEnergy-Version` (number)
    Specify the version of this endpoint to use.

  - `Accept-Language` (string)
    Indicates the natural language and locale that the client prefers.

## Request fields (application/json):

  - `code` (string)
    Omit and one is generated.
    Example: SPRING25

  - `label` (string)
    Example: Summer forecourt

  - `campaign_ref` (string)
    Example: summer-forecourt

  - `organisation_id` (string)
    The intended owning organisation, stated explicitly, as either its Clerk
organization id or its Core id. Optional, and never the source of the owner —
it is validated against the organisation the credential resolves to and
refused with `403` if it names another.
    Example: org_2pXqL9wKvTb3Rm8ZaYcN4dHgJf

## Response 201 fields (application/json):

  - `id` (string, required)
    Unique identifier for the given referral code.
    Example: prom01JZQ8V5T7MKXR9NBCDEFGHJ4A

  - `url` (string, required)
    Example: https://api.ev.energy/v2/referral_codes/prom01JZQ8V5T7MKXR9NBCDEFGHJ4A

  - `code` (string, required)
    The public string a driver types. Immutable once issued.
    Example: SPRING24

  - `label` (string)
    Internal name for the owning organisation's UI. Never shown to drivers.
    Example: Forecourt poster - spring

  - `campaign_ref` (string)
    Free-text tag the owning organisation groups and reports on.
    Example: spring-forecourt

  - `status` (string)
    INACTIVE refuses new redemptions and preserves every historical redemption.
    Enum: "ACTIVE", "INACTIVE"

  - `limitation` (string)
    How many times the code may be redeemed.
    Enum: "SINGLE_USE", "SINGLE_USE_PER_USER", "UNLIMITED"

  - `created_at` (string)
    Example: 2026-07-01T09:12:00Z

  - `performance` (object)
    Redemption counts for one code, broken down by stage, from a single snapshot.
Core computes `in_progress_count` rather than leaving a client to difference two
reads, so all three numbers describe the same instant.

  - `performance.redeemed_count` (integer, required)
    Drivers attributed to this code.
    Example: 64

  - `performance.qualified_count` (integer, required)
    Of those, the ones who have completed the qualifying charge.
    Example: 41

  - `performance.in_progress_count` (integer, required)
    `redeemed_count` minus `qualified_count`, clamped at zero.
    Example: 23

## Response 400 fields (application/problem+json):

  - `type` (string)
    Example: https://api.ev.energy/v2/problems/example-problem/

  - `status` (number)
    Example: 400

  - `title` (string, required)
    Example: Short description

  - `detail` (string, required)
    Example: Long, more specific description.

  - `instance` (string)
    Example: https://api.ev.energy/v2/users/user01HN2P75GBNFRJPCZJXEFVXH5E

  - `notification` (object)
    Something that the user should be informed about.

  - `notification.id` (string, required)
    Unique identifier for the Notification
    Example: notf67O36PLTFDB57M0E5L33JZLGM0

  - `notification.url` (string, required)
    Example: https://api.ev.energy/notifications/notf67O36PLTFDB57M0E5L33JZLGM0

  - `notification.message_id` (string, required)
    Internal identifier for this notification type. E.g. 'ERR0023'

  - `notification.category` (string, required)
    Category of this notification type
    Enum: "ACTIONABLE", "SERVICE", "RETRY", "MARKETING", "INTERNAL"

  - `notification.event_time` (string, required)
    The timestamp of the event described by this notification

  - `notification.short_text_title` (string, required)
    Short title for the notification

  - `notification.short_text_body` (string, required)
    Short description of the event being notified

  - `notification.detail_page_title` (string, required)
    Title of a help page giving more information about this notification

  - `notification.detail_page_body` (string, required)
    Text of a help page giving more information about this notification

  - `notification.external_link` (string | null, required)
    URL of a web page giving further information about this notification

  - `notification.external_button_label` (string, required)
    Text to be displayed on a button leading to the external_link location

  - `notification.read_at` (string)
    When the user examined the contents of this notification

  - `notification.resolved_at` (string)
    When the problem associated with this notification was resolved

## Response 401 fields (application/problem+json):

  - `status` (number)
    Example: 401

  - `title` (string, required)
    Example: Unauthorized

  - `detail` (string, required)
    Example: Authentication credentials were not provided.

## Response 403 fields (application/problem+json):

  - `status` (number)
    Example: 403

  - `title` (string, required)
    Example: Forbidden

  - `detail` (string, required)
    Example: You do not have permission to perform this action.

## Response 406 fields (application/problem+json):

  - `status` (number)
    Example: 406

  - `title` (string, required)
    Example: Not Acceptable

  - `detail` (string, required)
    Example: Could not satisfy the request Accept header.

## Response 429 fields (application/problem+json):

  - `type` (string)
    Example: https://api.ev.energy/v2/problems/example-problem/

  - `status` (number)
    Example: 400

  - `title` (string, required)
    Example: Short description

  - `detail` (string, required)
    Example: Long, more specific description.

  - `instance` (string)
    Example: https://api.ev.energy/v2/users/user01HN2P75GBNFRJPCZJXEFVXH5E

  - `notification` (object)
    Something that the user should be informed about.

  - `notification.id` (string, required)
    Unique identifier for the Notification
    Example: notf67O36PLTFDB57M0E5L33JZLGM0

  - `notification.url` (string, required)
    Example: https://api.ev.energy/notifications/notf67O36PLTFDB57M0E5L33JZLGM0

  - `notification.message_id` (string, required)
    Internal identifier for this notification type. E.g. 'ERR0023'

  - `notification.category` (string, required)
    Category of this notification type
    Enum: "ACTIONABLE", "SERVICE", "RETRY", "MARKETING", "INTERNAL"

  - `notification.event_time` (string, required)
    The timestamp of the event described by this notification

  - `notification.short_text_title` (string, required)
    Short title for the notification

  - `notification.short_text_body` (string, required)
    Short description of the event being notified

  - `notification.detail_page_title` (string, required)
    Title of a help page giving more information about this notification

  - `notification.detail_page_body` (string, required)
    Text of a help page giving more information about this notification

  - `notification.external_link` (string | null, required)
    URL of a web page giving further information about this notification

  - `notification.external_button_label` (string, required)
    Text to be displayed on a button leading to the external_link location

  - `notification.read_at` (string)
    When the user examined the contents of this notification

  - `notification.resolved_at` (string)
    When the problem associated with this notification was resolved