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 a LCS account. Recipients with a 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

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: 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 number must be 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" or “vpin”); Default value: "otvc”. OTVC is one-time validation code. vPIN is validation PIN.
  • company (optional): recipient’s company; Value: String
  • order (optional): recipient’s order in 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 URL for a recipient after he signed/rejected the request. The return_url 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 recipient will remain on the LiveConsent page. 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).
  • signature_mode (optional): Signature mode for a recipient. Depending on this parameter all signatures that a recipient has to do, can be validated with a single code and will be made one after the other, without any interference from the signer (“bulk” mode) or the recipient will receive a different validation code for each signature (“unit” mode). Value: String (“bulk” or “unit”); Default value: “bulk”. Value “unit” is available only for requests with a single document.
  • 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 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,400” 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,400” 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.