Skip to main content

Auto Placement of Fields

The Auto Field Placement feature in our API allows you to automatically place fields on your PDFs based on specific string inputs. This means that if your document contains a phrase like "Sign Here," our system can automatically detect this string and place a signature field right next to it. This feature is designed to save you time and make it easier to automate placing signatures on a variety of documents.

Using this feature is straightforward. You simply need to specify the string you want the system to look for in your document. Once the string is identified, the corresponding field is placed automatically. This can be particularly useful for documents where the exact location of fields like signatures may vary, but the strings indicating where they should be placed, such as "Sign Here," remain consistent. By automating the placement of these fields, you can save time and avoid the need to manually locate and place each field in every document, ensuring accuracy and efficiency in your workflow.

Search Pattern Rules​

When using auto placement, the search property defines the text pattern that Blueink will look for in your PDF document. Understanding the rules for valid search patterns will help you create reliable and accurate field placements.

Case Sensitivity​

Search patterns are case-insensitive. This means:

  • "Signature" will match "signature", "SIGNATURE", or "SiGnAtUrE"
  • You don't need to worry about the exact capitalization in your PDF

Allowed Characters​

Search patterns support a wide range of characters to accommodate various document formats:

  • Letters: a-z, A-Z
  • Numbers: 0-9
  • Spaces: Regular spaces between words
  • Punctuation and Delimiters: : {{ }} [ ] { }

String Length​

  • Minimum: 1 character
  • Maximum: 255 characters

Common Pattern Examples​

Here are some common patterns developers use to distinguish different fields:

{
  "search": "Signature"
}
{
  "search": "Signature:"
}
{
  "search": "[Signature]"
}
{
  "search": "{Signature}"
}
{
  "search": "{{Signature 1}}"
}
{
  "search": "{{Signature 2}}"
}
{
  "search": "Tenant Signature"
}

Best Practices​

  1. Use Unique Patterns: Make your search patterns specific enough to avoid unintended matches elsewhere in the document.

  2. Include Delimiters: Adding brackets, colons, or other delimiters makes patterns more distinctive:

    • ✅ "[Signature]" is more specific than "Signature"
    • ✅ "Signature:" is more specific than "Signature"

  3. Number Similar Fields: When you have multiple similar fields, use numbered patterns:

    • "{{Signature 1}}", "{{Signature 2}}", "{{Signature 3}}"
    • "[Tenant Signature]", "[Landlord Signature]"

  4. Test Your Patterns: Always test your patterns with actual PDF documents to ensure they match correctly and don't create false positives.

  5. Be Descriptive: Use clear, descriptive text that matches what's actually in your PDF:

    • ✅ "Tenant Signature" clearly indicates the purpose
    • ❌ "Sig1" might be ambiguous

Implementation Examples​

The following examples show how to configure auto_placements in your Bundle request using the Client SDKs.

from blueink.client import Client

client = Client(api_key="your_api_key_here")

# Define bundle details with auto-placement
bundle_data = {
    "label": "Auto-Placement Example",
    "packets": [
        {
            "key": "signer-1",
            "name": "John Doe",
            "email": "[email protected]"
        }
    ],
    "documents": [
        {
            "key": "contract-doc",
            "file_url": "https://example.com/form.pdf",
            "auto_placements": [
                {
                    "kind": "sig",
                    "search": "Tenant Signature",
                    "h": 3,
                    "w": 25,
                    "offset_y": 2,
                    "editors": ["signer-1"]
                },
                {
                    "kind": "tms",
                    "search": "Tenant Date",
                    "h": 3,
                    "w": 25,
                    "offset_y": 2,
                    "editors": ["signer-1"]
                }
            ]
        }
    ]
}

response = client.bundles.create(data=bundle_data)

if response.status == 201:
    print(f"✅ Envelope created! Bundle ID: {response.data.id}")

Interactive Example​

Try it out using this example Postman request.