NAV Navbar
json
  • Introduction
  • Authentication
  • Working with the API
  • Basic Flow
  • Multiple Signers
  • Visual Signatures
  • No Initial Signers
  • Signing without an Account (No Account Signers)
  • Signature Quality
  • Signing as a Legal Entity (Seal)
  • Documents
  • Introduction

    This documentation describes the public Skribble API.

    The goal is to provide a simple API, which enables integrators to create signature requests programmatically. A signature request is a description of who should sign what. It is the main object in this API.

    The signature request enables the integrator to describe a short document flow between the participants in a signature process.

    The actual signing of a document by a person always happens inside the Skribble web application.

    Base URL

    The base URL of version 1 is: https://api.skribble.com/v1

    OpenAPI / Swagger 2.0

    We provide a machine-readable OpenAPI / Swagger 2.0 description here: https://api.skribble.com/v1/api-docs.

    A human-readable version is available to with Swagger UI.

    Using Swagger UI you can test all API calls right in your browser.

    API key

    Most API calls require an authenticated user. So, before you can really use our API, you need an api-key.

    An api-key can be accessed inside the Developers page of an business account. You can create and manage your api-keys on this page.
    If you don't already have a business account you can create one inside the Skribble application at https://my.skribble.com/business.
    More information on business accounts can be found on the Skribble business features web page.

    Skribble offers two types of API keys.
    Demo api-keys are for testing and development purposes. Signatures requested by such keys don't have any legal weight and are free of charge.
    Production api-keys are used for live systems. Signatures requested by such keys will be invoiced. All costs of signature requests created with your API key will be charged to your business.

    If you have problems generating a business and the api-key just drop us an e-mail at info@skribble.com.

    Authentication

    Almost all API calls require an authentication or access token. You obtain an access token by logging in with your username and api-key.

    If you don't have those, please take a look at chapter API key for creating demo or production keys for yourself. Contact our support team, if you need assistance.

    Login

    Example: HTTP POST request with application/x-www-form-urlencoded body

    POST /v1/access/login HTTP/1.1
    Host: api.skribble.com
    Content-Type: application/x-www-form-urlencoded
    Accept: */*
    Content-Length: 65
    
    username=customer_A&api-key=00000000-0000-0000-0000-000000000000
    

    Example Response:

    HTTP/1.1 200 OK
    Date: Fri, 07 Sep 2018 14:24:17 GMT
    Content-Type: text/plain;charset=UTF-8
    Content-Length: 1366
    
    eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJJWlMx
    Y0pXQXlXVFdZeDR6dXRGNzJlYWVILTA0MUprTDF5N2Z3aXA1T3UwIn0
    Ei3Hm3rhjOAq5dWo6Z0l6bzvyGCXd87oRoOWDM2sW4KErCKYmcQq6ks8FV
    j3Fn8wXNIVAnp5ClZvWNw9Uks1zM9P2IXBbBPn7DIQGvM ...
    

    To obtain an access token you must log in using the /access/login resource.

    Example Authorization Header:

    POST /v1/documents HTTP/1.1
    Host: api.skribble.com
    Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR... 
    ...
    

    On a successful login, the result will be a JSON Web Token, which should be included in every request made to the API.

    The access token is transported in an HTTP header called Authorization. The content of the header starts with Bearer followed by the JWT string.

    Token Life Cycle

    API-Key

    The api-key has a long, but not an unlimited lifetime.

    The validity period should depend on the volume of API calls and will be discussed individually for each customer as part of the shared secret agreement.

    Access Token

    The access token has a lifetime of about 60 minutes.

    Logout

    There is no logout. The access token will just expire after some time.

    If your api-key is compromised, please call our support hotline to reset your credentials.

    Working with the API

    The individual API calls are described in Swagger UI.

    What we want to show here is, how to solve some common use cases with our API.

    In this regard the Swagger UI is bad. It is auto-generated from the source code, so the documentation for endpoints, objects, and fields should be up to date.

    But the auto-generated examples just fill out every field there is in an object, regardless of usefulness.

    Most of the fields are optional, so I recommend starting with the minimal set of features and build onto that. The minimal set of parameters is shown in chapter Basic Flow.

    Basic Flow

    At some point, you need your customer to sign a contract. The contract is generated on your platform for each customer individually and saved as PDF.

    Now the contract shall be signed by your customer with Skribble.

    To accomplish this, we will:

    1. Create a signature request
    2. Redirect the user to the Skribble web application.
    3. Retrieve the signed document.

    1. Create a Signature Request

    The document workflow is quite easy: you have one document and need a single signature. The document is private and not publically available.

    We need to create SignatureRequest object in Skribble. A SignatureRequest is a description telling Skribble, who shall sign what (which document) and optionally how the signature should look like.

    So, let's start with the minimal information Skribble needs.

    a) Tell the user, what he is signing.

    Basic Information

    "title" : "MyWebApp_NDA",
    

    The title should be short and treated like a file name.

    b) Tell Skribble who the signer is.

    Signer Information

    "signatures" : [
      {
        "signer_email_address" : "robert@cool-startup.com"
      }
    ],
    

    The signatures array contains all signers for the document. In this case, there is only one.

    The signer_email_address contains the user's e-mail address. It has two functions:

    1. All notifications are sent to this e-mail address.
    2. The e-mail is used to find the user's ID in our database.

    c) Tell Skribble which document shall be signed.

    Document by content

    "content" : "JVBERi0xLjMKJcTl8uXrp/Og0MTGCjQg..."
    

    Document by file_url

    "file_url" : "https://myapp.com/path/to/document"
    

    We have a private document, so the best way is to directly transfer it to Skribble.

    The content field contains the Base64 encoded bytes of the PDF document.

    As an alternative, you can give Skribble an URL, where it can download the document. The URL must not be used together with the content field.

    d) Tell Skribble what to do, when it is done.

    Adding callbacks

    "callback_success_url" : "https://myapp.com/some/path/SKRIBBLE_SIGNATURE_REQUEST_ID/success?document_id=SKRIBBLE_DOCUMENT_ID&token=12345678",
    "callback_error_url" : "https://myapp.com/some/path/SKRIBBLE_SIGNATURE_REQUEST_ID/error?document_id=SKRIBBLE_DOCUMENT_ID&token=12345678"
    

    This is actually an optional step, but it helps a lot.

    When all signers finished signing the document, we want to save the final version of it. One way to achieve this, is to use Skribble's callback functionality.

    There are three callback types in a SignatureRequest. One for the success case callback_success_url, one in case of an error callback_error_url and one for updates to the SignatureRequest callback_update_url

    Success occurs when the document has been successfully signed by all parties involved. Update occurs when just one person of a party signed. All other states lead to an error.

    The URLs can contain any parameters, such as internal transaction numbers, etc. The call is always made via HTTP POST with content-type text/plain without a body.

    Callback Placeholders

    Example Callback URLs

    
    # URL without placeholders: Will be called without any changes.
    https://example.com/some/path/56432?my_process_id=115533&pretty_print=yes
    
    # URL with placeholders
    https://example.com/some/path/SKRIBBLE_SIGNATURE_REQUEST_ID/success?document_id=SKRIBBLE_DOCUMENT_ID&pretty_print=yes
    
    # Assuming
    # the document ID is: 4986d80b-83a6-4cf8-aef9-84989bdd6c18
    # the SignatureRequest ID is: 85f94809-900b-44fa-8d65-64e854cd5cd5
    # then it will be called as:
    https://example.com/some/path/85f94809-900b-44fa-8d65-64e854cd5cd5/success?document_id=4986d80b-83a6-4cf8-aef9-84989bdd6c18&pretty_print=yes
    
    

    URLs may contain placeholders, which will be replaced with the current SignatureRequest data before the URL is called. Currently these two placeholders are supported:

    Placeholder Name Description
    SKRIBBLE_SIGNATURE_REQUEST_ID Will be replaced with the SignatureRequest ID, which triggers the callback.
    SKRIBBLE_DOCUMENT_ID Will be replaced with the most recent or final document ID, which belongs to the triggering SignatureRequest.

    The placeholder names are case sensitive! They must be written exactly as shown in the table above.

    Callbacks with TLS Mutual Authentication

    Callbacks support TLS mutual authentication (mTLS). If the callback endpoint (your side) asks for a client authentication during the TLS handshake, Skribble will authenticate itself with a X.509 certificate for api.skribble.com.

    Skribble api.skribble.com client certificate

    Putting it all together

    POST /v1/signature-requests

    {
      "title" : "MyWebApp_NDA",
    
        "signatures" : [
            {
                "signer_email_address" : "robert@cool-startup.com"
            }
        ],
    
        "content" : "JVBERi0xLjMKJcTl8uXrp/Og0MTGCjQg...",
    
      "callback_success_url" : "https://myapp.com/some/path/SKRIBBLE_SIGNATURE_REQUEST_ID/success?document_id=SKRIBBLE_DOCUMENT_ID&token=12345678",
      "callback_error_url" : "https://myapp.com/some/path/SKRIBBLE_SIGNATURE_REQUEST_ID/error?document_id=SKRIBBLE_DOCUMENT_ID&token=12345678"
    }
    

    Put all this information together in one JSON and send it via POST to /v1/signature-requests to create a SignatureRequest.

    Response

    Response Example:

    {
      "id": "97ec0648-2428-46b6-a83b-4420f4143a7b",
      "title": "MyWebApp_NDA",
      "document_id": "179fa760-da06-4ed3-a1c0-5aad86ebb361",
      "signing_url": "https://my.skribble.com/view/97ec0648-2428-46b6-a83b-4420f4143a7b",
      "status_overall": "OPEN",
      "signatures": [
        {
          "signer_email_address": "robert@cool-startup.com",
          "order": -1,
          "status_code": "OPEN"
        }
      ],
      "owner": "api_username",
      "read_access": [],
      "write_access": [
        "robert@cool-startup.com"
      ],
      "callback_success_url" : "https://myapp.com/some/path/SKRIBBLE_SIGNATURE_REQUEST_ID/success?document_id=SKRIBBLE_DOCUMENT_ID&token=12345678",
      "callback_error_url" : "https://myapp.com/some/path/SKRIBBLE_SIGNATURE_REQUEST_ID/error?document_id=SKRIBBLE_DOCUMENT_ID&token=12345678",
      "created_at": "2019-02-12T10:32:09.466Z",
      "updated_at": "2019-02-12T10:32:09.466Z"
    }
    

    Skribble will respond with the SignatureRequest object it created.

    The only information we need for the next step is the signing_url.

    Let's go to the next step.

    2. Redirect the user to the Skribble web application.

    The user has to visit the Skribble web application to actually sign the document.

    When we created a SignatureRequest the user received a notification from Skribble, that there is a document waiting to be signed.

    Still, we want to continue immediately and redirect the browser directly to Skribble showing the uploaded document.

    Skribble provides a signing_url inside the SignatureRequest. The signing_url not only points to the Skribble web application, but will directly open the document for signing. That is, if the user is known to Skribble and logged in. Otherwise, the user must login or register and then will be shown the document.

    There are some more options to tailor the signing flow to your application's specific needs.

    ExitURL, ErrorURL, DeclineURL and redirectTimeout

    Example: will automatically redirect to https://google.com after 20 seconds when the signing was successful

    https://my.skribble.com/view/8229873d-d7c7-4e2b-a8a3-331353243d97?exitURL=https%3A%2F%2Fgoogle.com&redirectTimeout=20
    

    When the user signs the document successfully he/she would stay on Skribble's web application.

    However, you can add 3 exit points as query parameters to the signing_url. Skribble will respect those parameters and redirects the user to the provided URLs when the signature process finishes.

    Using this you can bring the user back from Skribble to your application.

    Make sure you encode your exit URLs properly. This is especially important for GET parameter separators like '?' and '&' such that they are not interpreted by browsers as GET parameters on Skribble's web application itself.

    Exit points:

    Redirection timeout:

    If exitURL is specified the user will be automatically redirect to the given URL when their signature process was successful. The redirection timeout defaults to 45 seconds. Using the URL parameter redirectTimeout this duration can be adjusted. However, for usability reasons the duration cannot be shorter than 10 seconds or longer than 90 seconds. If values outside this range are given the actual timeout will be enforced to stay within the min and max.

    3. Retrieve the signed document.

    To Retrieve the signed document, we have to call GET /v1/documents/{id}/content with the correct document ID.

    Documents in Skribble are unchangeable (immutable). Changes to the document content always lead to a new document with a new ID.

    This means, that the document ID you receive after uploading, will not be the same one you download after signing.

    There are two approaches to get the correct document ID.

    Using Callbacks

    Callback URL examples:

    "callback_success_url" : "https://myapp.com/some/path/SKRIBBLE_SIGNATURE_REQUEST_ID/success?document_id=SKRIBBLE_DOCUMENT_ID&token=12345678",
    "callback_error_url" : "https://myapp.com/some/path/SKRIBBLE_SIGNATURE_REQUEST_ID/error?document_id=SKRIBBLE_DOCUMENT_ID&token=12345678"
    

    Example success callback:

    https://myapp.com/some/path/60dd69dc-3d25-49da-ba0b-e7a44e353854/success?document_id=32e2d2fa-b793-43c2-8e54-3e33d24aba39&token=12345678
    

    Get the document content:

    GET /v1/documents/32e2d2fa-b793-43c2-8e54-3e33d24aba39/content HTTP/1.1
    

    The easiest way to get the correct document ID after signing, is to use success and failure callbacks.

    The callback URLs may contain placeholders, which are replaced with the current SignatureRequest data, before the URL is called.

    Placeholder Name Description
    SKRIBBLE_SIGNATURE_REQUEST_ID Will be replaced with the SignatureRequest ID, which triggers the callback.
    SKRIBBLE_DOCUMENT_ID Will be replaced with the most recent or final document ID, which belongs to the triggering SignatureRequest.

    So, if the success callback triggers, the URL contains the correct document ID, which can then be used to retreive the document.

    Read the SignatureRequest status

    Example of a SigntureRequest

    {
        "id": "e4c708db-1c33-4c97-a02d-5015e3fde177",
        "title": "Document_sign_empty",
        "document_id": "1189401b-7161-4ddc-81ca-1c5a622f753b",
        "signing_url": "https://my.skribble.com/view/e4c708db-1c33-4c97-a02d-5015e3fde177",
        "status_overall": "SIGNED",
        "signatures": [
          ...
        ],
        ...
        "created_at": "2019-01-03T14:47:05.263Z",
        "updated_at": "2019-01-03T14:47:11.662Z"
      }
    

    Get the document content:

    GET /v1/documents/1189401b-7161-4ddc-81ca-1c5a622f753b/content HTTP/1.1
    

    If using callbacks is no option for you, then you can just read the status of the SignatureRequest.

    The SignatureRequest always holds the current state of the process. So, you can get the signature request state with GET /v1/signature-requests/{id}.

    Read the field document_id and retrieve the signed document with a call to GET /v1/documents/{id}/content.

    Searching for SignatureRequests

    If you are not using callbacks, then most of the time, you will use some kind of search to find the SignatureRequests you need.

    The GET /v1/signature-requests supports searching for SignatureRequests with some filter criteria:

    Parameter Description
    status_overall (optional) Filter on the field "status_overall"
    signature_status (optional) Filter on the field "signatures[].status_code"
    signer_email_address (optional) Filter on the field"signatures[].signer_email_address"

    Example: Show all signed signature requests for user "walter.demo":

    GET /signature-requests?signature_status=signed&signer_email_address=walter.demo%40devmue.de HTTP/1.1
    

    Returns a list with matching SigntureRequests:

    [
      {
        "id": "e4c708db-1c33-4c97-a02d-5015e3fde177",
        "title": "...",
        "message": "...",
        "document_id": "1189401b-7161-4ddc-81ca-1c5a622f753b",
        "signing_url": "..."
        "status_overall": "SIGNED",
        "signatures": [
          {
            "signer_email_address": "...",
            "status_code": "SIGNED",
            "signed_at": "2019-01-03T14:47:10.305Z"
          }
        ],
        ...
      },
      {
        "id": "0f74aac4-b5a7-4bfa-abdb-6d0bb112d756",
        "title": "...",
        "message": "...",
        "document_id": "820568f5-4a7e-487e-8a43-9c76d0cb595f",
        "signing_url": "...",
       ...
      },
      ...
    ]
    

    Signature States

    State for Signature for Signature Request
    open Waiting for the user to sign a signature At least one user has not signed or declined his/her signature yet.
    declined The user declined to sign At least one user declined to sign. The signature request failed.
    signed The user signed the signature request All users signed the signature request. The signature request was successfully completed.
    error A technical error occurred A technical error occurred. The signature request cannot be completed.

    Multiple Signers

    Example SignatureRequest with 3 signers, in no specific sequence:

    {
      "title" : "Jupiter Mission",
    
        "signatures" : [
            {
                "signer_email_address" : "dave@discovery.one"
            },
            {
                "signer_email_address" : "frank@discovery.one"
            },
            {
                "signer_email_address" : "heywood@discovery.one"
            }
        ],
    
        ...
    
    }
    

    The signature process with multiple signers is not much different than for one signer.

    The only difference is in the number of signatures in the SignatureRequest.

    In the example we have 3 signers. They can sign in any sequence they want and the signature position and appearance will be defined by the Skribble web application.

    If no sequence is defined, all participants are informed at the same time and are allowed to sign the document in any order. The system ensures that the document is nevertheless only changed sequentially.

    Define a signature order

    Example SignatureRequest with 3 signers, in order: Frank, Heywood, Dave:

    {
      "title" : "Jupiter Mission",
    
      "signatures" : [
        {
            "signer_email_address" : "dave@discovery.one",
            "order" : 3
        },
        {
            "signer_email_address" : "frank@discovery.one",
            "order" : 1
        },
        {
            "signer_email_address" : "heywood@discovery.one",
            "order" : 2
        }
      ],    
      ...
    
    }
    

    If the document must be signed in a logical or legal sequence, you can tell Skribble to follow a specific order using the field order.

    If the field contains a number, the document will be signed in the sorted order, starting with the smallest number.

    Notifications will also be send following the same order.

    Visual Signatures

    The appearance of a person's signature on the PDF document is just optics. It doesn't change the actual electronic signature.

    But we all like good looking documents and the appearance can hold some information for the reader.

    If a SignatureRequest doesn't contain any visual signature instructions, the user is free to create any visual signature representation he or she likes and place it anywhere on the document using the Skribble web application.

    This matches how the physical world handles placement information. The document can contain visual hints "Please sign here", but they are not enforced.

    In the digital world, we have some more options.

    PDF Form Fields

    Example using form fields:

    {
      "title" : "Jupiter Mission",
    
      "signatures" : [
        {
            "signer_email_address" : "dave@discovery.one",
            "visual_signature" : {
                "form_field" : "Person_1"
            }
        },
        {
            "signer_email_address" : "frank@discovery.one",
            "visual_signature" : {
                "form_field" : "Person_2"
            }
        }
      ],
      ...
    
    

    PDF documents support a concept of form fields. If a PDF document contains signature form fields, you can tell Skribble, that a signer must use it.

    In the example, Dave must sign in the form field 'Person_1' and Frank in the field 'Person_2'. The Skribble web application will enforce the usage of the fields.

    The PDF Acroform field must be of type signature and not of any other type. A form field defines fixed positions in the document. One signature can be displayed none, one or more times on one or more pages throughout the document.

    It does not define, what the contents of the field will show. This is still handled by the Skribble web application.

    The advantage of PDF form fields is, that a document designer can size and position the fields perfectly in a document, before the document is used in any project.

    Example form fields and order:

    {
      "title" : "Jupiter Mission Clearance",
    
      "signatures" : [
        {
            "signer_email_address" : "heywood.floyd@nasa.gov",
            "order": 1,
            "visual_signature" : {
                "form_field" : "project_lead"
            }
        },
        {
            "signer_email_address" : "frank@discovery.one",
            "order": 2,
            "visual_signature" : {
                "form_field" : "astronaut_1"
            }
        }
      ],
      ...
    
    

    You can combine this nicely with a signature order.

    Positioning a signature

    Example using position:

    {
      "title" : "Jupiter Mission",
    
      "signatures" : [
        {
            "signer_email_address" : "heywood.floyd@nasa.gov",
            "visual_signature" : {
                "position" : {
                    "x" : 120,
                    "y" : 60,
                    "width" : 257,
                    "height": 120,
                    "page" : "0"
                }
            }
        },
        {
            "signer_email_address" : "dave@discovery.one",
            "visual_signature" : {
                "position" : {
                    "x" : 420,
                    "y" : 60,
                    "width" : 257,
                    "height": 120,
                    "page" : "4"
                }
            }
        }
      ],
      ...
    
    

    You don't always have the luxury of a perfectly designed PDF form. But you still want to place the signature on the right spot in the document.

    For this situations, you can use a position to place a visual signature. The Skribble web application will enforce the usage of this position.

    In the background Skribble will create a Acroform signature field on this position and place the signature in the new field.

    In the example Heywood's signature will be visible on page 1 in the left lower corner. Dave's signature will only be visible on page 5.

    Mixing positioning information

    Example using a of positioning information:

    {
      "title" : "Dinner before Launch",
    
      "signatures" : [
        {
            "signer_email_address" : "heywood.floyd@nasa.gov",
            "visual_signature" : {
                "form_field" : "project_lead"
            }
        },
        {
            "signer_email_address" : "dave@discovery.one",
            "visual_signature" : {
                "position" : {
                    "x" : 420,
                    "y" : 60,
                    "width" : 257,
                    "height": 120,
                    "page" : "1"
                }
            }
        },
        {
            "signer_email_address" : "frank@discovery.one"
        }
      ],
      ...
    
    

    The visual signature information is distinct to each signer, so you can mix them when you need to.

    In the example:

    No Initial Signers

    Instead of creating a SignatureRequest with predefined signatures, it is possible to start with an empty one and let a user modify the SignatureRequest on the Skribble web application.

    Create a SignatureRequest without signers:

    {
      "title" : "Your Document Title",
      "content" : "...",
      "write_access" : ["heywood.floyd@nasa.gov"],
    
        ...
    }
    
    

    To create an empty SignatureRequest omit the signatures array and provide a user with the rights to modify the SignatureRequest instead.

    The access rights to the SignatureRequest is granted by providing a write_access array containing one or more e-mail addresses for the users with full access.

    Other settings can be provided as usual, e.g. callback URLs.

    When the user visits the URL provided in signing_url, he/she can add signers and define their visual signature appearance in the document, before the signature process continues as usual.

    Example response for an empty SignatureRequest

    {
      "id": "52bcf891-be18-b184-055f-54a0ecbbab24",
      "title": "Your Document Title",
      "document_id": "849b9822-0b125-560f-2874-f3eb20890256",
      "signing_url": "https://my.skribble.com/view/52bcf891-be18-b184-055f-54a0ecbbab24",
      "status_overall": "OPEN",
      "signatures": [],
      "owner": "api_...",
      "write_access": [ "heywood.floyd@nasa.gov" ],
      ...
    }
    
    

    Signing without an Account (No Account Signers)

    Create a SignatureRequest for a signer without a Skrible account (no account signer) in Skribble web application:

    {
        "title": "SigntureRequest for no account signer",
        ...
        "signatures": [
            {
                "signer_identity_data": 
                {
                    "provider" : "swisscom_ra_app",
                    "first_name": "Noah",
                    "last_name": "Count",
                    "mobile_number": "417...",
                    "issuing_country": "CH"
                }
            }
            ...
        ]
    }
    
    

    It is possible to create a SignatureRequest where one or more invited participants won't need a Skribble web application account to sign the SignatureRequest. Those signers are called "no account signers".

    To create a SignatureRequest for a user without an account omit the signatures array entry for this user and provide with the necessary data using the signer_idendity_data element instead.

    All signer_idendity_data data fields are mandatory:

    Other settings can be provided as usual, e.g. callback URLs, documents and so on.

    Each entry in the signatures array will be treated as a distinct identity. This means two entries with the same signer_identity_data are treated as two different identities and require that this person signs the document twice.

    Optionally you can combine signer_idendity_data and signer_email_address in your requests. In this case the system checks if a user exists in Skribble with the specified email and if one is found, then the existing Skribble user will be invited to sign the document. Otherwise the specified user in signer_idendity_data will be invited to sign.

    When the user visits the URL provided in the field signing_url inside the signature element, they will be forwarded to a special preview page of the document and can start the signature process as usual.

    Please note that you do not mix up the signing_url inside the signature field with the signing_url on the top level of the response. This contains the default URL for users with a regular account on Skribble web application.

    Example response for aSignatureRequest for signers without a Skribble web application account:

    {
      "id": "aaa36a91-80e7-b159-866c-69364fabcbbb",
      "title": "SignatureRequest for no account signer",
      ...
      "signatures": [
        {
          "signer_email_address": "ff16c80987244abeb92a9ae719536c55",
          ...
          "signer_identity_data": {
            "first_name": "Noah",
            "last_name": "Count"
          },
          "signing_url": "https://my.skribble.com/view/aaa36a91-80e7-b159-866c-69364fabcbbb/ff16c80987244abeb92a9ae719536c55"
        }
      ],
      "cc_email_addresses": [],
      "owner": "...",
      ...
    }
    
    

    Language parameter

    Skribble will display its content in the user's browser language setting. But you can change the setting by adding a lang parameter to the signing_url.

    Available languages are:

    Example for a lang parameter:

    https://my.skribble.com/view/aaa36a91-80e7-b159-866c-69364fabcbbb/ff16c80987244abeb92a9ae719536c55?lang=fr
    

    Signature Quality

    Create a SignatureRequest for a signer without a Skrible account (no account signer) in Skribble web application:

    {
        "title": "SigntureRequest AES",
        "content" : "JVBERi0xLjMKJcTl8u ... PRgo=",
        "signatures" : [
          {
            "name" : "John Smith",
            "email_address" : "john@devmue.de"
          }
        ],
        ...
    
        "quality" : "AES",
        "legislation" : "ZERTES"
    }
    
    

    Skribble supports different levels of signature qualities. For a discussion, when to use which quality, take a look at QES or AES.

    Two parameters determine the selected quality for the document. These are quality and legislation.

    The parameter quality supports following values:

    The qualities QES and AES_MINIMAL must provide a legislation parameter, because the QES is bound to legal regulations, which are slightly different in Switzerland than the EU.

    So the legislation parameter takes following values:

    Signing as a Legal Entity (Seal)

    Sealing is intended exclusively for companies. A seal is a signature, where the signer is a legal entity (a company) instead of a natural person.

    Creating seals is thus only available to business customers. For more information, please contact us at info@skribble.com, so that we can set-up and activate the sealing option for you.

    Create a seal :

    {
        "content" : "JVBERi0xLjUKJcOkw7zDtsOfC ... ",
        "visual_signature" : { 
            "position" : {            
            "x": 20,
            "y": 20,
            "width": 257,
            "height": 120,
            "page": "0"
          },
          "image" : {
            "content_type": "image/png",
            "content": "iVBORw0KGgo ... "
          }  
        }
    }
    
    

    Uploading and affixing an electronic seal to a document takes just one call using the /v1/seal resource.

    The JSON is similar to the SignatureRequest. It requires only the PDF document as a Base64 encoded string in the content field.

    Additionally, you can place a visual signature on the document, as described in the Visual Signatures chapter of the Skribble API documentation, but this is optional.

    An API response from a seal request contains a document_id of the newly created document with the seal.

    Use the /v1/documents resource to retrieve the document with the electronic seal or reuse it in further signature-requests, such as for personal electronic signatures.

    Response of a seal:

    {
     "document_id": "e4cde459-6e63-0095-10b8-55b39ec39f46"
    }
    
    

    Documents

    The API contains a /v1/documents resource. Which up until now was just used to download the signed content of a document.

    The resource is used heavily by the /v1/signature-requests resource in the background.

    For an integrator there are only a few reasons to use the /documents resource:

    a) You want to re-use a document in more than one SignatureRequest.

    b) You want to modify the document, before it is used in a SignatureRequest. The only supported modification right now is: adding a watermark to the document.

    Background

    Immutability

    The document content is not changeable (immutable). Changes to the document's content always leads to a new document with a new ID.

    The ownership and read-/ write-access are handed on from the parent to the child document.

    As a reminder: The document ID you receive after uploading will never be the same ID after signing or any other change made to the document.

    Encryption

    Documents are persisted only in an encrypted state. An individual AES-256 key is used for each document. The AES key itself is only accessible to the owner of a document and to users with read or write permissions.

    The owner of a document and people with write permissions can manage read-/write-access. The owner can never be changed.

    Document Formats

    PDF

    Skribble currently only supports PDF as a format (https://de.wikipedia.org/wiki/Portable_Document_Format).

    The PDF specification (ISO 32000-1:2008) is very extensive and we cannot guarantee that all PDF documents can be signed. There are very exotic applications in the world that create atypical PDFs and that can possibly lead to errors in the signature process.

    But these cases are very rare and if they do occur, come to us and we will be happy to explore the problem and work out a solution together.

    PDF/A

    Of course Skribble also supports PDF/A documents according to ISO 19005-1:2005 from level PDF/A-1b (https://de.wikipedia.org/wiki/PDF/A). Any changes Skribble makes to the document during the signature process do not violate the PDF/A rules. This means that a PDF/A document is still PDF/A-compliant even after the signature.

    If desired, a document can be converted from PDF to PDF/A via Skribble. (roadmap item)

    Create a document

    Example using content:

    {
      "title" : "3 Paged Document",
      "content" : "JVBERi0xLjMKJcTl8uXrp/Og0MTGCjQg..."
    }
    

    Example using file_url:

    {
      "title" : "3 Paged Document",
      "file_url" : "https://myapp.com/path/to/3_Paged_Document.pdf"
    }
    

    Example response:

    {
      "id": "9ee2b0a8-eaf1-4741-b1b7-9988e14bb391",
      "title": "3 Paged Document",
      "content_type": "application/pdf",
      "size": 428585,
      "page_count": 3,
      "page_width": 595,
      "page_height": 841,
      "owner": "api_....",
      "write_access": [],
      "created_at": "2019-02-20T20:27:59.416Z",
      "updated_at": "2019-02-20T20:28:10.318Z"
    }
    

    The document upload or creation uses the same paramters as creating a SignatureRequest. Actually it is the other way around, a SignatureRequest uses /documents parameters.

    The document content is either uploaded directly with the parameter combinations content and content_type or passed by URL in the parameter file_url. The server then downloads the content and takes the content type from the HTTP header.

    Either the content or the file_url parameter can be used, but not both at the same time.

    The caller is automatically assigned as the owner of the document and is solely authorized to assign further read and write permissions.

    Create a SignatureRequest with a document reference

    Example creating SignatureRequest with reference to document:

    POST /v1/signature-requests HTTP/1.1
    ...
    
    {
      "title" : "3 Paged Document",
    
      "document_id": "9ee2b0a8-eaf1-4741-b1b7-9988e14bb391",
    
      "signatures" : [
        {
            "signer_email_address" : "robert@cool-startup.com"
        }
      ],
    
      ...
    }
    

    A SignatureRequest can be created with a reference to an existing document by ID.

    Instead of using the fields content or file_url, just use the field document_id.