Anchor Field Placement

PDF anchors let your integration place fields without calculating PDF coordinates. The document contains stable text tokens in its PDF text layer; Covosign finds those tokens and resolves them to page, x, and y positions.

Use one anchor syntax for enterprise documents:

{{sN|field_type|parameters}}

For single-signer documents, use s1.

Supported Fields

Covosign currently supports these anchor field types:

Field type	Anchor format	Created result
signature	{{sN|signature|width|height}}	Creates a required SIGNATURE field.
text	{{sN|text|maxLength|width|fontSize|label|placeholder|requiredFlag}}	Creates a TEXT field. requiredFlag=f means required, requiredFlag=t means optional.
date	{{sN|date|width|height|fontSize}}	Creates a required DATE field. Width, height, and font size are optional and default to 200, 60, and 14.
image	{{sN|image|width|height|label}}	Marks where document content should be stamped. It is parsed as a valid anchor but does not create a signer field.

Anchor Parameters

Every anchor is wrapped in double braces and split by |:

{{sN|field_type|parameters}}

The first segment, sN, is the signer reference. Use s1 for the first signer, s2 for the second signer, and so on. When calling POST /signature-requests/{requestId}/fields/anchors, pass the same value in signerRef; Covosign assigns the created fields for that signer reference to the supplied recipientId.

Signature Anchors

{{sN|signature|width|height}}

Segment	Meaning
sN	Signer reference, for example s1.
signature	Creates a signer SIGNATURE field.
width	Signature field width in PDF points.
height	Signature field height in PDF points.

Example: {{s1|signature|200|50}} creates a required signature field for signer s1 with width 200 and height 50.

Text Anchors

{{sN|text|maxLength|width|fontSize|label|placeholder|requiredFlag}}

Segment	Meaning
sN	Signer reference, for example s1.
text	Creates a signer TEXT field.
maxLength	Maximum number of characters the signer can enter.
width	Text field width in PDF points.
fontSize	Signed text font size in points.
label	Field name shown in Covosign, for example Name.
placeholder	Reserved placeholder text segment. It can be empty and is currently not shown to the signer. Keep the segment in the anchor even when it is empty.
requiredFlag	f means required; t means optional.

Example: {{s1|text|50|308|24|Name||f}} means signer s1, text field, maximum 50 characters, width 308, font size 24, label Name, empty placeholder, and required.

The || before the final f is intentional. It means the placeholder segment is present but empty:

{{s1|text|50|308|24|Name||f}}
                         ^ empty placeholder

Date Anchors

{{sN|date|width|height|fontSize}}
{{sN|date}}

Segment	Meaning
sN	Signer reference, for example s1.
date	Creates a signer DATE field.
width	Optional date field width in PDF points.
height	Optional date field height in PDF points.
fontSize	Optional signed date font size in points.

If width, height, or font size are omitted, Covosign uses width 200, height 60, and font size 14.

Image Anchors

{{sN|image|width|height|label}}

Segment	Meaning
sN	Signer/content reference, for example s1.
image	Marks where document content should be stamped.
width	Image box width in PDF points.
height	Image box height in PDF points.
label	Descriptive image anchor name, for example Evidence Image.

Image anchors are used by POST /signature-requests/{requestId}/fields/anchors/image. They are ignored by /fields/anchors because they do not create signer-fillable fields.

Examples:

{{s1|signature|200|50}}
{{s1|date|180|32|12}}
{{s1|date}}
{{s1|text|50|308|24|Name||f}}
{{s1|text|40|248|24|Position/ Position||t}}
{{s1|image|300|140|Evidence Image}}

signature, date, and text anchors are created by POST /signature-requests/{requestId}/fields/anchors. image anchors are used by POST /signature-requests/{requestId}/fields/anchors/image to stamp content into the PDF.

Do not use {{covosign:...}} anchors for new enterprise templates. Customer names, addresses, paragraphs, claim IDs, and declarations should preferably be rendered in the final PDF before upload. If Covosign must replace fixed PDF text blocks, use the PDF text replacement endpoint below and reserve enough space in the PDF template.

Main API

Use POST /signature-requests/{requestId}/fields/anchors to parse signer anchors and create fields.

Call it after adding the signer recipient and before sending the request:

curl -X POST "https://api.covosign.com/api/v1/enterprise/signature-requests/{requestId}/fields/anchors" \
  -H "X-API-Key: csk_sandbox_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "recipientId": "{recipientId}",
    "signerRef": "s1"
  }'

signerRef defaults to s1. Every parsed signer field for that signer reference is assigned to the supplied recipientId.

If the PDF also contains {{s1|image|300|140|Evidence Image}}, the field parser recognizes it as a valid document-content anchor and skips it. Use the image endpoint below to stamp the actual image.

Evidence Images

Use the same anchor syntax in the PDF:

{{s1|image|300|140|Evidence Image}}

Then stamp the image while the request is still in DRAFT:

curl -X POST "https://api.covosign.com/api/v1/enterprise/signature-requests/{requestId}/fields/anchors/image" \
  -H "X-API-Key: csk_sandbox_your_key_here" \
  -F 'anchorKey={{s1|image|300|140|Evidence Image}}' \
  -F 'width=300' \
  -F 'height=140' \
  -F 'sizingMode=FIT' \
  -F 'image=@evidence.png;type=image/png'

The image endpoint updates the PDF document content. It does not create a signer-fillable field.

PDF Text Replacement

Use PDF text replacement only when your PDF template has fixed-size areas for customer-specific values. This is useful for bounded labels such as customer blocks, claim IDs, or short declarations.

Recommended approach

Use a DOCX template with templateData when Covosign should replace dynamic customer values. DOCX supports normal text wrapping and reflow before Covosign converts the document to PDF. Use PDF text replacement only when you must keep an existing PDF template and the replacement areas are fixed and predictable.

curl -X POST "https://api.covosign.com/api/v1/enterprise/signature-requests/{requestId}/anchors/text-replacements" \
  -H "X-API-Key: csk_sandbox_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "replacements": [
      {
        "anchorKey": "{{customer-block}}",
        "text": "Doublesix Ltd.\nAlex Golke\nWorld Trust Tower Unit D, 11\nN/A Hong Kong",
        "width": 220,
        "height": 72,
        "fontSize": 10
      },
      {
        "anchorKey": "{{claim-id}}",
        "text": "Claim-ID 247CCA",
        "width": 150,
        "height": 24,
        "fontSize": 12
      }
    ]
  }'

PDF replacement is not a document reflow engine. Covosign covers the anchor area and draws replacement text inside the supplied box. To avoid overlapping text or broken legal layout:

• Reserve enough blank space for the longest expected value.
• Provide explicit width, height, and fontSize.
• Keep replacement text short and predictable.
• Test with long company names, long addresses, long claim IDs, and every supported language.
• Prefer DOCX templateData when paragraphs need normal text wrapping and reflow.

DOCX Template Replacement

DOCX templates are the recommended option when Covosign replaces customer values such as company name, address, claim ID, legal text, or declarations.

Add placeholders to the DOCX template:

{{customer_block}}
{{claim_id}}
{{legal_block}}
{{declaration_en}}
{{s1|signature|200|50}}
{{s1|date|180|32|12}}

Then create a draft from the template:

curl -X POST "https://api.covosign.com/api/v1/enterprise/signature-requests/templates/{templateId}/use" \
  -H "X-API-Key: csk_sandbox_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "templateData": {
      "customer_block": "Doublesix Ltd.\nAlex Golke\nWorld Trust Tower Unit D, 11\nN/A Hong Kong",
      "claim_id": "Claim-ID 247CCA",
      "legal_block": "RD Legal GmbH\nSaarbrucker Str. 18\n10405 Berlin",
      "declaration_en": "I hereby declare the following statement..."
    }
  }'

Covosign replaces the DOCX placeholders, converts the filled document to PDF, and returns a draft. The signer receives only the generated PDF. After draft creation, call /fields/anchors to create signer fields from the generated PDF.

Choosing PDF or DOCX

Scenario	Recommended format
Your system already renders all customer values before upload	PDF
Covosign must replace long addresses, declarations, or legal paragraphs	DOCX with templateData
Covosign must replace only short fixed labels in an existing PDF layout	PDF with /anchors/text-replacements
Text length varies significantly between customers or languages	DOCX with templateData

Recommended Flow

1. Generate the final customer-specific PDF.
2. Put signer anchors such as {{s1|signature|200|50}} and {{s1|date|180|32|12}} in the PDF text layer.
3. Put image anchors such as {{s1|image|300|140|Evidence Image}} where images should be stamped.
4. Create the signature request with POST /signature-requests.
5. Add the signer with POST /signature-requests/{requestId}/recipients.
6. Create signer fields with POST /signature-requests/{requestId}/fields/anchors.
7. Optionally replace fixed PDF text with POST /signature-requests/{requestId}/anchors/text-replacements.
8. Optionally stamp images with POST /signature-requests/{requestId}/fields/anchors/image.
9. Send with POST /signature-requests/{requestId}/send.

Authoring Rules

• Anchors must be selectable text in the PDF text layer.
• Anchors may be visible for testing and hidden in production with white text on a white page.
• Do not flatten anchors into an image.
• Keep each anchor on one line.
• Use a unique signer reference per signer in multi-signer documents, for example s1, s2, and s3.
• Place image anchors at the top-left of the image area.

Preview

Use the preview endpoint to confirm the PDF text layer contains a specific anchor before sending:

curl -X POST "https://api.covosign.com/api/v1/enterprise/signature-requests/{requestId}/anchors/preview" \
  -H "X-API-Key: csk_sandbox_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "anchors": [
      { "anchorKey": "{{s1|signature|200|50}}" },
      { "anchorKey": "{{s1|image|300|140|Evidence Image}}" }
    ]
  }'

Testing

The enterprise demo includes PDFs and scripts that use this unified format:

node scripts/generate-test-pdf.mjs output/pdf/e2e-enterprise-test.pdf
./scripts/test-anchors-api.sh
./scripts/test-enterprise-flow.sh

The focused script validates that /fields/anchors creates SIGNATURE, DATE, and TEXT fields from the PDF anchors.