Send a document for signature via Connect (API)
-Add a small paragraph about how the API is used for.
API Request Structure
On the following section you will find all the necessary attributes to successfully interac zith the API.
API URL available through
https://connect.penbox.io/{version}/requests
add quick note about the current and available API version:
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 |
|---|---|---|
| data.user_title | The title that you want to use to address the person your sending the request to. This title can be used in the email that will be sent and can be pre-filled in the Penbox form. | No |
| data.storyblok_email | If you want to use the Penbox template for the email to sent, you can pt 'true' for this attribute | No |
| user.email | The email to which you will send the signature request | Yes |
| user.locale | The language you want to use to send the email and form | 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.invite_scenario_custom_frequency | The frequency in days at which the reminders are sent | Yes |
| options.handler_email | null: the handler will be the same person as the owner "other": you can define a different person as handler in the attribute options.handler_email_other "none": No handler is defined, which means that nobody will be notified via email when the request is completed | Yes |
| options.handler_email_other | Email address of the handler of the request, the handler is the person that will be notified when the request is completed. | Yes (when "other" is defined for the attribute options.handler_email) |
| 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 |
{
"data": {
"user_title": "madam",
"storyblok_email": false
},
"user": {
"email": "[email protected]",
"locale": "fr",
"given_name": "Olivia",
"family_name": "Peeters",
"internal_ref": "Penbox001"
},
"options" : {
"signature_method": "sms",
"attachments_to_sign": {
"base64": "" //Please insirt your file in a B64 format for this attribute,
"name": "Quote Test Olivia.pdf",
"metadata": {},
"type": "application/pdf"
},
"merge_signed_document": true
},
"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 '{
{
"data": {
"user_title": "madam",
"storyblok_email": false
},
"user": {
"email": "[email protected]",
"locale": "fr",
"given_name": "Olivia",
"family_name": "Peeters",
"internal_ref": "Penbox001"
},
"options" : {
"signature_method": "sms",
"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"
},
"webhooks": {
"https://webhook.site/dc659c33-a082-4f25-a71b-7a823e870b27": ["responses:completed"]
}
}'
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 signature request.
| Attribute | Description |
|---|---|
| signed_documents.uri | The uri to get the signed document |
| signed_documents.name | The name of the signed document |
| signed_documents.type | The format of the signed document |
| signed_documents.status | The status of the singed document. When "finished" the document is signed |
"responses": [
{
"id": "1f2ebbbd-bd3c-45fd-b2b4-1c19bf4638c4",
"data": {},
"user": {},
"attachments": [],
"signatures": {
"signed_documents": {
"uri": "https://connect.penbox.io/v1/signatures/46080e25-8287-4669-b032-3f78d0f02958",
"name": "a detroyer signed documents",
"type": "application/zip",
"status": "finished"
}
}
}
]
Updated 6 months ago