Master Award Controls

Is this page helpful? Give us feedback on our docs ->

About Master Award Controls

Warning: We strongly advise you to use Program & Rule logic wherever possible instead of Master Award Controls.

Master Controls do not provide the means for automated Award distribution and they do not allow for effective auditing in the way that Activity-driven Rules do.

Master Award Controls are essentially master create/update/delete tools that allow you to override any other Village-based business logic. There are four POST API types in this category:

1. Issue - Immediately issues a specified Award type and amount into an end-user's digital wallet

2. Burn - Immediately deletes a specified Award type and amount from an end-user's digital wallet

3. Transfer - Moves a specified Award type and amount from one user's digital wallet to another's

4. Exchange - Effectively a double transfer in one API request; trades an Award type for another Award type between two users' digital wallets.

The most common functional use case for Master Award Controls:

1. Supporting customer service escalations which require award adjustments

2. Rectifying production outages on your system

Note: the Village Admin Dashboard allows for the similar manual adjustment of Award balances if you wish to use a no-code option for your customer service and/or operations teams.

Issue API

Endpoint

POST/networks/YOUR_NETWORK_ID/issue

Where 'YOUR_NETWORK_ID' is replaced with your actual Network ID.

Body Fields

Field Name	JSON Key	Type	Description	Required
User	user	string	The user receiving newly issued assets. May be email or user_id.	Yes
Asset Short Name	asset_short_name	string	Short Name of the asset to be issued. This is the same Short Name created and viewable on the Village admin dashboard.	Yes
Issue Amount	issue_amount	string	Amount to be issued.	Yes
Metadata	metadata	object	Additional metadata for the user status change. See Metadata fields for options.	Yes

Metadata

Field Name	JSON Key	Type	Description	Required
Reference ID	reference_id	string	An optional identifier that can be used for reporting purposes.	No
Issue Timestamp	issue_timestamp	integer	The Unix timestamp of when the issuance occurred. If this is blank, Village will use the timestamp the activity was received via the Village API as the Issuance Timestamp.	No
Description	description	string	A description.	No

Example Body

// Example Issue Body
{
  "user": "[e-mail]",
  "asset_short_name": "XPOINT",
  "issue_amount": "800.404",
  "metadata": {
    "reference_id": "dpi_Ylo2Cfr8US8u1JIdAl2eZvKB",
    "issue_timestamp": 1664900628,
    "description": "Standard issuance of XPOINTs for off-platform activity."
  }
}

Burn API

Endpoint

POST/networks/YOUR_NETWORK_ID/burn

Where 'YOUR_NETWORK_ID' is replaced with your actual Network ID.

Body Fields

Field Name	JSON Key	Type	Description	Required
User	user	string	The user whose assets will be burned. May be email or user_id.	Yes
Asset Short Name	asset_short_name	string	Short Name of the asset to be burned. This is the same Short Name created and viewable on the Village admin dashboard.	Yes
Burn Amount	burn_amount	string	Amount to be burned.	Yes
Metadata	metadata	object	Additional metadata for the user status change. See Metadata fields for options.	Yes

Metadata

Field Name	JSON Key	Type	Description	Required
Reference ID	reference_id	string	An optional identifier that can be used for reporting purposes.	No
Burn Timestamp	burn_timestamp	integer	The Unix timestamp of when the burn occurred. If this is blank, Village will use the timestamp the activity was received via the Village API as the Burn Timestamp.	No
Description	description	string	A description.	No

Example Body

// Example Burn Body
{
  "user": "[e-mail]",
  "asset_short_name": "XPOINT",
  "burn_amount": "800.404",
  "metadata": {
    "reference_id": "dpi_Ylo2Cfr8US8u1JIdAl2eZvKB",
    "burn_timestamp": 1664900628,
    "description": "Standard issuance of XPOINTs for off-platform activity."
  }
}

Transfer API

Endpoint

POST/networks/YOUR_NETWORK_ID/transfer

Where 'YOUR_NETWORK_ID' is replaced with your actual Network ID.

Body Fields

Field Name	JSON Key	Type	Description	Required
Sender	sender	string	The user sending assets. May be email or user_id.	Yes
Recipient	recipient	string	The user who is receiving assets. May be email or user_id.	Yes
Transfer Assets	transfer_assets	array	An array of assets that will be transferred. The assets listed will be transferred to the Recipient's digital wallet.	Yes
Metadata	metadata	object	Additional metadata for the user status change. See Metadata fields for options.	No

Transfer Array

Field Name	JSON Key	Type	Description	Required
Asset Short Name	asset_short_name	string	Short Name of the asset to be transferred. This is the same Short Name created and viewable on the Village admin dashboard.	Yes
Amount	amount	string	Amount to be exchanged.	Yes

Metadata

Field Name	JSON Key	Type	Description	Required
Reference ID	reference_id	string	An optional identifier that can be used for reporting purposes.	No
Transfer Timestamp	transfer_timestamp	integer	The Unix timestamp of when the transfer occurred. If this is blank, Village will use the timestamp the activity was received via the Village API as the Transfer Timestamp.	No
Description	description	string	A description of the redemption.	No

Example Body

// Example Transfer Body
{
    "sender": "[e-mail]",
    "recipient": "[e-mail]",
    "transfer_assets": [
        {
            "asset_short_name": "VUSD",
            "amount": "2.5"
        },
        {
            "asset_short_name": "XPOINT",
            "amount": "500"
        }
    ],
    "metadata": {
        "reference_id": "dpi_Ylo2Cfr8US8u1JIdAl2eZvKB",
        "transfer_timestamp": 1664900628,
        "description": "Transfer of assets for services rendered"
    }
}

Exchange API

Endpoint

POST/networks/YOUR_NETWORK_ID/exchange

Where 'YOUR_NETWORK_ID' is replaced with your actual Network ID.

Body Fields

Field Name	JSON Key	Type	Description	Required
User 1	user_1	string	The first user who is exchanging assets. May be email or user_id.	Yes
User 1 Assets	user_1_assets	array	An array of assets that will be exchanged. The assets listed will be transferred to User 2's digital wallet.	Yes
User 2	user_2	string	The second user who is exchanging assets. May be email or user_id.	Yes
User 2 Assets	user_2_assets	array	An array of assets that will be exchanged. The assets listed will be transferred to User 1's digital wallet.	Yes
Metadata	metadata	object	Additional metadata for the user status change. See Metadata fields for options.	No

Exchange Array Fields

Field Name	JSON Key	Type	Description	Required
Asset Short Name	asset_short_name	string	Short Name of the asset to be exchanged. This is the same Short Name created and viewable on the Village admin dashboard.	Yes
Amount	amount	string	Amount to be exchanged.	Yes
Burn	burn	boolean	If set to true, the asset will be burned--or in other words, permanently deleted from the digital ledger--after the exchange is complete. Note that currency or fiat (such as USD) may not be burned. If the field is not submitted, it will default to false.	No

Metadata

Field Name	JSON Key	Type	Description	Required
Reference ID	reference_id	string	An optional identifier that can be used for reporting purposes.	No
Exchange Timestamp	exchange_timestamp	integer	The Unix timestamp of when the exchange occurred. If this is blank, Village will use the timestamp the activity was received via the Village API as the Exchange Timestamp.	No
Description	description	string	A description of the redemption.	No

Example Body

// Example Exchange Body
{
    "user_1": "[e-mail]",
    "user_1_assets": [
        {
            "asset_short_name": "VUSD",
            "amount": "5.00"
            "burn": false
        },
        {
            "asset_short_name": "VEUR",
            "amount": "1.50"
        }

    ],
    "user_2": "[e-mail]",
    "user_2_assets": [
        {
            "asset_short_name": "XPOINT",
            "amount": "100.00"
            "burn": true
        },
        {
            "asset_short_name": "EPOINT",
            "amount": "35.00"
            "burn": false
        }

    ],
    "metadata": {
        "reference_id": "dpi_Ylo2Cfr8US8u1JIdAl2eZvKB",
        "exchange_timestamp": 1664900628,
        "description": "Standard exchange rewards points for dollars & euros."
    }
}
    "sender": "[e-mail]",
    "recipient": "[e-mail]",
    "transfer_assets": [
        {
            "asset_short_name": "VUSD",
            "amount": "2.5"
        },
        {
            "asset_short_name": "XPOINT",
            "amount": "500"
        }
    ],
    "metadata": {
        "reference_id": "dpi_Ylo2Cfr8US8u1JIdAl2eZvKB",
        "transfer_timestamp": 1664900628,
        "description": "Transfer of assets for services rendered"
    }
}

Is this page helpful? Give us feedback on our docs ->