Forms Vault API
- Rich Walker
NOTE: This documentation is prior to the production release and is not available yet for use.
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_authenticationapi.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}}/tokenBody:
grant_type=password&username=usernameexample&password=mypasswordResponse:
{
"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_k3HUppDfUnzqULdqFormRecordList
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=10010002Response:
{
"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.523Response:
{
"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=errorTestResponse:
{
"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=33333333Response:
{
"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=33333333Response:
{
"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=33333333Response:
{
"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.
Related content
For help regarding Quik! Forms and the Quik! API
Email: support@quikforms.com | Phone: (877) 456-QUIK