Engagements
SmartVault's API allows the creation of engagements as entities with a specific template or without them, related to a certain client and the ability to modify those engagements individually at any time.
You can also add engagements as a bulk.
Engagement types
Below you can find a table with the equivalences for the engagement type and its name for the SmartVault API parameter.
This will be useful for adding / updating engagements.
Create an engagement
The account id, the client id where the engagement is going to be created and the engagement type are the path parameter for this request. Depending of the type of engagement that you are going to add to the client, you'll need to specify one type or another in the request path.
Parameters
account_idstringThe account's alphanumerical identification.client_idstringAlphabetic representation of the client ID on which the engagement will be created.engagement_typestringSmartVault equivalent name for the engagement type.Find more info on how to retrieve the account's id here.
Find the value needed for the "engagement_type" in the engagement types table here.
So if you wanted to add a certain engagement of "Payroll" type, the request path should look like:
/nodes/entity/SmartVault.Accounting.Firm/{ account_id }/SmartVault.Accounting.FirmClient/{ client_id }/SmartVault.Accounting.ClientPayrollEngagement;
Body parameters
For every new engagement added, you'll need to specify at least both the "engagement_type" specified above and the "entity_definition" in the request body.
Show body parameters
Request
Example of a request to add a new engagement to a client.
Show example request
Response
Returns a node response object with the newly added engagement.
Show success object
Returns an error object if the "engagement_type" defined in the request path and the "entity_definition" body parameter doesn't match.
Show error object
Returns an error object if the entity type defined in the request path already exists. Remember only one engagement of each type is allowed for each client.
Show error object
Create an engagement with a specific template
The main usage difference between adding an engagement and a template specific engagement is that when you create an engagement it uses a set of rules to determine which template is selected. Where a specific template differs in that it does not follow the rule set and you are picking which template exactly to use.
For this request, unlike the previous one, specifying the required parameters (account ID and client ID) must be done in the body of the request.
Body parameters
account_idstring (required)The account's alphanumerical identification.client_idstring (required)The client's alphanumerical identification.template_api_namestring (required)The name of the template being used to create the engagement.
The engagement type is automatically obtained based on this value.yearstring (optional)The client's alphanumerical identification. Not applicable if the engagement type is "Project"project_namestring (required if Project type)When adding "Project" type engagements there's an extra required parameter called "project_name" that you need to specify.Check here for more information on how to get all the values available for the "template_api_name" field.
Request
Show request example
Response
Returns a node response object pointing to the newly created engagement.
Show success object
Create an Engagement and a corresponding document upload folder
SmartVault allows the creation of an engagement and a document upload container in a single request. This is useful for when you have a document that needs to be uploaded to a given client's engagement, however the engagement may or may not yet exist.
The request will create the Engagement if it does not already exists, the upload folder for the document, and a document object placeholder. The response will return an upload URI which is used for subsequent calls to upload document bytes for the aforementioned document placeholder.
Body parameters
Show body parameters
Request
Example of a request to add a new engagement to a client.
Show example request
Response
Returns a node response object that points to where the bytes of the new document will be uploaded.
Show success object
Returns an error object if any of the required keys are missing.
Show error object
Returns an error object if account or client is not found.
Show error object
Returns an error object for an incorrect engagement.entity.meta_data.entity_definition body parameter.
Show error object
Returns an error object when the uploadFileRequest.name already exists.
Show error object
Create an engagement for all clients
SmartVault allows the creation of a engagement for every client in an account in a single request.
Parameters
account_idstringThe account's alphanumerical identification.Body parameters
The bulk engagement creation has 4 different parameters related to the engagements being added.
You'll need to specify at least both the "Type" (and the "Year" if it's not a "Project" engagement).
This "Type" value is a required string that needs to be the same value as the "entity_definition" body param while adding an individual engagement.
Request
Example of a request to add a new engagement to a client.
Show example request
Response
Returns a node response object that points to the account root where the engagement has been added.
Show success object
Returns an error object if any of the required keys are missing.
Show error object
Edit an engagement
SmartVault allows the modification of certain engagement parameters.
Parameters
account_idstringThe account's alphanumerical identification.client_idstringAlphanumeric representation of the client ID on which the engagement will be created.engagement_idstringAlphanumeric string that represents the engagement to be modified.Body parameters
Show body parameters
Example of a request to edit an engagement.
Show body request
Response
Returns a node response object of the engagement edited.
Show success object
Returns an error object if any of the required params are missing.