Home > API Reference > Document Preparation > Get Document Fields

Get Document Fields

Business applications can use this service API to get document fields i.e., initials, in-persons, signature fields or form fields.

https://api.signinghub.com/v3/packages/{package_id}/documents/{document_id}/fields/{page_no}

HTTP Verb

GET

Accept

application/json

Authorization

Bearer {access_token}

Request Body

 

Response

 

Status Code

Message

Response Body

200

OK

{
  "digital_signature": [
    {
      "order": 1,
      "tab_order": 2,
      "display_order": 2,
      "field_name": "signinghub_field_name",
      "page_no": 1,
      "embedded": true,
      "type": "ASSIGNED",
      "process_status": "UN_PROCESSED",
      "processed_on": "2015-02-13T12:10:00",
      "processed_as": "COLLABORATOR",
      "processed_by": "abc@xyz.com",
        "dimensions": {
        "field": {
          "x": 200,
          "y": 200,
          "width": 200,
          "height": 300
        },
        "page": {
          "width": 200,
          "height": 300
        }
      },
    "verification": null,
     "display": "VISIBLE"
    }
  ],
  "hand_signature": [
    {
      "order": 1,
      "tab_order": 2,
      "display_order": 2,
      "field_name": "signinghub_field_name",
      "page_no": 1,
      "embedded": true,
      "type": "ASSIGNED",
      "process_status": "UN_PROCESSED",
      "processed_on": "2015-02-13T12:10:00",
      "processed_as": "COLLABORATOR",
      "processed_by": "abc@xyz.com",
      "dimensions": {
        "field": {
          "x": 200,
          "y": 200,
          "width": 200,
          "height": 300
        },
        "page": {
          "width": 200,
          "height": 300
        }
      }
    }
  ],
  "electronic_signature": [
    {
      "order": 1,
      "tab_order": 2,
      "display_order": 2,
      "field_name": "signinghub_field_name",
      "page_no": 1,
      "embedded": true,
      "type": "ASSIGNED",
      "process_status": "UN_PROCESSED",
      "processed_on": "2015-02-13T12:10:00",
      "processed_as": "COLLABORATOR",
      "processed_by": "abc@xyz.com",
      "signature_sub_type": "WITNESS",
        "display": "visible",
      "dimensions": {
        "field": {
          "x": 200,
          "y": 200,
          "width": 200,
          "height": 300
        },
        "page": {
          "width": 200,
          "height": 300
        }
      },
      "authentication": {
        "enabled": true,
        "sms_otp": {
          "enabled": true,
          "otp_length": 8,
          "retry_duration": 30,
          "mobile_number": "00445566778899"
        }
      },
       "verification": null,
        "display": "VISIBLE"
    }
  ],
  "initials": [
    {
      "order": 1,
      "tab_order": 2,
      "display_order": 2,
      "field_name": "signinghub_initials_xyz",
      "page_no": 1,
      "embedded": true,
      "process_status": "PROCESSED",
      "processed_on": "2015-02-13T12:10:00",
      "processed_as": "COLLABORATOR",
      "processed_by": "abc@xyz.com",
      "dimensions": {
        "field": {
          "x": 200,
          "y": 200,
          "width": 200,
          "height": 300
        },
        "page": {
          "width": 200,
          "height": 300
        }
      }
 
    }
  ],
  "in_person_signature": [
    {
      "order": 1,
      "tab_order": 2,
      "display_order": 2,
      "field_name": "signinghub_initisls_xyz",
      "page_no": 1,
      "embedded": true,
      "process_status": "PROCESSED",
      "processed_on": "2015-02-13T12:10:00",
      "processed_as": "COLLABORATOR",
      "processed_by": "abc@xyz.com",
      "placeholder": "John Doe",
      "signature_sub_type": "WITNESS",
         "dimensions": {
        "field": {
          "x": 200,
          "y": 200,
          "width": 200,
          "height": 300
        },
        "page": {
          "width": 200,
          "height": 300
        }
        
      }
      
      "authentication": {
        "enabled": true,
        "sms_otp": {
          "enabled": true,
          "otp_length\": 4, retry_duration\"": 15,
          "mobile_number": "00445566778899"
        }
      },
       "verification": null,
        "display": "INVISIBLE"
    }
  ],
  "text": [
    {
      "order": 1,
      "tab_order": 2,
      "display_order": 2,
      "field_name": "SH_Name",
      "page_no": 1,
      "embedded": true,
      "type": "TEXT",
      "format": "dd/mm/yy",
      "align": "RIGHT",
      "value": "",
      "read_only": false,
      "visible": true,
      "multiline": true,
      "validation_rule": "MANDATORY",
      "max_length": 0,
      "format_type": "TEXT",
      "placeholder": "Name",
      "color": "#000000",
      "font": {
        "name": "HELVETICA",
        "size": 12,
        "embedded_size": 7.5
      },
 
      "dimensions": {
        "field": {
          "x": 200,
          "y": 200,
          "width": 200,
          "height": 300
        },
        "page": {
          "width": 200,
          "height": 300
        }
      }
    }
  ],
  "radio": [
    {
      "order": 1,
      "tab_order": 2,
      "display_order": 2,
      "field_name": "SH_Company",
      "page_no": 1,
      "embedded": true,
      "value": "",
      "read_only": false,
      "visible": true,
      "validation_rule": "MANDATORY",
      "radio_group_name": "radio button group name",
      "checked": true,
      "dimensions": {
        "field": {
          "x": 200,
          "y": 200,
          "width": 200,
          "height": 300
        },
        "page": {
          "width": 200,
          "height": 300
        }
      }
    }
  ],
  "checkbox": [
    {
      "order": 1,
      "tab_order": 1,
      "display_order": 2,
      "field_name": "SH_Company",
      "page_no": 1,
      "embedded": true,
      "read_only": false,
      "value": "",
      "checked": true,
      "visible": true,
      "validation_rule": "MANDATORY",
      "dimensions": {
        "field": {
          "x": 200,
          "y": 200,
          "width": 200,
          "height": 300
        },
        "page": {
          "width": 200,
          "height": 300
        }
      }
    }
  ],
  "dropdown": [
    {
      "order": 1,
      "tab_order": 1,
      "display_order": 2,
      "field_name": "SH_Field_Name",
      "page_no": 1,
      "embedded": true,
      "validation_rule": "MANDATORY",
      "read_only": false,
      "value": "Male",
      "choices": [
        "Male",
        "Female"
      ],
      "visible": true,
      "dimensions": {
        "field": {
          "x": 200,
          "y": 200,
          "width": 200,
          "height": 300
        },
        "page": {
          "width": 200,
          "height": 300
        }
      }
    }
  ],
  "listbox": [
    {
      "order": 1,
      "tab_order": 1,
      "display_order": 2,
      "field_name": "SH_Field_Name",
      "page_no": 1,
      "embedded": true,
      "validation_rule": "MANDATORY",
      "read_only": false,
      "value": "Male",
      "choices": [
        "Male",
        "Female"
      ],
      "visible": true,
      "dimensions": {
        "field": {
          "x": 200,
          "y": 200,
          "width": 200,
          "height": 300
        },
        "page": {
          "width": 200,
          "height": 300
        }
      }
    }
  ]
}
401

Unauthorized
{
  "Message": "Request authorization denied"
}
{
  "Message": "User authentication required"
}

403

Forbidden

{
  "Message": "Document does not belong to user"
}
{
  "Message": "Account is disabled"
}

404

Not Found

{
  "Message": "Document not found"
}

500

Internal Server Error

{
  "Message": "An internal server error occurred while processing the request"
}

The detail of each item provided in the request and response is provided below:

 Item Details
 Names
  Description
 Request Parameters:Top location of the field in pixel.
 access_token The access token obtained as a result of successful authentication. If "scope" parameter was used in authentication request, then this service requires the access token to be obtained using the credentials of an Enterprise admin whose enterprise role has the application integration privileges.
 package_id The ID of the package to which the document is added.
 document_id
 The ID of the document for which the fields are requested.
 
 page_no (optional) Page no of the document for which the fields are requested. If page number is not provided fields of whole document are returned.
 Response Parameters:
 Message
 The service specific error message returned by the API. This message provides useful information about why the service has returned an error response.
 digital_signature
 A list of all digital signatures in the document.
 digital_signature > order
 Order of the recipient to whom this field is assigned. If the field is not assigned to anyone, value will be null. 
 digital_signature > tab_order Tab order in the PDF document.
 digital_signature >  display_order Display order according to the SigningHub viewer.
 digital_signature > field_name
 Unique identifier of the field.
 digital_signature > page_no Page number of the document on which the field exists.
 digital_signature > embedded True, if field is part of the PDF document.
 digital_signature > type If field is assigned or not, possible values are ASSIGNED, UN_ASSIGNED, SIGNED, LOGGED_IN_USER, HIDDEN and PLACEHOLDER.
 digital_signature > process_status Whether the field is processed or not. Possible values are UN_PROCESSED, PROCESSED.
 digital_signature > processed_on Date time on which the document is processed.
 digital_signature > processed_as User who processed the field as COLLABORATOR, DELEGATEE, GROUP_MEMBER or OWNER.
 digital_signature > processed_by Email address of the user who processed the field.
 digital_signature > dimensions >  field > x

 Left location of the field in pixel.
 digital_signature > dimensions >  field > y

 Top location of the field in pixel.
 digital_signature > dimensions >  field > width

 Width of the field in pixel.
 digital_signature > dimensions >  field > height

 Height of the field in pixel.
 digital_signature > dimensions  > page > width

 Width of the page where field is placed in the PDF.
 digital_signature > dimensions >  page > height

 Height of the page where field is placed in the PDF.
digital_signature > verification Returns the verification response of signature field. In case of no verification, null is returned. 
 digital_signature > display Returns the visibility value of the digital signature field, possible values are "VISIBLE" and "INVISIBLE".
 hand_signature > order Order of the recipient to whom this field is assigned. If the field is not assigned to anyone, value will be null. 
 hand_signature > tab_order Tab order in the PDF document.
 hand_signature > display_order Display order according to the SigningHub viewer.
 hand_signature > field_name

 Unique identifier of the field.
 hand_signature > page_no Page number of the document on which the field exists.
 hand_signature > embedded

 True, if field is part of the PDF document.
 hand_signature > type
If field is assigned or not, possible values are ASSIGNED, UN_ASSIGNED, SIGNED, LOGGED_IN_USER, HIDDEN and PLACEHOLDER.
 hand_signature > process_status Whether the field is processed or not. Possible values are UN_PROCESSED, PROCESSED.
 hand_signature > processed_on
 Date time on which the document is processed.
 hand_signature > processed_as User who processed the field as COLLABORATOR,DELEGATEE,GROUP_MEMBER or OWNER.
 hand_signature > processed_by Email address of the user who processed the field.
 hand_signature > dimensions  > field > x

 Left location of the field in pixel.
 hand_signature > dimensions  > field > y
 Top location of the field in pixel.
 hand_signature > dimensions  > field > width

 Width of the field in pixel.
 hand_signature > dimensions  > field > height Height of the field in pixel.
 hand_signature > dimensions  > page > width

 Width of the page where field is placed in the PDF.
 hand_signature > dimensions  > page > height

 Height of the page where field is placed in the PDF.
 electronic_signature > order Order of the recipient to whom this field is assigned. If the field is not assigned to anyone, value will be null. 
 electronic_signature > tab_order Tab order in the PDF document.
  electronic_signature  > display_order

 Display order according to the SigningHub viewer.
 electronic_signature  > field_name

 Unique identifier of the field.
 electronic_signature > page_no Page number of the document on which the field exists.
 electronic_signature  > embedded

 True, if field is part of the PDF document.
  electronic_signature > type
If field is assigned or not, possible values are ASSIGNED, UN_ASSIGNED, SIGNED, LOGGED_IN_USER, HIDDEN and PLACEHOLDER.
  electronic_signature  > process_status
 Whether the field is processed or not. Possible values are UN_PROCESSED, PROCESSED.
  electronic_signature  > processed_on

Date time on which the document is processed.
  electronic_signature  > processed_as User who processed the field as COLLABORATOR,DELEGATEE,GROUP_MEMBER or OWNER.
 electronic_signature  > processed_by

Email address of the user who processed the field.
 electronic_signature  > signature_sub_type The signature sub-type can be a WITNESS signature. If witness signatures are enabled in service plan, E-Signature fields are signed with a common certificate shared by all the users in the service plan. Possible values are WITNESS or NONE.
 electronic_signature   > dimensions > field > x

 Left location of the field in pixel.
 electronic_signature   > dimensions > field > y

 Top location of the field in pixel.
 electronic_signature   > dimensions > field > width

 Width of the field in pixel.
 electronic_signature   > dimensions > field > height

 Height of the field in pixel.
 electronic_signature   > dimensions > page > width

 Width of the page where field is placed in the PDF.
 electronic_signature   > dimensions > page > height

 Height of the page where field is placed in the PDF.
 electronic_signature   > authentication > enabled True,  if authentications are enabled for the electronic signature fields.
 electronic_signature   > authentication > sms_otp  > enabled

 True, if SMS OTP authentication is enabled for the electronic signature fields.
 electronic_signature   > authentication > sms_otp  > mobile_number
 Mobile number of the recipient to whom the field is assigned. SMS OTP is sent on this number for authentication.
 electronic_signature  > verification  Returns the verification response of the field. In case of no verification, null is returned.   
 electronic_signature  > display Returns the visibility value of the electronic signature field, possible values are "VISIBLE" and "INVISIBLE". 
 initials > order Order of the recipient to whom this field is assigned. If the field is not assigned to anyone, value will be null. 
 initials > tab_order

 Tab order in the PDF document.
 initials > display_order Display order according to the SigningHub viewer.
 initials > field_name

 Unique identifier of the field.
 initials > page_no Page number of the document on which the field exists.
 initials > embedded

 True, if field is part of the PDF document.
 initials > process_status Whether the field is processed or not. Possible values are UN_PROCESSED, PROCESSED.
 initials > processed_on Date time on which the document is processed.
 initials > processed_as User who processed the field as COLLABORATOR,DELEGATEE,GROUP_MEMBER or OWNER.
 initials > processed_by Email address of the user who processed the field.
 initials > dimensions > field > x

 Left location of the field in pixel.
 initials > dimensions > field > y 

 Top location of the field in pixel.
 initials > dimensions > field >  width

 Width of the field in pixel.
 initials > dimensions > field >  height

 Height of the field in pixel.
 initials > dimensions > page >  width

 Width of the page where field is placed in the PDF.
 initials > dimensions > page >  height

 Height of the page where field is placed in the PDF.
 in_person_signature > order Order of the recipient to whom this field is assigned. If the field is not assigned to anyone, value will be null. 
 in_person_signature > tab_order

 Tab order in the PDF document.
 in_person_signature  > display_order Display order according to the SigningHub viewer.
 in_person_signature > field_name Unique identifier of the field.
 in_person_signature > page_no Page number of the document on which the field exists.
 in_person_signature > embedded True, if field is part of the PDF document.
 in_person_signature  > process_status Whether the field is processed or not. Possible values are UN_PROCESSED, PROCESSED.
 in_person_signature  > processed_on Date time on which the document is processed.
 in_person_signature  > processed_as User who processed the field as COLLABORATOR,DELEGATEE,GROUP_MEMBER or OWNER.
 in_person_signature  > processed_by Email address of the user who processed the field.
 in_person_signature  > placeholder Name of the in-person signer or placeholder e.g., Customer, Sales Representative etc.
 in_person_signature  > signature_sub_type The signature sub-type for in-person signatures can be a WITNESS signature. If witness signatures are enabled in service plan, In-person fields are signed with a common certificate shared by all the users in the service plan. Possible values are WITNESS or NONE.
 in_person_signature  > dimensions > field > x

 Left location of the field in pixel.
 in_person_signature  > dimensions > field > y

 Top location of the field in pixel.
 in_person_signature  > dimensions > field > width

 Width of the field in pixel.
  in_person_signature  > dimensions > field > height

 Height of the field in pixel.
 in_person_signature  > dimensions > page > width

 Width of the page where field is placed in the PDF.
  in_person_signature  > dimensions > page > height Height of the page where field is placed in the PDF.
 in_person_signature  > authentication> enabled True,  if authentications are enabled for the electronic signature fields.
 in_person_signature  > authentication> sms_otp  > enabled

 True, if SMS OTP authentication is enabled for the electronic signature fields.
 in_person_signature  > authentication> sms_otp  > mobile_number

 Mobile number of the recipient to whom the field is assigned. SMS OTP is sent on this number for authentication.
 in_person_signature > verification Returns the verification response of inperson field. In case of no verification, null is returned.
 in_person_signature > display Returns the visibility value of the inperson field, possible values are "VISIBLE" and "INVISIBLE".
 text > order Order of the recipient to whom this field is assigned. If the field is not assigned to anyone, value will be null. 

 text > tab_order

 Tab order in the PDF document
 text > display_order
 Display order according to the SigningHub viewer.
 text > field_name Unique identifier of the field.
 text > page_no
 Page number of the document on which the field exists.
 text > embedded
 True, if field is part of the PDF document.
 text > type
 Type of the text field, possible values are "TEXT", "NAME", "COMPANY", "JOBTITLE", "EMAIL", "DATE".
 text > format  Text format of the field. Used for the date type field only. Possible values are

  • m/d

  • m/d/yy

  • m/d/yyyy

  • mm/dd/yy

  • mm/dd/yyyy

  • mm/yy

  • mm/yyyy

  • d-mmm

  • d-mmm-yy

  • d-mmm-yyyy

  • dd-mmm-yy

  • dd-mmm-yyyy

  • yy-mm-dd

  • yyyy-mm-dd

  • mmm-yy

  • mmm-yyyy

  • mmmm-yy

  • mmmm-yyyy

  • mmmm d, yyyy

  • dd/mm/yy
 text > align Text alignment for the form field. Possible values are "RIGHT", "LEFT", "CENTER" or "JUSTIFY"
 text > value
 Value of the field.
For type=DATE or format_type=DATE, the value is expected to follow ISO 8601 format. Following the format YYYY-MM-DD hh:mm:ss +00. As the values are for date fields client applications can send YYYY-MM-DD and ignore hh:mm:ss +00. If value is not in proper format an error will be returned. 
 text > read_only True, if the field is marked read only in the PDF document.
 text > visible True, if the field is not hidden in the PDF document.
 text > multiline True, if the field is multi line in the PDF document.
 text > validation_rule One or more rules for validation of the fields, possible values are "MANDATORY" or "OPTIONAL".
 text > max_length Maximum content length allowed to be filled in the field.
 text > format_type If field is a textbox it can follow different input types. Possible values are ALPHANUMERIC, NUMBER, TEXT, EMAIL, TIME or DATE. 
 text > placeholder
 Placeholder text for the textbox field.
 text > color Color of the text in the form fields. 
 text > font > name Font name for the text field. For user defined fields SigningHub only support "COURIER", "HELVETICA". In case of existing fields in a PDF file, font value can be anything that is set in the PDF. 
 text > font > size  Font size for the text field.
 text > font > embedded_size Size of the font in the original PDF document. 
 text > dimensions > field > x Left location of the field in pixel.
 text > dimensions > field > y  Top location of the field in pixel.
 text > dimensions > field > width
 Width of the field in pixel.
 text > dimensions > field >  height

 Height of the field in pixel.
 text > dimensions > page >  width

 Width of the page where field is placed in the PDF.
 text > dimensions > page >  height  Height of the page where field is placed in the PDF.
 radio > order Order of the recipient to whom this field is assigned. If the field is not assigned to anyone, value will be null. 
 radio > tab_order Tab order in the PDF document.
 radio > display_order Display order according to the SigningHub viewer.
 radio > field_name Unique identifier of the field.
 radio > page_no Page number of the document on which the field exists.
 radio > embedded True, if field is part of the PDF document.
 radio > value Value of the field.
 radio > read_only True, if the field is marked readonly in the PDF document.
 radio > visible True if the field is not hidden in the PDF document.
 radio > validation_rule One or more rules for validation of the fields possible values are "MANDATORY" or "OPTIONAL".
 radio > radio_group_name The group name to which the field belongs.
 radio > checked True, if the field is selected
 radio > dimensions > field > x Left location of the field in pixel.
 radio > dimensions > field > y Top location of the field in pixel.
 radio > dimensions > field >  width

 Width of the field in pixel.
 radio > dimensions > field >  height

 Height of the field in pixel.
 radio > dimensions > page >  width

 Width of the page where field is placed in the PDF
 radio > dimensions > page > height Height of the page where field is placed in the PDF.
 checkbox > order Order of the recipient to whom this field is assigned. If the field is not assigned to anyone, value will be null. 
 checkbox > tab_order Tab order in the PDF document
 checkbox > display_order Display order according to the SigningHub viewer.
 checkbox > field_name

 Unique identifier of the field.
 checkbox > page_no Page number of the document on which the field exists.
 checkbox > embedded True, if field is part of the PDF document.
 checkbox > read_only True, if the field is marked read only in the PDF document.
 checkbox > value Value of the field.
 checkbox > checked True if the field is selected.
 checkbox > visible True if the field is not hidden in the PDF document.
 checkbox > validation_rule One or more rules for validation of the fields possible values are "MANDATORY" or "OPTIONAL".
 checkbox > dimensions > field >  x

 Left location of the field in pixel.
 checkbox > dimensions > field >  y

 Top location of the field in pixel.
 checkbox > dimensions > field >  width

 Width of the field in pixel.
 checkbox > dimensions > field >  height

 Height of the field in pixel.
 checkbox > dimensions > page >  width

 Width of the page where field is placed in the PDF.
 checkbox > dimensions > page >  height

 Height of the page where field is placed in the PDF.
 dropdown > order Order of the recipient to whom this field is assigned. If the field is not assigned to anyone, value will be null. 
 dropdown > tab_order Tab order in the PDF document.
 dropdown > display_order Display order according to the SigningHub viewer.
 dropdown > field_name Unique identifier of the field.
 dropdown > page_no Page number of the document on which the field exists.
 dropdown > embedded True, if field is part of the PDF document.
 dropdown > validation_rule One or more rules for validation of the fields possible values are "MANDATORY" or "OPTIONAL".
 dropdown > read_only True, if the field is marked read only in the PDF document.
 dropdown > value Value of the field .
 dropdown > choices  Choices available for the dropdown to choose a value from.
 dropdown > visible True, if the field is not hidden in the PDF document.
 dropdown > dimensions > field  > x

 Left location of the field in pixel.
 dropdown > dimensions > field  > y

 Top location of the field in pixel.
 dropdown > dimensions > field  > width

 Width of the field in pixel.
 dropdown > dimensions > field  > height

 Height of the field in pixel.
 dropdown > dimensions > page  > width

 Width of the page where field is placed in the PDF.
 dropdown > dimensions > page  > height

 Height of the page where field is placed in the PDF.
 listbox > order Order of the recipient to whom this field is assigned. If the field is not assigned to anyone, value will be null.  
 listbox > tab_order

 Tab order in the PDF document.
 listbox > display_order Display order according to the SigningHub viewer.
 listbox > field_name Unique identifier of the field.
 listbox > page_no Page number of the document on which the field exists.
 listbox > embedded True, if field is part of the PDF document.
 listbox > validation_rule One or more rules for validation of the fields possible values are "MANDATORY" or "OPTIONAL".
 listbox > read_only True, if the field is marked read only in the PDF document.
 listbox > value

 Value of the field.
 listbox > choices Choices available for the dropdown to choose a value from.
 listbox > visible True, if the field is not hidden in the PDF document.
 listbox > dimensions > field > x Left location of the field in pixel.
 listbox > dimensions > field > y Top location of the field in pixel.
 listbox > dimensions > field >  width

 Width of the field in pixel.
 listbox > dimensions > field >  height

 Height of the field in pixel.
 listbox > dimensions > page >  width

 Width of the page where field is placed in the PDF.
 listbox > dimensions > page >  height

 Height of the page where field is placed in the PDF.






See also
Assign Document Field
Add Digital Signature Field
Add Electronic Signature Field
Add In-person Field
Add Initials Field
Add TextBox Field
Add RadioBox Field
Add CheckBox Field
Autoplace Fields
Update Digital Signature Field
Update Electronic Signature Field
Update In-person Field
Update Initials Field
Update TextBox Field
Update RadioBox Field
Update CheckBox Field
Delete Document Field