Send a document for signature via Connect (API)

API Request Structure

In this guide, you'll discover how to send a request with an document to sign passed as a binary via the optionsproperty.

Additionally, you'll learn how to interpret back the signature propertyreturn in the requestpayload.

API endpoint

https://connect.penbox.io/{version}/requests

Request Headers

You will find all the details regarding Payload Structure

AttributeDescriptionMandatory
Content-TypeIs always application/jsonYes
AuthorizationThis is where you can paste your authorization bearerYes

If you don't have an authorization bearer yet, please follow the instructions on the following page: https://dash.readme.com/project/penbox/v1/refs/getting-started-with-connect .

Request Payload Data Structure

You will find all the details regarding Payload Structure

Attribute

Description

Mandatory

user.locale

The language you want to use to send the email and form

Yes

user.phone

The mobile phone number which you will send the signature request

No

user.email

The email to which you will send the signature request

Yes

user.given_name

The first name of the person to which you're sending the request

Yes

user.family_name

The last name of the person to which you're sending the request

Yes

user.internal_ref

An internal reference number that you have for the person/company that you're sending the request to.

No

options.signature_method

sms, handwritten, null, email

Yes

options.attachments_to_sign

"base64": the format of the file to sign in base64
"name": the name of the file to sign
"metadata": the metadata of the file to sign
"type": the type of the file to sign, which is mostly pdf

Yes

owner.email

To define the owner of the request

No

flow.slug

The slug of the flow you want to use

Yes

{
    "user": {
        "email": "[email protected]",
        "locale": "fr",
        "given_name": "Olivia",
        "family_name": "Peeters",
        "internal_ref": "Penbox001"
    },
    "options" : {
        "signature_method": "email",
        "attachments_to_sign": {
            "base64": "" //Please insirt your file in a B64 format for this attribute,
            "name": "Quote Test Olivia.pdf",
            "metadata": {},
            "type": "application/pdf"
        }
    },
    "owner":{
        "email":"[email protected]"
    },    
    "flow": {
        "slug": "servicing-file-sign"
    }
}

Try your request

Lets try out our complete request.

Please be aware that the header will be differently according to the user.
To get your authorization bearer please follow the instructions on this page.

curl --location 'https://connect.penbox.io/v1/requests' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6ImNvbm5lY3QtMTYxNTU2MzUzMSJ9.eyJjbGllbnRfaWQiOiJwZW5ib3gtZGV2Iiwic3ViIjoiZ29vZ2xlLW9hdXRoMnwxMTE2NDQyMjc2NzE0ODE1NDg0NDMiLCJlbWFpbCI6InBpZXJyZS52YW5oYWVyZW5AcGVuYm94LmlvIiwic2NvcGUiOiJjb21wYW55OmQwZTFkMmUxLTliZmEtNGUyNi04ZjZiLWYyM2YzYWZiMzlmZCIsImlhdCI6MTY5MTM5OTY3OSwiZXhwIjoxNjkxNDAzMjc5LCJhdWQiOiJodHRwczovL2NvcmUucGVuYm94LmlvIiwiaXNzIjoiaHR0cHM6Ly9jb25uZWN0LnBlbmJveC5pbyJ9.djqnqz4s8TNRk64piHj3bGqVBXtfgr49xSYMzlZUE-93dHkk6ufwUy6Jt2LUZ-kej2EalnukPx5SqCYjTZGESwsU7UWIpVGLbeSzIk1ziKivx9TnN6vEKm_WNGIaAQJaxtc5WMFwXi5n76uzXrn0F9gNv63jPMIdBH-bzeGKxZ_2fqfpbh7eSAs7nBb5XTjG2AEwnQGoe_lQGfLlYJyz-vfV2Li-5KcOFtkBegskvCmnbxVXq9rX6LfJ0wna2J-kgsXgv2LiSGvoplQ-H0InOBWz2yz3F7rgm-u6eaR-h1H8wdsn1EJUcSktcFj3DA7IOvcYAzGxIJGoRfZuK1HeCia2bUQ0qmcz9BHCKtQL_ZF9z4JSBg9oA4Ra1ZC6GHNyVNKOwbmUNjEqJ2LA2b6lPpVfyMsfZmIZNqWg8DwCMODzvUfmS3T7ofUQ5HxOQQNyRj9bD_omycZyVAZhpJ88Q5Eh2rQ29nou8tebEKH7l_knw_z1jbsVmxAyhf1Z3uYxgT0EJzXgC3A9ldcuxvfJ3nwp-eKgT-yjZaF8uOUqRxZ7cs9FQXgV6pmtfv-c-3uhDnHHl-Wx9sX7Rv1c3uNE1oRvuYtdi-1L78boyQNTgTBdP80xrcHY8wpR4OkMYmLMUS4HGsoi9U0TOMjS6NRu23GrAsLje5Hho5yGT-RoFoY' \
--data-raw '{
    {
    "user": {
        "email": "[email protected]",
        "locale": "fr",
        "given_name": "Olivia",
        "family_name": "Peeters",
        "internal_ref": "Penbox001"
    },
    "options" : {
        "signature_method": "email",
        "attachments_to_sign": {
            "base64": "" //Please insirt your file in a B64 format for this attribute,
            "name": "Quote Test Olivia.pdf",
            "type": "application/pdf"
        }
    },
    "owner":{
        "email":"[email protected]"
    },    
    "flow": {
        "slug": "servicing-file-sign"
    }
}'

👍

Congrats, at this point you should be able to create your own signature request via API

API Response Structure

On this section we will be explaining all the response details of a request signature property.

📘

Package to sign

Set of documents to be sign as a whole package (e.g: the contract & the general conditions)

⚠️

The signatures inner properties are the list of signature elements of the form

In the example describe here below signed_documents is the key defined for the signature element of the form servicing-file-sign

AttributeDescription
signed_documents.uriThe uri to get the signed document(s) on our CONNECT API (cf: this page)
signed_documents.nameThe name of the package to sign
signed_documents.typeThe format of the package to sign
signed_documents.statusThe status of the package to sign. When "finished" the package is signed
signed_documents.signed_filesThe list of files contained in the package to sign
"responses": [
        {
            "id": "1f2ebbbd-bd3c-45fd-b2b4-1c19bf4638c4",
            "data": {},
            "user": {},
            "attachments": [],
            "signatures": {
                "signed_documents": {
                    "id": "46080e25-8287-4669-b032-3f78d0f02958",
                    "uri": "https://connect.penbox.io/v1/signatures/46080e25-8287-4669-b032-3f78d0f02958",
                    "name": "my signed documents",
                    "type": "application/zip",
                    "status": "finished",
                    "signed_files": [
                    	{
                        "id": "a78f641a-62af-4d2f-94df-70de7d620001",
                        "uri": "attachments:a78f641a-62af-4d2f-94df-70de7d6200001",
                        "name": "my-signed-document.pdf",
                        "type": "application/pdf"
                      }
                    ]
                }
            }
        }
    ]