Integration codes
Using the REST API to create all the resources needed to set up a signing process can be cumbersome in some cases. And some times you need to communicate data about the signing process between components of your system that don't talk directly to Penneo.
That is why we have created a structured data format to relay information about a signing process in a uniform way. We call it integration codes. If you stick to this format, you will be able to talk to different Penneo components and pre-configure your signing process without going through the REST API.
You can read more about the different ways you can use the integration codes in the subsections.
Below you can see the JSON schema that is the technical description of the integration code format. We recommend that you always use the current version if you are beginning a new project.
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"title": "Penneo Desktop Application JSON Schema v2.0.0",
"description": "A merge code that creates a case in the Penneo application ready for shipping",
"properties": {
"schemaVersion": {
"type": "string",
"description": "JSON Schema Version",
"enum" : ["2.0.0"]
},
"clearData": {
"type": "boolean",
"description": "Clear any data already typed in the application before loading JSON data",
"default": false
},
"templateId": {
"type": ["integer", "string"],
"description": "Identifier or name of case file type"
},
"name": {
"type": "string",
"description": "Name of case file"
},
"language": {
"type": "string",
"enum": [
"en",
"da",
"no",
"sv"
],
"description": "Case file language"
},
"folderId": {
"type": ["integer", "string"],
"description": "Id or a name of a folder where the casefile will be stored on the server."
},
"visibilityMode": {
"type": "string",
"enum": [
"all_documents",
"certain_documents"
],
"description": "Determines what documents the signer could see. All of the docs from the case or only those that he has to sign"
},
"signOnMeeting": {
"type": "boolean",
"description": "Enables sign at the meeting for this case file"
},
"sendAt": {
"type": "string",
"description": "ISO-8601 Date/Time format to specify when case file will be sent"
},
"expireAt": {
"type": "string",
"description": "ISO-8601 Date/Time format to specify when case file will expire"
},
"messageTemplate": {
"type": "string",
"description": "Name of an email template that has been chosen."
},
"messageSubject": {
"type": "string",
"description": "Subject/title of an email that will be send to all the signers."
},
"messageText": {
"type": "string",
"description": "Email message that will be send to all the signers."
},
"metaData": {
"type": "string"
},
"sendAt": {
"type": "string",
"description": "Date of sending the emails."
},
"documents": {
"type": "array",
"description": "Documents (in PDF format) attached to the casefile, to be signed",
"items": {
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "A human readable description of the document."
},
"typeId": {
"type": ["integer", "string"],
"description": "A unique indentifier or a name of a document type."
},
"localPath": {
"type": "string",
"description": "Path to the file: Supports both local files and online resources."
},
"metaData": {
"type": "string"
}
}
},
"required": [
"name",
"localPath"
]
},
"signers": {
"type": "array",
"description": "Signers that need to sign documents and will receive email message",
"items": {
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "Signers name."
},
"email": {
"type": "string",
"description": "Signers email address."
},
"onBehalfOf": {
"type": "string"
},
"ssn": {
"type": ["string", "integer"],
"minLength": 10,
"maxLength": 12,
"pattern": "^(\\d[+-A]?){9,12}[0-9A-Z]?$",
"description": "Social security number"
},
"vatid": {
"type": ["integer", "string"],
"description": "Only allow a signer that maps to the provided company VAT number to sign the documents",
"minLength": 8,
"maxLength": 8
},
"isPrivate": {
"type": "boolean"
},
"reminderInterval": {
"type": ["integer", "string"],
"description": "Defines how often (in days) an email reminder about signing documents should be send."
},
"enableTouch": {
"type": "boolean",
"description": "Determines if Touch Signatures are enabled for a signer"
},
"roles": {
"type": "array",
"description": "An array of IDs of signer's roles in the case file",
"items": {
"type": ["integer", "string"],
"description": "A unique indentifiers or names for signers roles."
}
}
}
}
},
"copyRecipients": {
"type": "array",
"description": "Recipients that will receive a copy of a casefile",
"items": {
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "Copy recipient name"
},
"email": {
"type": "string",
"description": "Copy recipient email"
}
},
"required": [
"name",
"email"
]
}
},
"submitWhenReady": {
"type": "boolean",
"description": "Defines if the case is ready to be submited or should be edited."
},
"fileReference": {
"type": "string",
"description": "A path to a reference file"
},
"deleteFileReference": {
"type": ["boolean", "string"],
"description": "Defines if the file will be deleted after it will be used"
}
}
}
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"title": "Penneo Desktop Application JSON schema v.1.0.0",
"description": "A merge code that creates a case in the Penneo application ready for shipping.",
"properties": {
"Template": {
"type": ["string", "null"],
"description": "A unique indentifier for a casefile type."
},
"Name": {
"type": ["string", "null"],
"description": "Name of a case."
},
"Folder": {
"type": ["string", "null"],
"description": "Id of a folder where the casefile will be stored on the server."
},
"VisibilityMode": {
"type": ["string", "null"],
"description": "-----UNDEFINED-----"
},
"MessageTemplate": {
"type": ["string", "null"],
"description": "Name of an email template that has been chosen."
},
"MessageSubject": {
"type": ["string", "null"],
"description": "Subject/title of an email that will be send to all the signers."
},
"MessageText": {
"type": ["string", "null"],
"description": "Email message that will be send to all the signers."
},
"MetaData": {
"type": ["string", "null"],
"description": "-----UNDEFINED-----"
},
"SendAt": {
"type": ["string", "null"],
"description": "Date of sending the emails."
},
"Documents": {
"type": ["array", "null"],
"description": "Documents (in PDF format) attached to the casefile, to be signed.",
"items": {
"type": "object",
"properties": {
"Name": {
"type": ["string", "null"],
"description": "A human readable description of the document."
},
"Type": {
"type": ["string", "null"],
"description": "A unique indentifier for a document type."
},
"LocalPath": {
"type": ["string", "null"],
"description": "Path to the file: Supports both local files and online resources."
},
"MetaData": {
"type": ["string", "null"],
"description": "-----UNDEFINED-----"
}
}
},
"required": [
"Name",
"LocalPath"
]
},
"Signers": {
"type": ["array", "null"],
"description": "Signers that need to sign documents and will receive email message.",
"items": {
"type": ["object", "null"],
"properties": {
"Name": {
"type": ["string", "null"],
"description": "Signers name."
},
"Email": {
"type": ["string", "null"],
"description": "Signers email address."
},
"OnBehalfOf": {
"type": ["string", "null"],
"description": "-----UNDEFINED-----"
},
"SSN": {
"anyOf": [
{
"type": "string",
"minLength": 10,
"maxLength": 10
},
{
"type": "string",
"minLength": 0,
"maxLength": 0
},
{
"type": "null"
}
],
"description": "Only allow a signer that matches the provided social security number to sign the documents."
},
"VATID": {
"type": ["string", "null"],
"description": "Only allow a signer that maps to the provided company VAT number to sign the documents.",
"minLength": 8,
"maxLength": 8
},
"Private": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "string",
"minLength": 0,
"maxLength": 0
},
{
"type": "null"
}
],
"description": "-----UNDEFINED-----"
},
"ReminderInterval": {
"type": ["integer", "string", "null"],
"description": "Defines how often (in days) an email reminder about signing documents should be send."
},
"Roles": {
"type": ["array", "null"],
"description": "Roles of a signer in the case file.",
"items": {
"type": ["string", "integer", "null"],
"description": "A unique indentifiers for signers roles."
}
}
}
}
},
"CopyRecipients": {
"type": ["array", "null"],
"description": "Recipients that will receive a copy of a casefile.",
"items": {
"type": ["object", "null"],
"properties": {
"Name": {
"type": ["string", "null"],
"description": "Copy recipients name."
},
"Email": {
"type": ["string", "null"],
"format":"email",
"description": "Copy recipients email."
}
},
"required": [
"Name",
"Email"
]
}
},
"SubmitWhenReady": {
"type": ["boolean", "null"],
"description": "Defines if the case is ready to be submited or should be edited."
},
"FileReference": {
"type": ["string", "null"],
"description": "A path to a reference file"
},
"DeleteFileReference": {
"type": ["boolean", "string", "null"],
"description": "Defines if the file will be deleted after it will be used"
}
}
}
Join our API newsletter to be notified on the latest API updates
To ensure you are always up to date with any API changes, we invite you to sign up for our API newsletter.
Find the signup form at the link below - and remember to share it with other relevant stakeholders in your company!
Updated 10 months ago