# Create a signup form

`POST /crm/forms` · Rivier · contacts

Create a signup form: fields, the consent words, double opt-in. Returns the hosted address and the embed code.

- Scope: contacts:write
- Graphql: Mutation.contactsFormCreate
- Sdk: contacts.form.create
- Cli: contacts form create

## Request body

`application/json`

```json
{
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "minLength": 1,
      "maxLength": 120
    },
    "kind": {
      "type": "string",
      "enum": [
        "signup",
        "lead",
        "preference",
        "contact",
        "support",
        "enquiry",
        "comment"
      ],
      "default": "signup"
    },
    "title": {
      "type": "string",
      "maxLength": 200
    },
    "intro": {
      "type": "string",
      "maxLength": 1000
    },
    "submitLabel": {
      "type": "string",
      "maxLength": 40
    },
    "fields": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "key": {
            "type": "string",
            "pattern": "^[a-z][a-z0-9_]{0,39}$"
          },
          "label": {
            "type": "string",
            "minLength": 1,
            "maxLength": 120
          },
          "type": {
            "type": "string",
            "enum": [
              "text",
              "email",
              "phone",
              "textarea",
              "select",
              "checkbox",
              "hidden"
            ]
          },
          "required": {
            "type": "boolean"
          },
          "options": {
            "type": "array",
            "items": {
              "type": "string",
              "maxLength": 80
            },
            "maxItems": 40
          },
          "maps": {
            "type": "string",
            "pattern": "^(name|firstName|lastName|email|phone|country|language|company|custom\\.[a-z][a-z0-9_]{0,39})$"
          }
        },
        "required": [
          "key",
          "label",
          "type"
        ],
        "additionalProperties": false
      },
      "minItems": 1,
      "maxItems": 30
    },
    "consents": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "channel": {
            "type": "string",
            "enum": [
              "email",
              "sms",
              "whatsapp",
              "phone"
            ]
          },
          "purpose": {
            "type": "string",
            "pattern": "^[a-z][a-z0-9_]{0,29}$",
            "default": "marketing"
          },
          "text": {
            "type": "string",
            "minLength": 10,
            "maxLength": 600
          },
          "required": {
            "type": "boolean"
          }
        },
        "required": [
          "channel",
          "text"
        ],
        "additionalProperties": false
      },
      "maxItems": 6,
      "default": []
    },
    "optIn": {
      "type": "string",
      "enum": [
        "double",
        "single"
      ],
      "default": "double"
    },
    "tags": {
      "type": "array",
      "items": {
        "type": "string",
        "minLength": 1,
        "maxLength": 40,
        "pattern": "^[\\p{L}\\p{N}][\\p{L}\\p{N} _.:/-]*$"
      },
      "maxItems": 20
    },
    "lifecycle": {
      "type": "string",
      "enum": [
        "subscriber",
        "lead",
        "customer",
        "partner",
        "other"
      ]
    },
    "policyVersion": {
      "type": "string",
      "maxLength": 40
    },
    "policyUrl": {
      "type": "string",
      "format": "uri",
      "maxLength": 300
    },
    "successMessage": {
      "type": "string",
      "maxLength": 300
    },
    "redirectUrl": {
      "type": "string",
      "format": "uri",
      "maxLength": 300
    },
    "allowedOrigins": {
      "type": "array",
      "items": {
        "type": "string",
        "maxLength": 200
      },
      "maxItems": 20
    },
    "leadMagnet": {
      "type": "object",
      "properties": {
        "assetId": {
          "type": "string",
          "format": "uuid"
        },
        "url": {
          "type": "string",
          "format": "uri",
          "maxLength": 500
        },
        "label": {
          "type": "string",
          "maxLength": 80
        }
      },
      "additionalProperties": false
    },
    "widget": {
      "type": "string",
      "enum": [
        "email_signup",
        "newsletter",
        "waitlist",
        "contact",
        "lead_form"
      ]
    },
    "defaultLanguage": {
      "type": "string",
      "pattern": "^[a-z]{2}(-[A-Za-z]{2})?$",
      "default": "en"
    },
    "copy": {
      "type": "object",
      "additionalProperties": {
        "type": "object",
        "properties": {
          "title": {
            "type": "string",
            "maxLength": 200
          },
          "intro": {
            "type": "string",
            "maxLength": 1000
          },
          "submitLabel": {
            "type": "string",
            "maxLength": 40
          },
          "successMessage": {
            "type": "string",
            "maxLength": 300
          },
          "consents": {
            "type": "array",
            "items": {
              "type": "string",
              "minLength": 10,
              "maxLength": 600
            },
            "maxItems": 6
          },
          "fields": {
            "type": "object",
            "additionalProperties": {
              "type": "string",
              "maxLength": 120
            }
          }
        },
        "additionalProperties": false
      },
      "propertyNames": {
        "pattern": "^[a-z]{2}(-[A-Za-z]{2})?$"
      }
    },
    "design": {
      "type": "object",
      "properties": {
        "theme": {
          "type": "string",
          "enum": [
            "auto",
            "light",
            "dark"
          ],
          "default": "auto"
        },
        "size": {
          "type": "string",
          "enum": [
            "compact",
            "regular",
            "large"
          ],
          "default": "regular"
        },
        "accent": {
          "type": "string",
          "pattern": "^#[0-9a-f]{6}$"
        },
        "radius": {
          "type": "integer",
          "minimum": 0,
          "maximum": 32
        },
        "font": {
          "type": "string",
          "enum": [
            "inherit",
            "system"
          ],
          "default": "inherit"
        }
      },
      "additionalProperties": false
    },
    "destination": {
      "type": "object",
      "properties": {
        "inboxId": {
          "type": "string",
          "format": "uuid"
        }
      },
      "additionalProperties": false
    },
    "route": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "field": {
            "type": "string",
            "maxLength": 60
          },
          "contains": {
            "type": "string",
            "maxLength": 120
          },
          "language": {
            "type": "string",
            "maxLength": 20
          },
          "inboxId": {
            "type": "string",
            "format": "uuid"
          }
        },
        "required": [
          "inboxId"
        ],
        "additionalProperties": false
      },
      "maxItems": 10
    },
    "autoConfirm": {
      "type": "boolean",
      "default": true
    },
    "guard": {
      "type": "object",
      "properties": {
        "enabled": {
          "type": "boolean",
          "default": true
        }
      },
      "additionalProperties": false
    },
    "active": {
      "type": "boolean",
      "default": true
    },
    "page": {
      "type": "object",
      "properties": {
        "headline": {
          "type": "string",
          "maxLength": 200
        },
        "body": {
          "type": "string",
          "maxLength": 4000
        },
        "accent": {
          "type": "string",
          "pattern": "^#[0-9a-f]{6}$"
        }
      },
      "additionalProperties": false
    }
  },
  "required": [
    "name",
    "fields"
  ],
  "additionalProperties": false
}
```

## Responses

- `201`: Success
- `400`: The request was malformed
- `401`: No valid credential
- `403`: The credential lacks the scope, origin or address
- `429`: Over the key's rate limit; see Retry-After

## Example

```sh
curl -X POST 'https://api.rivier.ai/crm/forms' \
  -H 'Authorization: Bearer $KEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "name": "string",
  "fields": [
    {
      "key": "string",
      "label": "string",
      "type": "text"
    }
  ]
}'
```