Details

openapi: 3.0.1 info: title: Forms version: '0.0' tags: - name: Forms - name: Form Submissions - name: Download/Upload servers: - url: 'https://banno.com' paths: '/a/forms/api/v0/institutions/{institutionId}/forms/{formId}/submissions': get: tags: - Form Submissions description: Gets a list of form entries. security: - clientCredentials: [ https://jackhenry.com/forms/submissions.read ] parameters: - $ref: '#/components/parameters/institutionId' - $ref: '#/components/parameters/formId' - $ref: '#/components/parameters/offset' - $ref: '#/components/parameters/limit' - $ref: '#/components/parameters/start' - $ref: '#/components/parameters/end' responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/get-form-entries' '/a/forms/api/v0/institutions/{institutionId}/forms/{formId}/versions/{versionId}/submissions/{submissionId}': post: tags: - Form Submissions description: >- Update and/or submit a public form submission. Prerequisite: the form submission been iniated via `POST /a/forms/api/v0/institutions/{institutionId}/forms/{formId}/submissions`. The body will be key/value pairs that fill out the form. The key is the block name, followed by a period, then followed by the field name. security: - clientCredentials: [ https://jackhenry.com/forms/submissions.write ] parameters: - $ref: '#/components/parameters/institutionId' - $ref: '#/components/parameters/formId' - $ref: '#/components/parameters/versionId' - $ref: '#/components/parameters/submissionId' - name: finished in: query description: >- When the submission should be finalized, pass the `finished` flag in the query parameters to indicate to the serer that the submission is complete and it should check all the data submitted, send out the email, and create the case. schema: type: boolean - name: g-recaptcha-response in: header description: >- Google's reCaptcha is enabled for this endpoint. In order for a form submission to be updated and/or finalized it must have a valid reCaptcha value. This comes from the Google reCaptcha widget. Docs here: https://developers.google.com/recaptcha/docs/display To render the reCaptcha widget you'll need a non-secret Google API key. Please contact the Forms service owners for this key. required: true schema: type: string description: A long string returned by the Google reCaptcha Javascript widget. requestBody: content: application/json: schema: type: object properties: NameBlock1.firstName: type: string example: Value NameBlock1.lastName: type: string example: otherValue CheckboxChoiceBlock1.choice1: type: array example: - value A - value B items: type: string description: >- Example. Real block names will vary. Note that blocks can contain multiple values (such as in `CheckboxChoiceBlock1`). These field names may be listed multiple times: once for each value. application/x-www-form-urlencoded: schema: type: object properties: NameBlock1.firstName: type: string example: Value NameBlock1.lastName: type: string example: otherValue CheckboxChoiceBlock1.choice1: type: array example: - value A - value B items: type: string description: >- Example. Real block names will vary. Note that blocks can contain multiple values (such as in `CheckboxChoiceBlock1`). These field names may be listed multiple times: once for each value. multipart/form-data: schema: type: object properties: NameBlock1.firstName: type: string example: Value NameBlock1.lastName: type: string example: otherValue CheckboxChoiceBlock1.choice1: type: array example: - value A - value B items: type: string description: >- Example. Real block names will vary. Note that blocks can contain multiple values (such as in `CheckboxChoiceBlock1`). These field names may be listed multiple times: once for each value. required: false responses: '200': description: OK content: {} '401': description: >- Forbidden. There are 2 possible response payloads: `captcha-missing` and `captcha-invalid-valie`. Make sure to send the `g-recaptcha-response` header with the value generated by the reCaptcha widget. '422': description: Form field validation error content: application/json: schema: $ref: '#/components/schemas/form-submission-validation-failure' '500': description: >- upstream service error: reCaptcha API may be down x-codegen-request-body-name: body '/a/forms/api/v0/institutions/{institutionId}/forms': get: tags: - Forms description: >- This is to be able to request the list of forms from within the CMS editor. Since that will be cross-domain, it will be un-authenticated and has CORS support. security: - clientCredentials: [ https://jackhenry.com/forms/forms.read ] parameters: - $ref: '#/components/parameters/institutionId' responses: '200': description: OK content: application/json: schema: type: array items: $ref: '#/components/schemas/form' post: tags: - Forms description: >- Create a form. Note that the `options.name` values must be unique across all blocks for that form; a recommended naming scheme is something like `textBlock1`, `numberBlock1`, `textBlock2`, etc. security: - clientCredentials: [ https://jackhenry.com/forms/forms.write ] parameters: - $ref: '#/components/parameters/institutionId' requestBody: content: application/json: schema: $ref: '#/components/schemas/create-form' required: false responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/form' x-codegen-request-body-name: body '/a/forms/api/v0/institutions/{institutionId}/forms/{formId}': get: tags: - Forms description: Gets a form. security: - clientCredentials: [ https://jackhenry.com/forms/forms.read ] parameters: - $ref: '#/components/parameters/institutionId' - $ref: '#/components/parameters/formId' responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/form' put: tags: - Forms description: Update form security: - clientCredentials: [ https://jackhenry.com/forms/forms.write ] parameters: - $ref: '#/components/parameters/institutionId' - $ref: '#/components/parameters/formId' requestBody: content: application/json: schema: $ref: '#/components/schemas/form' required: false responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/form' x-codegen-request-body-name: body '/a/forms/api/v0/institutions/{institutionId}/forms/list': post: tags: - Forms description: >- Create multiple forms. Note that the `options.name` values must be unique across all blocks for that form; a recommended naming scheme is something like `textBlock1`, `numberBlock1`, `textBlock2`, etc. security: - clientCredentials: [ https://jackhenry.com/forms/forms.read ] parameters: - $ref: '#/components/parameters/institutionId' requestBody: content: application/json: schema: type: array items: $ref: '#/components/schemas/form' required: false responses: '200': description: OK content: application/json: schema: type: array items: $ref: '#/components/schemas/form' x-codegen-request-body-name: body '/a/forms/api/v0/institutions/{institutionId}/forms/{formId}/submissions/{submissionId}': get: tags: - Form Submissions description: Retrieves a form submission. security: - clientCredentials: [ https://jackhenry.com/forms/submissions.read ] parameters: - $ref: '#/components/parameters/institutionId' - $ref: '#/components/parameters/formId' - $ref: '#/components/parameters/submissionId' responses: '200': description: >- OK. Note that blocks can have multiple values (i.e., `CheckboxChoiceBlock`) may have multiple entries under the `data` property, each with a different value. content: application/json: schema: $ref: '#/components/schemas/form-submission' delete: tags: - Form Submissions description: Deletes a form submission. security: - clientCredentials: [ https://jackhenry.com/forms/submissions.write ] parameters: - $ref: '#/components/parameters/institutionId' - $ref: '#/components/parameters/formId' - $ref: '#/components/parameters/submissionId' responses: '200': description: >- OK. Sets the `deletedOn` property of the form submission to the current time, kills all stored key-value pairs that were sent in as part of the form. content: application/json: schema: $ref: '#/components/schemas/form-entry' '/a/forms/api/v0/institutions/{institutionId}/forms/{formId}/uploads/{uploadId}': get: tags: - Download/Upload description: Safe to use with an `href` with target set for a new tab. security: - clientCredentials: [ https://jackhenry.com/forms/uploads.read ] parameters: - $ref: '#/components/parameters/institutionId' - $ref: '#/components/parameters/formId' - $ref: '#/components/parameters/uploadId' responses: '200': description: >- Starts downloading of the requested upload. Headers are set such that the browser will download the file in the original filename that they uploaded it as. content: {} components: securitySchemes: clientCredentials: type: oauth2 description: OAuth2 using the client credentials flow flows: clientCredentials: tokenUrl: https://banno.com/a/oidc-provider/api/v0/token scopes: {} schemas: form-submission: type: object properties: submission: $ref: '#/components/schemas/form-entry' data: type: array items: $ref: '#/components/schemas/block' form: type: object properties: formId: type: string format: uuid institutionId: type: string format: uuid versionId: type: string format: uuid name: type: string example: Form Name priorityLevel: type: string example: medium status: type: string example: approved lastUpdated: type: string format: date-time lastUpdatedBy: type: string format: uuid endUserNotifications: type: object properties: emailAutoResponse: type: string institutionNotifications: type: object properties: includeData: type: boolean example: false institutionGroup: type: string format: uuid emailAddresses: type: array items: type: string format: email purgeAfter: type: object properties: numberOf: type: integer timeUnit: type: string example: never blockLayout: type: object properties: blocks: type: array items: $ref: '#/components/schemas/block' block: type: object properties: identifier: type: object properties: blockName: type: string description: Block Name example: NameBlock1 fieldName: type: string example: firstName value: type: array items: type: string example: value blockOf: type: string example: nameBlock contextOf: type: string example: primary identifier: type: object properties: blockName: type: string description: Block Name example: NameBlock1 fieldName: type: string example: firstName form-submission-validation-failure: type: array items: type: object properties: identifier: $ref: '#/components/schemas/identifier' failures: type: array items: type: string description: Reason(s) why this particular Field failed to validate example: Phone number does not have enough digits form: type: object properties: formId: type: string description: Returned with or without authentication. format: uuid name: type: string description: Returned with or without Authentication. example: Form Name institutionId: type: string description: Requires authentication. format: uuid versionId: type: string description: Requires authentication. format: uuid priorityLevel: type: string description: Requires authentication. status: type: string description: Requires authentication. lastUpdated: type: string description: Requires authentication. format: date-time lastUpdatedBy: type: string description: Requires authentication. format: uuid endUserNotifications: type: object properties: emailAutoResponse: type: object properties: subject: type: string from: type: string format: email text: type: string description: Plaintext of the message. description: Requires authentication. institutionNotifications: type: object properties: includeData: type: boolean institutionGroup: type: string format: uuid emailAddresses: type: array items: type: string format: email description: Requires authentication. purgeAfter: type: object properties: numberOf: type: integer timeUnit: type: string description: Requires authentication. blockLayout: type: object properties: blocks: type: array items: $ref: '#/components/schemas/block' description: Requires authentication. description: >- Note that the `options.name` values must be unique across all blocks for that form; a recommended naming scheme is something like `textBlock1`, `numberBlock1`, `textBlock2`, etc. example: formId: 97b31e33-b62d-11e5-ba68-56e107cbb805 institutionId: a2912f3a-17e1-4327-84ae-42a887157a52 versionId: 97b31e3c-b62d-11e5-ba68-56e107cbb805 name: Form Name priorityLevel: medium status: approved lastUpdated: '2016-01-08T17:31:03.955Z' lastUpdatedBy: 97b31e3d-b62d-11e5-ba68-56e107cbb805 endUserNotifications: emailAutoResponse: subject: email subject from: someone@example.com text: |- This is the plaintext of the message. Second paragraph institutionNotifications: includeData: false institutionGroup: d30771df-468d-4a06-ad3c-4b4952946662 emailAddresses: [] purgeAfter: numberOf: 0 timeUnit: never blockLayout: blocks: [] create-form: type: object properties: name: type: string priorityLevel: type: string status: type: string endUserNotifications: type: object properties: emailAutoResponse: type: string institutionNotifications: type: object properties: includeData: type: boolean institutionGroup: type: string format: uuid emailAddresses: type: array items: type: string format: email purgeAfter: type: object properties: numberOf: type: integer timeUnit: type: string blockLayout: type: object properties: blocks: type: array items: $ref: '#/components/schemas/block' description: >- Note that the `options.name` values must be unique across all blocks for that form; a recommended naming scheme is something like `textBlock1`, `numberBlock1`, `textBlock2`, etc. example: name: Form Name priorityLevel: medium status: approved endUserNotifications: {} institutionNotifications: includeData: false institutionGroup: d30771df-468d-4a06-ad3c-4b4952946662 emailAddresses: [] purgeAfter: numberOf: 0 timeUnit: never blockLayout: blocks: [] get-form-entries: type: array items: $ref: '#/components/schemas/form-entry' form-entry: type: object properties: submissionId: type: string format: uuid versionId: type: string timestamp: type: string format: date-time finished: type: boolean example: false ip: type: string referrer: type: string profileId: type: string deletedOn: type: string parameters: institutionId: name: institutionId in: path description: Institution ID required: true schema: type: string format: uuid formId: name: formId in: path description: Form ID required: true schema: type: string format: uuid versionId: name: versionId in: path description: Version ID required: true schema: type: string format: uuid submissionId: name: submissionId in: path description: Submission ID required: true schema: type: string format: uuid uploadId: name: uploadId in: path description: Upload ID required: true schema: type: string format: uuid offset: name: offset in: query schema: type: integer limit: name: limit in: query schema: type: integer start: name: start in: query schema: type: string format: date-time end: name: end in: query schema: type: string format: date-time