Activity - Create / Update

Purpose

To insert or update an Activity attached to an Account, Project, or Credit which your API Credentials have access to.

Request

Endpoint

POST /activity

Authentication

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

Request Body Parameters

NOTE: The internal_activty_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.
• 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_activity_id **	string	The unique ID of the Activity from your internal system. Recommended to perform "upsert" logic, described above.
internal_account_id **	string	The unique ID of the Account from your internal system.
attached_to_type ***	ENUM("project","account","credit")	The resource type which this activity is attached to.
attached_to_internal_id ***	string	The ID of the resource that this activity is attached to on your internal system
type ***	ENUM("note","document","action_item")	The Activity type, which informs the user what type of Activity it is (but there is no enforced business logic for different types).
status *	ENUM("draft","open","reviewed","completed","canceled")	The Activity status. Activity in a "draft" status is not visible to any users and does not trigger any notifications.
subject *	string	The Activity title.
description	string	The Activty description.
due_date	string	String representation of a date (format: "yyyy-mm-dd") when this activity is due.
assigned_users	[string, string, string...]	A list of internal user ids of size 0 to n which are assigned to this activity.
created_by.email ***	string	The email of the user on your internal system.
created_by.full_name ***	string	The full name of the user on your internal system, or within Incentify.
completable_by	ENUM("both","us","them")	Which party can set status of an Activity to "completed". Options are: (1) us - your internal system (ie; API calls only). (2) them - the set of users who are assigned to the Activity. (3) both - "us" and "them"
created_at	string	The date and time that the User was created. The value is specified in RFC 3339 Format (2022-05-03T17:13:44Z).
updated_at	string	The date and time that the User was last updated. The value is specified in RFC 3339 Format (2022-05-03T17:13:44Z).
id	integer	The ID of the Activity on the Incentify system.

Request Body Example

{
    "internal_activity_id": "p23223",
    "internal_account_id": "XXXXX3",
    "attached_to_type": "project",
    "attached_to_internal_id": "p99323",
    "subject": "Submit Form 38D",
    "description": "This must be submitted by October 15th in order to apply for the program.",
    "type": "action_item",
    "status": "draft",
    "due_date": "2024-12-30",
    "assigned_users": [
        "XXXXXXXa1",
        "XXXXXXXa2",
        "XXXXXXXa3"
    ],
    "created_by": {
        "email": "[email protected]",
        "full_name": "John Doe"
    },
    "completable_by": "both"
}

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": {
        Activity Resource here (See "Activity - Overview" page)
    },
    "errors": []
}

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"
    ]
}

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	Activity updated is returned. The data structure of the Activity is a Activity Resource.
errors	object	If the request fails, this will contain information about the error.