Composite Endpoints

This composite endpoint simplifies the process of managing client, engagement, and document information. It abstracts away the complexities of handling Firm, Client, and Engagement identifiers, returning an upload URI for document routing.

Key Features:

Simplified Upsert: Upsert (update/insert) client, engagement, and document data.
Reduce Complexity: No need for the developer to manage or track multiple entities.
File Upload: Returns a URI for file upload and routing to the correct folder.

Request Body Structure

{
    "accountId": "OrganizationalUnitId",
    "Client": {...},     // Client Object            
    "engagement": {...}, // Engagement Object
    "fileTag": "Folder tag to route the document",
    "uploadFileRequest": {
        "name": "2022_12345678910_Deer, Mary Sue_PreparerCopyK1Package.txt",
        "replace": 0,  // Replace options {0, 1, 2}
        "description": "Preparer Copy - Printed by My Awesome apps!!"
    },
    "uploadVersionData": {
        "length": 1405,  // Length of the file in bytes
        "md5_checksum": "D/pj1png88JDuzHAZ8xoEA==" // Base64 endcoded string
    }
}

Why use this endpoint?

This composite endpoint allows developers to quickly create needed entities for proper file routing without the need to manage clients, engagements, and documents separately, enabling faster integration.

Upserting a Client

At the core of SmartVault is the client entity. Each client has an associated vault where their folders and files are stored. Before routing any document, ensure the client is created and mapped to your application’s client.

In order to properly map a SmartVault client to your application, you must have an identifier and provide that as an Alias when creating the client.
A SmartVault client should map one-to-one with a client in your application.

Example: Client Alias
These properties are defined by your application and must be unique for each client.

{
    "Domain": "awesome-app.com",  // Alphanumerical
    "Type": "identifier",         // Alphanumerical
    "Value": "12345678911"        // Alphanumerical
}

Client Types

SmartVault supports two main types of clients:

1. Organization
2. Persons
Each type has subtypes. For more details, refer to the SmartVault Client API documentation.

Example: Individual Client

{
    "persons": [{
        "names": [{
            "FirstName": "Mary",
            "MiddleName": "Sue",
            "LastName": "Deer"
        }],
        "phone_numbers": [{
            "Number": "123-456-7890"
        }],
        "email_addresses": [{
            "address": "mDeer1@email.com"
        }]
    }],
    "aliases": [{
        "Domain": "awesome-app.com",
        "Type": "identifier",
        "Value": "12345678910"
    }],
    "type_qualifier": "Individual"
}

Example: Corporate Client

{
    "organization": {
        "names": [{
            "name": "Tax Man LLC"
        }],
        "email_addresses": [{
            "address": "taxmanllc@taxman.com"
        }],
        "phone_numbers": [{
            "Number": "+1123456789"
        }]
    },
    "aliases": [{
        "Domain": "awesome-app.com",
        "Type": "identifier",
        "Value": "9873902-Ajdl-21898"
    }],
    "end_of_fiscal_year": 12,
    "type_qualifier": "Corporate"
}

For more information on client creation, please review the full documentation here.

The Engagement Object

The Engagement Object is used to create the folder structure for a file. It performs an upsert operation, creating the engagement if it doesn’t already exist.

Example: Engagement Object

{
    "entity": {
        "meta_data": {
            "entity_definition": "The engagement type"
        },
        "smart_vault": {
            "accounting": {
                "engagement": {
                    "period": "The year/month/period for this engagement."
                }
            }
        }
    }
}

For default values of structured accounts, refer to the Engagement Types documentation.

File Tags

File tags are used to route documents to the appropriate folder within SmartVault.

Tags can be added or removed, and if a tag is not found, the document is uploaded to the "miscellaneous" folder. If the miscellaneous folder does not exist, the file will not be routed, and an error will be returned. Ensure your application can handle this scenario.

Tax Returnspreparerfilecopy.taxreturn.tags.accounting.smartvault.com

Tax Returnspreparerreviewcopy.taxreturn.tags.accounting.smartvault.com

Miscellaneousmisc.tags.core.smartvault.com

Tax Returnscomplete.taxreturn.tags.accounting.smartvault.com

File Objects

The SmartVault system utilizes File and Version objects for document uploads. Below are the necessary attributes:

Example: File and Version Object

"uploadFileRequest": {
    "name": "test_file_name.txt",
    "replace": 1  // 0=Fail, 1=Replace, 2=Autocorrect
},
"uploadVersionData": {
    "length": 1405,
    "md5_checksum": "D/pj1png88JDuzHAZ8xoEA=="
}

Fail = 0Throws FileAlreadyExistsException, prompts the user to choose another name.

Replace = 1Replaces the existing file with the new file; name remains unchanged.

Autocorrect = 2Appends (1) to the file name if a file with the same name exists.

Engagement-document

Construct the Client object that the document belongs to. Client should map one-to-one with an identity on your application.

POST/nodes/engagement-document

Show Body Parameters

Example: Engagement document

{
    "accountId": "{{smartvault_account_id}}",
    "client": {
        "persons": [{
            "names": [{
                "FirstName": "Mary",
                "MiddleName": "Sue",
                "LastName": "Deer"
            }],
            "phone_numbers": [{
                "Number": "123-456-7890"
            }],
            "email_addresses": [{
                "address": "mDeer1@email.com"
            }]
        }],
        "aliases": [{
            "Domain": "awesome-app.com",
            "Type": "identifier",
            "Value": "12345678910"
        }],
        "type_qualifier": "Individual"
    },
    "engagement": {
        "entity": {
            "meta_data": {
                "entity_definition": "SmartVault.Accounting.TaxEngagement"
            },
            "smart_vault": {
                "accounting": {
                    "engagement": {
                        "period": "2024"
                    }
                }
            }
        }
    },
    "fileTag": "preparerfilecopy.taxreturn.tags.accounting.smartvault.com",
    "uploadFileRequest": {
        "name": "2022_12345678910_Deer, Mary Sue_PreparerCopyK1Package.txt",
        "replace": 1, 
        "description": "Preparer Copy - Printed by My Awesome apps!!"
    },
    "uploadVersionData":{
        "length": 1405,
        "md5_checksum": "D-pj1png88JDuzHAZ8xoEA=="
    }
}

SmartVault

Composite Endpoints

.css-1r0pe6c{color:inherit;-webkit-text-decoration:none;text-decoration:none;}.css-1r0pe6c:hover{-webkit-text-decoration:underline;text-decoration:underline;}Document Routing

Show Body Parameters

Document Routing