Introduction

Docdown automates your document generation workflows.

Upload your PDF documents and define the template fields.
Setup your custom automations with visual Workflow Builder.
Use web forms, integrations, or this REST API to trigger your workflow and generate your document.

Authentication

To verify your authentication:

curl "https://api.docdown.io/v1/auth" \
  -H "Authorization: bearer API_KEY"

The above endpoint returns JSON structured like this:

{
  "id": "5196dq15-b03d-4687-bd7x-570b53890534",
  "name": "My Name",
  "email": "my@email.com"
}

Make sure to replace API_KEY with your API key.

Docdown uses API keys to allow access to the API. You can get your API key here.

Docdown expects the API key to be included in all API requests to the server in a header that looks like the following:

Authorization: bearer API_KEY

Replace API_KEY with your personal API key.

HTTP Request

GET https://api.docdown.io/v1/auth

Documents

To get all documents in your Docdown account:

curl "https://api.docdown.io/v1/documents" \
  -H "Authorization: bearer API_KEY"

The above endpoint returns JSON structured like this:

[
  {
    "id": "2118cff9-dd53-4355-b103-c4ba30dd08fe",
    "name": "certificate.pdf",
    "fields": [
      {
        "key": "photo",
        "label": "Photo",
        "required": false,
        "type": "string",
        "helpText": "Image URL."
      },
      {
        "key": "certify",
        "label": "Certify",
        "type": "boolean",
        "required": false,
        "helpText": "True or non-empty value marks the field as checked."
      },
      {
        "key": "full_name",
        "label": "Full Name",
        "type": "string",
        "required": false,
        "helpText": "Text field that expects text data."
      },
      {
        "key": "date_of_signature_dd_mm_yyyy",
        "label": "Date of Signature (DDMMYYYY)",
        "type": "string",
        "required": false,
        "helpText": "Text field that expects text data."
      },
      {
        "key": "signature",
        "label": "Signature",
        "children": [
          {
            "key": "signerName",
            "type": "string",
            "required": true,
            "helpText": "Full legal name of the signer."
          },
          {
            "key": "signerEmail",
            "type": "string",
            "required": true,
            "helpText": "Email address of the signer. Signer will receive completed document and audit trail at this address after completion."
          },
          {
            "key": "signature",
            "type": "string",
            "helpText": "Signature image URL.",
            "required": true
          }
        ]
      }
    ]
  }
]

To get a single document:

curl "https://api.docdown.io/v1/documents/get/<DOCUMENT_ID>" \
  -H "Authorization: bearer API_KEY"

You can request an array of all the documents you have setup in your account. The endpoint responds with Document objects, which includes id, name and fields attributes.

The fields attribute is a list of field schema for all the fields you have setup in the document. Each schema object represents what the API expects when sending data to the API.

HTTP Request

GET https://api.docdown.io/v1/documents

Parameters

Parameter	Description
DOCUMENT_ID	The id of the document

Workflows

To get an array of workflows:

curl "https://api.docdown.io/v1/workflows" \
  -H "Authorization: bearer API_KEY"

The above endpoint returns JSON structured like this:

[
  {
    "id": "2325667e-96d0-4063-863b-8a813aeef812",
    "name": "Generate certificate from Zapier",
    "active": true,
    "steps": [
      {
        "id": "8b1dea48-5370-45ca-aaed-abd3ef2ccea0",
        "name": "Incoming Webhook",
        "type": "incomingWebhook",
        "order": 1
      },
      {
        "id": "58a36313-17a2-457b-ac4c-e2a3e73f57b5",
        "name": "Email",
        "type": "email",
        "order": 2
      }
    ]
  }
]

You can request an array of all the workflows you have setup in your account. The endpoint responds with Workflow objects, which includes id, name, active and steps attributes.

HTTP Request

GET https://api.docdown.io/v1/workflows

Workflow Schema

You can request the field schema that a workflow expects for execution. Each schema object inside the fields array describes what the API expects for each field.

To get the fields schema for a workflow:

curl "https://api.docdown.io/v1/workflows/schema/<WORKFLOW_ID>" \
  -H "Authorization: bearer API_KEY"

The above endpoint returns JSON structured like this:

{
  "fields": [
    {
      "key": "photo",
      "label": "Photo",
      "required": false,
      "type": "string",
      "helpText": "Image URL."
    },
    {
      "key": "certify",
      "label": "Certify",
      "type": "boolean",
      "required": false,
      "helpText": "True or non-empty value marks the field as checked."
    },
    {
      "key": "full_name",
      "label": "Full Name",
      "type": "string",
      "required": false,
      "helpText": "Text field that expects text data."
    },
    {
      "key": "date_of_signature_dd_mm_yyyy",
      "label": "Date of Signature (DDMMYYYY)",
      "type": "string",
      "required": false,
      "helpText": "Text field that expects text data."
    },
    {
      "key": "signature",
      "label": "Signature",
      "children": [
        {
          "key": "signerName",
          "type": "string",
          "required": true,
          "helpText": "Full legal name of the signer."
        },
        {
          "key": "signerEmail",
          "type": "string",
          "required": true,
          "helpText": "Email address of the signer. Signer will receive completed document and audit trail at this address after completion."
        },
        {
          "key": "signature",
          "type": "string",
          "helpText": "Signature image URL.",
          "required": true
        }
      ]
    }
  ]
}

HTTP Request

GET https://api.docdown.io/v1/workflows/schema/<WORKFLOW_ID>

Parameters

Parameter	Description
WORKFLOW_ID	The id of the worklfow

Executing a Workflow

To execute a workflow, send a POST request to https://api.docdown.io/v1/trigger/<WORKFLOW_ID> with the field data in the request body.

To trigger the workflow:

curl "https://api.docdown.io/v1/trigger/<WORKFLOW_ID>" \
  -H "Authorization: bearer API_KEY" \
  -H "Content-Type: application/json" \
  -d \"{
    "photo": "https://upload.wikimedia.org/wikipedia/commons/thumb/6/68/Joe_Biden_presidential_portrait.jpg/480px-Joe_Biden_presidential_portrait.jpg",
    "certify": true,
    "full_name": "Joe Biden",
    "date_of_signature_dd_mm_yyyy": "01012021",
    "signature":{
        "signerName": "Joe Biden",
        "signerEmail": "potus@us.gov",
        "signature": "https://upload.wikimedia.org/wikipedia/commons/thumb/d/d9/Joe_Biden_Signature.svg/176px-Joe_Biden_Signature.svg.png"
    }
    }\"
  }

The above request body can also be flattened as below:

curl "https://api.docdown.io/v1/trigger/<WORKFLOW_ID>" \
  -H "Authorization: bearer API_KEY" \
  -H "Content-Type: application/json" \
  -d \"{
      "photo": "https://upload.wikimedia.org/480px-Joe_Biden_presidential_portrait.jpg",
      "certify": true,
      "full_name": "Joe Biden",
      "date_of_signature_dd_mm_yyyy": "01012021",
      "signature.signerName": "Joe Biden",
      "signature.signerEmail": "potus@us.gov",
      "signature.signature": "https://upload.wikimedia.org/176px-Joe_Biden_Signature.svg.png"
    }\"
  }

The above command returns JSON structured like this:

{
  "workflowRunId": "5196de15-b03d-4687-bc7a-570b53890534",
  "resourceUrl": "https://api.docdown.io/v1/resource/file/5196de15-b03d-4687-bc7a-570b53890534?mode=blob"
}

HTTP Request

POST https://api.docdown.io/v1/trigger/<WORKFLOW_ID>

Parameters

Parameter	Description
WORKFLOW_ID	The id of the worklfow

Get the generated PDF file from workflow execution

To trigger the workflow:

curl "https://api.docdown.io/v1/resource/file/<WORKFLOW_RUN_ID>" \
  -H "Authorization: bearer API_KEY"

The above command returns either binary PDF file or base64 encoded string.

HTTP Request

GET https://api.docdown.io/v1/resource/file/<WORKFLOW_RUN_ID>

Parameters

Parameter	Description
WORKFLOW_RUN_ID	The id of the worklfow execution

Query Parameters

Parameter	Default	Description
mode	"base64"	If set to "blob", the result will be in binary format, else in base64 encoded string.

Replace the WORKFLOW_RUN_ID with workflowRunId from the response of /v1/trigger/WORKFLOW_ID.

Get the data of the workflow execution

curl "https://api.docdown.io/v1/resource/data/<WORKFLOW_RUN_ID>" \
  -H "Authorization: bearer API_KEY"

The above command returns JSON structured like this:

{
  "field_1": "field1_value",
  "field_2": "field2_value"
}

HTTP Request

GET https://api.docdown.io/v1/resource/data/<WORKFLOW_RUN_ID>

Parameters

Parameter	Description
WORKFLOW_RUN_ID	The id of the worklfow execution

Replace the WORKFLOW_RUN_ID with workflowRunId from the response of /v1/trigger/WORKFLOW_ID.

Workflow History

You can request an array of all the workflows executions for a particular Workflow. The endpoint responds with History objects, which contains id, workflow, workflowId and file_name, file_url attributes. This object also includes the received value for fields of each step of the workflow, prefixed with step{order}-.

To get an array of completed workflow executions:

curl "https://api.docdown.io/v1/workflows/completed/<WORFKLOW_ID>" \
  -H "Authorization: bearer API_KEY"

The above endpoint returns JSON structured like this:

[
  {
    "id": "1f1fbfb7-9001-4256-a85c-6c291525aa97",
    "workflow": "Google Form workflow",
    "workflowId": "2de38ef5-5677-49b6-84d1-875b67e35020",
    "file_name": "file.pdf",
    "file_url": "https://api.docdown.io/v1/resource/file/1f1fbfb7-9001-4256-a85c-6c291525aa97?mode=blob",
    "step1-first_name": "",
    "step1-last_name": ""
  }
]

HTTP Request

GET https://api.docdown.io/v1/workflows/completed/<WORKFLOW_ID>

Parameters

Parameter	Description
WORKFLOW_ID	The id of the worklfow

Errors

The Docdown API uses the following error codes:

Error Code	Meaning
400	Bad Request -- Your request is invalid or validation failed.
401	Unauthorized -- Your API key is incorrect.
403	Forbidden -- Your access leve is inadequate or usage quota is over limit.
404	Not Found -- The specified item could not be found.
406	Not Acceptable -- You requested a format that isn't acceptable.
429	Too Many Requests -- Slow down!
500	Internal Server Error -- We had a problem with our server. Try again later.
503	Service Unavailable -- We're temporarily offline for maintenance. Please try again later.

The Docdown API rate limit is 10 requests per 10 seconds.