---
title: "Create freeform invite"
url: "https://docs.signnow.com/docs/doc-group-freeform-invite/operations/post-v2-document-groups-document_group_id-free-form-invites"
type: "endpoint"
section: "doc-group-freeform-invite"
slug: "doc-group-freeform-invite/operations/post-v2-document-groups-document_group_id-free-form-invites"
method: "POST"
path: "/v2/document-groups/{document_group_id}/free-form-invites"
operation_id: "post-v2-document-groups-document_group_id-free-form-invites"
authorization: "bearer"
---

# Create freeform invite

`POST /v2/document-groups/{document_group_id}/free-form-invites`

This endpoint allows API users to create and send a FreeForm invite to sign a document group.

**FreeForm invite**

A FreeForm invite is an invite with a document that does not contain fields; recipients can add their signature anywhere on the document.
> A FreeForm invite can be sent to the sender's own email address.

**Schedule a freeform invite**

To send a FreeForm document group invite at a later time, use the [Schedule document group invite](/docs/scheduled-doc-group-invite/operations/post-document-group-scheduled-invite) endpoint with `is_freeform_invite: true`.

## Authorization

bearer

## Path Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `document_group_id` | string | Yes | ID of the document group. |

## Request Body

**Schema**

```json
{
  "type": "object",
  "required": [
    "to",
    "client_timestamp"
  ],
  "properties": {
    "cc": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "email": {
            "type": "string",
            "description": "CC recipient's email address."
          }
        }
      },
      "description": "Array with the list of CC email addresses."
    },
    "to": {
      "type": "array",
      "items": {
        "type": "object",
        "required": [
          "email"
        ],
        "properties": {
          "email": {
            "type": "string",
            "description": "Signer's email address. **Note**: A FreeForm invite can be sent to the sender's own email address."
          },
          "language": {
            "type": "string",
            "description": "Sets the language of the signing session and notification emails for the signer. Possible values: `en` for English, `es` for Spanish, and `fr` for French. If not set, the language is determined by the language of your SignNow account. If emails are branded, you can set up [your own](/docs/guides-branding#language-branding) email texts in different languages."
          },
          "redirect_uri": {
            "type": "string",
            "description": "The link that opens after a signer signs the document group. This field overrides the general `redirect_uri`.",
            "x-stoplight": {
              "id": "lcfnb28x6nalk"
            }
          },
          "redirect_target": {
            "type": "string",
            "default": "blank",
            "description": "Determines whether to open the redirect link in the new tab in the browser, or in the same tab after the signing session. Possible values: `blank` - opens the link in the new tab, `self` - opens the link in the same tab.",
            "x-stoplight": {
              "id": "l98jmc0673jxg"
            }
          },
          "close_redirect_uri": {
            "type": "string",
            "description": "The link that opens after a signer selects the **Close** button.",
            "x-stoplight": {
              "id": "z8u5arnl0loe4"
            }
          }
        }
      },
      "description": "Array with the list of signers."
    },
    "message": {
      "type": "string",
      "description": "Email body message for all signers."
    },
    "subject": {
      "type": "string",
      "description": "Email subject for all signers."
    },
    "redirect_uri": {
      "type": "string",
      "description": "When the document is signed, the signer is redirected to this URI."
    },
    "client_timestamp": {
      "type": "integer",
      "maximum": 4294967295,
      "minimum": 0,
      "description": "UNIX timestamp.",
      "x-stoplight": {
        "id": "h1cu9trup60is"
      }
    }
  },
  "x-examples": {
    "Example 1": {
      "cc": [
        {
          "email": "cc@email.com"
        }
      ],
      "to": [
        {
          "email": "signer@email.com"
        }
      ],
      "message": "You have been invited to sign a document group",
      "subject": "You have been invited to sign a document group",
      "redirect_uri": "https://example.com",
      "client_timestamp": 1530017036
    }
  }
}
```

**Example** (`Example 1`)

```json
{
  "cc": [
    {
      "email": "cc@mail.com"
    }
  ],
  "to": [
    {
      "email": "signer@mail.com",
      "language": "en",
      "redirect_uri": "https://redirect-uri.com",
      "redirect_target": "blank",
      "close_redirect_uri": "https://close-redirect-uri.com"
    }
  ],
  "message": "Custom message",
  "subject": "Custom subject",
  "redirect_uri": "https://signnow.com",
  "client_timestamp": 1719852788
}
```

## Responses

### 201

Success

**Example** (`Success`)

```json
{
  "data": {
    "id": "2aXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
  }
}
```

### 400

* Incorrect or missing token.
* More than 20 documents in the document group.
* Document group has no documents.
* Document group has active fields.
* Document group has deleted or trashed documents.
* Owner cannot be a signer.
* Invite has more than 50 signers.
* User doesn't own the document group.
* Missing `to` email.
* `to` is not an array.
* `to` is not an array of arrays.
* `cc`  is not an array.
* `cc` is not an array of arrays.
* `message` is not a string.
* Empty `message`.
* `message` is longer than 1000 characters.
* `message` contains unsupported characters.
* `subject` is not a string.
* Empty `subject.
* `subject` is longer than 1000 characters.
* `subject` contains unsupported characters.
* `redirect_uri` is not a string.
* Empty `redirect_uri`.
* `redirect_uri` is not a correct URL.
* `redirect_uri` is longer than 2048 characters.
* Missing `to.email`.
* `to.email` is not a string.
* Empty `to.email`.
* `to. email` is not a correct email address.
* Missing `cc.email`.
* `cc.email` is not a string.
* Empty `cc.email`.
* `cc. email` is not a correct email address.
* Emails in `to` are not unique.
* Emails in `cc` are not unique.
* Invite has more than 50 signers.
* Invite has more than 50 emails in `cc`.
* Missing `client_timestamp`.
* `client_timestamp` is not an integer.
* `client_timestamp` is out of range.
* `language` is not a string.
* Incorrect `language`.
* `to.close_redirect_uri` is not a string.
* Empty `to.close_redirect_uri`.
* `to.close_redirect_uri` is not a correct URL address.
* `to.close_redirect_uri` is longer than 2048 characters.
* `to.redirect_uri` is not a string.
* Empty `to.redirect_uri`.
* `to.redirect_uri` is not a correct URL address.
* `to.redirect_uri` is longer than 2048 characters.
* `redirect_target` is not a string.
* Incorrect `redirect_target`.
* One of redirect URLs is required if `redirect_target` is added.

**Example** (`Empty message`)

```json
{
  "errors": [
    {
      "code": 19054007,
      "message": "Field `message` must not be empty string."
    }
  ]
}
```

**Example** (`Empty subject`)

```json
{
  "errors": [
    {
      "code": 19054011,
      "message": "Field `subject` must not be empty string."
    }
  ]
}
```

**Example** (`Empty cc.email`)

```json
{
  "errors": [
    {
      "code": 19054029,
      "message": "Field `email` in `cc` should not be empty string."
    }
  ]
}
```

**Example** (`Empty to.email`)

```json
{
  "errors": [
    {
      "code": 19054028,
      "message": "Field `email` in `to` should not be empty string."
    }
  ]
}
```

**Example** (``cc` not array`)

```json
{
  "errors": [
    {
      "code": 19054004,
      "message": "Field `cc` should be of type array."
    }
  ]
}
```

**Example** (``to` not array`)

```json
{
  "errors": [
    {
      "code": 19054002,
      "message": "Field `to` should be of type array"
    }
  ]
}
```

**Example** (`Owner is signer`)

```json
{
  "errors": [
    {
      "code": 19055005,
      "message": "Document group owner can not be signer."
    }
  ]
}
```

**Example** (`Missing cc.email`)

```json
{
  "errors": [
    {
      "code": 19054021,
      "message": "Field `email` in `cc` should not be null."
    }
  ]
}
```

**Example** (`Missing to.email`)

```json
{
  "errors": [
    {
      "code": 19054018,
      "message": "Field `email` in `to` should not be null."
    }
  ]
}
```

**Example** (`Too many signers`)

```json
{
  "errors": [
    {
      "code": 19054026,
      "message": "Maximum number of signers is 50."
    }
  ]
}
```

**Example** (`message too long`)

```json
{
  "errors": [
    {
      "code": 19054008,
      "message": "Field `message` should not exceed 1000 characters."
    }
  ]
}
```

**Example** (`subject too long`)

```json
{
  "errors": [
    {
      "code": 19054012,
      "message": "Field `subject` should not exceed 1000 characters."
    }
  ]
}
```

**Example** (`Empty redirect_uri`)

```json
{
  "errors": [
    {
      "code": 19054015,
      "message": "Field `redirect_uri` must not be empty string."
    }
  ]
}
```

**Example** (`Incorrect language`)

```json
{
  "errors": [
    {
      "code": 19054034,
      "message": "Field `language` in `to` is invalid, allowed values: en, fr, es."
    }
  ]
}
```

**Example** (`Missing `to` field`)

```json
{
  "errors": [
    {
      "code": 19054001,
      "message": "Field `to` should not be null."
    }
  ]
}
```

**Example** (`message not string`)

```json
{
  "errors": [
    {
      "code": 19054006,
      "message": "Field `message` should be of type string"
    }
  ]
}
```

**Example** (`subject not string`)

```json
{
  "errors": [
    {
      "code": 19054010,
      "message": "Field `subject` should be of type string."
    }
  ]
}
```

**Example** (`DG has no documents`)

```json
{
  "errors": [
    {
      "code": 19055002,
      "message": "Document group has no documents."
    }
  ]
}
```

**Example** (`cc.email not string`)

```json
{
  "errors": [
    {
      "code": 19054022,
      "message": "Field `email` in `cc` should be of type string."
    }
  ]
}
```

**Example** (`language not string`)

```json
{
  "errors": [
    {
      "code": 19054033,
      "message": "Field `language` in `to` must be a string."
    }
  ]
}
```

**Example** (`to.email not string`)

```json
{
  "errors": [
    {
      "code": 19054019,
      "message": "Field `email` in `to` should be of type string."
    }
  ]
}
```

**Example** (`DG has active fields`)

```json
{
  "errors": [
    {
      "code": 19055001,
      "message": "Document group has active fields."
    }
  ]
}
```

**Example** (`Missing redirect URL`)

```json
{
  "errors": [
    {
      "code": 19054045,
      "message": "In `to`, one of the `redirect_uri` fields is required when `redirect_target` is added."
    }
  ]
}
```

**Example** (`More than 50 signers`)

```json
{
  "errors": [
    {
      "code": 19054026,
      "message": "Maximum number of signers is 50."
    }
  ]
}
```

**Example** (`Empty to.redirect_uri`)

```json
{
  "errors": [
    {
      "code": 19054036,
      "message": "The `redirect_uri` field in `to` must not be empty."
    }
  ]
}
```

**Example** (`redirect_uri too long`)

```json
{
  "errors": [
    {
      "code": 19054017,
      "message": "Field `redirect_uri` should not exceed 2048 characters."
    }
  ]
}
```

**Example** (``cc` emails not unique`)

```json
{
  "errors": [
    {
      "code": 19054025,
      "message": "Cc emails must be unique."
    }
  ]
}
```

**Example** (``to` emails not unique`)

```json
{
  "errors": [
    {
      "code": 19054024,
      "message": "To emails must be unique."
    }
  ]
}
```

**Example** (`redirect_uri not a URL`)

```json
{
  "errors": [
    {
      "code": 19054016,
      "message": "Field `redirect_uri` should be a valid url."
    }
  ]
}
```

**Example** (`Too many emails in `cc``)

```json
{
  "errors": [
    {
      "code": 19054027,
      "message": "Maximum number of cc is 50."
    }
  ]
}
```

**Example** (`redirect_uri not string`)

```json
{
  "errors": [
    {
      "code": 19054014,
      "message": "Field `redirect_uri` should be of type string."
    }
  ]
}
```

**Example** (`Missing client_timestamp`)

```json
{
  "errors": [
    {
      "code": 19054030,
      "message": "Field `client_timestamp` should not be null."
    }
  ]
}
```

**Example** (``cc` not array of arrays`)

```json
{
  "errors": [
    {
      "code": 19054005,
      "message": "Field `cc` must be an array of arrays."
    }
  ]
}
```

**Example** (``to` not array of arrays`)

```json
{
  "errors": [
    {
      "code": 19054003,
      "message": "Field `to` must be an array of arrays."
    }
  ]
}
```

**Example** (`to.redirect_uri too long`)

```json
{
  "errors": [
    {
      "code": 19054038,
      "message": "Parameter `redirect_uri` must not exceed 2048 characters."
    }
  ]
}
```

**Example** (`Incorrect redirect_target`)

```json
{
  "errors": [
    {
      "code": 19054044,
      "message": "The `redirect_target` field in `to` is invalid, allowed values: self, blank."
    }
  ]
}
```

**Example** (`to.redirect_uri not a URL`)

```json
{
  "errors": [
    {
      "code": 19054037,
      "message": "The `redirect_uri` field in `to` contains a URL in an invalid format."
    }
  ]
}
```

**Example** (`20+ documents in doc group`)

```json
{
  "errors": [
    {
      "code": 19055006,
      "message": "Document group can not contain more than 20 documents."
    }
  ]
}
```

**Example** (`Incorrect or missing token`)

```json
{
  "code": 1537,
  "error": "invalid_token"
}
```

**Example** (`redirect_target not string`)

```json
{
  "errors": [
    {
      "code": 19054043,
      "message": "The `The `redirect_target` field in `to` must be a string."
    }
  ]
}
```

**Example** (`to.redirect_uri not string`)

```json
{
  "errors": [
    {
      "code": 19054035,
      "message": "The `redirect_uri` field in `to` must be a string."
    }
  ]
}
```

**Example** (`Empty to.close_redirect_uri`)

```json
{
  "errors": [
    {
      "code": 19054040,
      "message": "The `close_redirect_uri` field in `to` must not be empty."
    }
  ]
}
```

**Example** (`client_timestamp not integer`)

```json
{
  "errors": [
    {
      "code": 19054031,
      "message": "Field `client_timestamp` should be of type int."
    }
  ]
}
```

**Example** (`User not document group owner`)

```json
{
  "errors": [
    {
      "code": 19001010,
      "message": "Current user is not document group owner."
    }
  ]
}
```

**Example** (`client_timestamp out of range`)

```json
{
  "errors": [
    {
      "code": 19054032,
      "message": "The `client_timestamp` should be between 0 and 4294967295."
    }
  ]
}
```

**Example** (`to.close_redirect_uri too long`)

```json
{
  "errors": [
    {
      "code": 19054042,
      "message": "Parameter `close_redirect_uri` must not exceed 2048 characters."
    }
  ]
}
```

**Example** (`to.close_redirect_uri not a URL`)

```json
{
  "errors": [
    {
      "code": 19054041,
      "message": "The `close_redirect_uri` field in `to` contains a URL in an invalid format."
    }
  ]
}
```

**Example** (`cc.email is not an email address`)

```json
{
  "errors": [
    {
      "code": 19054023,
      "message": "Field `email` in `cc` should be a valid email address."
    }
  ]
}
```

**Example** (`to.close_redirect_uri not string`)

```json
{
  "errors": [
    {
      "code": 19054039,
      "message": "The `close_redirect_uri` field in `to` must be a string."
    }
  ]
}
```

**Example** (`to.email is not an email address`)

```json
{
  "errors": [
    {
      "code": 19054020,
      "message": "Field `email` in `to` should be a valid email address."
    }
  ]
}
```

**Example** (`Message has unsupported characters`)

```json
{
  "errors": [
    {
      "code": 19054009,
      "message": "Invalid characters provided for `message`."
    }
  ]
}
```

**Example** (`Subject has unsupported characters`)

```json
{
  "errors": [
    {
      "code": 19054013,
      "message": "Invalid characters provided for `subject`."
    }
  ]
}
```

**Example** (`DG has deleted or trashed documents`)

```json
{
  "errors": [
    {
      "code": 19055003,
      "message": "Document group contains deleted documents."
    }
  ]
}
```

### 403

User is not verified

**Example** (`User is not verified`)

```json
{
  "errors": [
    {
      "code": 19001049,
      "message": "User is not verified."
    }
  ]
}
```

### 422

Document group has active invites

**Example** (`Document group has active invites`)

```json
{
  "errors": [
    {
      "code": 19001036,
      "message": "An invite already exists for this document group."
    }
  ]
}
```

### 429

Too Many Requests

**Example** (`Too many requests`)

```json
{
  "errors": [
    {
      "code": 19001058,
      "message": "Too many requests."
    }
  ]
}
```

## Code Examples

> Replace `$SIGNNOW_ACCESS_TOKEN` and any `{placeholder}` values before running.

### cURL

```bash
curl -X POST \
  "https://api.signnow.com/v2/document-groups/{document_group_id}/free-form-invites" \
  -H "Authorization: Bearer $SIGNNOW_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"cc": [{"email": "cc@mail.com"}], "to": [{"email": "signer@mail.com", "language": "en", "redirect_uri": "https://redirect-uri.com", "redirect_target": "blank", "close_redirect_uri": "https://close-redirect-uri.com"}], "message": "Custom message", "subject": "Custom subject", "redirect_uri": "https://signnow.com", "client_timestamp": 1719852788}'
```

---
*Full reference: https://docs.signnow.com/docs/doc-group-freeform-invite/operations/post-v2-document-groups-document_group_id-free-form-invites*