Project - Create / Update

Purpose

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

Request

Endpoint

POST /project

Authentication

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

Request Body Parameters

NOTE: The internal_project_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_project_id **	string	The unique ID of the Project from your internal system. Needed to perform "upsert" logic, described above.
internal_account_id **	string	Required only if your Incentify account is a parent/child account configuration. NOTE: You can NOT create a project inside of your Parent Account - you can only create them inside a Child Account.
title *	string	The name of the project. Limit XXX characters.
access_policy *	enum	Can be one of the following values: (1) `private`, (2) `all_internal` or (3) `all_users`. Learn about Access Policies
status *	string	A "Snake Case" representation of one of the custom Project 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.
description	string	The name of the project. Limit XXX characters.
date_project_start	date	Date the project will/did start. The date format is yyyy-mm-dd.
date_project_end	date	Date the project will/did end. The date format is yyyy-mm-dd.
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 project. (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[].is_assigned	boolean	Set to "true" if this User is one of the primary leads of this Project (this person is highlighted as a Project "lead" in the User Interface).

entity_access ****

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

If the scope of a project's access_policy includes a specific user (ie; the access_policy is "all_internal_users" and the specific user is an "internal user"), then that user automatically has access to the project so there is no need to set that user in entity_access. However, in this scenario, you WOULD need to set the user in this array IF you are specifiying that this user should either (1) have "read only" access to the project or (2) be assigned to the project.
If the project's access_policy does NOT include a specific user (ie; in the example above, it is an "external user"), then that specific user MUST be included in the entity_access array in order to gain access to the project. In addition, you can optionally supply values for both "read only" and "assigned to" accordingly as described above.
When updating a project if you no longer include a user in the entity_access array, then that user will no longer have access to the project (ie; be removed).
If you change a project's access_policy to increase the access scope and thereby now include a specific user who previously required an entity_access record, then that user's entity_access will be deleted as the user's access is now already considered as part of the project's access_policy.

For further information:

Request Body Example

{
    "internal_account_id":"child_account_1893",
    "internal_project_id":"project_1234",
    "title":"Big Development Project",
    "access_policy":"all_internal",
    "status":"in_progress",
    "description":"Sample description goes here",
    "date_project_start":"2024-01-21",
    "date_project_end":"2025-08-15",
    "custom_data_points": {
        "dp_key_3728372728323":"Management",
        "dp_key_9836483737322":"90000"
    },
    "entity_access": [
        {
            "internal_user_id":"XXXXXXX-XXX-XXXXXXXX1",
            "read_only":false,
            "is_assigned":true
        },
        {
            "internal_user_id":"XXXXXXX-XXX-XXXXXXXX2",
            "read_only":false,
            "is_assigned":true
        }
    ]
}

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": {
        Project Resource here (See "Project - 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	Project updated is returned. The data structure of the Project is a Project 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