Send Form | Pinnacle | Documentation

import { PinnacleClient } from "rcs-js";
async function main() {
    const client = new PinnacleClient({
        apiKey: "YOUR_API_KEY_HERE",
    });
    await client.forms.send({
        from: "agent_iM9wQcyBBjYn",
        to: "+14155551234",
        form: "form_Oy2n7iUoi9CJwUU6",
        fallback: {
            from: "+14155550000",
        },
        options: {
            webviewMode: "FULL",
        },
    });
}
main();

{
  "form": {
    "id": "form_abc123",
    "url": "https://forms.pinnacle.sh/form_abc123",
    "name": "Contact request",
    "description": null,
    "fields": [
      {
        "key": "full_name",
        "label": "Full name",
        "required": true,
        "type": "text"
      }
    ],
    "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"
  },
  "submission": {
    "id": "fsub_xyz789",
    "url": "https://forms.pinnacle.sh/fsub_xyz789",
    "form_id": "form_abc123",
    "from": "agent_iM9wQcyBBjYn",
    "to": "+14155551234",
    "data": null,
    "ip_address": null,
    "user_agent": null,
    "submitted_at": null,
    "created_at": "2026-04-24T00:00:00Z"
  },
  "message_id": "msg_123"
}

Send a form to a recipient over SMS or RCS, or mint a standalone submission URL.

Pass form as either an existing form id (form_*) or an inline { fields, ... } definition to mint a new form for this send.

The delivery channel is inferred from from:

from: "agent_*" → RCS (with optional SMS fallback)
from: "+E.164" → SMS

When to is provided, Pinnacle dispatches a message whose body contains the submission URL and the recipient is recorded on the response: submission.to echoes the same E.164 number and message_id is the id of the outbound SMS/RCS.

When to is omitted, no message is sent — submission.to and message_id are both null — which is useful for embedding the URL in your own outreach.

On completion, a FORM.SUBMISSION webhook event is delivered to webhooks subscribed to the sender. See Receiving Messages and User Events.

Authentication

PINNACLE-API-KEYstring

API Key authentication via header

Request

This endpoint expects an object.

Send via RCSobjectRequired

Send a form from an RCS agent. from must be an agent_* id.

Send via SMSobjectRequired

Send a form from a phone number. from must be an E.164 phone.

Response

Form sent (or URL minted when to is omitted).

SendFormResponseobject

Successful POST /forms/send response.

When to was provided in the request, the message was dispatched: submission.to echoes that recipient and message_id is the id of the outbound SMS/RCS that carried the URL.
When to was omitted, no message was sent: both submission.to and message_id are null and only the submission URL is returned.

ScheduledFormSendResponseobject

Response shape for a scheduled form send — returned in place of SendFormResponse when options.schedule is set.

Errors

400

Bad Request Error

401

Unauthorized Error

404

Not Found Error

500

Internal Server Error