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 two callback types in a SignatureRequest. One for the success case callback_success_url and one in case of an error callback_error_url.

    Success occurs when the document has been successfully signed by all parties involved. 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 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.

    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/sign?id=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 is one more field to enable a nice user flow, the exitURL.

    ExitURL, ErrorURL and DeclineURL

    Example: will redirect to https://google.com after signing

    https://my.scribble.com/sign?id=8229873d-d7c7-4e2b-a8a3-331353243d97&exitURL=https%3A%2F%2Fgoogle.com
    

    When the user signs the document successfully, he/she normally stays on the Skribble web application.

    But you can add 3 exit points as query parameters to the signing_url, then the user will be redirected to the provided URL, when the signature process finished.

    So, you can bring the user back from Skribble to your application!

    Exit points:

    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/sign?id=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" : 320,
                    "height": 240,
                    "page" : "0"
                }
            }
        },
        {
            "signer_email_address" : "dave@discovery.one",
            "visual_signature" : {
                "position" : {
                    "x" : 420,
                    "y" : 60,
                    "width" : 320,
                    "height": 240,
                    "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" : 320,
                    "height": 240,
                    "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/sign?id=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": "...",
      ...
    }
    
    

    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": 200,
            "height": 200,
            "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.