---
title: "Create an account assignment"
method: POST
path: "/v1/account-assignments"
tags: ["Accounts"]
---

# Create an account assignment

`POST /v1/account-assignments`

## Request

- Base URL: `https://api.prod.keyban.io`
- URL: `https://api.prod.keyban.io/v1/account-assignments`
- Auth: one of:
  - API key in header `X-Api-Key`
  - `bearer` (a scheme the document does not define)

Register a pending loyalty benefit for an identity so it is applied automatically at account creation; supports optional upsert to avoid duplicates.

## Request body

- CreateAccountAssignmentDto
  - `application` string, uuid, required: The unique identifier of the application
  - `email` string, email, nullable: Contact email of the assigned account
  - `phoneNumber` string, e164, nullable: Contact phone number of the assigned account
  - `name` string, nullable: Name of the user to be assigned
  - `balance` union: The optimistic loyalty balance
    - string
    - number
  - `rewardTier` union: UUID or name of a fixed reward tier applied to this account
    - string, uuid
    - string

## Response `201`

Account assignment created successfully

- AccountAssignmentDto: Account assignment data
  - `id` string, uuid, required: The unique identifier of the account assignment
  - `createdAt` string, date-time, required: Creation date (ISO 8601)
  - `updatedAt` string, date-time, required: Last update date (ISO 8601)
  - `application` string, uuid, required: The unique identifier of the application
  - `email` string, email, nullable: Contact email of the assigned account
  - `phoneNumber` string, e164, nullable: Contact phone number of the assigned account
  - `name` string, nullable: Name of the user to be assigned
  - `balance` union: The optimistic loyalty balance
    - string
    - number
  - `rewardTier` object, nullable, required
    - `id` string, uuid, required: Entity UUID
    - `createdAt` string, date-time, required: Creation date (ISO 8601)
    - `updatedAt` string, date-time, required: Last update date (ISO 8601)
    - `application` string, uuid, required: The unique identifier of the application
    - `name` string, required: The name of the loyalty reward tier
    - `requiredVisits` integer, required: The number of visits required to reach this reward tier
    - `currencyToPointRatio` integer, required: Number of loyalty points earned for each 1 unit of currency spent (e.g., if the ratio is 2 and currency is EUR, spending €1 earns 2 points). Used to calculate point accruals from transaction amounts.
    - `bgImageUrl` string, uri, nullable: Background image for the reward tier. Supported formats: WEBP (preferred), PNG. Recommended size: 1920×1080 px (landscape). Max file size: 1 MB.

---

[API](https://skmtc.dev/keyban/apis/keyban-rest-apis.md) · [All operations](https://skmtc.dev/keyban/apis/keyban-rest-apis/llms.txt) · [OpenAPI document](https://skmtc.dev/keyban/apis/keyban-rest-apis/revisions/0bb79a1da961?raw)