---
title: "Replace signer: Step 2 - Replace"
url: "https://docs.signnow.com/docs/document-field-invite/operations/post-field-invite"
type: "endpoint"
section: "document-field-invite"
slug: "document-field-invite/operations/post-field-invite"
method: "POST"
path: "/field_invite"
operation_id: "post-field-invite"
authorization: "bearer"
---

# Replace signer: Step 2 - Replace

`POST /field_invite`

This endpoint allows API users to assign a new signer to the invite. This is step 2 of 3 to replace a signer in an invite.

## Authorization

bearer

## Request Body

**Schema**

```json
{
  "type": "object",
  "required": [
    "email",
    "role_id",
    "is_replace",
    "password",
    "phone"
  ],
  "properties": {
    "email": {
      "type": "string",
      "minLength": 1,
      "description": "New signer's email address."
    },
    "phone": {
      "type": "string",
      "description": "required if `\"authentication_type\": \"phone\"`.\nPhone number requested for identity verification."
    },
    "role_id": {
      "type": "string",
      "minLength": 1,
      "description": "The role id for the new signer. You can find it in the response from `GET /document/{{document_id}}` request as the `role_id` parameter in the `field_invites` array."
    },
    "password": {
      "type": "string",
      "minLength": 1,
      "description": "required if `\"authentication_type\": \"password\"`.\nPassword requested for identity verification."
    },
    "reminder": {
      "type": "number",
      "description": "In how many days to send a reminder to the signer; 30 days max."
    },
    "is_replace": {
      "type": "boolean",
      "description": "Boolean: determines whether to use the subject, message, and order of signing specified in the invite to the previous signer. Possible values: `\"true\"` - yes, keep the subject, message, and order of signing from the previous signer's invite; `\"false\"` - use the subject, message, and the order of signing from this payload."
    },
    "expiration_days": {
      "type": "number",
      "description": "In how many days the invite expires; 30 days max."
    },
    "authentication_type": {
      "type": "string",
      "minLength": 1,
      "description": "Type of recipient's identity verification. Possible values: `\"password\"` or `\"phone\"`. `phone` is available on paid plans; on a free trial or without a paid subscription, use `password`."
    },
    "decline_by_signature": {
      "type": "number",
      "description": "Adds the `Decline` button to the Signature field for the signer. Possible values: 0 - no `Decline` button, 1- add the `Decline` button."
    }
  },
  "x-examples": {
    "example-1": {
      "email": "new_signer@email.com",
      "role_id": "d9b491bd632e25cc5ec1a3b0b83dfccc164382bd",
      "password": "123456",
      "reminder": 0,
      "is_replace": true,
      "expiration_days": 30,
      "authentication_type": "password",
      "decline_by_signature": 0
    }
  },
  "description": ""
}
```

**Example** (`example-1`)

```json
{
  "email": "new_signer@email.com",
  "role_id": "d95a500c73fb0f226ece99a3ec804005f20d4312",
  "password": "123456",
  "reminder": 0,
  "is_replace": true,
  "expiration_days": 30,
  "authentication_type": "password",
  "decline_by_signature": 0
}
```

## Responses

### 200

Successful response. Returns the ID of the new invite.

**Example** (`Successful response`)

```json
{
  "id": "30e75828e8124c43d6fd769402a757b5d4d383a3"
}
```

### 400

* Wrong, expired, or missing token.
* `email` isn't a valid email address.
* The role with `role_id` doesn't exist.
* An invite for this role already exists. Delete it with `DELETE /field_invite/{field_invite_id}` first.
* The role has no invite to replace. Send the invite first.
* Phone authentication on a free trial or without a paid subscription.

**Example** (`Wrong email`)

```json
{
  "errors": [
    {
      "code": 65536,
      "message": "Email must be a valid email."
    }
  ]
}
```

**Example** (`Wrong token`)

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

**Example** (`Role not found`)

```json
{
  "errors": [
    {
      "code": 65582,
      "message": "Role does not exists"
    }
  ]
}
```

**Example** (`No invite to replace`)

```json
{
  "errors": [
    {
      "code": 65615,
      "message": "Invite could not be replaced"
    }
  ]
}
```

**Example** (`Invite already exists`)

```json
{
  "errors": [
    {
      "code": 65615,
      "message": "Invite already exists"
    }
  ]
}
```

**Example** (`Phone authentication not available`)

```json
{
  "errors": [
    {
      "code": 65582,
      "message": "Phone authentication can't be used with the current subscription."
    }
  ]
}
```

## Code Examples

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

### cURL

```bash
curl -X POST \
  "https://api.signnow.com/field_invite" \
  -H "Authorization: Bearer $SIGNNOW_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"email": "new_signer@email.com", "role_id": "d95a500c73fb0f226ece99a3ec804005f20d4312", "password": "123456", "reminder": 0, "is_replace": true, "expiration_days": 30, "authentication_type": "password", "decline_by_signature": 0}'
```

---
*Full reference: https://docs.signnow.com/docs/document-field-invite/operations/post-field-invite*