Send Form | Pinnacle | Documentation

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.

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](/guides/messages/receiving).

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

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 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.

1	import { PinnacleClient } from "rcs-js";
2
3	async function main() {
4	const client = new PinnacleClient({
5	apiKey: "YOUR_API_KEY_HERE",
6	});
7	await client.forms.send({
8	from: "agent_iM9wQcyBBjYn",
9	to: "+14155551234",
10	form: "form_Oy2n7iUoi9CJwUU6",
11	fallback: {
12	from: "+14155550000",
13	},
14	options: {
15	webviewMode: "FULL",
16	},
17	});
18	}
19	main();

1	{
2	"form": {
3	"id": "form_abc123",
4	"url": "https://forms.pinnacle.sh/form_abc123",
5	"name": "Contact request",
6	"description": null,
7	"fields": [
8	{
9	"key": "full_name",
10	"label": "Full name",
11	"required": true,
12	"type": "text"
13	}
14	],
15	"can_update": false,
16	"expires_at": null,
17	"theme_override": null,
18	"submission_count": 0,
19	"last_submitted_at": null,
20	"archived_at": null,
21	"created_at": "2026-04-24T00:00:00Z",
22	"updated_at": "2026-04-24T00:00:00Z"
23	},
24	"submission": {
25	"id": "fsub_xyz789",
26	"url": "https://forms.pinnacle.sh/fsub_xyz789",
27	"form_id": "form_abc123",
28	"from": "agent_iM9wQcyBBjYn",
29	"to": "+14155551234",
30	"data": null,
31	"ip_address": null,
32	"user_agent": null,
33	"submitted_at": null,
34	"created_at": "2026-04-24T00:00:00Z"
35	},
36	"message_id": "msg_123"
37	}