Skip to main content
POST
Start a trial
  • Credential: an API key. A trial key returns 401 unauthorized.
  • Line-scoped keys: the list of lines of a line-scoped key is not applied.
  • Test keys: an isnap_test_ account key starts a real trial: see Test keys.
  • Idempotency-Key: not honored. For a wholesale partner, a repeated call starts another trial. A direct account receives 409 trial_already_active, a repeat of a call whose response was lost included. See How a trial works.
  • Events: none. trial.linked is sent later, when the prospect pairs: see Events.
  • Secret: token is the pairing code. The response carries Cache-Control: no-store, whatever its status. See How a trial works.
  • Limit: a direct account has one live trial at a time: see Limits on live trials.

Errors

The errors that every operation shares are in Errors.

Authorizations

Authorization
string
header
required

An API key created in the iSnap dashboard, or a trial key, sent as Authorization: Bearer <key>. An API key starts with isnap_live_ or isnap_test_; both act on the same account, lines and billing. A trial key acts on its trial only.

Body

application/json

Options of a trial. Every field is optional.

max_outbound_without_inbound
integer

Number of messages the trial key can send in a row without a reply, a reaction or a read receipt from the prospect. When the trial runs on an iMessage line, a read does not count: only a reply or a reaction does. From 1 to 100. Default: 10. The send that reaches this number succeeds and makes the trial dormant.

Required range: 1 <= x <= 100
Example:

10

welcome_message
string

Text of the confirmation message that the prospect receives once, when pairing succeeds. From 1 to 280 characters. Default: a confirmation text written by iSnap. The message is not retried when its delivery fails, and it does not count as a send of the trial.

Required string length: 1 - 280
Example:

"You are connected to Acme. Reply here at any time."

Text appended, after a blank line, to every message the trial key sends, in place of the footer of iSnap. From 1 to 300 characters. Default: Sent for free with iSnap - isnap.ai. A footer cannot be turned off. Characters outside GSM-7 make each SMS segment shorter.

Required string length: 1 - 300
Example:

"Sent free via Acme"

metadata
object

Your own key-value data. iSnap stores it as sent and does not interpret it. Events about this resource carry it in data.metadata. At most 20 keys and 8,192 bytes once serialized as JSON.

Example:

Response

The trial, waiting for the prospect to send the pairing code.

success
enum<boolean>
required

Always true on a success response.

Available options:
true
data
object
required

A trial that was just started.

trace_id
string
required

Trace id of the request that produced this response: 32 lowercase hexadecimal characters. Quote it when you report a problem to iSnap.

request_id
string
required

Id of the request that produced this response: req_ followed by 25 letters or digits.