Creating a Flow instance

This guide shows how to create a simple Flow instance where two participants sign an agreement. To be sure you can successfully authenticate with the Scrive Flow service, read the guide on authentication first.

The code in this guide is written in Python, but you are free to use any language. If you want to follow along, import the requests library, define a helper function for checking status codes of the responses, and configure the correct credentials.

import json
import requests

def assert_status_code(res, code):
  '''On unexpected status code, exit and print the response.'''
  if res.status_code != code:
    print(f"Expected status {code}, but received {res.status_code}:")
    print(res.text)
    exit()

# use the correct server and OAuth 1.0 credentials here
server = "https://api-testbed.scrive.com"
client_key = 'c8f0ac51f32e8565_12565'
client_secret = 'c9cc5684316d6128'
token_key = 'b70052170c5d76a4_25226'
token_secret = '7b004c14ba6a5d21'

headers = {
  'Authorization':
    f'oauth_signature_method="PLAINTEXT", '
    f'oauth_consumer_key="{client_key}", '
    f'oauth_token="{token_key}", '
    f'oauth_signature="{client_secret}&{token_secret}"'
}

Preparing the documents

Any document used in a Flow instance has to first be uploaded through the Scrive Document API. In our example, we have a PDF file of an agreement in our working directory, named agreement.pdf, which we upload.

file = open('agreement.pdf', 'rb')
res = requests.post(f"{server}/api/v2/documents/new", headers=headers, files={'file': file})
assert_status_code(res, 201)

The response contains identifiers expected by the endpoint for creating Flow instances: the document ID and an ID of each Signatory, i.e. party of the document.

response = res.json()
document_id = response['id']
author = response['parties'][0]

The new document uploaded above has only a single party to it, its author. The author is a special kind of participant which does not play a role in the Flow instance. We have to additionally create the two parties that will be the participants of our Flow instance and add them to the document.

parties = [{}, {}]
data={"document": json.dumps({"parties": [author] + parties})}
res = requests.post(f"{server}/api/v2/documents/{document_id}/update", headers=headers, data=data)
assert_status_code(res, 200)

Creating an instance

The document we want to have signed in a Flow instance has been prepared and we can now compose the instance creation request.

document = res.json()
request = {
  "title": "Simple Two Person Agreement",
  "documents": [
    {
      "document_id": document['id'],
      "label": "agreement",
      "type": "esign",
      "parties": [
        {
          "participant": "bodil",
          "signatory_id": document['parties'][1]['id'],
        },
        {
          "participant": "inga",
          "signatory_id": document['parties'][2]['id'],
        },
      ],
    }
  ],
  "participants": [
    {
      "label": "bodil",
      "name": "Bodil Oskarsson",
      "emails": [
        {
          "email": "bodil.oskarsson@example.com",
        },
      ],
    },
    {
      "label": "inga",
      "name": "Inga Engberg",
      "phones": [
        {
          "phone": "0225-4141465",
        },
      ],
      "authentication": {
        "view": {
          "max_attempts": 3,
          "provider": "sms_otp",
        },
        "sign": [
          {
          "label": "inga_sign_auth",
          "max_attempts": 3,
          "provider": "sms_otp",
          },
        ],
      },
    },
  ],
  "process": {
    "type": "parallel_all",
    "steps": [
      {
        "type": "sign",
        "participant": "bodil",
        "documents": [
          "agreement"
        ],
      },
      {
        "type": "sign",
        "participant": "inga",
        "authentication": "inga_sign_auth",
        "documents": [
          "agreement"
        ],
      },
    ],
  },
}

res = requests.post(f"{server}/flow/instances", headers=headers, json=request)
assert_status_code(res, 201)

The execution of instance's process has started now. Invitation messages were sent to Bodil's email and Inga's phone. They have access to their Overview page and can sign the agreement.

The response to the instance creation request contains details about the instance useful for further interactions with it.