Upload document

URL

POST http://api.sign.net:8000/signing/upload

Parameters

HeaderTypeDescription
AuthorizationstringBearer API Key of the user account to be retrieved from. Can be retrieved from the user's profile page.
BodyTypeDescription
viewerobjectA string array of viewer objects (see full object types below

Viewers can view a document and its signatures but are not allowed to sign or edit the document

If there is no viewer for the document, leave this as a string empty array.
signer objectA string array of signer objects (see full object type below)

Signers are given specific annotation fields to fill in that is specified by the document owner. Once all of the signer's annotations have been filled in (i.e. verified), the document is considered signed by the signer.

If there are no signers for the document, leave this as a string empty array.
ownerEmailstringAccount Email of the document owner.
domainstringDomain to upload the document to.

If the document is to be uploaded to a user's business account, the domain will be the user's business domain name (e.g. companyname.sign.net). Otherwise, if it's just for the user's personal account, the domain should be app.sign.net
titlestringTitle of document.

This title will be displayed to users, not filename
fileNamestringName of the PDF file being uploaded.
fileobjectThe PDF file of the document to be signed. Has to be less than 10MB in size.
additionalMsgstringOptional additional signing message
requireNotarisationboolEnable or disable notarisation
passcodeinteger4-8 numeric characters
dueDatestringDocument signature due date in 'dd-mm-yyyy' format

viewer object

bodytypedescription
emailstringThe email of the viewer
firstNamestringThe first name of the viewer
lastNamestringThe last name of the viewer

signer object

bodytypedescription
domainstringThe domain of the signer.
emailstringThe email of the signer.
firstNamestringThe first name of the signer.
lastNamestringThe last name of the signer.
signOrdernumberThe sign order of the signer. This will determine which signer will sign first and which will sign last. a smaller number will sign first and a larger number will sign after. If signing order does not matter, please put all of the signOrder as the same number.
annotationsobjectThe edits to be made on the document (e.g adding a signature, or a date, or a name, etc)

annotations

bodytypedescription
ifVerifiedbooleanWhether the annotation is signed and approved and verified by signer.
typestringThe type of the annotation. E.g. Name, Date, Text, Stamp or Signature.
contentstringThe content of the annotation.
E.g. if it is a name type annotation, then the content will the name.

For Signature type annotation, the content is either "Signature" if isVerified is set to false.

Example:
"type":"Signature",
"content":"Signature",
"isVerified":false,

If isVerified is set to True, the content has to be "Signature Id"
Note: signature id can be obtained from <<http://api.sign.net:8000/signing/signature-list>> endpoint. See more at https://docs.sign.net/docs/annotations#listsignatures

Example:
"type":"Signature",
"content":"96b6af56dbf04a0db443bc62554bd76d.png",
"isVerified":true,
styleobjectStyle affects how will the annotation look like.

style

bodytypedescription
widthnumberThe size of the Name/Date/Text/Stamp/Signature in terms of width.
heightnumberThe size of the Name/Date/Text/Stamp/Signature in terms of height.
xnumberx determine where the annotation will be placed on the document horizontally.
ynumberx and y determine where the annotation will be placed on the document vertically.
pagenumberIf your document has multiple pages, the "page" parameter will determine which page the annotation will be placed.
fontSizestringThe font size of the annotation (Name/Date/Text/Stamp/Signature)

Parameters example

Postman Example

{
    "viewer" :[
       {
        "email": "[email protected]",
        "firstName": "viewer",
        "lastName": "test"
        }
              ],
    "signer" :
    [
      {
        "domain": "app.sign.net", 
        "email": "[email protected]",
        "firstName": "John",
        "lastName": "Doe",
        "signOrder": 1,
        "annotations": [ {
            "isVerified": false,
            "type": "Signature",
            "content": "Signature",
            "style": {
                "width": 10,
                "height": 10,
                "x": 10,
                "y": 10,
                "page": 10,
                "fontSize": "0pt"
            }
        } 
      ]
    }
  ],
    "ownerEmail" : "[email protected]",
    "domain" : "app.sign.net",
    "title" : "title",
    "fileName" : "test",
    "file" : object
}

Full sample example

Parameters type

type Params = {
  domain: string | null,
  title: string,
  fileName: string,
  ownerEmail: string,
  signers: Array<ParamSigner>,
  viewers: Array<ParamViewer>
};

type ParamSigner = {
  annotations: Array<ParamAnnotation>
} & SignerField;

type ParamAnnotation = {
  type: AnnotationTypes,
  content: string
} & AnnotationField;

type AnnotationTypes = "Name" | "Date" | "Stamp" | "Signature"  | 'NonEditableText'
  | 'EditableText' | "Email" ;

type ParamViewer = {
  email: string,
  firstName: string,
  lastName: string
};

type SignerField = {
  domain: string | null,
  email: string,
  firstName: string,
  lastName: string,
  signOrder: number
};

type AnnotationField = {
  isVerified: boolean,
  style: Style
};

type Style = {
  width: number,
  height: number,
  x: number,
  y: number,
  page: number,
  fontSize?: string | null
};

Response type

type ResponseData = {
  result: {
    message: string
    docId: string
  }
}

If the upload of the document is successful

{
  "status": "OK",
  "data":{
     "message": 'Insert document successfully.',
     "docId": "qwerty123"
  }
}

Error codes

INVALID_API_KEYInvalid internal API key. The internal API keys does not match.
INVALID_USER_API_KEYThe user API key provided does not match any existing records.
NO_PERMISSIONThe user does not have the permissions to perform this function.
INVALID_DATAThere are missing data, or data provided was invalid
NO_FILE_ATTACHEDThere are no files attached(one of the parameters)
MISSING_BODYThere are no input of parameters(body)

If missing or invalid data is provided in the parameters

{
    "status" : "Err",
    "error" : {
        "code" : "INVALID_DATA",
        "message" : "Missing or invalid data provided"
    }
}

If no file is attached

{
    "status" : "Err",
    "error" : {
        "code" : "NO_FILE_ATTACHED",
        "message" : "no file attached"
    }
}
{
    "status" : "Err",
    "error" : {
        "code" : "MISSING_BODY",
        "message" : "Missing request body"
    }
}

If no parameters is entered



Examples of different scenarios for uploading document

Difference in these scenarios lies in the signers object in the request body of the API request.

Scenario 1 : Self sign a document with completed annotations

Use case: Sender is uploading a document with himself as a signer and filling it in with verified completed annotations.

Signature content can be obtain from with get signature list API (get the id e.g. 891289219823213.png). Refer to https://docs.sign.net/docs/annotations#listsignatures

Sender: [email protected]

Signers: [email protected]

viewers: none

Document is completed, user will receive an email with the completed document attached.

{
  "domain": "app.sign.net",
  "title": "demoAPI",
  "fileName": "demo.pdf",
  "ownerEmail": "[email protected]",
  "signers": [
    {
      "annotations": [
        {
          "type": "Signature",
          "content": "96b6af56dbf04a0db443bc62554bd76d.png",
          "isVerified": true,
          "style": {
            "width": 150,
            "height": 100,
            "x": 55,
            "y": 249,
            "page": 1,
            "fontSize": "0pt"
          }
        }
      ],
      "domain": "app.sign.net",
      "email": "[email protected]",
      "firstName": "Nigel",
      "lastName": "Tay",
      "signOrder": 0
    }
  ],
  "viewers": "[]",
  "additionalMsg": "null",
  "dueDate": "null",
  "requireNotarisation": "false",
  "passcode": "null",
  "file": object
}

Scenario 2: Self sign a document with incomplete annotations (to be updated later)

Use case: Sender is uploading a document with himself as a signer. Document is not completed, user can update it via API, from app.sign.net or simply click the link in your email.

Sender: [email protected]

Signers: [email protected]

viewers: none

Document is uploaded, user can now sign it to update it.

{
  "domain": "app.sign.net",
  "title": "demoAPI",
  "fileName": "demo.pdf",
  "ownerEmail": "[email protected]",
  "signers": [
    {
      "annotations": [
        {
          "type": "Signature",
          "content": "Signature",
          "isVerified": true,
          "style": {
            "width": 150,
            "height": 100,
            "x": 55,
            "y": 249,
            "page": 1,
            "fontSize": "0pt"
          }
        }
      ],
      "domain": "app.sign.net",
      "email": "[email protected]",
      "firstName": "Nigel",
      "lastName": "Tay",
      "signOrder": 0
    }
  ],
  "viewers": "[]",
  "additionalMsg": "null",
  "dueDate": "null",
  "requireNotarisation": "false",
  "passcode": "null",
  "file": object
}

Scenario 3: Sending out a document to another recipient for signing

Use case - Sender ([email protected]) is sending out this pdf document to signer([email protected]) to sign. Signer is required to fill in the following annotations - Signature, Editable text and Date.

Sender: [email protected]

Signers: [email protected]

viewers: none

{
  "domain": "app.sign.net",
  "title": "demoAPI",
  "fileName": "demo.pdf",
  "ownerEmail": "[email protected]",
  "signers": [
    {
      "annotations": [
        {
          "type": "Signature",
          "content": "Signature",
          "isVerified": false,
          "style": {
            "width": 150,
            "height": 100,
            "x": 380,
            "y": 502,
            "page": 1,
            "fontSize": "0pt"
          }
        },
        {
          "type": "EditableText",
          "content": "D.O. number",
          "isVerified": false,
          "style": {
            "width": 237,
            "height": 50,
            "x": 86,
            "y": 366,
            "page": 1,
            "fontSize": "16pt"
          }
        },
        {
          "type": "Date",
          "content": "Date",
          "isVerified": false,
          "style": {
            "width": 150,
            "height": 25,
            "x": 383,
            "y": 621,
            "page": 1,
            "fontSize": "16pt"
          }
        }
      ],
      "domain": "app.sign.net",
      "email": "[email protected]",
      "firstName": "Client",
      "lastName": "example",
      "signOrder": 0
    }
  ],
  "viewers": "[]",
  "additionalMsg": "null",
  "dueDate": "null",
  "requireNotarisation": "false",
  "passcode": "null",
  "file": object
}

Get Sent Documents

Retrieves a list of the user's sent documents

http://api.sign.net:8000/signing/view/sent-documents
Request BodyData TypeDescription
domainstringDomain to query for sent documents.

Expected Result

Update Document

POST http://api.sign.net:8000/signing/sign

Updates a document annotations

Request BodyData typeDescription
docIdstringDocument ID of document to update annotations.
domainstringDomain where user belongs to.
annotationsAnnotation Object ArrayAnnotations to update the document with. Can have multiple annotations in the array.
docPasswordstring (optional)Password to accesss Document, if any,

Annotation Object

KeyData TypeDescription
idstringID of annotation to update.
contentstringContent of annotation field converted to string.

Sample Request

Expected Response

viewDocument

URL

http://api.sign.net:8000/signing/view-document

The viewDocument function helps retrieve a document and its relevant information based on a document ID specified by the user.

Input Parameters

Parameters Type

userApiKey: string
  docId: string
  domain: string

Parameters Explanation

HeaderTypeDescription
AuthorizationstringBearer API Key of the user account to be retrieved from. Can be retrieved from the user's profile page.
BodyTypeDescription
docIdstringThe docId parameter will be inputted by the user. This is the ID of the document that they would want to retrieve.
domainstringThe domain parameter will be inputted by the user. This is the domain which the user belongs in.

Parameters Example

To start off, we will first have to input the user's personal API key, which can be done by:
Going to the Authorization tab>Choosing 'Bearer Token'>Inputting user API key as the token

Next, we will need to input the document ID of the document that we want to retrieve, as well as the domain of the user. To do this, navigate to the body tab before inputting the needed parameters.

Response

Response Type

type ResponseData = {
  logs: ResponseLog[]
  domainOwners: DomainOwner[]
  ownerShareReferralCode: string
} & ViewDocument

Response Example

{
    "status": "OK",
    "data": {
        "document": {
            "id": "12345",
            "title": "Title1",
            "ownerId": "fa8302",
            "domain": "app.sign.net",
            "createdAt": 1633322731440,
            "updatedAt": 1633322731440,
            "isDocumentEncrypted": false,
            "firstName": "John",
            "lastName": "Lim",
            "email": "[email protected]",
            "dueDate": null,
            "ownerTrustScore": 0,
            "additionalMsg": null,
            "requireNotarisation": false,
            "notarisationStatus": null,
            "transactionHash": null,
            "merkleRoot": null,
            "notarisationTimeStamp": null,
            "verifyPassbase": false,
            "verifyMyInfo": false,
            "verifyMobilePhone": false,
            "verifyStripe": false,
            "verifyWallet": false,
            "passcode": null,
            "checksum": "dnqweienqq48y238ndjwekd",
            "notarisationNetwork": null,
            "paymentMethod": null,
            "templateId": null
        },
        "recipients": [
            {
                "userId": "fa8302",
                "firstName": "john",
                "lastName": "lim",
                "signOrder": 0,
                "trustScore": 0,
                "status": "Active",
                "email": "[email protected]",
                "verifyPassbase": false,
                "verifyMyInfo": false,
                "verifyMobilePhone": false,
                "verifyStripe": false,
                "verifyWallet": false,
                "role": null
            }
        ],
        "annotations": [
            {
                "id": "dhua28",
                "type": {
                    "type": "Signature",
                    "filePath": "123abc.png"
                },
                "isVerified": true,
                "content": "123abc.png",
                "width": 150,
                "height": 100,
                "x": 700.423,
                "y": 128.542,
                "page": 1,
                "fontSize": "0pt",
                "userId": "f530a4",
                "docId": "276df4b023ce41a4a4a7ecbf1a8b7b98",
                "email": "[email protected]"
            },
            {
                "id": "6a05a8",
                "type": {
                    "type": "Stamp",
                    "filePath": "app.sign.net/stampabc.png"
                },
                "isVerified": true,
                "content": "app.sign.net/stampabc.png",
                "width": 150,
                "height": 150,
                "x": 699.3678,
                "y": 140.08456,
                "page": 1,
                "fontSize": "0pt",
                "userId": "f530a4",
                "docId": "276df4",
                "email": "[email protected]"
            }
        ],
        "logs": [
            {
                "userId": "f530a4",
                "action": "View",
                "createdAt": 1639362972958,
                "ipAddr": "192.168.3.82",
                "credentialName": null
            },
            {
                "userId": "f530a4",
                "action": "View",
                "createdAt": 1636700190772,
                "ipAddr": "192.168.3.8",
                "credentialName": null
            },
        ],
        "domainOwners": [],
        "ownerShareReferralCode": "sign_denq0q92328"
    }
}

Response Data Explanation

Response DataTypeDescription
ViewDocumentdocumentThe document information which includes all the information included in the document schema, as well as the annotations and recipients of the document.
domainOwnersDomainOwner[]The domain owners of the domain in which the document belongs in.
logsResponseLog[]The log files of all the activity of the document, such as viewing activity.
ownerShareReferralCodestringThe referral code of the owner of the document.

Error Response Example

{
  "status": "Err",
  "error":{
    "code": "INVALID_DOC_ID",
    "message": "Invalid document ID provided"
  }
}

Error Code Explanation

ErrorDescription
INVALID_API_KEYInvalid internal API key. The internal API keys does not match.
INVALID_DOC_IDThe document that matches the provided document ID could not be found/retrieved.

Summary Table

EndpointInputExpected OutputRemarks
viewDocumentTyping {
internalApiKey: string
userApiKey: string
data: {
docId: string
domain: string
}
}
User inputs their API key, which can be found under their account settings.

User inputs the document ID of the specific document in which he or she wants to view.

User inputs the domain that the user belongs in.
Typing: {
logs: ResponseLog[]
domainOwners: DomainOwner[]
ownerShareReferralCode: string} & ViewDocument

Successful response:
• creates a log entry stating that user X successfully viewed document X.
• returns a string of the domain owner(s) for the requested document
• returns the domain/document owner’s referral code
• returns the document along with the recipients and annotations
Example of successful response:
{
"status": "OK",
"data": {
"document": {
"id": "12345",
"title": "Title1",
"ownerId": "fa8302",
"domain": "app.sign.net",
"createdAt": 1633322731440,
"updatedAt": 1633322731440,
"isDocumentEncrypted": false,
"firstName": "John",
"lastName": "Lim",
"email": "[email protected]",
"dueDate": null,
"ownerTrustScore": 0,
"additionalMsg": null,
"requireNotarisation": false,
"notarisationStatus": null,
"transactionHash": null,
"merkleRoot": null,
"notarisationTimeStamp": null,
"verifyPassbase": false,
"verifyMyInfo": false,
"verifyMobilePhone": false,
"verifyStripe": false,
"verifyWallet": false,
"passcode": null,
"checksum": "dnqweienqq48y238ndjwekd",
"notarisationNetwork": null,
"paymentMethod": null,
"templateId": null
},
"recipients": [
{
"userId": "fa8302",
"firstName": "john",
"lastName": "lim",
"signOrder": 0,
"trustScore": 0,
"status": "Active",
"email": "[email protected]",
"verifyPassbase": false,
"verifyMyInfo": false,
"verifyMobilePhone": false,
"verifyStripe": false,
"verifyWallet": false,
"role": null
}
],
"annotations": [
{
"id": "dhua28",
"type": {
"type": "Signature",
"filePath": "123abc.png"
},
"isVerified": true,
"content": "123abc.png",
"width": 150,
"height": 100,
"x": 700.423,
"y": 128.542,
"page": 1,
"fontSize": "0pt",
"userId": "f530a4",
"docId": "276df4",
"email": "[email protected]"
},
{
"id": "6a05a8",
"type": {
"type": "Stamp",
"filePath": "app.sign.net/stampabc.png"
},
"isVerified": true,
"content": "app.sign.net/stampabc.png",
"width": 150,
"height": 150,
"x": 699.3678,
"y": 140.08456,
"page": 1,
"fontSize": "0pt",
"userId": "f530a4",
"docId": "276df4",
"email": "[email protected]"
}
],
"logs": [
{
"userId": "f530a4",
"action": "View",
"createdAt": 1639362972958,
"ipAddr": "192.168.3.82",
"credentialName": null
},
{
"userId": "f530a4",
"action": "View",
"createdAt": 1636700190772,
"ipAddr": "192.168.3.8",
"credentialName": null
},
],
"domainOwners": [],
"ownerShareReferralCode": "sign_denq0q92328"
}
}