Documents API

1.0 Usage

1.1 User Registration

Under normal circumstances, the registration process is automated, and takes place when a user, or service, makes the first request against Documents API. In cases where you wish to manually register a user, or update user information, you can submit an IDP-issued identity token:

curl -X POST https://api.documents.ones-now.com/auth/id_token \
    -H "Content-Type: application/json" \
    -d '{"id_token": "<id_token>"}'

The Documents API differentiates between two types:

• Users
• Service

A service is a application registered on IDP, that may submit and query documents from Documents API on behalf of a user.

1.2 Digital Signature Request (DSR)

1.2.1 Make a Signature request

1.2.1.1 Use CURL

To submit a new digital signature request, you need the following details:

• signing_parties: User ID’s, usernames, or public keys
  • to include multiple signing parties, add multile signing_parties parameters
  • to have a user sign it’s own document, you do not need to include signing_parties
• issue_time: The unix time in seconds, at which the request was issued
• subject: The subject of the signature (for ex. Please sign this document)
• title: The title of the document (for ex. Rental Agreement)
• callback_url: The URL at which you want to be notified about changes related to this document

This is an example request:

curl -X POST https://api.documents.ones-now.com/signatures \
    -H "Content-Type: application/x-www-form-urlencoded" \
    -H "Authorization Bearer <token>" \
    -d "signing_parties=username1" \
    -d "issue_time=1723708291" \
    -d "subject=Please sign" \
    -d "title=Rentral Agreement" \
    -d "file=@/path/to/file.pdf" \
    -d "callback_url=https://my-domain/callback"

The JSON response will contain the document and file ID as well as signing parties:

{
    file_id: '67830388-53fc-4000-8846-0676cdb5be40',
    document_id: '907c4e9a-ed8e-4aaf-9568-caa0a77d4930',
    signatures: [
        {
            signature_id: '4890ee11-9b26-4ee0-b0d3-60cf043aaa03',
            user_id: 'af018b75-4362-47a9-b463-0731e29644ec',
            user_identifier: 'a9fa6083-10a2-4128-829e-df20ed9b43af'
        }
    ]
}

The user_identifier is the global user ID, and should be known to IDP. The user_id is specific to Documents API and not known to IDP.

1.2.1.2 Use NodeJS without Library

import axios from "axios"
import * as FormData from 'form-data'
const fs = require('fs')


const form = new FormData.default()
form.append('title', "Rentral Agreement")
form.append('signing_parties', userId)
form.append('issue_time', 1723708291)
form.append('subject', 'Please sign')
form.append('file', fs.createReadStream('./tests/assets/source_a4_vertical.pdf'))

const headers = form.getHeaders()
const axiosConfig = {
    headers: { ...headers, Authorization: `Bearer ${accessToken}` }
}
const response = await axios.post<SignatureRequestResult>(
    https://api.documents.ones-now.com/v1/a/signatures/request,
    form,
    axiosConfig
)

1.2.1.3 Use NodeJS with generic Library Helper

Make a signature request using the signatureRequest function:

import axios from "axios"
import * as FormData from 'form-data'
const fs = require('fs')

import { signatureRequest } from "@ones.dev/documents-api"


const formData = new FormData.default()
formData.append('title', "Rentral Agreement")
formData.append('signing_parties', userId)
formData.append('issue_time', 1723708291)
formData.append('subject', 'Please sign')
formData.append('file', fs.createReadStream('./tests/assets/source_a4_vertical.pdf'))

const additionalHeaders = formData.getHeaders()
const response = await signatureRequest(
    https://api.documents.ones-now.com,
    formData,
    {
        accessToken,
        additionalHeaders
    },
)

1.2.2 Unknown Signing Parties

When you submit a signature request with a signing party that’s not already known, Documents API will try to attempt to fetch the user information from IDP. If that’s not possible, the request will be rejected.

1.2.3 Access Rules

User access

By default, all users involved in a signature request, can access the document, signatures, and files.

• Owner (submitter)
• Signing party (if the user is not the owner)

Service access

When a document is submitted by a service, on behalf of a user, the service automatically get’s access to the document, signatures, and files. This is useful, if you prefer to handle document access management on your own.

IMPORTANT: Service access is enabled, whenever a resource-specific JWT token is used to submit a signature request. Documents API verifies the JWT with the IDP public key, and extracts the service identifier from the the audience.

1.3 List Documents

To list all documents as user or service, you can use the following request:

curl -X GET /v1/a/documents \
    -H "Authorization Bearer <token>"

You will only see documents, you have access to.

{
    data: [
        {
            id: '1559c052-6c35-4b85-ad4e-e7c131397d03',
            relay_id: '328214c8-89cd-4160-9e67-693ea65dda3f',
            is_signed: false,
            created_at: '2024-07-13T10:15:53.234544',
            modified_at: '2024-07-13T10:15:53.234552'
        },
        {
            id: 'ee94ddeb-9da6-494b-b522-66a0cb80a2e3',
            relay_id: '8ef26e0d-232d-4c8b-9496-a74d77822203',
            is_signed: false,
            created_at: '2024-07-13T10:37:35.841295',
            modified_at: '2024-07-13T10:37:35.841303'
        },
        {
            id: 'abf58a3e-eb3b-490b-bdf2-f3c41dd4352b',
            relay_id: '4c1106e9-ac93-4fd7-8235-39bdf3f06f11',
            is_signed: false,
            created_at: '2024-07-13T10:39:04.468416',
            modified_at: '2024-07-13T10:39:04.468421'
        },
    ],
    total: 14
}

1.4 Get Document

To get an individual document, you can use the following request:

curl -X GET https://api.documents.ones-now.com/v1/a/documents/1559c052-6c35-4b85-ad4e-e7c131 \
    -H "Authorization Bearer <token>"

You will receive the document details, if you are allowed to access them:

{
    id: '907c4e9a-ed8e-4aaf-9568-caa0a77d4930',
    relay_id: 'd2da2e4d-0c62-4a5a-aac9-ee90b92e46ed',
    is_signed: false,
    created_at: '2024-07-13T10:54:28.359640',
    modified_at: '2024-07-13T10:54:28.359645'
}

1.5 Get Document Files

To get all files associated with a document, you can use the following request:

curl -X GET https://api.documents.ones-now.com/v1/a/documents/1559c052-6c35-4b85-ad4e-e7c131/files \
    -H "Authorization Bearer <token>"

You will receive a list of files, if you are allowed to access them:

{
    data: [
        {
            id: '67830388-53fc-4000-8846-0676cdb5be40',
            document_id: '907c4e9a-ed8e-4aaf-9568-caa0a77d4930',
            name: null,
            size: 4624,
            hash: '9738e1d01ad512ee9a02fb14d13f1fedb366e6212eb0753b2f89e7ff6b6861a9',
            filename: 'source_a4_vertical.pdf',
            bucket_name: 'documents',
            path: 'uploads/a6ebd3f7-d45c-4369-8f6c-8cc0f89e7610-source_a4_vertical.pdf',
            created_at: '2024-07-13T10:54:28.368120',
            modified_at: '2024-07-13T10:54:28.368125'
        }
    ],
    total: 1
}

1.6 Download File

To download a specific document file, you need the document ID and file ID:

curl -X GET https://api.documents.ones-now.com/v1/a/files/download/1559c052-6c35-4b85-ad4e-e7c131/files/67830388-53fc-4000-8846-0676cdb5be

2.0 JavaScript Library

2.1 Installation

Create a file .npmrc in your project root directory and add the following line:

registry=https://npm.pantherx.org

Install the library:

npm install @ones.dev/documents-api

2.2 Function Usage

• getDocuments
• getDocument
• getDocumentFiles
• getDocumentSignatures
• getDocumentsWithUserSignature
• getFile
• downloadFile (will redirect to the file URL)
• urlToDownloadFile (will return the file URL)
• downloadDocumentFile (will redirect to the file URL)
• urlToDownloadDocumentFile (will return the file URL)
• signatureRequest
• verfyDocument
• getSignature

2.3 Class Usage

const api = new DocumentsApi({
    baseUrl: 'https://api.documents.ones-now.com',
    accessToken: '...'
})

const document = await api.getDocument('1559c052-6c35-4b85-ad4e-e7c131')