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
| Attribute | Description | Mandatory |
|---|---|---|
| Content-Type | Is always application/json | Yes |
| Authorization | This is where you can paste your authorization bearer | Yes |
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_documentsis the key defined for the signature element of the formservicing-file-sign
| Attribute | Description |
|---|---|
| signed_documents.uri | The uri to get the signed document(s) on our CONNECT API (cf: this page) |
| signed_documents.name | The name of the package to sign |
| signed_documents.type | The format of the package to sign |
| signed_documents.status | The status of the package to sign. When "finished" the package is signed |
| signed_documents.signed_files | The 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"
}
]
}
}
}
]
Updated 1 day ago