Penneo Sign Production (Preview)

Penneo transforms complex processes into a seamless, human-centric experience. By integrating digital signatures into automated workflows, our platform makes it effortless to validate who approved what data and when, reducing administrative burdens while ensuring full compliance and security. This connector allows you to send documents for signing.

This connector is available in the following products and regions:

Service	Class	Regions
Copilot Studio	Premium	All Power Automate regions except the following: - US Government (GCC) - US Government (GCC High) - China Cloud operated by 21Vianet - US Department of Defense (DoD)
Logic Apps	Standard	All Logic Apps regions except the following: - Azure Government regions - Azure China regions - US Department of Defense (DoD)
Power Apps	Premium	All Power Apps regions except the following: - US Government (GCC) - US Government (GCC High) - China Cloud operated by 21Vianet - US Department of Defense (DoD)
Power Automate	Premium	All Power Automate regions except the following: - US Government (GCC) - US Government (GCC High) - China Cloud operated by 21Vianet - US Department of Defense (DoD)

Contact
Name	Penneo Support
URL	https://www.support.penneo.com

Connector Metadata
Publisher	Penneo Integration
source	Swagger
Website	https://penneo.com
Privacy policy	https://penneo.com/privacy-policy
Categories	Productivity

Penneo Sign

Prerequisites

To use this connector, you will need an active Penneo account.

Supported Actions

Create a new case file

Creates a new case file in Penneo with the specified documents and signers. The case file will be created in Penneo, and a UUID and a payloadHash will be returned that can be used to check the creation status via the queue status endpoint.

Check job status

Retrieves the current status of a casefile by providing the job UUID and payloadHash. This endpoint is used to poll for job completion status after submitting a case file creation request. The endpoint is rate-limited to 20 requests per minute per uuid-payloadHash combination.

Get case file details

Retrieves the details of a specific case file from Penneo based on casefileId. This includes its signers, documents, and current status.

Download document

Downloads the content of a document from the Penneo as a base64 encoded string. By default, the signed version of the document is returned; use the signed parameter to get the unsigned version instead. If your case file includes more documents ensure to loop over each document.

Obtaining Credentials

The connector has been configured to use OAuth with Authorization Code Grant. Users will have to login with their regular credentials when they use the connector.

Getting Started

Creating a Case File

Prepare Your Documents:
- Convert your PDF documents to base64 encoding
- Ensure documents are valid PDF files
Configure Signers:
- Provide signer name and email (required)
- Optionally provide role, language, signing order, etc.
- Configure email notifications and custom email templates if needed
Create the Case File:
- Use the "Create a new case file" action
- Fill in the case file details:
  - Title
  - Documents (base64 encoded PDFs)
  - Signers (with names and optional details)
  - Optional settings (expiration, language, visibility, etc.)
Check CaseFile creation status:
- After creating a case file, you'll receive a UUID and payloadHash
- Use the "Check job status" action to poll for job completion
- Respect the rate limit of 20 requests per minute per uuid-hash combination

Note: You can check what each field does by checking https://penneo.readme.io/reference/createcasefile.

Retrieving a Case File and its Documents

Get the case file details:
- Use the "Get case file details" action with the case file id
- The response includes the case file status, signers, and the list of documents (with their document ids)
Download a document:
- Use the "Download document" action with the document id obtained from the case file details
- The response contains the document content as a base64 encoded string, which you can decode to retrieve the PDF file

Known Issues and Limitations

Rate Limiting: The Check job status endpoint is rate-limited to 20 requests per minute per uuid-hash combination. Implement appropriate retry logic with exponential backoff.
Asynchronous Processing: Case file creation is asynchronous. You must use the job status endpoint to check completion rather than expecting immediate results.
Base64 Encoding: Documents must be base64 encoded. Ensure proper encoding to avoid request failures(you can use base64 string function in the Power Platform to encode the binary PDF files).
Production Environment: This connector is configured for the Penneo production environment (app.penneo.com).
Document Size: Large documents may take longer to process. Consider document size limits when encoding to base64.

Deployment Instructions

Run the following commands and follow the prompts:

paconn create --api-def apiDefinition.swagger.json --api-prop apiProperties.json --icon icon.png --script script.csx

Actions

Check job status	Retrieves the current status of an asynchronous job by providing the job UUID and payloadHash. This endpoint is used to poll for job completion status after submitting a case file creation request. The action is rate-limited to 20 requests per minute per uuid-payloadHash combination.
Create a new case file	Creates a new case file in Penneo with the specified documents and signers. The case file will be created asynchronously, and a job UUID and a payloadHash will be returned that can be used to check the creation status via the Check job status action. You can configure signers, documents, signing order, email notifications, access control, and various other case file settings.
Download document	Downloads the content of a document from Penneo as a base64 encoded string. By default, the signed version of the document is returned.
Get case file details	Retrieves the details of a specific case file from Penneo, including its signers, documents, and current status. Case file statuses: 0=new, 1=pending, 2=rejected, 3=deleted, 4=signed, 5=completed, 6=failed, 7=expired, 8=anonymized. Use status 5 (completed) as trigger for downloading the signed documents.

Check job status

Operation ID:: CheckJobStatus

Retrieves the current status of an asynchronous job by providing the job UUID and payloadHash. This endpoint is used to poll for job completion status after submitting a case file creation request. The action is rate-limited to 20 requests per minute per uuid-payloadHash combination.

Parameters

Name	Key	Required	Type	Description
uuid	uuid	True	uuid	The UUID of the job to check. This is returned when the job is created.
payloadHash	payloadHash	True	string	The SHA-256 hash of the payload. This is returned when the job is created and is used to verify the request authenticity.

Returns

Body: QueueJob

Create a new case file

Operation ID:: CreateCaseFile

Creates a new case file in Penneo with the specified documents and signers. The case file will be created asynchronously, and a job UUID and a payloadHash will be returned that can be used to check the creation status via the Check job status action. You can configure signers, documents, signing order, email notifications, access control, and various other case file settings.

Parameters

Name	Key	Required	Type	Description
title	title	True	string	The case file title.
sendAt	sendAt		integer	Timestamp when case file should be sent. Null = immediately
name	name	True	string	Name of the signer
role	role		string	Role for the signer. Allowed: letters, numbers, spaces, comma, underscore, hyphen. Must start with a letter/number and must not end with a space.
email	email		email	Signer email. Penneo will handle all communications
failUrl	failUrl		uri	Redirect URL after failure
language	language		string	Signer language
emailText	emailText		string	Custom text for the signature request email. Defaults to company template if not provided.
signOrder	signOrder		integer	The signing order. 0 means no enforced order.
successUrl	successUrl		uri	Redirect URL after success
emailSubject	emailSubject		string	Subject of the signature request email. Defaults to company template if not provided.
reminderInterval	reminderInterval		integer	Days before reminder is sent
reminderEmailText	reminderEmailText		string	Custom text for the reminder email. Defaults to company template if not provided.
completedEmailText	completedEmailText		string	Custom text for the completed email. Defaults to company template if not provided.
reminderEmailSubject	reminderEmailSubject		string	Subject of the reminder email. Defaults to company template if not provided.
completedEmailSubject	completedEmailSubject		string	Subject of the completed email. Defaults to company template if not provided.
enableInsecureSigning	enableInsecureSigning		boolean	If true, signer can use touch signatures (draw, text, image upload)
insecureSigningMethods	insecureSigningMethods		array of string	Allowed insecure signing methods. Defaults to company setting if empty.
secureSigningMethods	secureSigningMethods		array of string	The allowed secure electronic signing methods. Overrides case file and customer settings when set.
vatin	vatin		string	VAT identification number of signer's company
ssnType	ssnType		string	Type of SSN/mobile. Example 'dk:cpr', 'se:pin', 'no:nin', 'be:nrn', 'fi:pic' or 'sms'. Defaults to 'legacy'
activeAt	activeAt		integer	Activation timestamp
expireAt	expireAt		integer	Expiration timestamp
accessControl	accessControl		boolean	If enabled, SSN/VATIN/phone is validated before access
emailFormat	emailFormat		string	Defines email format
onBehalfOf	onBehalfOf		string	The company/organization that this signer signs on behalf of
storeAsContact	storeAsContact		boolean	If true, signer will be stored as contact in Penneo
socialSecurityNumberPlain	socialSecurityNumberPlain		string	The signer's SSN or phone number (E.164 format recommended)
expireAt	expireAt		integer	Timestamp when the case file will expire. If not provided, defaults apply
language	language		string	The case file language, will be applied for every signer that does not have a language set
pdf	pdf	True	string	Base64 encoded PDF
signable	signable		boolean	True creates a signable document. False, the document is added as an attachment and is non signable.
roles	roles		array of string	Signer roles allowed to sign this document. Defaults to all signers if empty.
title	title	True	string	The document title
documentOrder	documentOrder		integer	The signing order of the document. Defaults to order provided.
metaData	metaData		string	Metadata of the document, searchable in Penneo
sensitiveData	sensitiveData		boolean	If true, signers must validate their identity before accessing documents. Disables email attachments for signed documents.
signOnMeeting	signOnMeeting		boolean	Specifies if documents should be signed during a meeting.
visibilityMode	visibilityMode		integer	0 = Signers see all documents. 1 = Signers see only documents they need to sign.
disableEmailAttachments	disableEmailAttachments		boolean	Disables email attachments for signed documents in finalization emails. Overridden if sensitiveData is true.
disableNotificationsOwner	disableNotificationsOwner		boolean	If true case file owner will not receive notifications for the case file.
folderId	folderId		integer	The folder id where you want to place your casefile
metaData	metaData		string	Metadata of the case file, searchable in Penneo
reference	reference		string	The reference of the case file, will be shown in the Penneo web application
name	name	True	string	Name of the recipient
email	email	True	email	Email of the recipient

Returns

Body: JobResponse

Download document

Operation ID:: DownloadDocument

Downloads the content of a document from Penneo as a base64 encoded string. By default, the signed version of the document is returned.

Parameters

Name	Key	Required	Type	Description
Document Id	documentId	True	integer	The id of the document to download. Retrieve the documentIds with the "Get case file details"-action.
Signed	signed		boolean	Get the signed or the unsigned document. By default, the signed document is returned if the document has been signed.

Returns

Body: DocumentContent

Get case file details

Operation ID:: GetCaseFileDetails

Retrieves the details of a specific case file from Penneo, including its signers, documents, and current status. Case file statuses: 0=new, 1=pending, 2=rejected, 3=deleted, 4=signed, 5=completed, 6=failed, 7=expired, 8=anonymized. Use status 5 (completed) as trigger for downloading the signed documents.

Parameters

Name	Key	Required	Type	Description
Case File Id	caseFileId	True	integer	The id of the case file to retrieve. Retrieve the case file id with the "Check job status" action.

Returns

Details of a case file retrieved from the Penneo secure archive.

Body: CaseFileDetails

Definitions

JobResponse

Name	Path	Type	Description
jobs	jobs	array of Job	Array of created jobs (typically contains one job)
status	status	string	Status of the job creation request
message	message	string	Human-readable message about the job creation

Job

Name	Path	Type	Description
uuid	uuid	uuid	Unique identifier for the job that can be used to check status
uuid	payload.uuid	uuid	UUID of the created case file
bundleUuid	payload.bundleUuid	uuid	UUID of the bundle containing the case file
etlVersionUuid	payload.etlVersionUuid	uuid	UUID of the ETL version used for processing
organizationUuid	payload.organizationUuid	uuid	UUID of the organization that owns this case file
customData	payload.customData	object	Additional metadata and context for the job
createdAt	createdAt	date-time	ISO 8601 timestamp when the job was created
payloadHash	payloadHash	string	SHA-256 hash of the payload, used for verification when checking job status

QueueJob

Name	Path	Type	Description
type	type	string	The type of the queue job (e.g., 'casefile_creation')
uuid	uuid	uuid	Unique identifier for the job
result	result	object	The result of the queue job execution, returned as JSON when the job is completed. Contains the outcome and any relevant data.
jobStatus	jobStatus	string	Current status of the job. Possible values 'pending' (waiting to be processed), 'processing' (currently being executed), 'completed' (successfully finished), 'failed' (execution failed), 'aborted_duplicated' (aborted due to duplication)
payload	payload	object	The original payload submitted with the job, stored as JSON. Contains the case file data and metadata.
retries	retries	integer	The number of times the job has been retried after a failure
createdAt	createdAt	date-time	The date and time when the queue job was created
updatedAt	updatedAt	date-time	The date and time when the queue job was last updated
maxRetries	maxRetries	integer	The maximum number of retries allowed for this job before it is marked as failed
payloadHash	payloadHash	string	SHA-256 hash of the payload, used for verification and security purposes
errorMessage	errorMessage	string	Error message describing why the job failed, if applicable. Only present when jobStatus is 'failed'.

CcRecipient

Name	Path	Type	Description
name	name	string	Name of the recipient
email	email	email	Email of the recipient

CaseFileDetails

Details of a case file retrieved from the Penneo secure archive.

Name	Path	Type	Description
userId	userId	integer	Id of the user who owns the case file.
customerId	customerId	integer	Id of the customer the case file belongs to.
signers	signers	array of SignerDetails	List of signers on the case file.
id	id	integer	The case file id.
title	title	string	The case file title.
status	status	integer	The case file status.
documents	documents	array of DocumentDetails	List of documents in the case file.
expireAt	expireAt	integer	UNIX timestamp when the case file expires.
ccRecipients	ccRecipients	array of CcRecipient	List of CC recipients who receive a copy of the signed documents.
created	created	integer	UNIX timestamp when the case file was created.
activated	activated	integer	UNIX timestamp when the case file was activated.
updated	updated	integer	UNIX timestamp when the case file was last updated.
completed	completed	integer	UNIX timestamp when the case file was completed.

SignerDetails

A signer on a case file.

Name	Path	Type	Description
name	name	string	Name of the signer.
id	id	integer	The signer id.
signingRequest	signingRequest	SigningRequestDetails	The signing request associated with a signer.

SigningRequestDetails

The signing request associated with a signer.

Name	Path	Type	Description
id	id	integer	The signing request id.
email	email	string	Signer email.
status	status	integer	The status of the signing request.

DocumentDetails

A document in a case file.

Name	Path	Type	Description
id	id	integer	The document id. Use this to download the document with the "Download document" action.
status	status	integer	The document status.
signable	signable	boolean	True if the document is signable.

DocumentContent

Name	Path	Type	Description
Document Content	content	byte	Base64 encoded content of the document.