NOTE: This documentation is prior to the production release and is not available yet for use.
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
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 |
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 |
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 } |
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 } |
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" } |
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.
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 } |
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" } ] } |
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" } ] } |
This endpoint updates the form package:
Route: {{api.vault.url}}/api/formpackages
HTTP Verb: PUT
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 } |
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" } ] } |
For example, Sending an empty FormPackageIds List would cause an invalid request error.