Credit - Create / Update

Purpose

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

Request

Endpoint

POST /credit

Authentication

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

Request Body Parameters

NOTE: The internal_credit_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.

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_credit_id **	int	The unique ID of the Credit from your internal system. Recommended to perform "upsert" logic, described above.
internal_project_id **	int	The unique ID of the Project from your internal system which you are attaching this Credit to. Credits can NOT be moved between Projects once created.
status *	string	A "Snake Case" representation of one of the custom Credit Status options from your Incentify account (ie; if the Status on Incentify is "In Progress", then submit "in_progress"). The default statuses are as follows: "Planning", "In Progress", "Completed", "Abandoned" and "Archived". Please check your Account if your team has customized the default options with a new set of options.
incentive_program ****	object	Contains data related to the incentive program this credit relates to.
incentive_program.id	string	ID of the incentive program on the Incentify database.
incentive_program.internal_incentive_program_id	string	ID of the incentive program in your database.
incentive_program.jurisdiction_full_name	string	Supply the full name of the jurisdiction that offers this Incentive Program in a "standard" string format (examples: United States, California - or - Nevada, USA - or - Los Angeles County, California).
incentive_program.name	string	The name of the incentive program in your database.
incentive_program.description	string	The description of the incentive program in your database. Max length 3,000 characters.
incentive_program.amount	string	[optional] The general amount/calculation this incentive program is worth from your database. Max length 3,000 characters.
incentive_settings	object	Contains selections related to the Incentive Program specific only for this Credit.
incentive_settings.type	string	A "Snake Case" representation of one of the custom Incentive Type options from your Incentify account (ie; if the Incentive Type on Incentify is "State Refundable Credit", then submit "state_refundable_credit"). The default statuses are as follows: "US Federal Credit", "US Federal Allocated Credit", "US Federal Grant", "US Federal Negotiated Incentive", "State Tax Credit", "State Allocated Credit", "State Cash Grant", "State Transferable Credit", "State Rebate", "State Refundable Credit", "State Negotiated Incentive", "State Tax Abatement", "Municipal Tax Credit", "International Tax Credit", "International Refundable Credit", "International Transferable Credit", "International Rebate", "International Cash Grant", "International Negotiated Incentive" and "Bond Guarantee". Please check your Account if your team has customized the default options with a new set of options.
incentive_settings.carry_forward_years	integer	The number of year the program can be carried forward.
incentive_settings.legislative_framework	enum	The type of the program framework - potential values are statutory, discretionary and negotiated.
jurisdiction_full_name	string	Supply the full name of the jurisdiction (ie; United States, California - or - Nevada, USA - or - Los Angeles, California).
amount	object	Contains information about the Credit Amount.
amount.local	float	The Credit Amount in Local Currency (ie; 100000.50)
amount.status	string	Can be either estimated or final.
amount.discounted_rate	float	The discounted rate of the credit (if any). For example, if this was a transferrable and the estimated discount/sale rate was 0.92343.
vintage_tax_year	integer	The first usable tax year of the Credit.
legal_entity	object	Contains information about the Legal Entity that is the "owner" of this Credit.
legal_entity.internal_legal_entity_id	string	The unique ID of the Legal Entity from your internal system.
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.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_general	string	General credit notes.
group_name	string	Group name of credit - nothing more than a "tag" for grouping Credits.
date_certification_initial	date	Initial certification date. Format is yyyy-mm-dd.
date_certification_final_estimated	date	Estimated final certification date. Format is yyyy-mm-dd.
date_certification_final_actual	date	Actual final certification date. Format is yyyy-mm-dd.
date_activity_start	date	The date the Credit activity will/did start. Format is yyyy-mm-dd.
date_activity_end	date	The date the Credit activity will/did end. Format is yyyy-mm-dd.
date_audit_start	date	The date the Credit audit will/did start. Format is yyyy-mm-dd.
date_audit_end	date	The date the Credit audit will/did end. Format is yyyy-mm-dd.
status_certification	string	A "Snake Case" representation of one of the custom Certification Status options from your Incentify account (ie; if the Status on Incentify is "Final certification issued", then submit "final_certification_issued"). The default statuses are as follows: "Initial planning/under consideration", "Initial application being compiled", "Initial application submitted to jurisdiction", "Terms being discussed with jurisdiction", "Initial application approved by jurisdiction", "In receipt of agreement from jurisdiction", "Agreement with jurisdiction signed", "Final application being compiled", "Final application submitted to jurisdiction", "Final application in review with jurisdiction", "Final certification issued" and "Final certificate received". Please check your Account if your team has customized the default options with a new set of options.
status_monetization	string	A "Snake Case" representation of one of the custom Monetization Status options from your Incentify account (ie; if the Status on Incentify is "In Progress", then submit "in_progress"). The default statuses are as follows: "Open", "Awaiting", "In Progress" and "Closed". Please check your Account if your team has customized the default options with a new set of options.
status_audit	string	A "Snake Case" representation of one of the custom Monetization Status options from your Incentify account (ie; if the Status on Incentify is "In Progress", then submit "in_progress"). The default statuses are as follows: "Audit phase not begun", "Pre-audit in process", "Audit in process", "Auditor drafting report", "Draft audit report received/in review" and "Final report issued/audit complete". Please check your Account if your team has customized the default options with a new set of options.
status_notes	string	Notes specific to the overall status of the Credit.
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)
entity_access ****	array	Array container of one or more Entity Access definitions (ie; user-level access/level) to this credit. (Please see advanced logic about this array below this table)
entity_access[].internal_user_id	string	The unique ID of of the User from your Internal System. NOTE: This user must already exist in the Incentify database - see User - Create/Update.
entity_access[].read_only	boolean	Set to "true" if this User's Permission Group actions should be ignored (ie; view/access only).

entity_access ****

Below is the custom/complex logic for entity_access on Credits:

• Only set Entity Access on the Credit if a User does NOT have access to the Project (ie; users with Project access already have access to all credits within that Project)
• This is a mechanism for adding a user to a specific Credit who does NOT have access at the Project level

For further information:

• Entity Access
• Access Policies

incentive_program ****

If you are linking this Credit to an Incentive Program that exists in the official Incentify Database, then you ONLY need to supply id in this object. You can choose to include the other parameters in the request but they will be ignored.

If you are linking this Credit an Incentive Program that does NOT exist in the official Incentify Database (ie; a custom/discretionary program or a statutory program that Incentify does not have), then you need to leave id out of the request (or NULL) and include the following parameters:

• internal_incentive_program_id (REQUIRED on create and update)
• jurisdiction_full_name (REQUIRED on create and update)
• name (REQUIRED on create and update)
• description (REQUIRED on create and update)
• amount (OPTIONAL on create and update)

Request Body Example

{
    "internal_credit_id": "p23223",
    "internal_project_id": "p99323",
    "status": "in_progress",
    "incentive_program": {
        "id": NULL,
        "internal_incentive_program_id": "my_program_id",
        "jurisdiction_full_name": "California, United States",
        "name": "New Jobs Tax Credit",
        "description": "This is a program designed to stimulate small businesses...",
        "amount": "This program is worth up to $10,000 per employee that..."
    },
    "incentive_settings": {
        "type": "state_refundable_credit",
        "carry_forward_years": 4,
        "legislative_framework": "statutory"   
    },  
    "jurisdiction_full_name": "Los Angeles, California",
    "amount": {
       "local": 50000.00,
       "status": "estimated",
       "discounted_rate": 1
    },
    "vintage_tax_year": integer,
    "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_general": "Here is some text about this credit.",
    "group_name": "Season 15",
    "date_certification_initial": "2024-01-15",
    "date_certification_final_estimated": "2024-01-15",
    "date_certification_final_actual": "2024-01-15",
    "date_activity_start": "2024-01-15",
    "date_activity_end": "2024-01-15",
    "date_audit_start": "2024-01-15",
    "date_audit_end": "2024-01-15",
    "date_credit_expiration_date": "2024-01-15",
    "status_certification": "final_certification_issued",
    "status_monetization": "in_progress",
    "status_audit": "audit_phase_not_begun",
    "status_notes": "Here is some text about the current status of the credit",
    "custom_data_points": {
        "dp_key_3728372728323":"Management",
        "dp_key_9836483737322":"90000"
    },
    "entity_access": [
        {
            "internal_user_id":"XXXXXXX-XXX-XXXXXXXX1",
            "read_only":false
        },
        {
            "internal_user_id":"XXXXXXX-XXX-XXXXXXXX2",
            "read_only":false
        }
    ]
}

Successful Response

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

Response Body

{
    "code":200,
    "success":true,
    "data": {
        Credit Resource here (See "Credit - 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	boolean	Either true (success) or false (fail).
data	object	Credit updated is returned. The data structure of the Credit is a Credit 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.