---
title: "Create or Update a Wallet Consumer"
method: POST
path: "/services/wallet/consumer"
tags: ["Services"]
---

# Create or Update a Wallet Consumer

`POST /services/wallet/consumer`

This API method allows the calling application to create or update a wallet consumer for a wallet specified by the identity-value. The consumer will be created if it does not exist, otherwise the existing wallet consumer will be updated.

## Query parameters

- `identity-value` string, string, required

## Request body

- WalletConsumerCreatePayload
  - `friendlyName` string, required — The friendly name of the Wallet Consumer to be created
  - `type` string, required — The type of the Wallet Consumer to be created. These types are managed on a per-retailer basis.
  - `status` string, required — The status of the Wallet Consumer to be created. Can be set to ACTIVE or DELETED
  - `state` string — The state of the Wallet Consumer to be created.
  - `data` object
    - `key1` string — Meta 1 property, up to 255 characters; up to 255 characters for Key 1 Value
    - `key2` string — Meta 2 property, up to 255 characters; up to 255 characters for Key 2 Value
  - `meta` MetaEntity
    - `key1` string — Meta 1 property, up to 250 characters; up to 750 characters for Key 1 Value
    - `key2` string — Meta 2 property, up to 250 characters; up to 750 characters for Key 2 Value
  - `personal` object — It contains the data about the person.
    - `title` string, required — The title of the person.
    - `firstName` string, required — First name of the person.
    - `lastName` string, required — Last name of the person.
    - `preferredName` string — If provided, the preferred name of the person.
    - `language` string — If provided, the preferred language of the person.
    - `gender` string — If provided, the given gender of the person.
    - `birthDate` string — If provided, the given date of birth.
  - `address` object[] — Any kind of address.
    - `name` string, required — An identifier for this particular address.
    - `type` 'local' | 'overseas' | 'bfpo' — Type of address, usually not required but may be needed for BFPO.
    - `line1` string, required — First address line.
    - `line2` string — Second address line.
    - `line3` string — Third address line.
    - `city` string, required — City.
    - `state` string — State/Provence, if applicable in the territory.
    - `county` string, required — County.
    - `postcode` string, required — Postcode.
    - `country` string, required — Country.
  - `contact` object[] — Contact details for an entity.
    - `name` string, required — Unique per type of contact, used to differentiate contacts of the same type.
    - `type` 'email' | 'phone' | 'whatsapp', required — The type of contact, used to set the communication medium.
    - `value` string, required — The contact value to be used in communications.
  - `communication` object[] — Information relating to a marketing channel, including optin options.
    - `type` 'default' | 'sms' | 'email' | 'postal' | 'phone', required — The type of channel used for communication.
    - `optin` object — Information about optin options.
      - `admin` boolean, required — Indication of optin to administrative communications.
      - `marketing` boolean — Indication of optin to marketing communications.
  - `consent` object[] — Types of consent that may have been agreed to.
    - `name` string, required — A unique name identifying the name of the consented agreement. Take care for the name to be specific enough to be identified later.
    - `accepted` boolean, required — A simple boolean indicating consent has been agreed.
    - `datetime` string — The date and time that the consent was given.
    - `link` string — A link (if applicable) to the consent agreement.
    - `signature` string — A digital signature link, image link, or some other proof that the consent was agreed.
  - `preference` object — Information about the store preference.
    - `store` object[] — Information about the store.
      - `brand` string — The name of the brand.
      - `outlet` string[] — Information about the outlet.
  - `segment` object[] — It holds information about a marketing segment against an entity.
    - `labels` string[], required — List of segment labels that the entity belongs to for the given segmentation entry. The list can be used to denote hierarchy, lowest indexed items are higher in hierarchy terms. At least one item is required.
    - `data` object — A place to store arbitrary domain-specific data against the segmentation object.
    - `base` 'DEM' — An optional base of segmentation that is being applied.
    - `weight` integer — The relative importance of the segmentation entry, lower numbers are lighter and more important, higher numbers are heavier and sink lower.
    - `confidence` number — The score of how likely the segmentation is to be correct. Valid values are floats less than or equal to 1.
  - `segmentation` object[] — It holds information about the result of Marketing Segmentation against a given entity.
    - `name` string, required — Customer defined name / category for the segment.
    - `segments` object[], required — It contains segment objects in the array.
      - `labels` string[], required — List of segment labels that the entity belongs to for the given segmentation entry. The list can be used to denote hierarchy, lowest indexed items are higher in hierarchy terms. At least one item is required.
      - `data` object — A place to store arbitrary domain-specific data against the segmentation object.
      - `base` 'DEM' — An optional base of segmentation that is being applied.
      - `weight` integer — The relative importance of the segmentation entry, lower numbers are lighter and more important, higher numbers are heavier and sink lower.
      - `confidence` number — The score of how likely the segmentation is to be correct. Valid values are floats less than or equal to 1.
  - `dimension` object[] — Dimensions are a means for defining arbitrary facts against an entity. The Air system may define standard dimension names against entities.
    - `label` string, required — Name of a dimension, standard supported names may exist in the main entity, refer to entity documentation for details.
    - `value` string, required — The value for the dimension, must be a string.

## Response `200`

Success

- WalletConsumerEntity
  - `consumerId` string, required — EES AIR Wallet Consumer ID
  - `walletId` string, required — EES AIR Wallet ID
  - `friendlyName` string, required — Wallet Consumer Friendly Name
  - `type` string, required — Wallet Consumer type. Types are managed per retailer base and could be set-up as part of the Onboarding process.
  - `status` 'ACTIVE' | 'DELETED', required — Wallet Consumer status.
  - `state` string, required — Wallet Consumer State. States are managed per retailer base and could be set-up as part of the Onboarding process.
  - `data` union, required — Additional Wallet Consumer Data. Please note Wallet Consumer Data structure could be defined within AIR per Client. If this structure is defined, AIR can provide validation of content using regular expressions.
    - object — Older key/value pair consumer data.
      - `key` object[]
        - `key1` unknown
        - `key2` unknown
    - object — Structured data for a consumer.
      - `key` object[]
        - `name` string
        - `segments` object[]
          - `key1` unknown
          - `key2` unknown
  - `meta` MetaEntity, required
    - `key1` string — Meta 1 property, up to 250 characters; up to 750 characters for Key 1 Value
    - `key2` string — Meta 2 property, up to 250 characters; up to 750 characters for Key 2 Value
  - `dateCreated` string, date-time, required — Date this Wallet Consumer was created
  - `lastUpdated` string, date-time, required — Date this Wallet Consumer was last updated

## Other responses

- `201` — Created
- `400` — Bad Request.
- `401` — Unauthorized.
- `403` — Forbidden.
- `404` — Not Found
- `415` — Unsupported Media Type
- `423` — Locked
- `429` — Too Many Requests
- `500` — Server Error

---

[API](https://skmtc.net/eagleeye/apis/wallet-api.md) · [All operations](https://skmtc.net/eagleeye/apis/wallet-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/eagleeye/wallet-api/revisions/90a122bb14cc/schema)