Document - Create

Purpose

To insert a Document attached to an Activity, Account, Project, or Credit which your API Credentials have access to. Update is not possible here, Documents are immutable, once created they can only be deleted.

Request

Endpoint

POST /document

Authentication

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

Request Body Parameters

IMPORTANT: Both the internal_document_id AND internal_account_id are required in the request to create a Document - the endpoint will validate that these values MATCH those of the upload record to ensure there is no accidental cross account contamination (ie; assuring documents go to the CORRECT account and not that of another customer).

NOTE: A Document can NOT be updated (only created or deleted). Therefore, if a Document originated from the Incentify system, then you will need to ingest that Document from Incentify into your internal system and then set the new internal_document_id back onto the Document on Incentify for future mapping/reference. This is done via the Delta - Consumed & Mapped Endpoint. We recommend reading this guide to understand the logic/flow for doing this: Guide - Syncing Changed Resources.

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

Required Request Parameters

• * are required only on create.
• ** 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_account_id **	string	The ID of the Account on your internal system.
internal_document_id **	string	The ID of the Document on your internal system.
attached_to_type **	ENUM("project","account","credit", "activity")	The object type this document is attached to.
attached_to_internal_id **	string	The ID of the Object this document is attached to on your internal system.
upload.id **	string	The unique ID for the upload which was provided in the response to POST on /upload.
upload.filename **	string	The filename of the uploaded document.
upload.size **	string	size and scale of document upload (eg: 2.5MB)
upload.extension **	ENUM("pdf", "docx", "xlsx", "csv", ...)	the file extension of document upload
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.
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 Document on the Incentify system.

Request Body Example

{
    "internal_account_id": "XXXXX3",
    "internal_document_id": "d23223",
    "attached_to_type":"activity",
    "attached_to_internal_id": "a342534",
    "upload": {
        "id": "f3405384a42123c09290681835f0ef29",
        "filename": "Super_Ipmortant_Critical_Tax_Information",
        "size": "2.45 MB",
        "extension": "pdf"
    },
    "created_by": {
        "email": "[email protected]",
        "full_name": "John Doe"
    }
}

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": {
        Docuemnt Resource here (See "Docuemnt - 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	Document updated is returned. The data structure of the Document is a Document Resource.
errors	object	If the request fails, this will contain information about the error.