Create a User

Every piece of data in Sail is scoped to a user. Before you can create connections, fetch expenses, or access account information, you need a Sail user for each of your end users.

Requirements

Before you create a user, make sure you have the following:

An API key with any scope (user endpoints don't need a specific scope)

Create the user

Send a POST request to the Create User endpoint with your end user's ID in your system, as external_user_id. This is the only required field. The optional fields are most useful if you plan to access personal information through the Identity endpoint later.

curl -X POST https://live.savewithsail.com/api/v1/users \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "external_user_id": "your-user-123"
  }'

Save the id from the response. You need it for all subsequent API calls for this user.

You can also pass optional contact fields (email, first_name, last_name, phone, address) when creating a user. See request fields below for the full list.

📘
For a backfill or a nightly sync, use Create Users in Bulk instead of looping this endpoint. It takes up to 500 users per request, each element identical in shape to the body above, and resolves the whole batch in one round trip.
Partial success is intentional: a duplicate external_user_id or email rejects only that element, and the rest of the batch is still created. The response is always 200, so check the failed count and the failures array rather than the status code.

The response

The User object only contains ids, status, and timestamps. Any contact information you send at creation is stored by Sail but never returned in the User object.

The response is the same regardless of which optional fields you include.

📘
To read back the contact data you sent at creation, call Get Originated Identity. This endpoint needs the identity key scope and an ephemeral user token.

Next steps

To complete your setup, see Set up webhooks.