Forms Vault API

Description:

This API is designed to work with Quik! App customers who wish to receive submitted forms in order to process, validate, store and/or receive the data directly from forms. The Quik! App user will initiate a form submit event (there are a few ways this can happen) which will send the form data back to the Quik! App and store it in the Forms Vault. The Forms Vault API will allow a 3rd party (i.e. your system) to authenticate and retrieve detail form data records for Quik! App customer accounts that are associated to the API requestor.

Base endpoints routes:

api.auth.url: https://devwebsvcs.quikforms.com/rest_authentication
api.vault.url: https://devwebsvcs.quikforms.com/rest/quikvault/v1000

Endpoints:

Authentication:

In order to make any request to the Vault API the customer must be authenticated by obtaining a token from the following URL.

The body of the request must have the following parameters:

Parameters
grant_type	REQUIRED - always with the value password.
user_name	REQUIRED - the user name of the customer to be authenticated.
password	REQUIRED - password of the user.

Request:

POST {{api.auth.url}}/token

Body:

grant_type=password&username=usernameexample&password=mypassword

Response:

{
    "access_token": "eydhbGciOiJSUzI1NiIsImtpZCI6fjBBREM5MTQ5RDFGM0M1MDgzRDFCRDM1hTFGRtU4NTQ0NkJBNkEwQzhSUzI1NiIsInR5cCI6IkpXVCIsIng1dCI6IkN0eVJTZEh6eFFnOUc5TlJIOTZGUkd1bW9NZyJ9.eyJuYmYiOjE2Mzc2MDg4MjMsImV4cCI6MTYzNzYxMjQyMywiaXNzIjoiaHR0cHM6Ly9kZXZ3ZWJzdmNzLnF1aWtmb3Jtcy5jb20vcmVzdF9hdXRoZW50aWNhdGlvbiIsImF1ZCI6Imh0dHBzOi8vZGV2d2Vic3Zjcy5xdWlrZm9ybXMuY29tL3Jlc3RfYXV0aGVudGljYXRpb24vcmVzb3VyY2VzIiwiY2xpZW50X2lkIjoicmVzb3VyY2Vvd25lcmNsaWVudCIsIkN1c3RvbWVySWQiOiIxMDAwMTEyNiIsIlVzZXJJZCI6IjEyMzcxNDM2IiwiUm9sZUlkIjoiMTIzNzE0MzYiLCJNYXN0ZXJVc2VySWQiOiIxMjM3MTQzNiIsInN1YiI6IjEyMzcxNDM2IiwiYXV0aF90aW1lIjoxNjM3NjA4ODIzLCJpZHAiOiJsb2NhbCIsImp0aSI6IjZBQjA5RUNGRDNBQ0Q1MjgzRkQ0QUU4QzYyNjRDM0QyIiwiaWF0IjoxNjM3NjA4ODIzLCJzY29wZSI6WyJvcGVuaWQiLCJwcm9maWxlIiwib2ZmbGluZV9hY2Nlc3MiXSwiYW1yIjpbInB3ZCJdfQ.ikkWOyAzF8797YDkjWZPVUz86leiWAtHL31rCoSquZlKkelgG0QaYzH7MmpbGhn0ZN6mQ4YrFcppp9n5Q55-6hd26U8dtEmeItl6Huj6fb_gHr8rBJ2L5Ur_HeSmGksJQf4wS6k5o-88p-LNjfNV2yXLwizp3yhS_qmkor-yKOdI7wuNeC4-hBA-sHjm3ReJTMhyW70nSytF3QUJVYVenaRIdhH5PXSI59PdF7bcmxEY4ZvH0Vfai2lPawXhRP94n9hVmDP_S4k30BjieUpYqviTs-hEBgRzruFROhRK3LIisKid0ibp5IZXnR4USyOF_yJYh_k3HUppDfUnzqULdq",
    "expires_in": 3600,
    "token_type": "Bearer",
    "refresh_token": "3211EE43F6067A6F3A2A4DC815D4F8B5EDCB315801213BDFF0C08CFF1F5306B2",
    "scope": "offline_access openid profile"
}

Every request should have an Authorization header with the access token, for example:

Authorization: Bearer eydhbGciOiJSUzI1NiIsImtpZCI6fjBBREM5MTQ5RDFGM0M1MDgzRDFCRDM1hTFGRtU4NTQ0NkJBNkEwQzhSUzI1NiIsInR5cCI6IkpXVCIsIng1dCI6IkN0eVJTZEh6eFFnOUc5TlJIOTZGUkd1bW9NZyJ9.eyJuYmYiOjE2Mzc2MDg4MjMsImV4cCI6MTYzNzYxMjQyMywiaXNzIjoiaHR0cHM6Ly9kZXZ3ZWJzdmNzLnF1aWtmb3Jtcy5jb20vcmVzdF9hdXRoZW50aWNhdGlvbiIsImF1ZCI6Imh0dHBzOi8vZGV2d2Vic3Zjcy5xdWlrZm9ybXMuY29tL3Jlc3RfYXV0aGVudGljYXRpb24vcmVzb3VyY2VzIiwiY2xpZW50X2lkIjoicmVzb3VyY2Vvd25lcmNsaWVudCIsIkN1c3RvbWVySWQiOiIxMDAwMTEyNiIsIlVzZXJJZCI6IjEyMzcxNDM2IiwiUm9sZUlkIjoiMTIzNzE0MzYiLCJNYXN0ZXJVc2VySWQiOiIxMjM3MTQzNiIsInN1YiI6IjEyMzcxNDM2IiwiYXV0aF90aW1lIjoxNjM3NjA4ODIzLCJpZHAiOiJsb2NhbCIsImp0aSI6IjZBQjA5RUNGRDNBQ0Q1MjgzRkQ0QUU4QzYyNjRDM0QyIiwiaWF0IjoxNjM3NjA4ODIzLCJzY29wZSI6WyJvcGVuaWQiLCJwcm9maWxlIiwib2ZmbGluZV9hY2Nlc3MiXSwiYW1yIjpbInB3ZCJdfQ.ikkWOyAzF8797YDkjWZPVUz86leiWAtHL31rCoSquZlKkelgG0QaYzH7MmpbGhn0ZN6mQ4YrFcppp9n5Q55-6hd26U8dtEmeItl6Huj6fb_gHr8rBJ2L5Ur_HeSmGksJQf4wS6k5o-88p-LNjfNV2yXLwizp3yhS_qmkor-yKOdI7wuNeC4-hBA-sHjm3ReJTMhyW70nSytF3QUJVYVenaRIdhH5PXSI59PdF7bcmxEY4ZvH0Vfai2lPawXhRP94n9hVmDP_S4k30BjieUpYqviTs-hEBgRzruFROhRK3LIisKid0ibp5IZXnR4USyOF_yJYh_k3HUppDfUnzqULdq

FormRecordList

Returns a list of forms from the vault that match with the parameters. List of CustomerIDs must be related to the authenticated customer account as a child account.

Route: {{api.vault.url}}/api/formpackages

HTTP Verb: GET

Parameters	Description
CustomerIDList	OPTIONAL - List of CustomerIDs, if null returns all child CustomerIDs
SubmitStatusID	OPTIONAL - If null return all statuses (customer should use 5 to get newly submitted forms (“Submitted by Owner”), other accepted values include: 6 (Processed by 3rd Party), 8 (Complete), 9 (Archived), 10 (Deleted))
FormViewRequestUNID	OPTIONAL - This is a unique identifier for FormViewRequest
FormPackageStatusID	OPTIONAL - The valid value for this parameter are 1 (Pending), 2 (Active), 3 (Inactive), 4 (Delete), 5 (Saved). Other values will return no results.
FormPackageTypeID	OPTIONAL - The valid value for this parameter are 1 (Saved Form Package), 2 (Submitted Form Package), 3 (Client Intake Form). Other values will return no results.
DateCreatedStart	OPTIONAL - Beginning of date created range
DateCreatedEnd	OPTIONAL - End of date created range
DateCompletedStart	OPTIONAL - Beginning of date completed range
DateCompletedEnd	OPTIONAL - End of date completed range

Examples:

200 OK - Filter by CustomerID list (autenticated with their parent CustomerId)

Request:

GET {{api.vault.url}}/api/formpackages?CustomerIdList=100100001&CustomerIdList=10010002

Response:

{
    "ResultData": [
        {
            "FormPackageID": 3888533,
            "CustomerID": 10010001,
            "FormViewRequestID": 72275437,
            "FormPackageStatusID": 2,
            "FormPackageTypeID": 2,
            "SubmitStatusID": 6,
            "FormPackageName": "Test de Request",
            "DateCreated": "2021-11-10T16:20:06.097",
            "DateCompleted": null,
            "DateToDelete": null,
            "FormIds": [
                216
            ],
            "FormPackageType": "Submitted Form Package",
            "SubmitStatus": "Processed by 3rd Party",
            "FormViewRequestUNID": "06be473f-999b-4bd9-9f6a-6f2e83081128",
            "FormPackageStatus": "Active",
            "EnvelopeID": null,
            "EnvelopeStatus": null,
            "EnvelopeDateSent": null
        },
        {
            "FormPackageID": 3888534,
            "CustomerID": 10010001,
            "FormViewRequestID": 72275438,
            "FormPackageStatusID": 2,
            "FormPackageTypeID": 2,
            "SubmitStatusID": 6,
            "FormPackageName": "Test de Request",
            "DateCreated": "2021-11-10T16:41:05.937",
            "DateCompleted": null,
            "DateToDelete": null,
            "FormIds": [
                217
            ],
            "FormPackageType": "Submitted Form Package",
            "SubmitStatus": "Processed by 3rd Party",
            "FormViewRequestUNID": "bc492bae-dde0-4f82-8b22-6c91b8350597",
            "FormPackageStatus": "Active",
            "EnvelopeID": null,
            "EnvelopeStatus": null,
            "EnvelopeDateSent": null
        },
        {
            "FormPackageID": 3888537,
            "CustomerID": 10010002,
            "FormViewRequestID": 72275454,
            "FormPackageStatusID": 2,
            "FormPackageTypeID": 2,
            "SubmitStatusID": 6,
            "FormPackageName": "Test de Request",
            "DateCreated": "2021-11-10T22:32:03.397",
            "DateCompleted": null,
            "DateToDelete": null,
            "FormIds": [
                220
            ],
            "FormPackageType": "Submitted Form Package",
            "SubmitStatus": "Processed by 3rd Party",
            "FormViewRequestUNID": "ae605d7f-6fb9-47d9-8e6b-44ea8d4d76e8",
            "FormPackageStatus": "Active",
            "EnvelopeID": null,
            "EnvelopeStatus": null,
            "EnvelopeDateSent": null
        }
    ],
    "ErrorCode": 0,
    "Message": "Getting data has been successful",
    "Errors": null
}

200 OK - Filter by range of dates (autenticated with their parent CustomerId)

Request:

GET {{api.vault.url}}/api/formpackages?DateCreatedStart=2020-11-11T14:49:20.523&DateCreatedEnd=2021-11-17T14:49:20.523

Response:

{
    "ResultData": [
        {
            "FormPackageID": 3888533,
            "CustomerID": 10010001,
            "FormViewRequestID": 72275437,
            "FormPackageStatusID": 2,
            "FormPackageTypeID": 2,
            "SubmitStatusID": 6,
            "FormPackageName": "Test de Request",
            "DateCreated": "2021-11-10T16:20:06.097",
            "DateCompleted": null,
            "DateToDelete": null,
            "FormIds": [
                216
            ],
            "FormPackageType": "Submitted Form Package",
            "SubmitStatus": "Processed by 3rd Party",
            "FormViewRequestUNID": "06be473f-999b-4bd9-9f6a-6f2e83081128",
            "FormPackageStatus": "Active",
            "EnvelopeID": null,
            "EnvelopeStatus": null,
            "EnvelopeDateSent": null
        },
        {
            "FormPackageID": 3888534,
            "CustomerID": 10010001,
            "FormViewRequestID": 72275438,
            "FormPackageStatusID": 2,
            "FormPackageTypeID": 2,
            "SubmitStatusID": 6,
            "FormPackageName": "Test de Request",
            "DateCreated": "2021-11-10T16:41:05.937",
            "DateCompleted": null,
            "DateToDelete": null,
            "FormIds": [
                217
            ],
            "FormPackageType": "Submitted Form Package",
            "SubmitStatus": "Processed by 3rd Party",
            "FormViewRequestUNID": "bc492bae-dde0-4f82-8b22-6c91b8350597",
            "FormPackageStatus": "Active",
            "EnvelopeID": null,
            "EnvelopeStatus": null,
            "EnvelopeDateSent": null
        },
        {
            "FormPackageID": 3888537,
            "CustomerID": 10010001,
            "FormViewRequestID": 72275454,
            "FormPackageStatusID": 2,
            "FormPackageTypeID": 2,
            "SubmitStatusID": 6,
            "FormPackageName": "Test de Request",
            "DateCreated": "2021-11-10T22:32:03.397",
            "DateCompleted": null,
            "DateToDelete": null,
            "FormIds": [
                220
            ],
            "FormPackageType": "Submitted Form Package",
            "SubmitStatus": "Processed by 3rd Party",
            "FormViewRequestUNID": "ae605d7f-6fb9-47d9-8e6b-44ea8d4d76e8",
            "FormPackageStatus": "Active",
            "EnvelopeID": null,
            "EnvelopeStatus": null,
            "EnvelopeDateSent": null
        }
    ],
    "ErrorCode": 0,
    "Message": "Getting data has been successful",
    "Errors": null
}

400 Bad Request - The value passed is not valid.

In the case that some of the parameters is receiving an incorrect value type, the endpoint will return a 400 Bad Request responseresponse.

For example, suppose that the following request is sending a text instead of a valid CustomerId:

Request:

{{api.vault.url}}/api/formpackages?CustomerIdList=errorTest

Response:

{
    "errors": {
        "CustomerIdList": [
            "The value 'errorTest' is not valid."
        ]
    },
    "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1",
    "title": "One or more validation errors occurred.",
    "status": 400,
    "traceId": "00-9041e3ea76f9884b9b495d9e8a27dc40-68b618b98eebd44d-00"
}

FormDataDetails

Returns the details of a single form package’s data from the vault given the following query parameters:

Route: {{api.vault.url}}/api/formpackages/details

HTTP Verb: GET

Parameters	Description
FormPackageID	REQUIRED - a single FormPackageID
FormViewRequestID	REQUIRED - the FormViewRequestID that owns the form data
FormViewRequestUNID	REQUIRED - the transactional UNID for the form view package.
CustomerID	REQUIRED - the CustomerID that owns the form package record. Must be related to the authenticated customer.

Take note that all these parameters are required and can be obtained from the response of the FormRecordList.

Examples

200 OK - Endpoint returns a valid response.

Request:

GET {{api.vault.url}}/api/formpackages/details?FormPackageID=1111111&FormViewRequestID=222222&FormViewRequestUNID=292add46-e5e5-4f6a-a23f-dbc6ffd36ab5&CustomerID=33333333

Response:

{
    "ResultData": {
        "CustomerId": 33333333,
        "FormPackageId": 1111111,
        "FormViewRequestId": 222222,
        "FormViewRequestUNID": "292add46-e5e5-4f6a-a23f-dbc6ffd36ab5",
        "FormIDs": [
            548
        ],
        "FormPackageStatuId": 1,
        "FormPackageStatus": "Pending",
        "SubmitStatusId": 2,
        "SubmitStatus": "Recipient Opened",
        "FormPackageTypeId": 2,
        "FormPackageType": "Submitted Form Package",
        "FormPackageName": "Test de Request",
        "DateCreated": "2021-10-27T19:49:30.44",
        "DateCompleted": null,
        "DateToDelete": null,
        "EnvelopeId": null,
        "EnvelopeStatus": null,
        "DateSent": null,
        "Fields": [
            {
                "Role": "Minor",
                "RoleNumber": 1,
                "Fields": [
                    {
                        "FieldName": "1min.ClientID",
                        "BaseField": "ClientID",
                        "Desc": "Client ID",
                        "Value": "Test Value"
                    }
                ]
            }
        ]
    },
    "ErrorCode": 0,
    "Message": "",
    "Errors": null
}

404 Not Found - Form package not found.

In the case that some of the parameters do not match with any form packages the endpoint will return a 404 Not Found response.

For example, suppose that the following request does not match with any existing form package of the customer:

Request:

GET {{api.vault.url}}/api/formpackages/details?FormPackageID=1111111&FormViewRequestID=222222&FormViewRequestUNID=292add46-e5e5-4f6a-a23f-dbc6ffd36ab5&CustomerID=33333333

Response:

{
    "ErrorCode": 1,
    "Message": "Form package not found or invalid.",
    "Errors": [
        {
            "Message": "Form package not found or invalid.",
            "Type": "ETI.Core.Entities.Exceptions.EntityNotFoundException"
        }
    ]
}

400 Bad Request - Invalid request

When one or more of the required parameters are missing or invalid you could get a 400 Bad Request response indicating the field that needs to be provided.

For example, the following request missing the FormPackageID parameter:

Request:

GET {{api.vault.url}}/api/forms-vault/forms/details?FormViewRequestID=222222&FormViewRequestUNID=292add46-e5e5-4f6a-a23f-dbc6ffd36ab5&CustomerID=33333333

Response:

{
    "ErrorCode": 0,
    "Message": "Invalid Form Package Request: Invalid FormPackageId parameter.",
    "Errors": [
        {
            "Message": "Invalid Form Package Request: Invalid FormPackageId parameter.",
            "Type": "ETI.Services.FormPackages.Exceptions.InvalidFormPackageRequestException"
        }
    ]
}

Update Form Package

This endpoint updates the form package:

Route: {{api.vault.url}}/api/formpackages

HTTP Verb: PUT

Examples

200 OK - Endpoint returns a valid response.

Request:

{
    "FormPackageIds":[291185811],
    "SubmitStatusId":1
}

Response:

{
    "ResultData": [
        {
            "FormPackageId": 2944858,
            "FormViewRequestID": 54205053,
            "FormViewRequestUNID": "aabdc2ae-af1f-49b4-b47a-d57082356bc1",
            "SubmitStatusID": 1,
            "SubmitStatus": "Unused"
        }
    ],
    "ErrorCode": 0,
    "Message": "Update successful",
    "Errors": null
}

404 Not Found - Form package not found.

In the case that some of the parameters do not match with any form packages the endpoint will return a 404 Not Found response.

For example, suppose that the following request does not match with any existing form package of the customer:

Sample Response:

{
    "ErrorCode": 404,
    "Message": "No records found for the authenticating user.",
    "Errors": [
        {
            "Message": "No records found for the authenticating user.",
            "Type": "NotFound"
        }
    ]
}

400 Bad Request - Invalid request

For example, Sending an empty FormPackageIds List would cause an invalid request error.