Create Hosted Session

POST/hosted-sessions

Creates a hosted session: an authenticated, time-limited, single-use URL for a Sail-rendered UI flow. Three flows are supported. connect_account is the sole way to establish Sail-managed connections (card, store, benefit_account). reconnect re-authenticates a Sail-managed connection when credentials go stale. upload_receipt lets users submit itemized receipts (optionally against a specific needs_review expense). Experiences beyond these flows belong in your own UI, built on the API.

Body application/json

user_idstringrequired

The Sail user this session is for.

flow"connect_account" | "reconnect" | "upload_receipt"required

Which hosted UI flow to render.

optionsobject

Flow-specific options:

connect_account requires connection_type (card, store, or benefit_account); accepts modal.
reconnect requires connection_id (a Sail-managed connection; external connections have no credentials and return 409 connection_not_reconnectable).
upload_receipt accepts an optional expense_id to attach the receipt to a specific needs_review expense.

Show options properties

connection_type"card" | "store" | "benefit_account"

Required for connect_account.

merchant_idstring

For connect_account with connection_type: store. Skips merchant selection and goes directly to the login screen for this merchant.

administrator_idstring

For connect_account with connection_type: benefit_account. Skips administrator selection and goes directly to the login screen for this administrator.

connection_idstring

Required for reconnect. The existing connection to re-authenticate.

modalboolean

For connect_account and reconnect. Renders as an overlay when true.

expense_idstring

For upload_receipt. Attaches the uploaded receipt to this expense and triggers re-adjudication.

Response

URL generated.

urlstring<uri>

The single-use hosted session URL to embed or redirect the user to.

expires_atstring<date-time>

When the URL expires and can no longer be opened.

flowstring

The flow this session was created for.

Standard error envelope covering 400, 401, 403, 404, 429, and 500.

errorobject

The error detail.

Show error properties

codestring

Machine-readable code, e.g. not_found, token_scope_mismatch, product_not_enabled, insufficient_key_scope, insufficient_token_scope, user_token_required, user_token_expired, invalid_user_token, invalid_key_configuration, connection_not_reconnectable, rate_limited.

messagestring

Human-readable error message. May change, so match on error.code instead.

paramstring

The request field that caused the error, when applicable. Null otherwise.

curl -X POST "https://live.savewithsail.com/api/v1/hosted-sessions" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer <token>" \ -d '{ "user_id": "string", "flow": "connect_account", "options": { "connection_type": "card", "merchant_id": "string", "administrator_id": "string", "connection_id": "string", "modal": true, "expense_id": "string" } }'

const response = await fetch(`https://live.savewithsail.com/api/v1/hosted-sessions`, { method: 'POST', headers: { 'Content-Type': 'application/json', 'Authorization': 'Bearer <token>' }, body: JSON.stringify({ "user_id": "string", "flow": "connect_account", "options": { "connection_type": "card", "merchant_id": "string", "administrator_id": "string", "connection_id": "string", "modal": true, "expense_id": "string" } }) }); const data = await response.json();

import requests response = requests.request( "POST", "https://live.savewithsail.com/api/v1/hosted-sessions", headers={ "Authorization": "Bearer <token>" }, json={ "user_id": "string", "flow": "connect_account", "options": { "connection_type": "card", "merchant_id": "string", "administrator_id": "string", "connection_id": "string", "modal": True, "expense_id": "string" } }, ) data = response.json()

<?php $ch = curl_init(); curl_setopt($ch, CURLOPT_URL, "https://live.savewithsail.com/api/v1/hosted-sessions"); curl_setopt($ch, CURLOPT_RETURNTRANSFER, true); curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "POST"); curl_setopt($ch, CURLOPT_HTTPHEADER, ["Content-Type: application/json", "Authorization: Bearer <token>"]); curl_setopt($ch, CURLOPT_POSTFIELDS, '{ "user_id": "string", "flow": "connect_account", "options": { "connection_type": "card", "merchant_id": "string", "administrator_id": "string", "connection_id": "string", "modal": true, "expense_id": "string" } }'); $response = curl_exec($ch); curl_close($ch);

package main import ( "fmt" "io" "net/http" "strings" ) func main() { req, _ := http.NewRequest("POST", "https://live.savewithsail.com/api/v1/hosted-sessions", strings.NewReader(`{ "user_id": "string", "flow": "connect_account", "options": { "connection_type": "card", "merchant_id": "string", "administrator_id": "string", "connection_id": "string", "modal": true, "expense_id": "string" } }`)) req.Header.Set("Content-Type", "application/json") req.Header.Set("Authorization", "Bearer <token>") resp, err := http.DefaultClient.Do(req) if err != nil { panic(err) } defer resp.Body.Close() data, _ := io.ReadAll(resp.Body) fmt.Println(string(data)) }

HttpClient client = HttpClient.newHttpClient(); HttpRequest request = HttpRequest.newBuilder() .uri(URI.create("https://live.savewithsail.com/api/v1/hosted-sessions")) .header("Content-Type", "application/json") .header("Authorization", "Bearer <token>") .method("POST", HttpRequest.BodyPublishers.ofString("{\n \"user_id\": \"string\",\n \"flow\": \"connect_account\",\n \"options\": {\n \"connection_type\": \"card\",\n \"merchant_id\": \"string\",\n \"administrator_id\": \"string\",\n \"connection_id\": \"string\",\n \"modal\": true,\n \"expense_id\": \"string\"\n }\n}")) .build(); HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString()); System.out.println(response.body());

require "net/http" require "uri" uri = URI("https://live.savewithsail.com/api/v1/hosted-sessions") http = Net::HTTP.new(uri.host, uri.port) http.use_ssl = uri.scheme == "https" request = Net::HTTP::Post.new(uri) request["Content-Type"] = "application/json" request["Authorization"] = "Bearer <token>" request.body = "{\n \"user_id\": \"string\",\n \"flow\": \"connect_account\",\n \"options\": {\n \"connection_type\": \"card\",\n \"merchant_id\": \"string\",\n \"administrator_id\": \"string\",\n \"connection_id\": \"string\",\n \"modal\": true,\n \"expense_id\": \"string\"\n }\n}" response = http.request(request) puts response.body