Place fields with text markers

Write each field into the document as a short piece of text, and Inkly creates a field wherever it finds one. If your system generates the PDF, this saves you measuring positions, and a field stays in the right place when the text around it moves.

Inkly never changes your PDF, and if a marker is wrong or its position cannot be read exactly, the whole send is refused and nothing goes out. For scans, PDFs exported from Microsoft Word, or a PDF you cannot edit, place fields by coordinates instead.

The three steps

Add a marker to the document
Put a marker where each field belongs, naming the signer by a short ref of your choice.
A marker in the document
```
Signed by: {{signature;signer=client}}
```
Upload the PDF
Start an upload and send the file, the same way as any other PDF.

Send with markers turned on

Set use_markers to true and give each signer the same ref the markers use. You do not need to send fields. Without use_markers, the PDF is not scanned for markers.

Send with markers

curl -X POST "https://www.inkly.so/api/v1/documents/from-upload" \
  -H "Authorization: Bearer $INKLY_API_KEY" \
  -H "Idempotency-Key: crm-8841-send-1" \
  -H "Content-Type: application/json" \
  -d '{
    "upload_id": "d06b8e24-9f13-4c7a-a5d8-3e1c7f2b6049",
    "use_markers": true,
    "recipients": [
      {
        "ref": "client",
        "name": "Alex Morgan",
        "email": "alex@example.com"
      },
      {
        "ref": "agency",
        "name": "Jordan Park",
        "email": "jordan@agency.example"
      }
    ]
  }'

You can combine markers with fields, up to 500 fields in total. Dropdown and prefilled fields still go in fields.

There is no test mode. Send to your own email address to check the result, and void the document if you do not want to finish it.

Syntax

Marker syntax

{{<type>;signer=<ref>[;required=false][;width=<fraction>][;height=<fraction>]}}

typeFirst, and case-insensitive: signature, initials, name, email, date, text, number, or checkbox. A dropdown needs options, so send it in fields.
signerRequired. The exact ref of a recipient with the signer role. A ref containing ; = { or } cannot be used in a marker.
requiredOptional: true or false. Defaults to true.
width, heightOptional: a decimal above 0 and up to 1, as a fraction of the page. The default sizes are below, under Where the field goes.

Option names are lowercase, each can appear once, and unknown options are refused. Spaces around ; and = are ignored. A marker can be up to 200 characters and must fit on one line.

Every field type uses the same pattern, with only the first word changing. This document asks the client for eight kinds of field and the agency for a signature. The request above sends it: one recipient for each signer the markers name.

Markers for two signers

Client name:  {{name;signer=client}}
Client email: {{email;signer=client}}
Start date:   {{date;signer=client}}
Seats:        {{number;signer=client}}
PO number:    {{text;signer=client;required=false;width=0.3}}
I agree to the terms {{checkbox;signer=client}}
Initials:     {{initials;signer=client}}
Signature:    {{signature;signer=client}}

Agency:       {{signature;signer=agency}}

A dropdown cannot be written as a marker, because its choices do not fit. Send it in fields with a position, and it is added to the fields the markers create:

Markers plus a dropdown

curl -X POST "https://www.inkly.so/api/v1/documents/from-upload" \
  -H "Authorization: Bearer $INKLY_API_KEY" \
  -H "Idempotency-Key: crm-8841-send-1" \
  -H "Content-Type: application/json" \
  -d '{
    "upload_id": "d06b8e24-9f13-4c7a-a5d8-3e1c7f2b6049",
    "use_markers": true,
    "recipients": [
      {
        "ref": "client",
        "name": "Alex Morgan",
        "email": "alex@example.com"
      },
      {
        "ref": "agency",
        "name": "Jordan Park",
        "email": "jordan@agency.example"
      }
    ],
    "fields": [
      {
        "recipient": "client",
        "type": "dropdown",
        "page": 1,
        "x": 0.1,
        "y": 0.4,
        "width": 0.3,
        "height": 0.03,
        "label": "Plan",
        "options": [
          "Starter",
          "Growth",
          "Scale"
        ]
      }
    ]
  }'

Hiding a marker

Make the marker white and set it at 1 or 2 points, so its size differs from the text around it. A marker the same size as the text beside it may be merged into that text by the tool that exports the PDF, and is then refused. We tested this with pdf-lib, Chrome print to PDF, and Google Docs.

Any hidden text works, such as text render mode 3 or zero opacity, which also suits colored backgrounds.

Marker color is not checked, so a marker left black will be visible to the signer. White text also stays in the PDF, where it can be found by text search or copying.

Where the field goes

The field starts at the marker's left edge, and its bottom sits on the marker's baseline, so it grows up from a signature line. A box that would run off the page is moved back onto it. Default sizes, in PDF points:

signature180 × 40
initials72 × 28
name, email, text180 × 20
date, number110 × 20
checkbox14 × 14

Inkly does not detect a field overlapping other text, so leave blank space around each marker and check the result by sending to your own email address.

What cannot be read

Inkly can only act on markers the PDF exposes as text, so a marker in a scan or an image, or one lost by the exporting tool, is not found. A marker must be plain ASCII and kept apart from right-to-left text such as Hebrew or Arabic.

A page containing a marker is refused as marker_page_unsupported if it has any of these anywhere on the page, even far from the marker, because Inkly cannot place a field on it exactly:

Page rotation, a user unit other than 1, or a visible area that does not start at the page's origin
Rotated, skewed, or mirrored marker text
Soft hyphens, zero-width or other invisible formatting characters, or accents drawn as separate glyphs
Character spacing or kerning adjustments
Type3 or vertical fonts, zero-size text, a broken font, or a font the PDF does not include other than the standard 14

Microsoft Word's PDF export adds kerning adjustments to ordinary text, so pages exported from Word are refused. Send coordinates for Word documents, or export the document from Google Docs instead.

Recovering from a refusal

marker_not_foundNo marker could be read. A scanned PDF has no text, so a scan needs coordinates. Fix the PDF and upload it again, or send fields with a new key on the same upload.
marker_invalidA marker is malformed, wraps onto another line, starts in the middle of other text, does not fit on its page, or takes the document over 500 fields. Fix the PDF, upload it again, and use a new key.
marker_unknown_recipientA marker names a signer that is not a signer ref in the request. Fix the request and use a new key on the same upload.
marker_page_unsupportedA page with a marker cannot be converted exactly. Fix the PDF and upload it again, or send fields with a new key on the same upload.
marker_pdf_too_complexThe PDF is over 5 million characters, 200,000 text items, or 256 MB of decoded streams. Send a simpler PDF, or send fields with a new key on the same upload.

A refused send is saved against its Idempotency-Key, so retrying that key returns the same refusal. An uploaded PDF cannot be replaced, so a corrected PDF always needs a new upload. A temporarily_unavailable response is not saved: retry the same request with the same key. Error responses never include marker text, and param gives only the location, such as markers.page.3.