# API Reference

# Introduction

Docsfold API is a service to generate PDFs and images from templates you previously created:

Create templates in our template editor (opens new window)
Use this API to generate PDFs and images

The base url for the api is https://app.docsfold.com/api/

# Authentication

Docsfold uses API keys for authentication in the API. When your account is created, an API key is generated for you. You can copy the key on the API section of Docsfold. You can also reset the API key if necessary, in the same section.

All requests must include the API key in the header, such as:

Authorization: Bearer <APIKEY>

You can find or generate a new API Key here (opens new window)

# Generate PDF

POST /v1/generate-pdf

Endpoint to create a PDF document. Currently only synchronous operations are supported.

# Parameters

template string REQUIRED

Uid of template to use

output_format string

Accepted values are file or url. If empty, default is url

If value is file, the resulting PDF file is returned in the response as a base64 string

If value is url, an URL to download the file is returned in the response

overrides JSON Object REQUIRED

A JSON object with the parameters to replace in the template

{
  "invoice_nr": "123",
  "created_date": "January 1, 2022",
  "due_date": "February 1, 2022",
  "company_name": "Acme Corp",
  "company_address": "Acme road, 1",
  "company_postal_code": "Sunnyville, 1000",
  "client_company_name": "Doe Corp",
  "client_name": "John Doe",
  "client_email": "john@doe.com",
  "payment_method": "Check",
  "payment_method_value": 1000,
  "items": [
    {
      "name": "Website design",
      "value": 300
    },
    {
      "name": "Hosting (3 months)",
      "value": 75
    },
    {
      "name": "Domain name (1 year)",
      "value": 10
    }
  ]
}

Sample Request

{
  "template": "I4s0gTCpK0HbIOPo",
  "output_format": "url",
  "overrides": {
    "invoice_nr": "123",
    "created_date": "January 1, 2022",
    "due_date": "February 1, 2022",
    "company_name": "Acme Corp",
    "company_address": "Acme road, 1",
    "company_postal_code": "Sunnyville, 1000",
    "client_company_name": "Doe Corp",
    "client_name": "John Doe",
    "client_email": "john@doe.com",
    "payment_method": "Check",
    "payment_method_value": 1000,
    "items": [
      {
        "name": "Website design",
        "value": 300
      },
      {
        "name": "Hosting (3 months)",
        "value": 75
      },
      {
        "name": "Domain name (1 year)",
        "value": 10
      }
    ]
  }
}

# Response Fields

Sample response:

{
	"status": "SUCCESS",
	"message": null,
    "uid": "81b5e051-9016-4538-8771-ba5d3a90ece2",
	"date": "2022-11-24T14:29:57.165Z",
	"template": "81b5e051-9016-4538-8771-ba5d3a90ece2",
	"pdf_url": "http://localhost:9000/pdf-file/81b5e051-9016-4538-8771-ba5d3a90ece2",
	"pdf_file": null
}

status string

Status of the operation SUCCESS if the PDF is successfully generated, ERROR otherwise.

message string

If status is ERROR, this field will have a description of the problem. Empty if SUCCESS

uid string

Uid of the generated document.

date string

Timestamp of the operation

template string

The template uid

pdf_url string

If output_format is url or empty, this field will have an URL to download the PDF file.

pdf_file string

If output_format is file, this field will have the file in a base64 encoded string.

# Generate Image

POST /v1/generate-image

Endpoint to create an image. Currently only synchronous operations are supported.

# Parameters

template string REQUIRED

Uid of template to use

output_format string

Accepted values are file or url. If empty, default is url

If value is file, the resulting image file is returned in the response as a base64 string

If value is url, an URL to download the file is returned in the response

render_pdf boolean

Accepted values are true or false. If empty, default is false

If true, instead of an image, a PDF file will be rendered from the image template.

overrides JSON List REQUIRED

A JSON list with the parameters to replace in the template

# Override element child parameters

name string REQUIRED

Element/layer name to change

text string For text, bar code or QR code layers only

Change the element text content. If the element is a bar code, the value must be a valid code.

url string For image layer only

Change the element image

width integer

Change the element width

height integer

Change the element height

width integer

Change the element width

x integer

Change the element x position

y integer

Change the element y position

borderColor string

Change the element border color, in hex format. e.g. "#00FF00"

borderWidth integer

Change the element border width

borderShadow string For image layer only

Change the element box shadow. The syntax is described here (opens new window)

font string For text layer only

Change the element text font. TODO list of fonts

fontSize string For text layer only

Change the element text size.

fontWeight string For text layer only

Change the element text weight.

fontColor string For text layer only

Change the element text color, in hex format. e.g. "#00FF00"

textShadow string For text layer only

Change the element text.

horizontalAlign string For text layer only

Change the element text horizontal alignment. left, center, right

verticalAlign string For text layer only

Change the element text vertical alignment. top, center, bottom

codeType string For bar code layer only

Change the element bar code type. Accepted values are UPC_A, UPC_E, CODE_39, CODE_128, PDF147, EAN_8, EAN_13

color string For circle and rectangle layers only

Change the element background color, in hex format. e.g. "#00FF00"

background boolean For text layers only

Enable/disable element background.

backgroundColor string For text layers only

Change the element background color, in hex format. e.g. "#00FF00"

backgroundRadius integer For text layers only

Change the element background radius.

backgroundHorizontalPadding integer For text layers only

Change the element background horizontal padding.

backgroundVerticalPadding integer For text layers only

Change the element background vertical padding.

opacity double For text, circle and rectangle layers only

Change the element opacity. Values between 0 and 1.

borderRadius integer For rectangle layers only

Change the element border radius.

{
  "template": "3iXlPJj7S54x6fXh",
  "output_format": "url",
  "overrides": [
    {
      "name": "content",
      "text": "Aut beatae Quis et quidem sunt sed obcaecati sunt ad alias pariatur aut dolore illum. Et assumenda nostrum in consectetur provident aut voluptatem ipsum aut nihil error aut illo fugit."
    },
    {
      "name": "footer",
      "text": "22:59 - 2022-12-30 - Your platform"
    },
    {
      "name": "name",
      "text": "Your name"
    },
    {
      "name": "account",
      "text": "@account"
    },
    {
      "name": "photo",
      "url": "https://images.unsplash.com/photo-1603780057844-108f8bd83502?ixlib=rb-4.0.3&ixid=MnwxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHx8&auto=format&fit=crop&w=465&q=80"
    }
  ]
}

# Response Fields

Sample response:

{
	"status": "SUCCESS",
	"message": null,
    "uid": "81b5e051-9016-4538-8771-ba5d3a90ece2",
	"date": "2022-11-24T14:29:57.165Z",
	"template": "81b5e051-9016-4538-8771-ba5d3a90ece2",
	"image_url": "http://localhost:9000/image-file/81b5e051-9016-4538-8771-ba5d3a90ece2",
	"image_file": null
}