Docs
OverviewPlatformPlatform APIA2P Messaging API
AI & MCP
Open dashboard
OverviewPlatformPlatform APIA2P Messaging API
AI & MCP
  • Overview
  • Introduction
  • Create an account
  • Choose your API
  • Authentication
  • AI & MCP
Product API
  • Guide
  • Quickstart
    • API tokens
    • Connected apps (OAuth)
    • Project readiness
    • Channel readiness
    • Senders
    • Attention
    • Recommendations
    • Overview
    • Contacts and attributes
    • Events
    • Query filter
    • Event query filter
    • Probes
    • Counting and retrieval
    • Segments
    • Overview
    • Creating a draft
    • Audience targeting
    • Message content
    • Dates and scheduling
    • Reading campaigns
    • Estimating and deleting
    • OverviewBeta
    • Templates
    • Creating and editing drafts
    • Triggers and exits
    • Nodes
    • Delays and waits
    • Overview
    • Statistics catalog
    • Building queries
    • Conversions & revenue
    • Reading results
    • Flow reports
    • Rate limits
    • Errors
  • Full API Reference
Ingest API
  • Guide
  • Quickstart
  • Authentication
  • Rate limits
  • Errors
  • Best practices
  • Full API Reference
Further reading
  • Query Filter
DashboardSupportinstasent.com

Platform API · Product API · Flows

Flow templates

GET /flow/templates returns the ready-made flows worth offering a project, scored against the events it really receives. This page covers relevance and scoring, the trigger's source, the values a template asks for, the SMS and RCS modes, the language of the messages, the integration filter, sources that deliver in batches and how they lengthen the first wait, reading one template built on a chosen source, the two ways to create a flow from a template, and how the senders are chosen.

On this page▾
  • Query parameters
  • The response
  • Relevance
  • The trigger's source
  • Sources that deliver in batches
  • One template on a chosen source
  • Scoring and order
  • Values the template asks for
  • SMS or RCS with SMS fallback
  • Message language
  • What the payload already carries
  • Creating a flow from a template
  • Let the server build the draft
  • Send your own graph
  • Choosing the senders
  • Responses and errors
  • What would an integration unlock
  • Errors
  • What's next

Writing a flow graph from nothing is the slowest and most error-prone way to build one. The template list is the shortcut: a catalogue of ready-made journeys (an abandoned-checkout reminder, a welcome, a winback and others), each scored for this particular project against the events it actually receives, and each carrying a complete graph with the trigger event, its source, the senders and the values the project already knows filled in.

The intended path is to pick the closest template, supply the values only the customer knows, and let the server build the draft. When you need to change the graph itself, take the item's payload, change only what you need, and create the flow from it.

The dashboard shows the same list as its template gallery, with the same recommendations; how customers use it is described in Flow templates.

GET/v1/project/{project}/flow/templates

List the flow templates worth offering this project.

The endpoint takes the PROJECT_AUTOMATION_READ scope and sits in the medium rate-limit class.

Query parameters

langstringdefault: en

en or es. The language of each template's title and description. It does not change the language of the messages, which follow the project's own language (see Message language).

channelstringdefault: sms

sms or rcs: the mode every payload is built in. See SMS or RCS with SMS fallback.

integrationstring

An integration key, such as shopify. Keeps only the templates that integration can feed, scored as if it were connected. See What would an integration unlock.

keystring

A template's key, together with datasourceId: the response then holds only that template, built on that source. See One template on a chosen source.

datasourceIdstring

With key, and only with it: the source to build that template on, one POST /flow accepts as datasourceId for it.

The response

{
  "entities": [
    {
      "key": "abandoned-checkout",
      "title": "Abandoned checkout",
      "description": "Reminds shoppers who started a checkout and did not buy within an hour, and a day later tells them their order is still saved. Stops as soon as they order.",
      "categories": ["ecommerce", "checkout_abandoned"],
      "icon": "shopping-cart",
      "recommended": true,
      "integrations": [
        { "integration": "shopify", "name": "Shopify", "connected": true, "datasourceId": "66c3a1b2e5a6b7c8d9e0f1a2", "eventType": "ecommerce_checkout_init" }
      ],
      "channels": ["sms", "rcs"],
      "channel": "sms",
      "variants": ["sms", "rcs"],
      "triggerKind": "event",
      "relevance": "received",
      "trigger": {
        "eventType": "ecommerce_checkout_init",
        "datasourceId": "66c3a1b2e5a6b7c8d9e0f1a2",
        "datasource": { "id": "66c3a1b2e5a6b7c8d9e0f1a2", "name": "My Shop", "type": "integration", "integration": "shopify" },
        "candidates": ["ecommerce_checkout_init", "ecommerce_checkout_abandon"],
        "candidateStates": [
          { "eventType": "ecommerce_checkout_init", "state": "received", "datasourceId": "66c3a1b2e5a6b7c8d9e0f1a2", "lastSeenAt": "2026-09-25T08:41:12+00:00" },
          { "eventType": "ecommerce_checkout_abandon", "state": "unavailable", "datasourceId": null, "lastSeenAt": null }
        ],
        "lastSeenAt": "2026-09-25T08:41:12+00:00",
        "sourceOptions": [
          { "datasourceId": "66c3a1b2e5a6b7c8d9e0f1a2", "name": "My Shop", "type": "integration", "integration": "shopify", "eventType": "ecommerce_checkout_init", "state": "received", "count": 412, "lastSeenAt": "2026-09-25T08:41:12+00:00", "recommended": true }
        ]
      },
      "score": 60,
      "scoring": [
        { "signal": "relevance", "delta": 40, "text": "My Shop sent 412 ecommerce_checkout_init events in the last 30 days" },
        { "signal": "business", "delta": 20, "text": "Suited to ecommerce businesses" }
      ],
      "used": false,
      "guidance": "...",
      "audience": { "segment": null, "name": null, "resolved": "all", "intent": null },
      "inputs": [],
      "pending": [],
      "payload": { "trigger": { "stepClass": "TRIGGER_CONTACT_EVENT", "eventType": "ecommerce_checkout_init", "...": "..." } }
    }
  ],
  "window": { "days": 30 }
}
keystring

The template's stable identifier. Pass it as template when you create a flow from it.

titlestring

The template's name, in the lang you asked for.

descriptionstring

What the journey does, in the lang you asked for.

categoriesstring[]

Free tags for grouping templates in a gallery.

iconstring

A Lucide icon name in kebab-case, fixed per template.

requiresstring[]

What the template needs from its trigger source; empty when nothing. Today the only value is realtimeEvents: the trigger and the exits have to arrive as they happen. See Sources that deliver in batches.

recommendedboolean

true on at most three templates: the best-scored ones whose trigger event was received and that have not been used yet. The same set the project's recommendations surface.

integrationsobject[]

The integrations that can send one of the trigger's candidate events, connected first, then by name. Empty for templates triggered by Instasent's own events, which no single integration unlocks.

integrationstring

The integration's key, as integration takes it.

namestring

Its display name.

connectedboolean

Whether the project has connected it.

datasourceIdstring

On a connected integration, the project's source of that integration the trigger would listen to if the person chooses this integration, even when it has not sent the event yet. Accepted as datasourceId when you create the flow. null when the integration is not connected or no candidate event resolves on it.

eventTypestring

The trigger event a draft built on that datasourceId listens to. null exactly when datasourceId is.

deliveryobject

How the integration delivers its events: mode and syncIntervalSeconds. See Sources that deliver in batches.

timingWarningobject

Set when the template requires realtime events and the integration delivers in batches: syncIntervalSeconds and addedWaitSeconds, what building the template on it adds to the first wait. null otherwise.

channelsstring[]

The send modes this project can use: sms, plus rcs when the project has an active RCS sender.

channelstring

The mode payload was built in, which is the channel you asked for.

variantsstring[]

The channels the template is written for: ["sms"], or ["sms", "rcs"] when it carries its own RCS journey. Distinct from channels, which says what this project can use. See SMS or RCS with SMS fallback.

triggerKindstring

What starts the flow: event, an event a contact produces. Every template listed today is event.

relevancestring

received, available or unavailable. See Relevance.

triggerobject

The trigger the template resolved to for this project.

eventTypestring

The event type the payload triggers on.

datasourceIdstring

The data source the payload's trigger listens to. Templates pin every trigger to one source, Instasent's own events included (see The trigger's source). null only when no source of the project sends or declares the event.

datasourceobject

datasourceId named: id, name, type, integration, delivery and timingWarning. null exactly when datasourceId is. It also names a default source that is not one of sourceOptions, such as an integration that declares the event and has not sent it yet.

candidatesstring[]

The event types the template can trigger on, in order of preference.

candidateStatesobject[]

Each of candidates, in the same order, resolved on the project's sources: eventType, state (received, available or unavailable), datasourceId and lastSeenAt.

lastSeenAtstring

The last time the trigger event arrived inside window, whatever relevance says. On an unavailable template a value means the event did arrive, but more than 30 days ago, from a source that does not declare it.

sourceOptionsobject[]

The sources the trigger can be pointed at, the recommended one first. See The trigger's source.

datasourcesobject[]

The sources that sent the trigger event, best first.

scoreinteger

The template's score for this project. Only templates scoring above zero are listed.

scoringobject[]

One entry per reason behind the score: signal, delta (points added or removed) and text, an English sentence built from the facts above.

usedboolean

true while a flow created from this template exists and is not archived.

guidancestring

In English, up to 600 characters, written for agents: why the flow is shaped as it is, what must stay (an exit, a consent policy, a wait) and what customers usually personalize. It describes the graph served in channel.

audienceobject

Who the trigger lets in. resolved is segment when the trigger is limited to a recommended segment the project has (segment is its uid, name its name), and all when it lets in every contact with a mobile phone. intent, when set, describes in English the audience the template is meant for, as a hint for narrowing it.

inputsobject[]

The values only the customer knows that this channel's messages need, each with key, kind, required and default (the value already filled for this project, or null). See Values the template asks for.

pendingstring[]

The input keys still without a value, written as $input:<key> in payload. A draft saved with any of them is not valid until it is filled.

payloadobject

The flow graph the server builds for this item, in the shape described in Nodes. You only send it yourself when you change the graph; see Creating a flow from a template.

window.days is the window the event counts behind relevance and scoring cover. It is the default window of the event volumes probe for this project: wider on small audiences, narrower on large ones, and clamped by the plan.

Relevance

Relevance answers the question that decides whether a flow will ever fire: does the event it triggers on actually arrive in this project?

relevanceWhat it meansWhat to do
receivedA source that can trigger flows sent the trigger event in the last 30 days.The flow fires today. The natural candidate to offer.
availableIt did not arrive in that time, but a connected integration declares that it sends it.The flow is buildable; it will fire once the events start arriving.
unavailableNo connected integration declares the event and it did not arrive in the last 30 days, or the event cannot trigger flows.Connecting a source that sends it comes before building the flow.

On projects with 20,000 contacts or more the counts cover 15 days, so there received means "in the last 15 days".

Only connected integrations declare events in advance. A source fed through the API or a CSV file declares nothing, so a template whose event comes only from such a source is unavailable until the first event arrives, and then received.

Relevance is data first. The events a project really receives outweigh the business type it declared, so a project that sells online while describing itself otherwise still sees the ecommerce journeys, as long as its orders arrive.

When a template can trigger on more than one event (a review request can follow a delivery or, failing that, a shipment), the first candidate the project receives is the one the payload uses, and a scoring sentence says so. A trigger filter in the graph follows the event it was rewritten to. trigger.candidateStates shows how each candidate resolved.

The trigger's source

Every template flow listens to one source: the payload's trigger.eventDatasource is set, and so is trigger.datasourceId. This holds for Instasent's own events too, such as the welcome's update: the template pins them to a source like any other event. A flow that should listen to every source is a change you make to the draft: set eventDatasource to an explicit null, because a draft sent with template that leaves the key out gets the template's source back (see Send your own graph). See Triggers and exits.

The default source is picked in this order:

  • A source that sent the event recently beats one that sent it only earlier in the window, which beats one that only declares it.
  • Among equals, the shop that owns the orders comes first for commerce events, then the fresher and busier source.
  • Instasent's own internal source goes last, and wins only when no other source qualifies, so a welcome listens to one of the project's own sources rather than to the changes Instasent records itself.

The exits listen to the trigger's source. When that source never sends an exit event that another source does (a checkout tracked through the API, orders from the shop), the exit is left on every source, so the journey still stops when the order arrives.

trigger.sourceOptions lists the sources the person may choose instead, each with datasourceId, name, type, integration, eventType (the candidate the flow starts on with that source, which can differ between sources), state, count, lastSeenAt, recommended, and delivery and timingWarning (see Sources that deliver in batches):

  • Only sources that sent a candidate event are options. An integration that only declares the event is never one, since nothing proves the event will come from it.
  • state is received (sent it in the last 30 days) or stale (sent it earlier in the window, lastSeenAt says when).
  • At most one option is recommended, the first: the one the server uses when you create the flow without datasourceId. None is flagged when the default source is not an option, for example an integration that declares the event and has not sent it yet; trigger.datasource names it then.
  • The list is empty when no source sent a candidate event.

Sources that deliver in batches

Most sources hand over each event as it happens: webhooks, the Ingest API, the API and Instasent's own events. A few integrations are different. The platform imports their events with a periodic sync, so an event can reach the project up to one sync interval after it happened. For most journeys that delay does not matter. For a journey that reacts within the hour and stops at a purchase, it does: if the reminder waits less than the interval, a purchase made in the meantime can arrive after the reminder was already sent.

The templates built for that kind of journey say so with requires: ["realtimeEvents"] (an abandoned checkout, for example). Each source the item offers carries two fields that tell you what happens if the flow listens to it:

deliveryobject

How the source delivers its events.

modestring

realtime, as they happen, or batch, pulled by the periodic integration sync.

syncIntervalSecondsinteger

Seconds between two syncs of a batch source, as they apply to this organization and its plan. On an integration that is not connected yet, the interval the plan would give it. null on a realtime source, and when the plan does not sync that source.

timingWarningobject

Set only when the template requires realtime events and the source delivers in batches; null otherwise.

syncIntervalSecondsinteger

The source's sync interval.

addedWaitSecondsinteger

What the server adds to the template's first wait when the flow is built on this source. 0 when the first wait already covers the interval.

The server does not leave the gap to you. When a template that requires realtime events is built on a batch source, its first wait is lengthened by about one sync interval: the interval, capped at 24 hours and rounded up to whole 15 minutes. This happens in both places a template is built:

  • in the item's payload, which is built on the default source, so when that source is a batch one, the payload already carries the longer wait;
  • in the draft POST /flow builds with template and no draft, on the datasourceId you send or on the default source.

How the first wait grows depends on its kind:

  • A fixed delay gets the whole margin. Every send after it shifts by the same amount, and an exit event that arrives with the next sync still finds the contact waiting.
  • A smart delay whose earliest send is already at the margin or later is left as it is. An earlier one has its window moved later, earliest and latest send together, so the earliest send lands at the margin.
  • A template that sends or branches before any wait is not changed, and addedWaitSeconds is 0.

In short: read requires to know whether timing matters for the template, delivery to know how a source sends its events, and timingWarning to know, per source, how much later the first message will go out. Show that to the person choosing the source: a checkout reminder that waits an hour on a realtime source can wait several hours on a batch one. When you send your own draft, its waits are yours and the server does not change them; a draft taken from the item's payload already includes the margin of the payload's source.

The margin is applied once, when the template's draft is built, and nowhere else. A graph you send yourself (template with your own draft) is never lengthened, even on a batch source. Neither is a draft you later replace with PUT /flow/{id}/draft: waits you edit, or a trigger eventDatasource you switch to a batch source, are your responsibility, so keep the waits before the first send longer than that source's syncIntervalSeconds. Flows that already exist keep their waits. At run time, fixed delays and exit events count from when the trigger event happened rather than when it arrived, so an exit event imported in the same batch as the trigger event still keeps the contact out; the customer-facing explanation is in Sources that import their events every so often.

One template on a chosen source

addedWaitSeconds tells you the size of the change, but the item's payload is always built on the default source. To see the graph a different source produces before creating the flow, ask for that template alone, built on that source:

curl "$BASE/flow/templates?key=abandoned-checkout&datasourceId=66c3a1b2e5a6b7c8d9e0f1a2&channel=sms" \
  -H "Authorization: Bearer $INSTASENT_TOKEN"
  • entities holds that one template, built exactly as POST /flow with template and the same datasourceId would build the draft, the lengthened first wait included in payload.
  • It is built even when it scores zero, and recommended is false: that flag only means something within the full list.
  • lang, channel and integration apply as on the list. Under an integration that cannot feed the template, entities is empty.
  • key without datasourceId, or the other way round, is a 400, and so is an unknown template or a source that POST /flow would refuse for it.

Scoring and order

score is the sum of the delta of every scoring entry. The signals include the trigger's relevance (a received event weighs most), extra sources that also send it, how well the template suits the project's business type, whether the trigger is the project's own sales conversion event, and whether a complementary or overlapping flow already exists. Each entry says in plain words what it measured, so the list can be shown to a person, or read by a model, as the reason a template is on offer.

Templates are ordered with used ones last, then by score. Treat the weights as the platform's judgement, not a contract: read scoring rather than recomputing it.

Values the template asks for

Some messages need a value only the customer knows: a discount code, a review link. The template declares them in inputs, and its messages carry each one as $input:<key>. An input with a default is already filled in payload; the others stay as $input:<key> and are listed in pending.

kindWhat it isAccepted value
discountCodeA code the shopper types at checkout.One line, up to 40 characters.
discountPercentWhat the code takes off.A whole number from 1 to 99, without the % sign, which the message writes.
reviewUrlThe page where the customer leaves a review.A full http(s) URL, up to 2,048 characters.
storeUrlThe store's website. Defaults to the brand's website.A full http(s) URL, up to 2,048 characters.

Every kind refuses an empty value and one containing {{ or }}; the URL kinds also refuse a single { or }.

The inputs are listed per channel: an item only carries the inputs its channel's messages use. Second purchase offer (first-purchase-bounceback) asks for discountCode and discountPercent; Ask for a review asks for reviewUrl; the templates whose message links the store, such as Win back customers, carry storeUrl, already filled with the brand's website. Abandoned checkout asks for nothing in SMS mode, and in RCS mode for storeUrl, which its buttons open.

Pass the values as inputs when you create the flow, whether the server builds the draft or you send your own. A value you leave out is never an error: the flow is created with valid: false and a pending-input error on the send that needs it, which the person can fill in the dashboard. See Creating a flow from a template.

SMS or RCS with SMS fallback

channel=rcs builds every send in the payload as RCS, with an SMS for contacts RCS cannot reach as its fallback. The consent policy is the same on both levels. There is no RCS-only mode. What the RCS message holds depends on the template:

  • A template with an RCS variant (variants includes rcs) is served as written for RCS: its own messages, which may be rich, each with its SMS as fallback. Abandoned checkout is one: each of its two messages is a card with a title and a description and a button that opens the contact's own checkout link, or the store website (the storeUrl input) when the contact has none. Its SMS fallback carries the link in the text.
  • A template without one turns every send into a plain-text RCS message with the same SMS, unchanged, as its fallback.

Two rules hold either way:

  • rcs is accepted only when the template's channels lists it, which means the project has an active RCS sender; otherwise the request is a 400.
  • The API default is sms. The dashboard gallery opens on RCS when the project can use it, but the person still sees the mode and can switch it. RCS messages are billed as RCS, so offer it as an option to the person who will publish the flow rather than switching to it on their behalf.

Message language

The messages in payload are written in the project's language: Spanish for a Spanish project, English otherwise. lang only translates title and description.

When the organization's plan allows multi-language messages, every send in the payload also carries the other language as a translation, in the option's localizations. At send time each contact receives the translation matching their language, and anyone else receives the default text. See Translations.

What the payload already carries

A template payload comes filled the way the platform recommends:

  • The senders. Each send carries a sender per channel, on every level: the message, its translations and, on RCS, the SMS fallback. For each channel it is the project's default sender when that sender is active, or the only active sender when there is just one. With several active senders and none set as default, the sender is left empty so the person chooses, unless you name one per channel as senders when you create the flow. An RCS sender counts only when it is accepted in at least one country.
  • The trigger's source, and the exits on the same source (see The trigger's source).
  • The values the project already knows, such as the store website; the rest are in pending.
  • The audience: contacts with a mobile phone, so nobody enters a journey that can never send, narrowed to a recommended segment when the template has one and the project has that segment.
  • Every marketing send waits in a smart delay that avoids illegal hours, and every send declares its consent policy.
  • A contact is never inside two runs of the same flow at once, and journeys that should happen once (a welcome) or not too often (a checkout reminder) carry their own re-entry limits.

What can still be missing is a pending input or a sender that could not be chosen. Either way the flow is saved with valid: false and an error on the send, and it can be completed through the API or in the dashboard. See The send.

Creating a flow from a template

There are two ways to create the flow, and both take PROJECT_AUTOMATION_WRITE: let the server build the draft from the template, or send your own graph together with the template's key. Either way the server sets what a template always sets (the senders and the trigger's source) wherever the draft has none, and the response lists each value it set in filled.

Let the server build the draft

Send the template's key as template and no draft. The server builds the draft exactly as the item's payload, in the channel you ask for, with your inputs filled in.

  1. 1

    List the templates

    Call GET /flow/templates and pick the item to use: typically a recommended one, or the one the user asked for by name. Read its inputs and pending.

  2. 2

    Collect the values

    Ask the user for each pending input. If they do not have one yet, leave it out: the flow is still created, and the person fills it later.

  3. 3

    Create the flow

    Send name, template and the values. The flow records where it came from and the template is marked used.

curl -X POST "$BASE/flow" \
  -H "Authorization: Bearer $INSTASENT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Second purchase offer",
    "template": "first-purchase-bounceback",
    "channel": "sms",
    "inputs": { "discountCode": "WELCOME10", "discountPercent": "10" }
  }'
templatestringrequired

The item's key. Any template in the catalogue can be built, scored or not.

inputsobject

Input key to value, for the keys the item lists in inputs. A value replaces the input's default; a key left out, or null, keeps it. Whatever stays without a value is pending.

sendersobject

{ "sms": "<id>", "rcs": "<id>" }, both optional: the sender every send of that channel takes, instead of the one the project would give it. Use it when the project has several active senders and none is the default, or when the user names one. Take the ids from GET /channel/sms/sender and GET /channel/rcs/sender. See Choosing the senders.

channelstringdefault: sms

sms or rcs, as on the list. A mode the project does not offer is a 400.

langstringdefault: en

en or es: the language of the built draft's name and description, as lang on the list. The messages follow the project's language.

datasourceIdstring

The source the trigger listens to: one of trigger.sourceOptions[].datasourceId, the default trigger.datasourceId, or the datasourceId of a connected entry in integrations. Leave it out and the server uses the recommended source. On a source whose timingWarning is set, the draft's first wait is longer by its addedWaitSeconds (see Sources that deliver in batches).

name, description and tags work as on any flow creation; the flow is named after the name you send.

Send your own graph

When you need to change the graph, take the item's payload, change only what the user asked for, and send it as draft together with template. The draft stays yours: the server never replaces a value you set, and only completes the parts a template draft always carries.

  • inputs are substituted in the draft. Each value you pass replaces every $input:<key> of that key, at every level: the message, its translations, the RCS message, its buttons and its SMS fallback. The checks are the ones of the first way: a key the template does not declare, or a value its kind refuses, is a 422 under errors.fields['inputs.<key>']. A $input:<key> you pass no value for stays in the text, pending.
  • Sends without a sender get one. Every level of a send whose sender is absent or null (the option, each translation and, on RCS, the SMS fallback and its translations) takes the senders one for its channel, or else the project's, picked as described in What the payload already carries. A sender you set is kept.
  • A trigger without a source gets the template's. When the trigger leaves out the eventDatasource key and listens to one of the template's trigger.candidates, it gets the source the template would pin for that event (see The trigger's source). Each exit that leaves out the key and listens to one of the template's exit events gets a source too, resolved against the trigger's; an exit event that only another source sends is left on every source, as in the template payload. An explicit null is kept: that trigger listens to every source. A trigger on an event the template does not list is left as you sent it.

channel and datasourceId shape the draft the server builds, so with a draft they are a 400: write the mode and the source into the graph itself. lang is ignored.

curl -X POST "$BASE/flow" \
  -H "Authorization: Bearer $INSTASENT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Second purchase offer",
    "template": "first-purchase-bounceback",
    "inputs": { "discountCode": "WELCOME10", "discountPercent": "10" },
    "senders": { "sms": "67bdfa983114d0062d733795" },
    "draft": { "trigger": { "stepClass": "TRIGGER_CONTACT_EVENT", "eventType": "ecommerce_order_create" } }
  }'

The draft above is shortened: send the whole payload, with your changes.

Choosing the senders

A send needs a sender for each channel it uses, and on both ways the server fills the ones the draft leaves empty. For each channel it uses, in this order:

  1. The id you pass in senders for that channel.
  2. Otherwise, the project's default sender for that channel, when it is active.
  3. Otherwise, the only active sender of that channel, when the project has just one. An RCS sender counts only when it is accepted in at least one country.

With several active senders, no default and nothing in senders, the sender stays empty: the flow is created with valid: false and the send reports it, for the person to choose in the dashboard or for you to set in a replace.

Each id in senders must be an active sender of that channel in this project. Any other id (another organization's, an inactive one, a sender of the other channel) is a 422 under errors.fields['senders.<channel>'], and so is a channel other than sms and rcs; the server never falls back to the project's pick in its place. A null value names no sender for that channel. On a draft built in SMS mode, an rcs entry is checked but has no send to fill.

Responses and errors

Both ways answer like any flow creation: 201 Created with flowId, draftId, valid, errors, nodeErrors and warnings, plus filled, the JSON path of each value the server set, from the draft root:

{
  "entity": {
    "flowId": "66b1f2a4e5a6b7c8d9e0f1a2",
    "draftId": "66b1f2a4e5a6b7c8d9e0f1b7",
    "valid": true,
    "errors": [],
    "nodeErrors": [],
    "warnings": [],
    "filled": [
      "trigger.eventDatasource",
      "trigger.exitSteps[0].eventDatasource",
      "trigger.nextStep.nextStep.channel.options[0].sender",
      "trigger.nextStep.nextStep.channel.options[0].localizations[0].sender"
    ]
  }
}

Object keys are joined with dots and list positions go in brackets, so each path addresses the same value in the draft GET /flow/{id}/draft returns. filled names senders and sources only: substituted inputs are not in it. It is empty when the server set nothing, and on a flow created without template. Show it to the person who will publish: it is what the server chose on their behalf.

Outcomes worth a check:

  • A value is refused: 422, with errors.fields['inputs.<key>'] naming each input and the reason, for a key the template does not declare or a value its kind refuses (an empty one included). Nothing is created.
  • A sender is refused: 422, with errors.fields['senders.<channel>'], for an id that is not an active sender of that channel in this project. The message says where to copy a valid id from. The senders are checked before the inputs, so fix them first. Nothing is created.
  • A value is missing: never refused. The flow is created with valid: false, and the send that needs it reports The message still has a template value to fill in: <key> in nodeErrors.
  • A sender could not be chosen: never refused either. The flow is created with valid: false, and the send reports it in nodeErrors.
  • The request is malformed: 400, for an unknown template; inputs or senders that is not an object; a channel that is not a string or that the project does not offer; inputs, senders, channel or datasourceId sent without a template; channel or datasourceId sent with a draft; or a datasourceId that is empty or is none of the accepted ones.
{
  "errors": {
    "fields": {
      "inputs.reviewUrl": ["The value must be a full http(s) url"]
    }
  }
}

What would an integration unlock

integration=<key> answers "which journeys would connecting this integration make possible?". It keeps only the templates that integration can feed and scores them as if it were connected:

  • If the project has connected it, the templates score on its real data.
  • If it has not, the integration counts as a source that has sent nothing yet, so its templates come back available with no trigger.datasourceId, unless another source already sends the event. trigger.sourceOptions still lists only the project's real sources.

An unknown integration, or one that cannot trigger flows, is a 400. Take the keys from the integrations of the items.

Errors

StatusWhen
400channel is not one the project can use (rcs without an active RCS sender, or an unknown value); integration is unknown or cannot trigger flows; key and datasourceId are not sent together, the template is unknown, or the source is one POST /flow would refuse for it.
401, 403, 429, 5xxAs described in Errors.

What's next

Creating and editing drafts

Read, replace and validate the draft, and the errors each call returns.

Triggers and exits

Why the trigger points at one source, and how exits and goals work.

Last updated October 27, 2026

PreviousOverviewNextCreating and editing drafts
  • Query parameters
  • The response
  • Relevance
  • The trigger's source
  • Sources that deliver in batches
  • One template on a chosen source
  • Scoring and order
  • Values the template asks for
  • SMS or RCS with SMS fallback
  • Message language
  • What the payload already carries
  • Creating a flow from a template
  • Let the server build the draft
  • Send your own graph
  • Choosing the senders
  • Responses and errors
  • What would an integration unlock
  • Errors
  • What's next

© 2026 Instasent

Privacy PolicyTerms & ConditionsCookie PolicyLegal Notice
All systems operational