Create Form API Reference

Serverhttps://api.pinnacle.sh/

Create a hosted form without sending it.

Returns the form object including its public URL — https://forms.pinnacle.sh/{form_id}.

To also deliver the URL to a recipient over SMS or RCS in a single call, use POST /forms/send.

Authorization

Pinnacle API key

PINNACLE-API-KEY<token>

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Body of POST /forms. Same shape as FormDefinition.

namestringOptional

Human-readable name for the form. Rendered as the form's title.

Example

"Contact request"

descriptionstringOptional

Longer description rendered below the title.

Example

"We'll follow up over SMS or RCS."

array<16 variants>

Ordered list of fields the recipient will fill out. At least one field is required.

Items

1 <= items

can_updatebooleanOptional

If true, the recipient can reopen the submission URL and edit their answers. When false (default), the submission URL becomes read-only (Already submitted) after the first submit.

Default

false

expires_atstringOptional

After this timestamp the form stops accepting submissions. Omit for no expiration.

Format

date-time

Example

"2026-12-31T23:59:59Z"

objectOptional

Per-form theme tweaks layered on top of your team's default theme. Omit or set to null to use team defaults.

Response Body

`application/json`

Pinnacle client libraries

import { PinnacleClient } from "rcs-js";

const client = new PinnacleClient({
  apiKey: process.env.PINNACLE_API_KEY!,
});

await client.forms.create({
    name: "Contact request",
    description: "We'll follow up over SMS or RCS.",
    fields: [{
            type: "text",
            key: "full_name",
            label: "Full name",
            required: true,
            placeholder: "Ada Lovelace",
            min_length: 2,
            max_length: 60
        }, {
            type: "email",
            key: "email",
            label: "Email",
            required: true,
            placeholder: "you@example.com"
        }, {
            type: "phone",
            key: "phone",
            label: "Phone",
            required: true,
            placeholder: "(555) 555-1212"
        }, {
            type: "select",
            key: "plan",
            label: "Plan",
            required: true,
            options: [{
                    value: "basic",
                    label: "Basic"
                }, {
                    value: "pro",
                    label: "Pro"
                }, {
                    value: "enterprise",
                    label: "Enterprise"
                }]
        }],
    can_update: false
});

Responses

{  "id": "form_abc123",  "url": "https://forms.pinnacle.sh/form_abc123",  "name": "Contact request",  "description": null,  "fields": [    {      "key": "full_name",      "type": "text",      "label": "Full name",      "required": true,      "min_length": 2    },    {      "key": "email",      "type": "email",      "label": "Email",      "required": true    }  ],  "can_update": false,  "expires_at": null,  "theme_override": null,  "submission_count": 0,  "last_submitted_at": null,  "archived_at": null,  "created_at": "2026-04-24T00:00:00Z",  "updated_at": "2026-04-24T00:00:00Z"}

Create Form

Request body

Authorization

Request Body

Response Body

`application/json`

`application/json`

`application/json`

`application/json`

Try asking

Create Form

AuthorizationCopy Anchor Link

Request BodyCopy Anchor Link

Response BodyCopy Anchor Link

200application/json

400application/json

401application/json

500application/json

Authorization

Request Body

Response Body

`application/json`

`application/json`

`application/json`

`application/json`