Utilization Resource - Overview

A Utilization is attached to one Credit. More than one Utilization can be attached to a Credit. Utilizations represent the monetization events of the Credit they are attached to. Utilizations can be "estimated" (ie; forecasted monetization in the future) or "actual" (ie; already monetized).

Methods

The API supports the following methods for Utilization resources:

• List:
  • Returns a list of Utilizations that match the API request parameters. For example, you can retrieve all Projects that the API Credentials have access to, or you can filter the list of Utilizations based on certain parameters. Learn More

Resource Representation

The following JSON structure shows the format of a Utilization resource:

{
    "id": integer,
    "created_at": string (RFC 3339 Format - 2022-05-03T17:13:44Z),
    "updated_at": string (RFC 3339 Format - 2022-05-03T17:13:44Z),
    "status": string,
    "type": string,
    "account": {
       "id": integer,
       "title": string,  
    },
    "created_by": {
       "id": integer,
       "first_name": string,
       "last_name": string,
       "email": string,
    },
    "project": {
       "id": integer,
       "title": string,   
    },
    "credit": {
       "id": integer,
    },
    "local_currency": {
        "code": string,
        "name": string,    
        "html_code": string,   
        "hex_code": string,
        "unicode": string,
    },
    "estimate": {
         "date": string (format YYYY-MM-DD),
         "amount": {
            "usd": {
               "gross_total": float,
               "exchange_rate": float,
               "discounted_value_as_percentage": float,    
               "discount_total": float,    
               "net_total": float,
            },
            "local": {
               "gross_total": float,
            },
        },
    },
    "actual": {
         "date": string (format YYYY-MM-DD),
         "amount": {
            "usd": {
               "gross_total": float,
               "exchange_rate": float,
               "discounted_value_as_percentage": float,    
               "discount_total": float,    
               "net_total": float,
            },
            "local": {
               "gross_total": float,
            },
        },
    },
    "current_percentage_of_credit_amount": integer,
    "variance": {
        "actual_to_estimate": {
           "base_amount": integer,
           "base_amount_percentage": integer
        }
    },
    "notes": string,
    "legal_entity": {
        "id": integer,
        "title": string,
    },   
    "site": {
        "id": integer,
        "title": string,
        "address": string,
        "gps_lng": float,
        "gps_lat": float,
    },
    "custom_data_points":[
        {
            "id": integer,
            "name": string,
            "type": string,
            "value": string,
        }
    ]
}

Resource Properties

The following table defines the properties that appear in this resource:

Key	Type	Definition
id	integer	The ID of the Utilization.
created_at	string	The date and time that the Utilization was created. The value is specified in RFC 3339 Format (2022-05-03T17:13:44Z).
updated_at	string	The date and time that the Utilization was last updated. The value is specified in RFC 3339 Format (2022-05-03T17:13:44Z).
status	string	Whether this Utilization is Estimated (not yet monetized) or Actual (has been monetized).
account	object	Contains information about the Incentify account this Utilization is attached to.
account.id	integer	The ID of the Incentify account that owns this Utilization.
account.title	string	The name of the Incentify account that owns this Utilization.
created_by	object	Contains information about the user that loaded this Utilization.
created_by.id	integer	The ID of the user that loaded this Utilization.
created_by.first_name	string	The first name of the user who loaded this Utilization.
created_by.last_name	string	The last name of the user who loaded this Utilization.
created_by.email	string	The email address of the user who loaded this Utilization.
project	object	Contains information about the Project this Utilization is attached to.
project.id	integer	The ID of the Project.
project.title	string	The name of the Project.
credit	object	Contains information about the Credit this Utilization is attached to.
credit.id	integer	The ID of the Credit.
local_currency	object	Contains information about the Local Currency.
local_currency.code	string	The local currency code (ie; USD, CAD, EUR, etc)
local_currency.name	string	The local currency name (ie; United States Dollar, etc)
local_currency.html_code	string	The local currency HTML Code.
local_currency.hex_code	string	The local currency Hex Code.
local_currency.unicode	string	The local currency Unicode.
estimate	object	Contains information about the estimated Utilization.
estimate.date	date	The estimated date of utilization. Format is yyy-mm-dd.
estimate.amount	object	Contains information about the estimated Utilization Amount.
estimate.amount.usd	object	Contains information about the estimated Utilization Amount in USD.
estimate.amount.usd.gross_total	float	The total estimated gross "face value" of the Utilization in USD.
estimate.amount.usd.exchange_rate	float	The estimated Exchange Rate of the Utilization.
estimate.amount.usd.discounted_value_as_percentage	float	The estimated percentage of the total amount discounted (ie; due to fees, discount on transferable credit sales, etc) of the Utilization.
estimate.amount.usd.discount_total	float	The estimated total amount discounted (ie; due to fees, discount on transferable credit sales, etc) of the Utilization in USD.
estimate.amount.usd.net_total	float	The estimated total net value of the Utilization in USD (Gross minus the total amount discounted) in USD.
estimate.local	object	Contains information about the estimated Utilization Amount in Local Currency.
estimate.local.gross_total	float	The total estimated gross "face value" of the Utilization in Local Currency.
actual	object	Contains information about the actual Utilization.
actual.date	date	The actual date of utilization. Format is yyy-mm-dd.
actual.amount	object	Contains information about the actual Utilization Amount.
actual.amount.usd	object	Contains information about the actual Utilization Amount in USD.
actual.amount.usd.gross_total	float	The total actual gross "face value" of the Utilization in USD.
actual.amount.usd.exchange_rate	float	The actual Exchange Rate of the Utilization.
actual.amount.usd.discounted_value_as_percentage	float	The actual percentage of the total amount discounted (ie; due to fees, discount on transferable credit sales, etc) of the Utilization.
actual.amount.usd.discount_total	float	The actual total amount discounted (ie; due to fees, discount on transferable credit sales, etc) of the Utilization in USD.
actual.amount.usd.net_total	float	The actual total net value of the Utilization in USD (Gross minus the total amount discounted) in USD.
actual.local	object	Contains information about the actual Utilization Amount in Local Currency.
actual.local.gross_total	float	The total actual gross "face value" of the Utilization in Local Currency.
current_percentage_of_credit_amount	integer	The percentage of the total credit amount a utilization amount represents.
variance.actual_to_estimate.base_amount	integer	Variance from the initial estimate in base/USD due to all adjustments to amount, exchange rate and discounts.
variance.actual_to_estimate.base_amount_percentage	integer	The variance expressed as a percentage of the "variance > actual_to_estimate > base_amount" compared to the current actual amount.
notes	string	General Utilization notes.
legal_entity	object	Contains information about the Legal Entity that is the "owner" of this Credit.
legal_entity.id	integer	The ID of the Legal Entity.
legal_entity.title	string	The company name of the Legal Entity.
site	object	Contains information about the Site (ie; location, such as a manufacturing facility) that this Credit is related to.
site.id	integer	The ID of the Site.
site.title	string	The name of the Site (ie; New York Headquarters, etc).
site.address	string	The street address of the Site.
site.gps_lng	float	The GPS longitude point.
site.gps_lat	float	The GPS latitude point.
custom_data_points[]	list	Contains a list of custom data points (ie; not system default fields). Therefore, the format of each is included in the data. "id" is the unique ID of the custom data point. "name" is the visual name of the field. "type" is the format (ie; string, date, etc). "value" is the value entered for that custom data point.