Utilization - Create / Update

Purpose

To insert or update a Utilization within a Credit which your API Credentials have access to.

Request

Endpoint

POST /utilization

Authentication

Include your API Key within the x-api-key header as described here.

Request Body Parameters

NOTE: The internal_utilization_id in the request is used to apply "upsert" logic - ie; if a matching record is found it will perform an update and if not it will perform an insert. Additionally, you must also supply the internal_credit_id as well (see below).

The following table lists the parameters supported in the JSON POST payload.

Required Request Parameters

* are required only on create.
** are required every request (both create and update), but the value is only set upon creation (ie; can not be changed).
*** are required only on create and can never be updated.
**** have custom/complex logic, which is defined as footnotes to the table below.
Marked with NO asterisk are optional parameters. If you do not include them in an update request then the current value will be preserved.

Parameter	Type	Definition
internal_utilization_id **	int	The unique ID of the Utilization from your internal system.
internal_credit_id **	int	The unique ID of the Credit from your internal system which you are attaching this Utilization to. Utilizations can NOT be moved between Credits once created.
type *	string	A "Snake Case" representation of one of the custom Utilization Type options from your Incentify account (ie; if the Utilization Type on Incentify is "Liability Offset", then submit "liability_offset"). Please check your Account Settings > Drop Down Customization to see the options for this value.
utilizing_enity	object	Contains information about the entity utilizing this credit.
utilizing_enity.type	string	Can either be `legal_entity` or `third_party_company`.
utilizing_enity.legal_entity	object	Contains information about the Legal Entity that is the "owner" of this Credit.
utilizing_enity.legal_entity.internal_legal_entity_id	string	The unique ID of the Legal Entity from your internal system.
utilizing_enity.legal_entity.title	string	The company name of the Legal Entity.
utilizing_enity.third_party_company.name	string	The company name of the third party entity (ie; a sale of a transferable)
estimate ****	object	Contains information about the estimated Utilization. (Please see advanced logic about this array below this table)
estimate.date	date	The estimated date of utilization. Format is yyy-mm-dd.
estimate.local	float	The total estimated gross "face value" of the Utilization in Local Currency.
estimate.discounted_rate	float	The discounted rate of the utilization (if any). For example, if this was a transferable and the estimated discount/sale rate was 0.92343.
actual ****	object	Contains information about the actual Utilization. (Please see advanced logic about this array below this table)
actual.date	date	The estimated date of utilization. Format is yyy-mm-dd.
actual.local	float	The total estimated gross "face value" of the Utilization in Local Currency.
actual.discounted_rate	float	The discounted rate of the utilization (if any). For example, if this was a transferable and the estimated discount/sale rate was 0.92343.
site	object	Contains information about the Site (ie; location, such as a manufacturing facility) that this Credit is related to.
site.internal_site_id	string	The unique ID of the Site from your internal system.
site.title	string	The name of the Site (ie; New York Headquarters, etc).
site.address	string	The street address of the Site.
notes	string	General Utilization notes.
custom_data_points	object	Object container for key/value pairs of custom data points.
custom_data_points.{incentify_cdp_key}	key/value (string/string)	The key (ie; `{incentify_cdp_key}`) is the unique identifier for the custom data point you are updating, which is obtained at the bottom of the Custom Data Point detail page in your Incentify Account. The value is a string format of the value you are setting. Please ensure the format of the string's value matches the expected format on Incentify. The formats expected are: (1) number (any integer, decimal, etc), (2) date (mm/dd/yyyy), (3) currency (integer with or without decimals but no other special characters like currency symbol or commas)

info

**** estimate and actual

Below is the custom/complex logic for estimate and actual utilization:

To create a utilization, you must include the estimate AND/OR the actual (ie; at least one).
To update a utilization, you may:
- Not include estimate and actual and both will not be modified
- Include one of them (ie; estimate or actual) and that one will be updated and the other will be removed
- Include both of them (ie; esimate and acutal) and both will be updated

info

Entity Access on the Utilization level has implicit rules due to the hierarchy of the Credit and Project. If a user has access to a Utilization's Project or Credit, then that user has implicit access to the Utilization.

For further information:

Request Body Example

{
    "internal_utilization_id": "u3443"
    "internal_credit_id": "c1342",
    "type": "liability_offset",
    "estimate": {
         "date": "2023-08-22",
         "local": 90000.00,
         "discounted_rate": 0.9234
    },
    "actual": {
         "date": "2023-09-01",
         "local": 80000.00,
         "discounted_rate": 1
    },
    "legal_entity": {
        "internal_legal_entity_id": "le13849",
        "title": "Big Entity, LLC"
    },   
    "site": {
        "internal_site_id": "s92323",
        "title": "El Segundo Factory",
        "address": "117 Sierra St, El Segundo CA 90245"
    },
    "notes": "Here is some text.",
    "custom_data_points": {
        "dp_key_3728372728323":"Management",
        "dp_key_9836483737322":"90000"
    }
}

Successful Response

If successful, this method returns an http code of 200 and response body with the following structure:

Response Body

{
    "code":200,
    "success":1,
    "data": {
        Utilization Resource here (See "Utilization - Overview" page)
    },
    "errors": [],
    "meta": {},
    "links": {}
}

Error Response

If the request has invalid fields/values, this method returns an http code of 400 and response body with the following structure:

Error Response Body

{
    "code":400,
    "success":false,
    "data": {},
    "errors": [
        "text describing error here"
    ],
    "meta": {},
    "links": {}
}

Properties

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

Key	Type	Definition
code	integer	HTTP Status Code (ie; 200, 403, etc).
success	integer	Either 1 (success) or 0 (fail).
data	object	Utilization updated is returned. The data structure of the Utilization is a Utilization Resource.
errors	object	If the request fails, this will contain information about the error.
meta	object	Contains information about pagination and total record count.
links	object	Contains pre-built links for forward/backward pagination.

Purpose​

Request​

Successful Response​

Error Response​

Purpose

Request

Successful Response

Error Response