--- title: Penneo API Integration on Truto slug: penneo category: E-Signature canonical: "https://truto.one/integrations/detail/penneo/" --- # Penneo API Integration on Truto **Category:** E-Signature **Status:** Generally available ## MCP-ready AI tools Truto exposes 22 tools for Penneo that AI agents can call directly. - **create_a_penneo_oauth** — Exchange credentials for a Penneo access token using the authorization code, refresh token, or API keys grant. Returns: grant_type. Required: grant_type, client_id, client_secret. - **delete_a_penneo_oauth_by_id** — Revoke a Penneo refresh token, rendering it permanently invalid. Returns an empty 200 response on success regardless of whether the token existed or was already invalid. Required: token. - **list_all_penneo_oauth** — Initiate the Penneo OAuth 2.0 authorization flow by redirecting the user's browser to Penneo's authorization endpoint. Returns a 302 redirect to the registered redirect_uri with an authorization code appended as a query parameter. Required: response_type, redirect_uri, client_id, code_challenge. - **list_all_penneo_version** — Get Penneo API version information for the running app. Returns: language, additionalSignersConfig. - **list_all_penneo_casefile_answers** — List all submission answers for a penneo casefile. Returns answer records whose fields are specific to the casefile's form question schema defined in penneo; the response shape is form-schema-specific and cannot be enumerated from the API reference — consult the upstream penneo Collect docs for the field-level breakdown. Required: casefile_id. - **list_all_penneo_casefile_files** — List files attached to a penneo casefile by casefile id. Returns a list of file metadata objects; the available source documents the response as file metadata without enumerating individual fields beyond the universal identifiers id, created_at, and updated_at. Required: casefile_id. - **list_all_penneo_forms** — List penneo forms with optional status filtering and sorting. Returns: id, language, additionalSignersConfig, createdAt, updatedAt. - **get_single_penneo_form_by_id** — Get a single penneo form by id, including its sections and signer configuration. Returns: id, language, additionalSignersConfig, createdAt, updatedAt. Required: id. - **create_a_penneo_form** — Create a new penneo form with sections and input fields. Returns: id, language, additionalSignersConfig, createdAt, updatedAt. Required: language, sections. - **update_a_penneo_form_by_id** — Update an existing penneo form by id. If the form is in DRAFT status, updates the existing draft; if ACTIVE, creates a new DRAFT version. Returns: id, language, additionalSignersConfig, createdAt, updatedAt. Required: id, language, sections. - **delete_a_penneo_form_by_id** — Archive a penneo form by id, setting its status to ARCHIVED. Returns an empty 200 response on success. Required: id. - **update_a_penneo_form_version_by_id** — Update a specific version of a Penneo form with sections and input fields. If the version is DRAFT, updates the existing draft; if ACTIVE, creates a new DRAFT version. Returns the updated form object including language and additionalSignersConfig. Required: external_id, version, language, sections. - **create_a_penneo_form_request** — Create a prefilled form request in Penneo for a specified form, with pre-populated field values. Returns a 200 success response when the form request is created. Required: form_id, answers. - **list_all_penneo_form_request_answers** — List all submitted answers for a specific Penneo form request. Returns the submission data object; the field structure is form-specific and depends on the form's field definitions in Penneo. Required: form_id, id. - **list_all_penneo_form_submissions** — List Penneo form submissions for a specific form. Returns: id, created_at, grant_type. Required: form_id. Supports filtering by completedAfter and completedBefore ISO-8601 UTC datetimes. - **list_all_penneo_form_submission_answers** — List all answers for a Penneo form submission. Returns: id, grant_type. Required: form_id, id. - **create_a_penneo_casefile** — Create a new Penneo case file with documents and signers via a multipart/form-data POST. PDF file uploads are supported as part of the request body. Processing is asynchronous; the returned job reference can be used to poll progress via the Penneo Queue Status Check endpoint. Returns: jobs, status, message. Required: data, files. - **create_a_penneo_job_status** — Check the status of an asynchronous Penneo case file creation job by polling with its UUID and payload hash. Returns: uuid, result, payload, retries, createdAt, jobStatus, updatedAt, maxRetries, payloadHash, errorMessage. Required: uuid, payloadHash. - **create_a_penneo_form_version_archive** — Archive a specific version of a penneo form, allowing management of existing form versions without affecting the currently published version. Returns an empty 200 response on success. Required: external_id, version. - **create_a_penneo_form_version_publish** — Publish a specific version of a Penneo form, making it the active published version. Returns a 200 response on success. Required: external_id, version. - **create_a_penneo_form_version_restore** — Restore a penneo form to a specific previous version. Returns a 200 response on success. Required: external_id, version. - **create_a_penneo_form_publish** — Publish a Penneo form by its external ID to make it available for end-users. Returns: id, language, additionalSignersConfig, createdAt, updatedAt, grant_type. Required: external_id. ## How it works 1. **Link your customer's Penneo account.** Use Truto's frontend SDK; we handle every OAuth and API key flow so you don't need to create the OAuth app. 2. **Authentication is automatic.** Truto refreshes tokens, stores credentials securely, and injects them into every API request. 3. **Call Truto's API to reach Penneo.** The Proxy API is a 1-to-1 mapping of the Penneo API. 4. **Get a unified response format.** Every response uses a single shape, with cursor-based pagination and data in the `result` field. ## Use cases - **Automate KYC onboarding for accounting and audit platforms** — Practice management SaaS can dispatch prefilled KYC forms and engagement letters to new clients the moment they're added in the platform, then pull structured AML answers back without manual data entry. - **Trigger employment contracts from ATS and HR workflows** — When a candidate moves to a 'Hired' stage, the SaaS can generate a contract, push it to Penneo as a casefile with signer roles, and sync the executed document back into the candidate profile. - **Embed eIDAS-compliant signing into legal and contract tools** — Legal case management platforms can route multi-party resolutions through Penneo's national eID signing flows, enforcing signing order and retrieving cryptographically sealed documents for an audit trail. - **Sync signed documents and form data into a system of record** — SaaS platforms can poll completed casefiles, download finalized PDFs, and extract submission answers to keep their CRM, ERP, or compliance records continuously up to date. - **Manage form versions and templates across customer tenants** — Product teams can programmatically create, publish, and archive form versions on behalf of customers so every signing request runs against the legally approved template. ## What you can build - **OAuth-based Penneo account connection** — Let end users connect their own Penneo workspace via OAuth so all signing actions execute under their credentials and audit log. - **Prefilled KYC and onboarding form dispatch** — Send Penneo form requests with answers prefilled from your SaaS data so signers complete onboarding in fewer clicks. - **Asynchronous casefile creation with status tracking** — Push PDFs and signer assignments into Penneo casefiles and poll job status by UUID to confirm staging before notifying the user. - **Structured signature data extraction** — Pull casefile and form submission answers back into your platform to update records, trigger downstream automations, or populate audit logs. - **Signed document archiving** — Retrieve finalized casefile files once all signers have completed so the executed PDFs land directly inside your customer's workspace. - **Form lifecycle management** — Create, update, publish, archive, and restore form versions programmatically to keep customer-facing templates governed and consistent. ## FAQs ### How do end users authenticate their Penneo account? Truto handles Penneo authentication via OAuth. Your users connect their Penneo workspace once, and Truto manages token storage, refresh, and revocation behind a single connection object. ### How are large document uploads and casefile creation handled? Casefile creation is asynchronous and uses multipart/form-data to accept PDFs and signer assignments. After submission, you poll the job status endpoint with the returned UUID to confirm the casefile was successfully staged before proceeding. ### Can we prefill data into forms sent to signers? Yes. When creating a form request, you can pass an answers payload populated with data from your SaaS, so the signer sees a partially completed form and only fills in what's missing. ### How do we retrieve structured answers from completed signings? You can list answers tied to a casefile or to a specific form submission, giving you machine-readable responses rather than only the rendered PDF, which is useful for syncing back to CRM fields or compliance systems. ### Does the integration support managing form templates and versions? Yes. You can list, create, update, and delete forms, and manage their lifecycle through version-level publish, archive, and restore actions to ensure signing requests always run against an approved template. ### How do we know when a casefile is fully signed and ready to archive? Because Penneo processes signing asynchronously, integrations rely on polling job status and listing casefile files to detect completion, then download the finalized, cryptographically sealed PDFs back into your platform.