CWB Webhook
This page contains samples as well as details about the CWB webhook object.
Last updated
This page contains samples as well as details about the CWB webhook object.
Last updated
* Check out the Webhooks page to get instructions on how to set your webhook.
This is the object (JSON) you will receive when you set up your webhook and someone fills out your form. It consists of the webhook event, apiVersion, and the data object . The data object contains the entry's (the form filler's) response, as well as reports generated by vForm on the response if required.
This section contains object samples for all possible webhook events, as well as explanations for each in the Explanation tab.
This object is made up of attributes that provide general information about the form entry. It also contains the field array, which consists of response objects for each section of the form.
The Sample and Explanation tabs below show a sample object as well as explanations for the attributes.
List of objects for each section of the form that contains responses from the person filling out the form and can contain a report on the responses after CWB performs verifications and validations on them as specified by the form owner.
Each section can be one of the following specified by the __type attribute in each objects. personal-information, identity, company-search, address, file-upload , reference ,supplementary-field , consent-verification.
The Sample and Explanation tabs below show a sample object as well as explanations for the attributes in the consent-verification field object.
This object stores the user's personal information; there may be one or more personal information fields, any of which can also be linked to identity or address fields by the form owner to serve as the default personal information for performing validations.
The Sample and Explanation tabs below show a sample object as well as explanations for the attributes in the personal-information field object.
The Sample and Explanation tabs below show a sample object as well as explanations for the attributes in the identity field object.
The Sample and Explanation tabs below show a sample object as well as explanations for the attributes in the company-search field object.
The Sample and Explanation tabs below show a sample object as well as explanations for the attributes in the file-upload field object.
The Sample and Explanation tabs below show a sample object as well as explanations for the attributes in the supplementary-field field object.
The Sample and Explanation tabs below show a sample object as well as explanations for the attributes in the reference field object.
The Sample and Explanation tabs below show a sample object as well as explanations for the attributes in the address field object.
| Attribute | Type | Description |
|---|---|---|
| Attribute | Type | Description |
|---|---|---|
| Attribute | Type | Description |
|---|---|---|
| Attribute | Type | Description |
|---|---|---|
| Attribute | Type | Description |
|---|---|---|
| Attribute | Type | Description |
|---|---|---|
| Attribute | Type | Description |
|---|---|---|
| Attribute | Type | Description |
|---|---|---|
| Attribute | Type | Description |
|---|---|---|
event
String
This represents the status of a webhook entry. Which can be one of the following:
"vForm.added": when there is a new response entry.
This comes with a data object that contains the response.
"vForm.updated": when there is an update on an old entry.
The data object will be updated.
"vForm.completed": when all updates are completed on an old entry.
Usually when all verifications have been processed.
The data object will be updated for the last time , containing the full response
and full verification details
apiVersion
String
The webhook version
id
String
vForm's object unique identifier.
businessId
String
This is the unique identifier of the business that created the vForm.
userId
String
This is the unique identifier of the user that created the vForm ,a vForm business can have multiple usersThis is the unique identifier of the business that created the vForm.
billingItemComponents
Array
This is a list of all the features (such as liveness check, facial compare, and id capture) and verifications that the vform's owner included while configuring the form and are intended to be paid for.
This can include one or more of the following based on the configuration . "phonenumber","drivers_license","bvn","nin"
"passport","inec","bav","aml","address_verification","vform"
"livenesss","facial_compare","id_capture" and "company_search"
transactionDetails
Object
This object contains details about the amount charged and deducted after the submission of this response as configured by the owner.
transactionId
String
TransactionDetail's object unique identifier.
amountCharged
Integer
Amount charged for this response.
currency
String (CountryCode)
Currency in which the charge was made.
availableBalance
Integer
Available balance in the vForm business account.
totalVerifications
Integer
The total number of verifications that vForm is expected to perform on this response.
completedVerifications
Integer
The total number of verifications vForm has completed on this response.
fields
Array of Objects
List of objects for each section of the form that contains responses from the person filling out the form and can contain a report on the responses after vform performs verifications and validations on them as specified by the form owner. Each section can be one of the following specified by __type in each objects. personal-information, identity, company-search, address, file-upload , reference ,supplementary-field , consent-verification.
fillDurationInMilliSeconds
Integer
The amount of time the person spent filling out the form in milliseconds.
createdAt
String (Date)
The date this response was submitted.
updatedAt
String (Date)
The date this response was last updated.
status
String
This is the overall status of this response which can be anyone of the following
"pending": This is the overall status of a response when there is/are
still a/some verification(s) to be done on the response or when some responses are still expected from a reference form.
"cleared": This is the overall status of the response when a form with no
verification has been submitted or when all the verifications and validations have been performed by vform on a response and are all passed
"not_cleared": This is the overall status of the response when one or
more of the verifications and validations performed by vform on a response failed.
"pending_payment": When payment is still pending, no verification will be done.
__type
String
A vform-defined tag for this section of the form.
It has a constant value of consent-verification.
id
String
Consent verification's object unique identifier.
label
String
A short descriptive title for the consent verification section of the form usually set by the form owner
value
Boolean
A true or false value indicating whether or not
the formfiller accepts the conditions of the consent.
__type
String
A vform-defined tag for this section of the form.
It has a constant value of personal-information.
This tag appears on all sections that accepts
personal information from the formfiller.
id
String
Personal information's object unique identifier.
label
String
A short descriptive title for the personal information section of the form usually set by the form owner
firstName
String
A mandatory first name, usually the formfiller's
or as specified by the form owner in the section's
label or description.
Example: If the formfiller is filling out a section that requires his/her guarantor or guardian's first name
lastName
String
A mandatory last name, usually the formfiller's
or as specified by the form owner in the section's
label or description.
Example: If the formfiller is filling out a section that requires his/her guarantor or guardian's last name/surname
String(email)
An email address , usually the formfiller's
or as specified by the form owner in the section's
label or description.
Example: If the formfiller is filling out a section that requires his/her guarantor or guardian's email
This can be optional or required as set by the form
owner
gender
String
Gender, usually the formfiller's
or as specified by the form owner in the section's
label or description.
Example: If the formfiller is filling out a section that requires his/her
guarantor or guardian's gender
This can be optional or required as set by the form
owner.
photo
String(url)
image, usually the formfiller's or as specified by the form owner in the section's label or description. Example: If the formfiller is filling out a section that requires his/her guarantor or guardian's photo This can be optional or required asset by the form owner.
relationship
String
Personal relationship, which can be one of the following
"brother","sister","father","mother","wife","husband","other".
This is usually based on the context that is specified by the form owner in the section label or description.
Example: If the formfiller is filling out a section that requires his/her relationship with his/her guarantor or guardian's
This can be optional or required as set by the form
owner.
mobile
String(phone)
Phone number, usually the formfiller's
or as specified by the form owner in the section's
label or description.
Example:If the formfiller is filling out a section that requires his/her guarantor or guardian's phone number
This can be optional or required as set by the form
owner.
middleName
String
Middle name, usually the formfiller's
or as specified by the form owner in the section's
label or description.
Example: If the formfiller is filling out a section that requires his/her guarantor or guardian's middle name
This can be optional or required as set by the form
owner.
dateOfBirth
String(date)
Date of birth, usually the formfiller's
or as specified by the form owner in the section's
label or description.
Example: If the formfiller is filling out a section that requires his/her guarantor or guardian's date of birth
This can be optional or required as set by the form
owner.
amlCheck
Object
This contains reports and status from vform when the form owner wants vform to perform an anti-money laundering(aml) check on the personal information field (firstname and lastname). This objects is not available if an aml check is not performed
-- report
Object
This is the report from the aml check.
-- status
String
This is the status from the aml check which can be anyone of the following
"cleared": When the form filler's name is not in aml list
"review_required":
"not_cleared": When the form filler's name is in aml list
__type
String
A vform-defined tag for this section of the form.
It has a constant value of identity.This tag appears
on all sections that accepts identity information from the formfiller.
id
String
Identity object unique identifier.
typeCountryCode
String(countryCode)
The country code under which the identity card was issued. This might also be the province/region code the identity card was issued.
firstName
String
This is the first name from the personal information field
linked/set to this identity field by the form owner for vform to perform
validations against.
The first personal information field is the default if none was linked by the form owner.
The first name is null if validations was not to be performed on it.
lastName
String
This is the last name from the personal information field
linked/set to this identity field by the form owner for vform to perform
validations against.
The first personal information field is the default if none was linked by the form owner.
The last name is null if validations was not to be performed on it.
label
String
A short descriptive title for the identity section of the form usually set by the form owner
dateOfBirth
String(date)
This is the date of birth from the personal information field
linked/set to this identity field by the form owner for vform to perform
validations against.
The first personal information field is the default if none was linked by the form owner.
The date of birth is null if validations was not to be performed on it.
identityCardPhotoFront
String(url)
The captured identity card's front image. If the identity number was manually entered, this will be an empty string.
identityCardPhotoBack
String(url)
The captured identity card's back image. If the identity number was manually entered, this will be an empty string.
photo
String(url)
This is the photo from the personal information field
linked/set to this identity field by the form owner for vform to perform
validations against.
The first personal information field is the default if none was linked by the form owner.
The photo is null if validations was not to be performed on it.
value
String
The identity number that was entered manually or extracted from the captured identity card. This can be optional or required as set set by the form owner.
type
String
The identity card type .
Example: Passport, ID Card, Residence Permit, Driving License. e.t.c
report
Object
This contains reports generated by vform when the form owner requests that vform perform verification and validations on the identity number. This will be null if no verification is to be conducted or if the verification is already in progress.
status
String
This is the status of the verification and validation conducted on the identity number by vForm.
which can be anyone of the following.
"not_applicable": When no verification is performed.
"pending": When the verification is in process.
"found": When the identity number is found in the official database.
"not_found": When the identity number is not found in the official database.
__type
String
A vform-defined tag for this section of the form.
It has a constant value of company-search.
This tag appears on all sections that accepts
business/company information from the formfiller.
id
String
Business-search's object unique identifier.
countryCode
String(countryCode)
The company country code,which specifies where the business search is to be performed by vForm.
companyName
String
The company's name This can be optional or required as set by the form owner.
companyAddress
String
The company's address This can be optional or required as set by the form owner.
registeredName
String
The business's registered name. This is required in order to perform a company search with vform.
label
String
A short descriptive title for the business search section of the form usually set by the form owner
supportEmail
String(email)
The business support email. This can be optional or required as set by the form owner.
supportPhoneNumber
String(email)
The business support phone number This can be optional or required as set by the form owner.
value
String
The company registration number. This is required in order to perform a company search with vform.
type
String
This is always registrationNumber
report
Object
This contains reports generated by vform when the form owner requests that vform perform a business verification on the business registered name. This will be null if no business search is to be conducted or if the verification is already in progress.
status
String
This is the status of the business search conducted on the business by vForm.
which can be anyone of the following.
"not_applicable": When no verification is performed.
"pending": When the verification is in process.
"found": When the business registration number is found in the official database.
"not_found": When the business registration number is not found in the official database.
__type
String
A vform-defined tag for this section of the form.
It has a constant value of file-upload.This tag
appears on all sections that accepts file uploads
from the formfiller.
id
Strnig
File upload's object unique identifier.
name
String
Uploaded file name
size
Integer
Uploaded file size
label
String
A short descriptive title for the file upload section of the form usually set by the form owner
fileType
String
Uploaded file type. This can be one of the following
png, jpg, jpeg, pdf, ppt, pptx, doc, docx, xls, xlsx
url
String(url)
Uploaded file url
status
String
This shows the status of the file upload. which is always "completed"
__type
String
A vform-defined tag for this section of the form.
It has a constant value of supplementary-field.
This tag appears on all sections that accepts
other neccessary information from the formfiller.
id
String
Supplement field's object unique identifier.
options
Arrays
This contains the available options if the question needs the formfiller to select one.
label
String
A question that the form owner wants the formfiller to respond to
value
Array
The formfiller's response(s) to the form owner's question.
type
String
The expected type of the supplied response(s).
which can be anyone of the following .
"text", "date", "checkbox", "dropdown","radio"
format
String
The format of the supplied response.
This can be "long" or "short" for text response , "daymonth" or "monthday"
for date response and null for other response
status
String
This shows the status of the supplementary field which is always "completed"
__type
String
A vform-defined tag for this section of the form.
It has a constant value of reference.
This tag appears on all sections that accept and contains
responses from a referenced form .
id
String
Reference field's object unique identifier.
firstName
String
Referenced form filler's firstname
lastName
String
Referenced form filler's lastname
label
String
A short descriptive title for the reference section of the form usually set by the form owner
fields
Array of Objects
List of objects for each section of the form that contains responses
from the person filling out the referenced form and can contain a report on the responses
after vform performs verifications and validations on them as specified
by the form owner.
Each section can be one of the following specified by __type in each objects.
personal-information, identity, company-search, address, file-upload ,supplementary-field,
consent-verification .
String(email)
Referenced form filler's email
status
String
This is the overall status of this referenced form response
which can be anyone of the following.
"pending": This is the overall status of a response when there is/are
still a/some verification(s) to be done on the response.
"cleared": This is the overall status of the response when a form with no
verification has been submitted or when all the verifications and validations
have been performed by vform on a response and are all passed.
"not_cleared": This is the overall status of the response when one or
more of the verifications and validations performed by vform on a response failed.
"pending_payment":
__type
String
A vform-defined tag for this section of the form.
It has a constant value of address.This tag appears
on all sections that accept address information from the formfiller.
id
String
Address field's object unique identifier.
label
String
A short descriptive title for the address section of the form usually set by the form owner
candidate
Object
This object contains personal information about the person who resides/works at the house/business address.
-- middleName
String
This is the middle name from the personal information field
linked/set to this address field by the form owner to serve as the address subject.
The first personal information field is the default if none was linked by the form owner .
-- dateOfBirth
String
This is the date of the birth from the personal information field
linked/set to this address field by the form owner to serve as the address subject.
The first personal information field is the default if none was linked by the form owner .
String(email)
This is the email address from the personal information field
linked/set to this address field by the form owner to serve as the address subject.
The first personal information field is the default if none was linked by the form owner .
-- firstName
String
This is the first name from the personal information field
linked/set to this address field by the form owner to serve as the address subject.
The first personal information field is the default if none was linked by the form owner .
-- lastName
String
This is the last name from the personal information field
linked/set to this address field by the form owner to serve as the address subject.
The first personal information field is the default if none was linked by the form owner .
-- mobile
String(phone)
This is the phone number from the personal information field
linked/set to this address field by the form owner to serve as the address subject.
The first personal information field is the default if none was linked by the form owner .
-- image
String(url)
This is the name from the personal information field
linked/set to this address field by the form owner to serve as the address subject.
The first personal information field is the default if none was linked by the form owner .
guarantor
Object
This object contains information about the guarantor.
If the address type is not "guarantor" the attributes will be null.
-- firstName
String
Guarantor's first name
-- lastName
String
Guarantors last name
String(email)
Guarantor's email
-- mobile
String(phone)
Guarantor's phone number
-- image
String(url)
Guarantor's image
business
Object
This object contains the information about the business
If the address type is not "business" the attributes will be null.
-- name
String
Business name
-- registrationNumber
String
Business registration number
String(email)
Business email address
-- mobile
String(phone)
Business phone number
address
Object
This object contains the address details
-- flatNumber
String
Flat number
-- buildingName
String
Building name
-- subStreet
String
Address sub street
-- lga
String
Address local government area
-- country
String(countryCode)
Address country
-- buildingNumber
String
Building number
-- landmark
String
Address closest landmark
-- street
String
Address street
-- city
String
Address city
-- state
String
Address state
type
String
The type of address set by the form owner
which can be one of the following : "individual","business","guarantor"
description
String
Any other information about the address the formfiller wants vForm to know
taskStatus
String
status
String
This is the status of the address verification conducted on the address details by vForm
which can be anyone of the following.
"not_applicable": when no verification is performed.
"pending": When the verification is in process.
"completed": When the verification is completed.
"payment_pending": When address verification payment is still pending, no verification will be done .
"awaiting_reschedule": When the address verification process has been reschedule.
"canceled": When the address verifcation process has been canceled.
report
Object
This contains reports from vform when the form owner requests that vform perform an address verification on the addres This will be null if no address verification is to be conducted or if the verification is already in progress.