> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://developers.hellosign.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://developers.hellosign.com/_mcp/server.

# Detect Document Fields

POST https://api.hellosign.com/v3/document/detect_fields

Detects form fields in a PDF document using either PDF form annotations or Dropbox Sign text tags.

Reference: https://developers.hellosign.com/api/document/detect-fields

## Authentication

- `Authorization` header (basic auth, required) — Use your API key with HTTP Basic authentication in the form `Basic <api_key>`. See [Authentication](/api/reference/authentication) for more information. ✅ Supported by Try it console (calls sent in `test_mode` only).
- `Authorization` header (bearer token, required) — You can use an Access Token issued through an OAuth flow to send calls to the Dropbox Sign API from your app. The access scopes required by this endpoint are listed in the gray box above. See [Authentication](/api/reference/authentication) for more information. ❌ **Not supported** by Try it console.

## Response

### 200

successful operation

- `detection_result` (DocumentFieldDetectionResponseDetectionResult, required)
- `warnings` (list of WarningResponse, optional) — A list of warnings.

## Errors

### 400 Client Request Error

failed_operation

- `error` (ErrorResponseError, required) — Contains information about an error that occurred.

## Types

### DocumentFieldDetectionResponseDetectionResult

- `document_hash` (string, required) — The SHA-256 hash of the analyzed document.
- `detection_mode` (string, required) — The field detection method used to analyze the document: `annotations` or `text_tags`.
- `page_count` (integer, required) — The total number of pages in the document.
- `pages_analyzed` (string, required) — The zero-based page indexes analyzed, represented by the requested `page_range`, or `all` when every page was analyzed.
- `detected_at` (long, required) — The Unix timestamp when the field detection result was generated.
- `form_fields_per_document` (list of SubFormFieldsPerDocumentBase, required) — The fields that should appear on the document, expressed as an array of objects. (For more details you can read about it here: [Using Form Fields per Document](/docs/openapi/form-fields-per-document).) **NOTE:** Fields like **text**, **dropdown**, **checkbox**, **radio**, and **hyperlink** have additional required and optional parameters. Check out the list of [additional parameters](/api/reference/constants/#form-fields-per-document) for these field types. * Text Field use `SubFormFieldsPerDocumentText` * Dropdown Field use `SubFormFieldsPerDocumentDropdown` * Hyperlink Field use `SubFormFieldsPerDocumentHyperlink` * Checkbox Field use `SubFormFieldsPerDocumentCheckbox` * Radio Field use `SubFormFieldsPerDocumentRadio` * Signature Field use `SubFormFieldsPerDocumentSignature` * Date Signed Field use `SubFormFieldsPerDocumentDateSigned` * Initials Field use `SubFormFieldsPerDocumentInitials` * Text Merge Field use `SubFormFieldsPerDocumentTextMerge` * Checkbox Merge Field use `SubFormFieldsPerDocumentCheckboxMerge`
- `form_field_groups` (list of SubFormFieldGroup, required) — Group information for fields defined in `form_fields_per_document`. String-indexed JSON array with `group_label` and `requirement` keys. `form_fields_per_document` must contain fields referencing a group defined in `form_field_groups`.
- `warnings` (list of WarningResponse, required) — Non-fatal issues encountered during field detection.
- `errors` (list of ErrorResponseError, required) — Errors encountered during field detection. Successfully detected fields may still be included in the response.
- `suggestions` (list of string, required) — Suggestions for improving the field detection results.

### WarningResponse

A list of warnings.

- `warning_msg` (string, required) — Warning message
- `warning_name` (string, required) — Warning name

### ErrorResponseError

Contains information about an error that occurred.

- `error_msg` (string, required) — Message describing an error.
- `error_name` (string, required) — Name of the error. See the `x-error-codes` catalog in openapi file for a complete list of possible error codes with detailed information including HTTP status codes, causes, remediation steps, and retry guidance.
- `error_path` (string, optional) — Path at which an error occurred.

### SubFormFieldsPerDocumentBase

The fields that should appear on the document, expressed as an array of objects. (For more details you can read about it here: [Using Form Fields per Document](/docs/openapi/form-fields-per-document).) **NOTE:** Fields like **text**, **dropdown**, **checkbox**, **radio**, and **hyperlink** have additional required and optional parameters. Check out the list of [additional parameters](/api/reference/constants/#form-fields-per-document) for these field types. * Text Field use `SubFormFieldsPerDocumentText` * Dropdown Field use `SubFormFieldsPerDocumentDropdown` * Hyperlink Field use `SubFormFieldsPerDocumentHyperlink` * Checkbox Field use `SubFormFieldsPerDocumentCheckbox` * Radio Field use `SubFormFieldsPerDocumentRadio` * Signature Field use `SubFormFieldsPerDocumentSignature` * Date Signed Field use `SubFormFieldsPerDocumentDateSigned` * Initials Field use `SubFormFieldsPerDocumentInitials` * Text Merge Field use `SubFormFieldsPerDocumentTextMerge` * Checkbox Merge Field use `SubFormFieldsPerDocumentCheckboxMerge`

- `type`: `text` (text)
  - `document_index` (integer, required) — Represents the integer index of the `file` or `file_url` document the field should be attached to.
  - `api_id` (string, required) — An identifier for the field that is unique across all documents in the request.
  - `height` (integer, required) — Size of the field in pixels.
  - `required` (boolean, required) — Whether this field is required.
  - `signer` (string, required) — Signer index identified by the offset in the signers parameter (0-based indexing), indicating which signer should fill out the field. **NOTE:** To set the value of the field as the preparer you must set this to `me_now` **NOTE:** If type is `text-merge` or `checkbox-merge`, you must set this to sender in order to use pre-filled data.
  - `width` (integer, required) — Size of the field in pixels.
  - `x` (integer, required) — Location coordinates of the field in pixels.
  - `y` (integer, required) — Location coordinates of the field in pixels.
  - `name` (string, optional) — Display name for the field.
  - `page` (integer, optional, nullable) — Page in the document where the field should be placed (requires documents be PDF files). - When the page number parameter is supplied, the API will use the new coordinate system. - Check out the differences between both [coordinate systems](https://faq.hellosign.com/hc/en-us/articles/217115577) and how to use them.
- `type`: `dropdown` (dropdown)
  - `document_index` (integer, required) — Represents the integer index of the `file` or `file_url` document the field should be attached to.
  - `api_id` (string, required) — An identifier for the field that is unique across all documents in the request.
  - `height` (integer, required) — Size of the field in pixels.
  - `required` (boolean, required) — Whether this field is required.
  - `signer` (string, required) — Signer index identified by the offset in the signers parameter (0-based indexing), indicating which signer should fill out the field. **NOTE:** To set the value of the field as the preparer you must set this to `me_now` **NOTE:** If type is `text-merge` or `checkbox-merge`, you must set this to sender in order to use pre-filled data.
  - `width` (integer, required) — Size of the field in pixels.
  - `x` (integer, required) — Location coordinates of the field in pixels.
  - `y` (integer, required) — Location coordinates of the field in pixels.
  - `name` (string, optional) — Display name for the field.
  - `page` (integer, optional, nullable) — Page in the document where the field should be placed (requires documents be PDF files). - When the page number parameter is supplied, the API will use the new coordinate system. - Check out the differences between both [coordinate systems](https://faq.hellosign.com/hc/en-us/articles/217115577) and how to use them.
- `type`: `hyperlink` (hyperlink)
  - `document_index` (integer, required) — Represents the integer index of the `file` or `file_url` document the field should be attached to.
  - `api_id` (string, required) — An identifier for the field that is unique across all documents in the request.
  - `height` (integer, required) — Size of the field in pixels.
  - `required` (boolean, required) — Whether this field is required.
  - `signer` (string, required) — Signer index identified by the offset in the signers parameter (0-based indexing), indicating which signer should fill out the field. **NOTE:** To set the value of the field as the preparer you must set this to `me_now` **NOTE:** If type is `text-merge` or `checkbox-merge`, you must set this to sender in order to use pre-filled data.
  - `width` (integer, required) — Size of the field in pixels.
  - `x` (integer, required) — Location coordinates of the field in pixels.
  - `y` (integer, required) — Location coordinates of the field in pixels.
  - `name` (string, optional) — Display name for the field.
  - `page` (integer, optional, nullable) — Page in the document where the field should be placed (requires documents be PDF files). - When the page number parameter is supplied, the API will use the new coordinate system. - Check out the differences between both [coordinate systems](https://faq.hellosign.com/hc/en-us/articles/217115577) and how to use them.
- `type`: `checkbox` (checkbox)
  - `document_index` (integer, required) — Represents the integer index of the `file` or `file_url` document the field should be attached to.
  - `api_id` (string, required) — An identifier for the field that is unique across all documents in the request.
  - `height` (integer, required) — Size of the field in pixels.
  - `required` (boolean, required) — Whether this field is required.
  - `signer` (string, required) — Signer index identified by the offset in the signers parameter (0-based indexing), indicating which signer should fill out the field. **NOTE:** To set the value of the field as the preparer you must set this to `me_now` **NOTE:** If type is `text-merge` or `checkbox-merge`, you must set this to sender in order to use pre-filled data.
  - `width` (integer, required) — Size of the field in pixels.
  - `x` (integer, required) — Location coordinates of the field in pixels.
  - `y` (integer, required) — Location coordinates of the field in pixels.
  - `name` (string, optional) — Display name for the field.
  - `page` (integer, optional, nullable) — Page in the document where the field should be placed (requires documents be PDF files). - When the page number parameter is supplied, the API will use the new coordinate system. - Check out the differences between both [coordinate systems](https://faq.hellosign.com/hc/en-us/articles/217115577) and how to use them.
- `type`: `radio` (radio)
  - `document_index` (integer, required) — Represents the integer index of the `file` or `file_url` document the field should be attached to.
  - `api_id` (string, required) — An identifier for the field that is unique across all documents in the request.
  - `height` (integer, required) — Size of the field in pixels.
  - `required` (boolean, required) — Whether this field is required.
  - `signer` (string, required) — Signer index identified by the offset in the signers parameter (0-based indexing), indicating which signer should fill out the field. **NOTE:** To set the value of the field as the preparer you must set this to `me_now` **NOTE:** If type is `text-merge` or `checkbox-merge`, you must set this to sender in order to use pre-filled data.
  - `width` (integer, required) — Size of the field in pixels.
  - `x` (integer, required) — Location coordinates of the field in pixels.
  - `y` (integer, required) — Location coordinates of the field in pixels.
  - `name` (string, optional) — Display name for the field.
  - `page` (integer, optional, nullable) — Page in the document where the field should be placed (requires documents be PDF files). - When the page number parameter is supplied, the API will use the new coordinate system. - Check out the differences between both [coordinate systems](https://faq.hellosign.com/hc/en-us/articles/217115577) and how to use them.
- `type`: `signature` (signature)
  - `document_index` (integer, required) — Represents the integer index of the `file` or `file_url` document the field should be attached to.
  - `api_id` (string, required) — An identifier for the field that is unique across all documents in the request.
  - `height` (integer, required) — Size of the field in pixels.
  - `required` (boolean, required) — Whether this field is required.
  - `signer` (string, required) — Signer index identified by the offset in the signers parameter (0-based indexing), indicating which signer should fill out the field. **NOTE:** To set the value of the field as the preparer you must set this to `me_now` **NOTE:** If type is `text-merge` or `checkbox-merge`, you must set this to sender in order to use pre-filled data.
  - `width` (integer, required) — Size of the field in pixels.
  - `x` (integer, required) — Location coordinates of the field in pixels.
  - `y` (integer, required) — Location coordinates of the field in pixels.
  - `name` (string, optional) — Display name for the field.
  - `page` (integer, optional, nullable) — Page in the document where the field should be placed (requires documents be PDF files). - When the page number parameter is supplied, the API will use the new coordinate system. - Check out the differences between both [coordinate systems](https://faq.hellosign.com/hc/en-us/articles/217115577) and how to use them.
- `type`: `date_signed` (date_signed)
  - `document_index` (integer, required) — Represents the integer index of the `file` or `file_url` document the field should be attached to.
  - `api_id` (string, required) — An identifier for the field that is unique across all documents in the request.
  - `height` (integer, required) — Size of the field in pixels.
  - `required` (boolean, required) — Whether this field is required.
  - `signer` (string, required) — Signer index identified by the offset in the signers parameter (0-based indexing), indicating which signer should fill out the field. **NOTE:** To set the value of the field as the preparer you must set this to `me_now` **NOTE:** If type is `text-merge` or `checkbox-merge`, you must set this to sender in order to use pre-filled data.
  - `width` (integer, required) — Size of the field in pixels.
  - `x` (integer, required) — Location coordinates of the field in pixels.
  - `y` (integer, required) — Location coordinates of the field in pixels.
  - `name` (string, optional) — Display name for the field.
  - `page` (integer, optional, nullable) — Page in the document where the field should be placed (requires documents be PDF files). - When the page number parameter is supplied, the API will use the new coordinate system. - Check out the differences between both [coordinate systems](https://faq.hellosign.com/hc/en-us/articles/217115577) and how to use them.
- `type`: `initials` (initials)
  - `document_index` (integer, required) — Represents the integer index of the `file` or `file_url` document the field should be attached to.
  - `api_id` (string, required) — An identifier for the field that is unique across all documents in the request.
  - `height` (integer, required) — Size of the field in pixels.
  - `required` (boolean, required) — Whether this field is required.
  - `signer` (string, required) — Signer index identified by the offset in the signers parameter (0-based indexing), indicating which signer should fill out the field. **NOTE:** To set the value of the field as the preparer you must set this to `me_now` **NOTE:** If type is `text-merge` or `checkbox-merge`, you must set this to sender in order to use pre-filled data.
  - `width` (integer, required) — Size of the field in pixels.
  - `x` (integer, required) — Location coordinates of the field in pixels.
  - `y` (integer, required) — Location coordinates of the field in pixels.
  - `name` (string, optional) — Display name for the field.
  - `page` (integer, optional, nullable) — Page in the document where the field should be placed (requires documents be PDF files). - When the page number parameter is supplied, the API will use the new coordinate system. - Check out the differences between both [coordinate systems](https://faq.hellosign.com/hc/en-us/articles/217115577) and how to use them.
- `type`: `text-merge` (text-merge)
  - `document_index` (integer, required) — Represents the integer index of the `file` or `file_url` document the field should be attached to.
  - `api_id` (string, required) — An identifier for the field that is unique across all documents in the request.
  - `height` (integer, required) — Size of the field in pixels.
  - `required` (boolean, required) — Whether this field is required.
  - `signer` (string, required) — Signer index identified by the offset in the signers parameter (0-based indexing), indicating which signer should fill out the field. **NOTE:** To set the value of the field as the preparer you must set this to `me_now` **NOTE:** If type is `text-merge` or `checkbox-merge`, you must set this to sender in order to use pre-filled data.
  - `width` (integer, required) — Size of the field in pixels.
  - `x` (integer, required) — Location coordinates of the field in pixels.
  - `y` (integer, required) — Location coordinates of the field in pixels.
  - `name` (string, optional) — Display name for the field.
  - `page` (integer, optional, nullable) — Page in the document where the field should be placed (requires documents be PDF files). - When the page number parameter is supplied, the API will use the new coordinate system. - Check out the differences between both [coordinate systems](https://faq.hellosign.com/hc/en-us/articles/217115577) and how to use them.
- `type`: `checkbox-merge` (checkbox-merge)
  - `document_index` (integer, required) — Represents the integer index of the `file` or `file_url` document the field should be attached to.
  - `api_id` (string, required) — An identifier for the field that is unique across all documents in the request.
  - `height` (integer, required) — Size of the field in pixels.
  - `required` (boolean, required) — Whether this field is required.
  - `signer` (string, required) — Signer index identified by the offset in the signers parameter (0-based indexing), indicating which signer should fill out the field. **NOTE:** To set the value of the field as the preparer you must set this to `me_now` **NOTE:** If type is `text-merge` or `checkbox-merge`, you must set this to sender in order to use pre-filled data.
  - `width` (integer, required) — Size of the field in pixels.
  - `x` (integer, required) — Location coordinates of the field in pixels.
  - `y` (integer, required) — Location coordinates of the field in pixels.
  - `name` (string, optional) — Display name for the field.
  - `page` (integer, optional, nullable) — Page in the document where the field should be placed (requires documents be PDF files). - When the page number parameter is supplied, the API will use the new coordinate system. - Check out the differences between both [coordinate systems](https://faq.hellosign.com/hc/en-us/articles/217115577) and how to use them.

### SubFormFieldGroup

- `group_id` (string, required) — ID of group. Use this to reference a specific group from the `group` value in `form_fields_per_document`.
- `group_label` (string, required) — Name of the group
- `requirement` (string, required) — Examples: `require_0-1` `require_1` `require_1-ormore` - Check out the list of [acceptable `requirement` checkbox type values](/api/reference/constants/#checkbox-field-grouping). - Check out the list of [acceptable `requirement` radio type fields](/api/reference/constants/#radio-field-grouping). - Radio groups require **at least** two fields per group.

## Examples

**Response**

```json
{
  "detection_result": {
    "document_hash": "string",
    "detection_mode": "string",
    "page_count": 1,
    "pages_analyzed": "all",
    "detected_at": 1,
    "form_fields_per_document": [
      {
        "api_id": "string",
        "document_index": 1,
        "height": 1,
        "name": "string",
        "page": 1,
        "required": true,
        "signer": "string",
        "type": "string",
        "width": 1,
        "x": 1,
        "y": 1
      }
    ],
    "form_field_groups": [
      {
        "group_id": "string",
        "group_label": "string",
        "requirement": "string"
      }
    ],
    "warnings": [
      {
        "warning_msg": "string",
        "warning_name": "string"
      }
    ],
    "errors": [
      {
        "error_msg": "string",
        "error_name": "string",
        "error_path": "string"
      }
    ],
    "suggestions": [
      "string"
    ]
  },
  "warnings": [
    {
      "warning_msg": "string",
      "warning_name": "string"
    }
  ]
}
```

**SDK Code**

```php PHP
<?php

namespace Dropbox\SignSandbox;

require_once __DIR__ . '/../vendor/autoload.php';

use SplFileObject;
use Dropbox;

$config = Dropbox\Sign\Configuration::getDefaultConfiguration();
$config->setUsername("YOUR_API_KEY");
// $config->setAccessToken("YOUR_ACCESS_TOKEN");

try {
    $response = (new Dropbox\Sign\Api\SignatureRequestApi(config: $config))->documentDetectFields(
        detection_mode: "annotations",
        file: new SplFileObject("./example_document.pdf"),
        page_range: "all",
    );

    print_r($response);
} catch (Dropbox\Sign\ApiException $e) {
    echo "Exception when calling SignatureRequestApi#documentDetectFields: {$e->getMessage()}";
}

```

```csharp C#
using System;
using System.Collections.Generic;
using System.IO;
using System.Text.Json;

using Dropbox.Sign.Api;
using Dropbox.Sign.Client;
using Dropbox.Sign.Model;

namespace Dropbox.SignSandbox;

public class DocumentDetectFieldsExample
{
    public static void Run()
    {
        var config = new Configuration();
        config.Username = "YOUR_API_KEY";
        // config.AccessToken = "YOUR_ACCESS_TOKEN";

        try
        {
            var response = new SignatureRequestApi(config).DocumentDetectFields(
                detectionMode: "annotations",
                file: new FileStream(
                    path: "./example_document.pdf",
                    mode: FileMode.Open
                ),
                pageRange: "all"
            );

            Console.WriteLine(response);
        }
        catch (ApiException e)
        {
            Console.WriteLine("Exception when calling SignatureRequestApi#DocumentDetectFields: " + e.Message);
            Console.WriteLine("Status Code: " + e.ErrorCode);
            Console.WriteLine(e.StackTrace);
        }
    }
}

```

```typescript TypeScript
import * as fs from 'fs';
import api from "@dropbox/sign"
import models from "@dropbox/sign"

const apiCaller = new api.SignatureRequestApi();
apiCaller.username = "YOUR_API_KEY";
// apiCaller.accessToken = "YOUR_ACCESS_TOKEN";

apiCaller.documentDetectFields(
  "annotations", // detectionMode
  fs.createReadStream("./example_document.pdf"), // file
  undefined, // fileUrl
  "all", // pageRange
).then(response => {
  console.log(response.body);
}).catch(error => {
  console.log("Exception when calling SignatureRequestApi#documentDetectFields:");
  console.log(error.body);
});

```

```java Java
package com.dropbox.sign_sandbox;

import com.dropbox.sign.ApiException;
import com.dropbox.sign.Configuration;
import com.dropbox.sign.api.*;
import com.dropbox.sign.auth.*;
import com.dropbox.sign.JSON;
import com.dropbox.sign.model.*;

import java.io.File;
import java.math.BigDecimal;
import java.time.LocalDate;
import java.time.OffsetDateTime;
import java.util.ArrayList;
import java.util.List;
import java.util.Map;

public class DocumentDetectFieldsExample
{
    public static void main(String[] args)
    {
        var config = Configuration.getDefaultApiClient();
        ((HttpBasicAuth) config.getAuthentication("api_key")).setUsername("YOUR_API_KEY");
        // ((HttpBearerAuth) config.getAuthentication("oauth2")).setBearerToken("YOUR_ACCESS_TOKEN");

        try
        {
            var response = new SignatureRequestApi(config).documentDetectFields(
                "annotations", // detectionMode
                new File("./example_document.pdf"), // _file
                null, // fileUrl
                "all" // pageRange
            );

            System.out.println(response);
        } catch (ApiException e) {
            System.err.println("Exception when calling SignatureRequestApi#documentDetectFields");
            System.err.println("Status code: " + e.getCode());
            System.err.println("Reason: " + e.getResponseBody());
            System.err.println("Response headers: " + e.getResponseHeaders());
            e.printStackTrace();
        }
    }
}

```

```ruby Ruby
require "json"
require "dropbox-sign"

Dropbox::Sign.configure do |config|
    config.username = "YOUR_API_KEY"
    # config.access_token = "YOUR_ACCESS_TOKEN"
end

begin
    response = Dropbox::Sign::SignatureRequestApi.new.document_detect_fields(
        "annotations", # detection_mode
        {
            file: File.new("./example_document.pdf", "r"),
            file_url: nil,
            page_range: "all",
        },
    )

    p response
rescue Dropbox::Sign::ApiError => e
    puts "Exception when calling SignatureRequestApi#document_detect_fields: #{e}"
end

```

```python Python
import json
from datetime import date, datetime
from pprint import pprint

from dropbox_sign import ApiClient, ApiException, Configuration, api, models

configuration = Configuration(
    username="YOUR_API_KEY",
    # access_token="YOUR_ACCESS_TOKEN",
)

with ApiClient(configuration) as api_client:
    try:
        response = api.SignatureRequestApi(api_client).document_detect_fields(
            detection_mode="annotations",
            file=open("./example_document.pdf", "rb").read(),
            page_range="all",
        )

        pprint(response)
    except ApiException as e:
        print("Exception when calling SignatureRequestApi#document_detect_fields: %s\n" % e)

```

```go
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.hellosign.com/v3/document/detect_fields"

	req, _ := http.NewRequest("POST", url, nil)

	req.SetBasicAuth("<api_key>", "")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```swift
import Foundation

let credentials = Data("<api_key>:".utf8).base64EncodedString()

let headers = ["Authorization": "Basic \(credentials)"]

let request = NSMutableURLRequest(url: NSURL(string: "https://api.hellosign.com/v3/document/detect_fields")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```