Throughout this guide, we will construct a signature request where users of the Plumaa ID mobile app can sign.

​
Get your API key

To get started, you need to download the app and get onboarded. Once you are setup on the mobile app, you have automatic access to the web app.

Sign into the webapp, create an organization and navigate to their settings. From there, you can follow our guide to setup an API Key.

Once you have an API Key, you’re ready to go.

​
Upload your content

The first step is to upload the content you want to be signed. This can be a PDF, a raw text file (e.g. a privacy policy), a JSON file or a specialized IOU format (debt acknowledgment).

To upload a file, we offer a pre-signed URL that allows you to upload the file directly to our storage infrastructure.

curl --request GET \
  --url https://api.plumaa.id/rest/v1/sign-file-url?filePath=<path-to-file>&md5Checksum=<MD5Checksum> \
  --header 'Authorization: Bearer <token>'

The API endpoint requires 2 query parameters:

  • filePath: The path to the file you want to upload. Each organization has its own root directory and files are versioned to ensure they are not overwritten.
  • md5Checksum: The MD5 checksum of the file you want to upload. This is used to verify the integrity of the file so it is not corrupted during the upload process.

Once you get a response, you can use the url to upload the file and the key to reference it when you create the signature request.

For example, to upload a simple text file, you can use the following process:

import { md5, util } from "node-forge";
import axios from "axios";
import plumaaClient from './plumaa-client'

// Our message. It is salted to ensure uniqueness
const saltedMessage = `Some message you want to get signed. Salt: _${Date.now()}_`

// Obtain the message MD5 checksum
const md5Checksum = md5
  .create()
  .update(util.createBuffer(saltedMessage, "utf8").bytes(), "raw")
  .digest()
  .toHex();

// Update
const { data } = await plumaaClient.signFileUrl({
  filePath: `/free/${Date.now()}.txt`,
  md5Checksum,
});

// Upload the file
await axios.put(data.url, saltedMessage, {
  headers: {
    "Content-MD5": util.encode64(util.hexToBytes(md5Checksum)),
  },
});

​
Create a signature request

A signature request is a request to sign a document. It can be sent to one or more signers by creating an invite for each signer.

To create a signature request, you can call the POST /signature-request endpoint.

curl --request POST \
  --url https://api.plumaa.id/rest/v1/signature-request \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "input": {
    "draft": true,
    "name": "<document name (e.g. privacy policy)>",
    "content": { ... }, // see below
    "organization": "<organization id>",
    "nom151": true
  }
}'

The creation endpoint includes a draft flag that allows you to create a signature request without sending it to the signers. Requests can be sent later by updating this field to false using the PUT /signature-request/ endpoint.

As you may notice, the content field is not fulfilled in the example above.

To create a signature request with a raw text content, you can use the following example. Note the key is that returned from the sign-file-url endpoint:

curl --request POST \
  --url https://api.plumaa.id/rest/v1/signature-request \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "input": {
    "draft": true,
    "name": "<document name (e.g. privacy policy)>",
    "content": {
      "raw": "<data.key>"
    },
    "organization": "<organization id>",
    "nom151": true
  }
}'

​
Create an invite

Once you have created a signature request, you can send invites to the signers. Each invite is tracked individually and will show up in the mobile app for the signer and the webapp for the organization.

To create an invite, you can call the POST /signature-request-invite endpoint.

curl --request POST \
  --url https://api.plumaa.id/rest/v1/signature-request-invite \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "input": {
    "signatureRequest": "<signature request id>",
    "subject": "<subject id>"
  }
}'

To get the subject id, you can use the GET /subject endpoint. Consider that a link between the subject and the organization must exist before creating the invite.

​
Let the signer to invite themselves

WelcomeConcepts