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/"
  • 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" ✓.