--- title: "Custom fields" url: "https://docs.signnow.com/docs/custom-fields" type: "page" section: "Documentation" slug: "custom-fields" --- # Custom fields # Custom fields Custom fields are pre-defined fillable fields that you save once in the SignNow UI and reuse across documents. Each saved custom field carries its own configuration. The exact set of saved properties depends on the field type. The rest of your team, or your customers in an embedded flow, can drop the field onto a document without re-configuring it. This guide is for API integrators who use **embedded editor** or **embedded sending** and want to offer their end-users a seamless, focused experience: only the pre-approved Custom fields tab in the sidebar, no Default fields tab, no Element settings button. Once a field is placed on a document, its `field_name` becomes the key that lets you pre-fill values from your own system (CRM, contract platform, HRIS) before the embedded link is opened. ## Use cases Two scenarios where custom fields shine in an embedded flow: ### 1. Adding fields to documents from third-party sources Your customer receives files from a third party (contracts forwarded from a partner, vendor agreements, NDAs from outside counsel). These documents have no fillable fields yet, and your customer needs to add them before sending for signature. With custom fields, you can offer an easy drag-and-drop interface where the sender chooses only from a library of pre-defined fields, already configured with the right type, validation, formatting, and resize behavior. There's no need to think about field properties; the sender just drops them on the page and sends. ### 2. Pre-filling ad-hoc documents before sending Your customer wants to send a one-off document and have it pre-populated with data from your app (a customer record, a deal, an employee profile) before the recipient sees it. With custom fields, your customer drags the pre-defined fields onto the document in the embedded editor. Once the fields are placed, there are two ways to pre-fill their values: - **Via API.** Your backend pre-fills the fields by `field_name` using the SignNow API. Use this when the value comes from your system and changes from one document to the next. - **Via UI.** The admin saves a static default directly on the custom field using the **Pre-filled Text** property in the editor. Every reuse of that field carries the value automatically, with no API call. Use this when the value is the same across documents. Works for text-type fields (text, date and time, email, and so on). Signature fields don't support a pre-filled value, so they always need to be completed by the signer. Either way, the recipient opens a document that's already filled in and ready to sign. ## Other benefits Beyond the two scenarios above, custom fields are useful any time you want consistent, governed field placement and content across many documents: - **Centralized validation.** Admins attach a `validator_id` to each custom field once (email, SSN, US ZIP, currency, date format, etc.), and every document built from those fields inherits the same validation rules. - **A focused experience for partners.** Hide the Default fields tab and the Element settings button so embedded users only see the fields you've already vetted, in the form you intend. - **Reusable libraries instead of rebuilt templates.** New documents can be assembled from the same set of approved fields. Validation, formatting, and resize behavior stay consistent across teams. ## Endpoints at a glance | Step | Endpoint | Purpose | | ---- | -------- | ------- | | 1 | SignNow UI | Create custom fields (no API) | | 2 | [`POST /document`](/docs/document/operations/upload-document) | Upload each file | | 2 | [`POST /documentgroup`](/docs/document-group/operations/create-document-group) | Group documents | | 3 | [`POST /v2/brands`](/docs/general-branding/operations/post-brands) | Create brand | | 4 | [`PUT /v2/brands/{{brand_id}}/resources/editor`](/docs/general-branding/operations/put-v2-brands-brand_id-editor) | Configure editor UI | | 5 | [`PUT /v2/document-groups/{{document_group_id}}/brand`](/docs/general-branding/operations/put-v2-document-groups-document_group_id-brand) | Assign brand to group | | 6 | [`GET /v2/document-groups/{{document_group_id}}`](/docs/document-group/operations/get-document-group-info-v2) | List documents in the group | | 6 | [`GET /document/{{document_id}}`](/docs/document/operations/get-document) | Read fields (full object) | | 6 | [`GET /v2/documents/{{document_id}}/fields`](/docs/document/operations/get-v2-documents-documentUniqueId-fields) | Read fields (lightweight) | | 6 | [`PUT /v2/documents/{{document_id}}/prefill-texts`](/docs/document/operations/put-v2-documents-document_id-prefill-texts) | Pre-fill text fields | | 7 | [`POST /v2/document-groups/{{document_group_id}}/embedded-editor`](/docs/embedded-editor/operations/post-v2-document-groups-document_group_id-embedded-editor) | Generate embedded editor link | | 7 | [`POST /v2/document-groups/{{document_group_id}}/embedded-sending`](/docs/embedded-sending/operations/post-v2-document-groups-document_group_id-embedded-sending) | Generate embedded sending link | ## End-to-end walkthrough Here's how to put it all together. Each step builds on the previous one, ending with an embedded link your users can open. ### Step 0. Authorize your requests Every call in this guide needs an `Authorization` header. You can use either an OAuth 2.0 access token or an API key; pick whichever fits your setup. The options and setup steps are in [Authentication](/docs/authentication). ### Step 1. Add custom fields in the SignNow UI Custom field creation is UI-only. There's no API to define a new custom field. An admin: 1. Opens any document in the SignNow editor and places a fillable field (text, signature, date, checkbox, etc.). 2. Configures the field's properties. For a text field those typically include **Pre-filled Text**, **Don't allow recipient to edit** (locks the pre-filled value), validation type, font style, character limit, line limit, resize behavior. For a date and time field, the format and the **Automatically fill out with the completion date and/or time** option are also saved. Other field types save the subset that applies to them. 3. Clicks the field and selects **Save as custom field**, or uses the **Save as custom field** action on the left panel. > Setting **Pre-filled Text** on a text-type custom field (text, date and time, email, and so on) before saving makes that value appear automatically whenever the field is reused, without an API call. Signature fields don't support a pre-filled value. ![custom_fields_1.png](/reference-assets/images/Fields%20guide/custom_fields_guide/custom_fields_1.png) From that point on, the field appears under the **Custom** tab on the left sidebar of the editor and can be dragged onto any document. **Saved vs. per-document properties** For text fields (including date and time, email, and so on): | Saved on the custom field | Set per document | | ----------------------------------- | ------------------------- | | **Pre-filled Text** | Position (x, y, page) | | Validation type / `validator_id` | Field name (auto-generated) | | Font style | Assigned role | | Character limit, line limit | Conditional rules | | Resize behavior | Payment data | | Date and time format and auto-fill | Formula | | **Don't allow recipient to edit** lock | | Signature fields save only the allowed signature types — typed, drawn, or uploaded image. Per-document properties are the same for every field type. > You cannot create a custom smart field. For this guide, assume the admin has saved the following custom fields: `Customer name`, `Customer email`, `Effective date`, and `Signature`. The `Customer email` field has `Email address` validation, and the `Effective date` field has `MM/DD/YYYY` validation. ### Step 2. [Create a document group](/docs/document-group/operations/create-document-group) Upload your documents first ([`POST /document`](/docs/document/operations/upload-document) for each file), then group them. ```bash curl --request POST \ --url https://api.signnow.com/documentgroup \ --header 'Authorization: Bearer {{access_token}}' \ --header 'Accept: application/json' \ --header 'Content-Type: application/json' \ --data '{ "document_ids": [ "7a3f1e8c92b04d6f5a8e3b7c1d2f4e5a6b8c9d0e", "9b8c7d6e5f4a3b2c1d0e9f8a7b6c5d4e3f2a1b0c" ], "group_name": "Service agreement package" }' ``` ```json { "id": "e1d2c3b4a5f6071829304a5b6c7d8e9f0a1b2c3d" } ``` Keep the returned `id`. You'll use it as the `document_group_id` in step 5, step 6, and step 7. ### Step 3. [Create a brand](/docs/general-branding/operations/post-brands) The brand is the container for all your customer-facing UI overrides. You only need to do this once per branded experience. ```bash curl --request POST \ --url https://api.signnow.com/v2/brands \ --header 'Authorization: Bearer {{access_token}}' \ --header 'Accept: application/json' \ --header 'Content-Type: application/json' \ --data '{ "title": "Custom-fields brand" }' ``` ```json { "id": "4cbe9d4ea4b649ecb77205e7c3a96d5d38968587" } ``` Save the `id`. You'll use it as the `brand_id` in step 4 and step 5. ### Step 4. [Configure the editor brand resource](/docs/general-branding/operations/put-v2-brands-brand_id-editor) Hide the Default fields tab and the Element settings button in the editor so end-users only see your curated custom fields. With both visibility flags set to `false`, the embedded user sees just the **Custom** tab in the left sidebar and no Element settings button in the header. **What the two flags do** | Flag | Default | What `false` does | | ----------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | | `field-settings.visibility` | `true` | Hides the Element settings button on the right side of the header so end-users can't reconfigure field properties. | | `default-fields.visibility` | `true` | Hides the Default fields tab in the left sidebar. The Custom fields tab becomes the only tab and the Default / Custom fields tab switcher disappears. | `field-settings` and `default-fields` apply to both embedded editor and embedded sending. Adjust the color palette and settings to match your brand and the surface area you want your end-users to see. ```bash curl --request PUT \ --url https://api.signnow.com/v2/brands/{{brand_id}}/resources/editor \ --header 'Authorization: Bearer {{access_token}}' \ --header 'Content-Type: application/json' \ --data '{ "settings": { "visibility": true }, "accessibility": { "visibility": true, "color": "#1E1B4B", "background": "#FFFFFF", "border": "#A5B4FC", "hover-color": "#1E1B4B", "hover-background": "#EEF2FF", "hover-border": "#A5B4FC", "active-color": "#1E1B4B", "active-background": "#C7D2FE", "active-border": "#818CF8", "enabled": true }, "navigation": { "visibility": false }, "progress-bar": { "default-color": "#E0E7FF", "completed-color": "#4F46E5" }, "sidebar": { "visibility": false }, "complete-footer": { "visibility": false }, "support-chat": { "visibility": false }, "sender-info": { "visibility": false }, "close-button": { "visibility": true }, "decline-button": { "visibility": false }, "download-button": { "visibility": false }, "document-name": { "visibility": true }, "request-payment": { "visibility": false }, "continue-button": { "visibility": true }, "step-progress-bar": { "visibility": true }, "toolbar": { "visibility": false }, "preview-button": { "visibility": true }, "thumbnails-button": { "visibility": false }, "editing-tools": { "background": "#F5F3FF" }, "manage-recipients": { "visibility": false }, "signing-settings": { "auto-apply-signatures-and-initials-to-document-fields": true, "guide-signers-only-through-required-fields": true }, "field-settings": { "visibility": false }, "default-fields": { "visibility": false } }' ``` `204 No Content` Learn more about [branding](/docs/guides-branding). ### Step 5. [Assign the brand to the document group](/docs/general-branding/operations/put-v2-document-groups-document_group_id-brand) This call links the brand to the document group so the embedded editor and sending flows pick up your branding when the link is opened. ```bash curl --request PUT \ --url https://api.signnow.com/v2/document-groups/{{document_group_id}}/brand \ --header 'Authorization: Bearer {{access_token}}' \ --header 'Content-Type: application/json' \ --data '{ "brand_id": "4cbe9d4ea4b649ecb77205e7c3a96d5d38968587" }' ``` `204 No Content` A brand can also be assigned at other scopes. Pick whichever matches the surface you want branded: - A single [document](/docs/general-branding/operations/put-v2-documents-document_id-brand). - An entire [application](/docs/general-branding/operations/put-v2-applications-application_id-brand). The request body is the same in every case: a single `brand_id`. ### Step 6 (optional). Pre-fill custom field values via API > Step 6 assumes the documents already have custom fields placed, either pre-placed in a template or added in a prior embedded editor session. Before generating the embedded link, you can pre-fill values on the text-type fields the sender placed on the documents in the group. Field names are not saved on the custom field. SignNow generates them automatically when the field is placed on a document (`Text Field 1`, `Text Field 2`, `Date and Time 1`, `Date and Time 2`, `Signature 1`, and so on). You have to read each document's fields and use the names that come back. If a custom field has a `label` set, it's returned alongside the auto-generated `name` and can help you identify which field is which when several share the same type. That makes pre-fill for a document group a three-call flow. Step 2 and step 3 are alternatives for reading field names; pick whichever fits your use case: | If you need... | Use endpoint | | --------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- | | Full field metadata (positions, validators, styling) and signatures | [`GET /document/{{document_id}}`](/docs/document/operations/get-document) (step 2) | | Just field names for pre-fill — text-type fields only | [`GET /v2/documents/{{document_id}}/fields`](/docs/document/operations/get-v2-documents-documentUniqueId-fields) (step 3) | **1. [List the documents in the group](/docs/document-group/operations/get-document-group-info-v2)** ```bash curl --request GET \ --url https://api.signnow.com/v2/document-groups/{{document_group_id}} \ --header 'Authorization: Bearer {{access_token}}' \ --header 'Accept: application/json' ``` ```json { "data": { "id": "a99a207dad724a13bef6089aa7f5b95965b301dc", "name": "Service agreement package", "state": "created", "documents": [ { "id": "596d07c497b5456b9325e5305fb0e22a47d6de7d", "document_name": "sample-service-agreement", "has_fields": true, "page_count": 1 } ] } } ``` Collect each `data.documents[].id` for the next call. **2. [Get each document's fields](/docs/document/operations/get-document)** For every document ID from step 1, request the document and read its `fields` array. The `field_name` you'll pass to the pre-fill call is each field's `json_attributes.name`, the auto-generated value. ```bash curl --request GET \ --url https://api.signnow.com/document/{{document_id}} \ --header 'Authorization: Bearer {{access_token}}' \ --header 'Accept: application/json' ``` ```json { "id": "596d07c497b5456b9325e5305fb0e22a47d6de7d", "parent_id": "ed55e1f4789149ccbaaca42712dbaeb9b18497eb", "user_id": "574dc73f30de456e80212f2333cb14293cc92fca", "document_name": "sample-service-agreement", "page_count": "1", "created": "1778584240", "updated": "1778593772", "original_filename": "sample-service-agreement.pdf", "owner": "owner@email.com", "owner_name": "Document Owner", "template": false, "document_group_info": { "document_group_id": "a99a207dad724a13bef6089aa7f5b95965b301dc", "document_group_name": "Service agreement package", "invite_id": null, "invite_status": null, "sign_as_merged": false, "doc_count_in_group": 1, "state": "created" }, "roles": [ { "unique_id": "be616d202b3d4c36a65b0fb8042ccc95549f0ecb", "signing_order": "1", "name": "Recipient 1" } ], "fields": [ { "id": "021b4a4cc4d34918826ee2d2690294e4c35737c5", "type": "text", "role_id": "be616d202b3d4c36a65b0fb8042ccc95549f0ecb", "role": "Recipient 1", "json_attributes": { "name": "Text Field 1", "page_number": 0, "x": 196, "y": 95, "width": 194, "height": 23, "required": true, "color": "000000", "align": "left", "font": "Arial", "font_size": 10, "max_lines": 0, "max_chars": 0, "stretch_mode": "fixed" } }, { "id": "56d02e0290614ce5978d4b2318de4122109c214b", "type": "text", "role_id": "be616d202b3d4c36a65b0fb8042ccc95549f0ecb", "role": "Recipient 1", "json_attributes": { "name": "Text Field 2", "label": "email", "page_number": 0, "x": 196, "y": 126, "width": 194, "height": 23, "required": true, "validator_id": "7cd795fd64ce63b670b52b2e83457d59ac796a39", "max_chars": 99, "max_lines": 1, "font": "Arial", "font_size": 10 } }, { "id": "491149598ec543909e9149a8716c928f5cd16528", "type": "text", "role_id": "be616d202b3d4c36a65b0fb8042ccc95549f0ecb", "role": "Recipient 1", "json_attributes": { "name": "Date and Time 1", "label": "Date", "page_number": 0, "x": 196, "y": 158, "width": 194, "height": 21, "required": true, "lock_to_sign_date": false, "validator_id": "13435fa6c2a17f83177fcbb5c4a9376ce85befeb", "max_chars": 10, "max_lines": 1 } }, { "id": "7e5b04c8a92d4e7193f0b8a3c5d1e6f7a02b9c4d", "type": "text", "role_id": "be616d202b3d4c36a65b0fb8042ccc95549f0ecb", "role": "Recipient 1", "json_attributes": { "name": "Date and Time 2", "label": "Date", "page_number": 0, "x": 196, "y": 190, "width": 194, "height": 21, "required": true, "lock_to_sign_date": false, "validator_id": "13435fa6c2a17f83177fcbb5c4a9376ce85befeb", "max_chars": 10, "max_lines": 1 } }, { "id": "21e54d4184b94e518aff02af8438875ce2f3ced2", "type": "signature", "role_id": "be616d202b3d4c36a65b0fb8042ccc95549f0ecb", "role": "Recipient 1", "json_attributes": { "name": "Signature 1", "page_number": 0, "x": 81, "y": 631, "width": 169, "height": 23, "required": true, "allowed_types": [ "type", "draw", "upload" ] } } ], "field_validators": [ { "id": "7cd795fd64ce63b670b52b2e83457d59ac796a39", "name": "Email address (simple e.g. john@gmail.com)", "description": "Please enter an email address (e.g. john@gmail.com)", "scope": "system", "error_message": "Please enter valid email address" }, { "id": "13435fa6c2a17f83177fcbb5c4a9376ce85befeb", "name": "Date Only (e.g. 09/28/2008)", "description": "Please enter a date mm/dd/yyyy.", "scope": "system", "error_message": "Please enter a date (mm/dd/yyyy)." } ] } ``` Pick the `json_attributes.name` value from each text-type field you want to pre-fill (`Text Field 1`, `Text Field 2`, `Date and Time 1`, `Date and Time 2`, and so on). If the same custom field is dragged onto the document more than once, each instance gets its own auto-incremented name, so you can pre-fill each instance independently. **3. [Get field name attributes](/docs/document/operations/get-v2-documents-documentUniqueId-fields) (alternative to step 2)** A lighter-weight option that returns only each field's `id`, `name`, `type`, and `value`. Use it when you don't need positions, validators, or styling and just want the names to pass to the pre-fill call. This endpoint returns text-type fields only (text, date and time, email, and so on). Signature fields are not included in the response, which is fine for this flow since signature fields can't be pre-filled anyway. ```bash curl --request GET \ --url https://api.signnow.com/v2/documents/{{document_id}}/fields \ --header 'Authorization: Bearer {{access_token}}' \ --header 'Accept: application/json' ``` ```json { "data": [ { "id": "021b4a4cc4d34918826ee2d2690294e4c35737c5", "name": "Text Field 1", "type": "text", "value": null }, { "id": "56d02e0290614ce5978d4b2318de4122109c214b", "name": "Text Field 2", "type": "text", "value": null }, { "id": "491149598ec543909e9149a8716c928f5cd16528", "name": "Date and Time 1", "type": "text", "value": null }, { "id": "7e5b04c8a92d4e7193f0b8a3c5d1e6f7a02b9c4d", "name": "Date and Time 2", "type": "text", "value": null } ], "meta": { "pagination": { "total": 4, "count": 4, "per_page": 15, "current_page": 1, "total_pages": 1, "links": [] } } } ``` Use each `data[].name` as the `field_name` in the pre-fill call. The `value` is `null` until a signer completes the field. **4. [Pre-fill text fields by `field_name`](/docs/document/operations/put-v2-documents-document_id-prefill-texts)** ```bash curl --request PUT \ --url https://api.signnow.com/v2/documents/{{document_id}}/prefill-texts \ --header 'Authorization: Bearer {{access_token}}' \ --header 'Content-Type: application/json' \ --data '{ "fields": [ { "field_name": "Text Field 1", "prefilled_text": "Acme, Inc." }, { "field_name": "Text Field 2", "prefilled_text": "billing@acme.example" }, { "field_name": "Date and Time 1", "prefilled_text": "06/01/2026" }, { "field_name": "Date and Time 2", "prefilled_text": "06/01/2026" } ] }' ``` `204 No Content` Repeat the field-name lookup (step 2 or step 3) and the pre-fill call (step 4) for every document returned by step 1. ### Step 7. Create the embedded link for the document group This generates a URL your customer opens to start using the branded experience. Pick the endpoint that fits your flow: | Flow | Endpoint | When to use | | ---------------- | --------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------ | | Embedded editor | [`POST /v2/document-groups/{{document_group_id}}/embedded-editor`](/docs/embedded-editor/operations/post-v2-document-groups-document_group_id-embedded-editor) | User opens the documents to place custom fields from your curated library, then reviews or fills values. No invite is sent from the editor. | | Embedded sending | [`POST /v2/document-groups/{{document_group_id}}/embedded-sending`](/docs/embedded-sending/operations/post-v2-document-groups-document_group_id-embedded-sending) | User sends the document group to signers from inside your app. | This guide uses the document-group endpoints because Step 2 created a group, and documents inside a group can only be opened in the embedded editor or sender through the doc-group endpoints. For a single-document flow, skip the grouping step and use [`POST /v2/documents/{{document_id}}/embedded-editor`](/docs/embedded-editor/operations/post-v2-documents-documentUniqueId-embedded-editor) or [`POST /v2/documents/{{document_id}}/embedded-sending`](/docs/embedded-sending/operations/post-v2-documents-document_id-embedded-sending) instead. #### [Embedded editor](/docs/embedded-editor/operations/post-v2-document-groups-document_group_id-embedded-editor) ```bash curl --request POST \ --url https://api.signnow.com/v2/document-groups/{{document_group_id}}/embedded-editor \ --header 'Authorization: Bearer {{access_token}}' \ --header 'Accept: application/json' \ --header 'Content-Type: application/json' \ --data '{ "redirect_uri": "https://your.app.example/after-edit", "redirect_target": "blank", "link_expiration": 45 }' ``` ```json { "data": { "url": "https://app.signnow.com/documentgroup/e1d2c3b4a5f6071829304a5b6c7d8e9f0a1b2c3d/edit?access_token={{access_token}}&redirect_uri=https%3A%2F%2Fyour.app.example%2Fafter-edit&embedded=1&redirect_target=blank" } } ``` #### [Embedded sending](/docs/embedded-sending/operations/post-v2-document-groups-document_group_id-embedded-sending) ```bash curl --request POST \ --url https://api.signnow.com/v2/document-groups/{{document_group_id}}/embedded-sending \ --header 'Authorization: Bearer {{access_token}}' \ --header 'Accept: application/json' \ --header 'Content-Type: application/json' \ --data '{ "type": "edit", "redirect_uri": "https://your.app.example/after-send", "redirect_target": "blank", "link_expiration": 45 }' ``` ```json { "data": [ { "url": "https://app.signnow.com/webapp/documentgroup/e1d2c3b4a5f6071829304a5b6c7d8e9f0a1b2c3d/setup_invite?access_token={{access_token}}&redirect_uri=https%3A%2F%2Fyour.app.example%2Fafter-send&redirect_target=blank" } ] } ``` ## What the end-user sees When your user opens the link from step 7, the document group loads in the editor with: - The **Custom** tab as the only tab in the left sidebar. No Default fields, no Default / Custom tab switcher. - No **Element settings** button in the editor header. Field properties are already set, so there's nothing to configure. - Every custom field rendered with the validation, label, and (where set) pre-filled value you wrote in step 6. - The brand styling applied across the editor or sending flow. The result is a smooth, focused embedded experience: admins curate the field library, your backend handles the data, and end-users get straight to placing fields and sending the document. **Embedded editor experience with custom fields** ![custom_fields_3.png](/reference-assets/images/Fields%20guide/custom_fields_guide/custom_fields_3.png) **Embedded sending experience with pre-filled custom fields** ![custom_fields_2.png](/reference-assets/images/Fields%20guide/custom_fields_guide/custom_fields_2.png) --- *Full page: https://docs.signnow.com/docs/custom-fields*