Create Request

What is a LCS Request

📘
LCS Request is...
Document or group of documents sent to one or more recipients for signing.

HTTP Request

Request Content-Type: application/json

JSON request data - name and value pairs description:

request: object with LCS request details; Value: JSON Object

request_name: name of the request; Value: String (UTF-8 characters, max 255 characters)
unique_submit_id (optional): unique id associated by requester; Value: String (UTF-8 characters, max 255 characters)
access_code_required (optional): code required for LCS request web access. This option is applied only to recipients without an LCS account. Recipients with an LCS account must always authenticate; Value: Boolean (true or false); Default value: false
request_notify_open (optional): notify the requester when recipients open the LCS request; Value: Boolean (true or false); Default value: false
request_create_draft (optional): create an LCS request as draft; Value: Boolean (true or false); Default value: false
request_message (optional): the LCS request message for recipients; Value: String (UTF-8 chars)
request_callback_url (optional): a valid https URL of your callback script; Value: String; Default value: default_callback_url: configured for each developer_key
signatures_order: (optional): recipients are required to sign the LCS request in the specified order; Value: Boolean (true or false); Default value: false
request_custom (optional): custom field for request; Value: String (UTF-8 characters, max 255 characters)
request_metadata (optional): metadata describing the request: Value: String (UTF-8 characters)
request_notify_signature (optional): notify the requester when recipients make a signature on request; Value: Boolean (true or false); Default value: false
request_validity_days (optional): request validity period in number of days; Value: Number. Must be a valid number in the range 1 to 180. Default value: 30
consent_bar_position (optional): request consent bar position on “Review and Sign” page; Value: String (“top” or “bottom”): Default value: “top”.

documents: list of documents details from the LCS request; Value: JSON Array with document JSON Objects:

document_type: method for PDF document transmission. Value: String ("url" or "base64")
document_content: the content of PDF document transmitted. Values:
•> URL of document, if document_type is "url". Document will be downloaded from URL
•> content of the document, in base 64 format, if document_type is "base64"
document_filename: filename of the PDF document. Must be unique filename in the request; Value: String (must be the filename from document_content if document_type is "url")
document_name (optional): name of PDF document. Value: String; If not declared it will be document_filename without extension. Must be unique document_name in the request;
document_checksum (optional): document checksum value; Value: String
document_checksum_algorithm (optional): checksum algorithm used for generating value of document_checksum.Value: String ("sha1" or "sha256"); Default value: "sha256"
document_custom (optional): custom field for the document; Value: String (UTF-8 characters, max 255 characters)
document_metadata (optional): metadata describing the document: Value: String (UTF-8 characters)

recipients: list of recipient’s information; The recipients are the signers and observers of the request. The recipients referenced in the JSON signatures object are the signers, and the non-referenced ones are the observers of the request.Value: JSON Array with recipient JSON Objects:

firstname: first name of recipient; Value: String (UTF-8 characters, max 75 characters)
lastname: last name of the recipient; Value: String (UTF-8 characters, max 75 characters)
code_delivery (optional): the transmission method for the document access code and/or the signature validation code; Value: String ("email" or "sms"); Default value: "sms".
email: recipient email; Value: String – valid email format; Must be unique email in the request;
phone: recipient’s phone number. Phone numbers must be in international format. May be null or empty if code_delivery is email; Value: String – valid phone number format
validation_method (optional): consent validation method for the recipient; Value: String ("otvc", "vpin" or "direct"); Default value: "otvc". OTVC is a one-time validation code, vPIN is validation PIN, and "direct" is the validation method without any other code required;
company (optional): recipient’s company; Value: String
order (optional): recipient’s order in the signature process. Value: Number; If signatures_order is true values must start from 1 followed by consecutive numbers. The signing order applies only to signers. If signatures_order in the request object is set to false the value is not used.
return_url (optional): customized return/redirect URL (HTTP GET webhook) for the "Finish" button after a recipient signs or rejects the request. The default "Finish" button behavior is the redirection to the LiveConsent Register Page for an unregistered user or the Login Page for a registered LiveConsent user. The customized "Finish" button redirects the recipient to the defined return_url. The return_url value is added to the default_return_url value that is defined as a setting of the developer account. Without specifying return_url, at the end of the signature process, the "Finish" button is set to the default behavior.
Value: String or "default_return_url" - which is a special value of the return_url (the recipient will be redirected to the URL defined in the default_return_url value).
Eg:
-for the "default_return_url" value "https://www.liveconsent.com/" and "return_url" value "solution/api/" the redirect value for the "Finish" button is "https://www.liveconsent.com/solution/api/"
-for the "default_return_url" value "https://www.liveconsent.com/" and "return_url" value "default_return_url" the redirect value for the "Finish" button is "https://www.liveconsent.com/"
automatic_return (optional): automatic redirection of the recipient to the specified return_url after successfully signing a document; Value: Boolean (true or false); Default value: false
signature_visual (optional): Visual image for signature. Depending on this parameter the recipient can sign with "Draw it" option only, "Type it" option only or both options for the signature image. Value: String ("all", "draw_it" and "type_it"); Default value: "all". ". If an invalid string value is sent, the default "all" value is associated.
sms_request_delivery (optional): notify the recipients (signers/observers) via SMS when a request is created or a manual reminder is sent; Value: Boolean (true or false); Default value: false
This option is available only by request. Please contact us on liveconsent.com, on our support platform or via email on [email protected]

signatures: list of signature information used to place an image of a signature in a document from current LCS request; Value: JSON Array with signature JSON Objects:

signature_recipient: email of the recipient that will sign the document. Value: String. Must be a valid email value from the recipients list.
signature_document: document filename to be signed. Value: String. Must be a valid document_filename value from the documents list.
signature_page_number: page number in PDF where image of signature is placed; Value: Number. Must be a valid number in the page range of the PDF document.
coordinates_type: type of coordinates of the signature; Value: String ("pdf" or "web").
signature_position: Coordinates of the signature image to set; Value: String
•> If coordinates_type is "web" the format is: "x,y" where x is the x coordinate top left reference, y is the y coordinate top left reference.
Example: "400,700".
To easily get web coordinates, you can use our "Place signature" tool: https://api.liveconsent.com/placesignature
•> If coordinates_type is "pdf" the format is: "x,y" where x is the x coordinate bottom left reference (PDF reference), y is the y coordinate bottom left reference (PDF reference). "x" and "y" are positive float numbers.
Example: "400,700" or "200,500.52".
If "signature_size" is not used, then height and width will have the default signature size values.
signature_size (optional): Size of the signature image (height or width: the image will be scaled depending on the height or width parameter); Value: String ("h,<height_size>" or "w,<width_size>" where <height_size> is signature image height and <width_size> is signature image width)
•> If coordinates_type is "web", then <height_size> or <width_size> are positive float numbers for represented dimension on web reference. Example: "h,40" or "w,83.52".
•> If coordinates_type is "pdf", then <height_size> or <width_size> are positive float numbers for represented dimension on PDF reference. Example: "h,40" or "w,83.52".
Default signature size values in pixels are available on our "Place signature" tool: https://api.liveconsent.com/placesignature
signature_type (optional): Type of image for signature: standard (visual image, LiveConsent info and timestamp) and basic (only visual image, without LiveConsent info and timestamp). Value: String ("basic" or "standard"); Default value: "standard". If invalid string value is sent, default "standard" value is associated.

initials: list of initials box information used to place an image of an initials box in a document from current LCS request; Value: JSON Array with initials JSON Objects:

initials_recipient: the recipient's email for which the initials box is added. Value: String. Must be a valid email value from the recipients list.
initials_document: the file name of the document for which the initials box is added. Value: String. Must be a valid document_filename value from the documents list.
initials_page_number: the number of the PDF page where the image of the initials box is placed; Value: Number. Must be a valid number in the page range of the PDF document.
coordinates_type: type of coordinates for the initials box; Value: String ("pdf" or "web").
initials_position: Coordinates of the initials box image to set; Value: String
•> If coordinates_type is "web" the format is: "x,y" where x is the x coordinate top left reference, y is the y coordinate top left reference.
Example: "400,700".
To easily get web coordinates, you can use our "Place signature" tool: https://api.liveconsent.com/placesignature
•> If coordinates_type is "pdf" the format is: "x,y" where x is the x coordinate bottom left reference (PDF reference), y is the y coordinate bottom left reference (PDF reference). "x" and "y" are positive float numbers.
Example: "400,700" or "200,500.52".
If " initials_size" is not used, then height and width will have the default signature size values.
initials_size(optional): Size of the initials box image (height or width: the image will be scaled depending on the height or width parameter); Value: String ("h,<height_size>" or "w,<width_size>" where <height_size> is initials box image height and <width_size> is initials box image width)
•> If coordinates_type is "web", then <height_size> or <width_size> are positive float numbers for represented dimension on web reference. Example: "h,40" or "w,83.52".
•> If coordinates_type is "pdf", then <height_size> or <width_size> are positive float numbers for represented dimension on PDF reference. Example: "h,40" or "w,83.52".

fields: list of fields information used to place it in a document from current LCS request; Value: JSON Array with fields JSON Objects:

field_type: type of field added to PDF document. Value: String ("checkbox").
field_unique_id: Unique ID for the field assigned by the requester within the current request; Value: String (UTF-8 characters, max 255 characters).
field_recipient: the recipient's email for which the field is added. Value: String. Must be a valid email value from the recipients list.
field_document: the file name of the document for which the field is added. Value: String. Must be a valid document_filename value from the documents list.
field_page_number: the number of the PDF page where the field is placed; Value: Number. Must be a valid number in the page range of the PDF document.
coordinates_type: type of coordinates for the field; Value: String ("pdf" or "web").
field_position: Coordinates of the field to set; Value: String
•> If coordinates_type is "web" the format is: "x,y" where x is the x coordinate top left reference, y is the y coordinate top left reference.
Example: "400,700".
To easily get web coordinates, you can use our "Place signature" tool: https://api.liveconsent.com/placesignature
•> If coordinates_type is "pdf" the format is: "x,y" where x is the x coordinate bottom left reference (PDF reference), y is the y coordinate bottom left reference (PDF reference). "x" and "y" are positive float numbers.
Example: "400,700" or "200,500.52".
field_options (optional): Object with LCS field options; Value: JSON Object
• mandatory (optional): The recipient is required review the field (fill in textfield or select the checkbox); Value: Boolean (true or false); Default value: false
• tooltip (optional): Value of the tooltip displayed for the field; Value: String (UTF-8 characters, max 255 characters). Null if not defined
• textfield_placeholder (optional): Placeholder value for a textfield; Value: String (UTF-8 characters, max 255 characters). Null if not defined
• textfield_lines_number (optional): The number of lines for a textfield. Value: Number. Default value:1
• textfield_characters_per_line (optional): The number of characters per line for a textfield. Value: Number. Default value: 20
• textfield_character_limit (optional): The maximum number of characters for a textfield. Value: Number. No default value is set. The value must be a number between 1 and textfield_lines_number x textfield_characters_per_line.
• textfield_prefilled_text (optional): The placeholder value is prefilled in the textfield. Placeholder value must be defined; Value: Boolean (true or false); Default value: false
• textfield_prefilled_text_readonly (optional): The prefilled text (placeholder value) is read only. Placeholder value must be defined and textfield_prefilled_text must be 'true'; Value: Boolean (true or false); Default value: false

Default field size values for field_type "checkbox" is 14 x 14 pt (PDF reference).
Default checkbox mark is "checkmark" ✓.

What is a LCS Request

📘LCS Request is...

HTTP Request

📘
LCS Request is...