---
title: "Update doc group invite"
url: "https://docs.signnow.com/docs/doc-group-field-invite/operations/update_document_group_invite"
type: "endpoint"
section: "doc-group-field-invite"
slug: "doc-group-field-invite/operations/update_document_group_invite"
method: "POST"
path: "/documentgroup/{document_group_id}/groupinvite/{invite_id}/invitestep/{step_id}/update"
operation_id: "update_document_group_invite"
authorization: "bearer"
---

# Update doc group invite

`POST /documentgroup/{document_group_id}/groupinvite/{invite_id}/invitestep/{step_id}/update`

This endpoint either replaces the recipient at a particular invite step or updates the invite attributes (reminder, expiration, language) for a recipient at that step.

Recipients can be identified and replaced by email or by SMS. Identify the current recipient by `user_to_update` (email) or `phone_invite_to_update` (phone number). Set the new recipient with `replace_with_this_user` (email) or `replace_with_this_phone_invite` (phone number). This supports all four conversions: email to email, email to phone, phone to email, and phone to phone. For SMS invites, see the [SMS invite guide](/docs/sms-invite).

To get the current SMS recipient's phone number for `phone_invite_to_update`, call [Get doc group invite](/docs/doc-group-field-invite/operations/get-document-group-invite) and read `actions[].signer_phone_invite`.

**Notes**

* Send both an identifier and a replacement. Use one identifier (`user_to_update` for email or `phone_invite_to_update` for phone) and one replacement (`replace_with_this_user` for email or `replace_with_this_phone_invite` for phone). To keep the same recipient and only change attributes, repeat the current value in the replacement field.
* For an SMS recipient, omitting `replace_with_this_phone_invite` still returns `200`, but the invite stops being delivered, so always send it.
* When replacing with an email recipient, `invite_email.email` must equal `replace_with_this_user`. When replacing with an SMS recipient, `invite_sms.phone_invite` must equal `replace_with_this_phone_invite`.
* `update_invite_action_attributes` is optional. If omitted, every document the recipient has in the step is updated; if provided, only the listed `document_id`s are updated.
* `expiration_days` accepts `1` to `180`. `0` means use the organization's default invite-expiration setting (falls back to `30` days).
* A phone recipient is rejected when the `CFR` or `require_login_for_signing` setting is enabled. SMS delivery may still be suppressed after a `200` if the recipient has opted out of or declined SMS consent.
* `allow_reassign` cannot be combined with `replace_with_this_phone_invite`.
* With `is_short_link_invite: true` the service generates the recipient, so neither `replace_with_this_user` nor `replace_with_this_phone_invite` may be sent.

## Authorization

bearer

## Path Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `document_group_id` | string | Yes | ID of the document group. |
| `invite_id` | string | Yes | ID of the document group invite. |
| `step_id` | string | Yes | ID of the invite step to update. |

## Request Body

**Schema**

```json
{
  "type": "object",
  "properties": {
    "invite_sms": {
      "type": "object",
      "required": [
        "phone_invite"
      ],
      "properties": {
        "reminder": {
          "type": "object",
          "properties": {
            "remind_after": {
              "type": "integer",
              "maximum": 179,
              "minimum": 1,
              "description": "Number of days after sending the invite when the recipient receives a reminder SMS. Must be less than `expiration_days`."
            },
            "remind_before": {
              "type": "integer",
              "maximum": 179,
              "minimum": 1,
              "description": "Number of days before the invite expires when the recipient receives a reminder SMS. Must be less than `expiration_days`."
            },
            "remind_repeat": {
              "type": "integer",
              "maximum": 7,
              "minimum": 1,
              "description": "Number of days between each reminder sent to the recipient."
            }
          },
          "description": "Settings for sending automatic reminders. A reminder applies to the recipient's first invite in the step, not to each document."
        },
        "phone_invite": {
          "type": "string",
          "example": "+14085550123",
          "description": "Phone number of the new SMS recipient in E.164 format (`+` followed by up to 13 digits, max 14 characters). Must match `replace_with_this_phone_invite`."
        },
        "expiration_days": {
          "type": "integer",
          "maximum": 180,
          "minimum": 1,
          "description": "Number of days before the invite expires. Accepts `1` to `180`. `0` uses the organization's default invite-expiration setting (falls back to `30`)."
        }
      },
      "description": "Settings for the new SMS recipient. Include when the updated recipient receives the invite by SMS. The `phone_invite` value must match `replace_with_this_phone_invite`."
    },
    "invite_email": {
      "type": "object",
      "required": [
        "email"
      ],
      "properties": {
        "email": {
          "type": "string",
          "format": "email",
          "example": "updated.signer@email.com",
          "description": "Email address of the new recipient. Must match `replace_with_this_user`."
        },
        "reminder": {
          "type": "object",
          "properties": {
            "remind_after": {
              "type": "integer",
              "maximum": 179,
              "minimum": 1,
              "description": "Number of days after sending the invite when the recipient receives a reminder. Must be less than `expiration_days`."
            },
            "remind_before": {
              "type": "integer",
              "maximum": 179,
              "minimum": 1,
              "description": "Number of days before the invite expires when the recipient receives a reminder. Must be less than `expiration_days`."
            },
            "remind_repeat": {
              "type": "integer",
              "maximum": 7,
              "minimum": 1,
              "description": "Number of days between each reminder sent to the recipient."
            }
          },
          "description": "Settings for sending automatic reminders. A reminder applies to the recipient's first invite in the step, not to each document."
        },
        "expiration_days": {
          "type": "integer",
          "maximum": 180,
          "minimum": 1,
          "description": "Number of days before the invite expires. Accepts `1` to `180`. `0` uses the organization's default invite-expiration setting (falls back to `30`)."
        }
      },
      "description": "Settings for the new email recipient. Include when the updated recipient receives the invite by email. The `email` value must match `replace_with_this_user`."
    },
    "user_to_update": {
      "type": "string",
      "example": "initial.signer@email.com",
      "description": "Current email recipient to update or replace, identified by email address. Provide either `user_to_update` or `phone_invite_to_update`, not both."
    },
    "client_timestamp": {
      "type": "integer",
      "example": 1531154773,
      "description": "Unix timestamp of the request."
    },
    "is_short_link_invite": {
      "type": "boolean",
      "example": false,
      "description": "Set to `true` for a short-link invite. Short-link invites cannot contain `replace_with_this_user` or `replace_with_this_phone_invite`, reminders, or SN Login authentication."
    },
    "phone_invite_to_update": {
      "type": "string",
      "example": "+14075985199",
      "description": "Current SMS recipient to update or replace, identified by phone number in E.164 format (`+` followed by up to 13 digits, max 14 characters). Source it from [Get doc group invite](/docs/doc-group-field-invite/operations/get-document-group-invite) and read `actions[].signer_phone_invite`. Provide either `user_to_update` or `phone_invite_to_update`. Note: The internal `sms_signer_+<phone>@no.reply` address is not a supported input."
    },
    "replace_with_this_user": {
      "type": "string",
      "example": "updated.signer@email.com",
      "description": "Email address of the new recipient that replaces the current one. Provide either `replace_with_this_user` or `replace_with_this_phone_invite`, not both. When provided, `invite_email.email` must equal this value."
    },
    "replace_with_this_phone_invite": {
      "type": "string",
      "example": "+14085550123",
      "description": "Phone number (E.164) of the new SMS recipient that replaces the current one. Provide either `replace_with_this_user` or `replace_with_this_phone_invite`. When provided, `invite_sms.phone_invite` must equal this value. Cannot be combined with `allow_reassign`, or with the `CFR` or `require_login_for_signing` settings."
    },
    "update_invite_action_attributes": {
      "type": "array",
      "items": {
        "type": "object",
        "required": [
          "document_id"
        ],
        "properties": {
          "language": {
            "type": "string",
            "example": "en",
            "description": "Language of the invite email or SMS. Allowed values: `en`, `es`, `fr`. Must be the same for one recipient."
          },
          "contact_id": {
            "type": "string",
            "example": "abc123def456abc123def456abc123def456abcd",
            "description": "40-character ID of the CRM contact to associate with this recipient."
          },
          "document_id": {
            "type": "string",
            "example": "abc123def456abc123def456abc123def456abcd",
            "description": "ID of the document within the document group to update for this recipient."
          },
          "allow_reassign": {
            "type": "integer",
            "example": 0,
            "description": "Allow the recipient to reassign the invite (`1`) or not (`0`). Cannot be used together with `replace_with_this_phone_invite`."
          },
          "decline_by_signature": {
            "type": "string",
            "example": "0",
            "description": "When a signer clicks a signature field, they can sign or decline the document group. Enabled (`1`) or disabled (`0`)."
          }
        }
      },
      "description": "Optional per-document settings for the recipient being updated. If omitted, all documents the recipient has in the step are updated; if provided, only the listed `document_id`s are updated."
    }
  }
}
```

**Example** (`Update SMS recipient (phone to phone)`)

```json
{
  "invite_sms": {
    "phone_invite": "+14085550123",
    "expiration_days": 30
  },
  "phone_invite_to_update": "+14075985199",
  "replace_with_this_phone_invite": "+14085550123",
  "update_invite_action_attributes": [
    {
      "document_id": "abc123def456abc123def456abc123def456abcd"
    }
  ]
}
```

**Example** (`Update email recipient (email to email)`)

```json
{
  "invite_email": {
    "email": "updated.signer@email.com",
    "expiration_days": 30
  },
  "user_to_update": "initial.signer@email.com",
  "replace_with_this_user": "updated.signer@email.com",
  "update_invite_action_attributes": [
    {
      "document_id": "abc123def456abc123def456abc123def456abcd",
      "allow_reassign": 0,
      "decline_by_signature": "0"
    }
  ]
}
```

**Example** (`Convert SMS recipient to email (phone to email)`)

```json
{
  "invite_email": {
    "email": "updated.signer@email.com",
    "expiration_days": 30
  },
  "phone_invite_to_update": "+14075985199",
  "replace_with_this_user": "updated.signer@email.com",
  "update_invite_action_attributes": [
    {
      "document_id": "abc123def456abc123def456abc123def456abcd",
      "allow_reassign": 0,
      "decline_by_signature": "0"
    }
  ]
}
```

**Example** (`Convert email recipient to SMS (email to phone)`)

```json
{
  "invite_sms": {
    "phone_invite": "+14075985199",
    "expiration_days": 30
  },
  "user_to_update": "initial.signer@email.com",
  "replace_with_this_phone_invite": "+14075985199",
  "update_invite_action_attributes": [
    {
      "document_id": "abc123def456abc123def456abc123def456abcd"
    }
  ]
}
```

## Responses

### 200

The invite step was updated successfully.

**Example** (`Example 1`)

```json
{
  "status": "success"
}
```

**Example** (`application/json`)

```json
{
  "status": "success"
}
```

### 400

Bad request. Possible errors:

* Neither `user_to_update` nor `phone_invite_to_update` provided.
* Both `user_to_update` and `phone_invite_to_update` provided (only one identifier allowed).
* Both `replace_with_this_user` and `replace_with_this_phone_invite` provided (only one replacement allowed).
* Incorrect user to update.
* The recipient in `user_to_update` or `phone_invite_to_update` is not on this step.
* Incorrect document ID in `update_invite_action_attributes`.
* Incorrect replace user email.
* Incorrect group invite ID in endpoint.
* Cannot update the invite with an email group.
* Invalid `phone_invite_to_update` or `replace_with_this_phone_invite` format.
* Phone number is valid but could not be found.
* `invite_email.email` does not match `replace_with_this_user`.
* `invite_sms.phone_invite` does not match `replace_with_this_phone_invite`.
* `allow_reassign` used together with `replace_with_this_phone_invite`.
* A short-link invite (`is_short_link_invite`) contains `replace_with_this_user` or `replace_with_this_phone_invite`.
* Phone recipient rejected because the `CFR` setting is enabled.
* Phone recipient rejected because the `require_login_for_signing` setting is enabled.
* SSO (SN Login) authentication is incompatible with SMS delivery.
* Daily invite limit exceeded.
* The organization does not allow senders to change the invite expiration.
* The organization does not allow senders to change invite reminders.
* The SMS message was blocked by a message filter.

**Example** (`Example 1`)

```json
{
  "errors": [
    {
      "code": 65582,
      "message": "Invite step does not belong to document group invite"
    }
  ]
}
```

**Example** (`CFR setting enabled`)

```json
{
  "errors": [
    {
      "code": 65582,
      "message": "The `replace_with_this_phone_invite` cannot be used with the `CFR` setting enabled."
    }
  ]
}
```

**Example** (`Phone number not found`)

```json
{
  "errors": [
    {
      "code": 104833,
      "message": "The phone_invite value holds a non-existent phone number."
    }
  ]
}
```

**Example** (`SMS invite not allowed`)

```json
{
  "errors": [
    {
      "code": 104956,
      "message": "Sending sms invite is not allowed."
    }
  ]
}
```

**Example** (`Incorrect user to update`)

```json
{
  "errors": [
    {
      "code": 65582,
      "message": "Invite step does not belong to document group invite"
    }
  ]
}
```

**Example** (`Recipient not on this step`)

```json
{
  "errors": [
    {
      "code": 65582,
      "message": "Cannot update signer signer1@email.com because user is not part of invite step"
    }
  ]
}
```

**Example** (`Short link invite conflict`)

```json
{
  "errors": [
    {
      "code": 65536,
      "message": "Short link invite cannot contain replace_with_this_user or replace_with_this_phone_invite fields."
    }
  ]
}
```

**Example** (`Daily invite limit exceeded`)

```json
{
  "errors": [
    {
      "code": 65639,
      "message": "Daily invite limit exceeded"
    }
  ]
}
```

**Example** (`Invalid phone number format`)

```json
{
  "errors": [
    {
      "code": 65582,
      "message": "The `phone_invite_to_update` value is invalid. It must start with `+` and contain up to 13 digits (total max 14 characters)."
    }
  ]
}
```

**Example** (`Neither identifier provided`)

```json
{
  "errors": [
    {
      "code": 65536,
      "message": "Either `user_to_update` or `phone_invite_to_update` field must be provided."
    }
  ]
}
```

**Example** (`Incorrect replace user email`)

```json
{
  "errors": [
    {
      "code": 65544,
      "message": "replace_with_this_user is invalid email."
    }
  ]
}
```

**Example** (`Require login setting enabled`)

```json
{
  "errors": [
    {
      "code": 65582,
      "message": "The `replace_with_this_phone_invite` cannot be used with the `require_login_for_signing` setting enabled."
    }
  ]
}
```

**Example** (`SSO login incompatible with SMS`)

```json
{
  "errors": [
    {
      "code": 19099002,
      "message": "Authentication type sso_login is incompatible with SMS delivery type."
    }
  ]
}
```

**Example** (`Email does not match replacement`)

```json
{
  "errors": [
    {
      "code": 65582,
      "message": "Email in the invite_email object must match the email of the user being updated."
    }
  ]
}
```

**Example** (`Phone does not match replacement`)

```json
{
  "errors": [
    {
      "code": 65582,
      "message": "`phone_invite` in the `invite_sms` object must match the `phone_invite` of the user being updated."
    }
  ]
}
```

**Example** (`Incorrect group invite id in endpoint`)

```json
{
  "errors": [
    {
      "code": 65582,
      "message": "unable to find document group invite of f1XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
    }
  ]
}
```

**Example** (`Only one recipient identifier allowed`)

```json
{
  "errors": [
    {
      "code": 65536,
      "message": "Only one field can be provided: either `user_to_update` or `phone_invite_to_update`."
    }
  ]
}
```

**Example** (`Reassign not allowed for phone invite`)

```json
{
  "errors": [
    {
      "code": 65536,
      "message": "The `allow_reassign` in `update_invite_action_attributes` could not be presented for `replace_with_this_phone_invite`."
    }
  ]
}
```

**Example** (`Only one replacement recipient allowed`)

```json
{
  "errors": [
    {
      "code": 65536,
      "message": "Only one field can be provided: either `replace_with_this_user` or `replace_with_this_phone_invite`."
    }
  ]
}
```

**Example** (`Cannot update the invite with an email group`)

```json
{
  "errors": [
    {
      "code": 65582,
      "message": "Field invite with email group is present"
    }
  ]
}
```

**Example** (`Editing reminders not allowed by organization`)

```json
{
  "errors": [
    {
      "code": 65582,
      "message": "Modifying invite reminders is not allowed by organization settings."
    }
  ]
}
```

**Example** (`Editing expiration not allowed by organization`)

```json
{
  "errors": [
    {
      "code": 65582,
      "message": "Modifying invite expiration is not allowed by organization settings."
    }
  ]
}
```

**Example** (`Incorrect document id in update invite action attributes`)

```json
{
  "errors": [
    {
      "code": 65582,
      "message": "Could not find existing action with document id c4XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX in update_invite_action_attributes payload"
    }
  ]
}
```

### 401

Incorrect or missing bearer token.

**Example** (`Example 1`)

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

**Example** (`Unauthorized`)

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

## Code Examples

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

### cURL

```bash
curl -X POST \
  "https://api.signnow.com/documentgroup/{document_group_id}/groupinvite/{invite_id}/invitestep/{step_id}/update" \
  -H "Authorization: Bearer $SIGNNOW_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"invite_sms": {"phone_invite": "+14085550123", "expiration_days": 30}, "phone_invite_to_update": "+14075985199", "replace_with_this_phone_invite": "+14085550123", "update_invite_action_attributes": [{"document_id": "abc123def456abc123def456abc123def456abcd"}]}'
```

---
*Full reference: https://docs.signnow.com/docs/doc-group-field-invite/operations/update_document_group_invite*