Quickstart

From credentials to your first file

This walks the whole loop — get a token, connect to an elder, send a file — against the sandbox, so you can run every command below without touching anyone's real records.

1. Get a token

Exchange your client ID and secret for a short-lived bearer token using the OAuth2 client-credentials grant.

curl https://api.elderella.com/oauth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d grant_type=client_credentials \
  -d client_id=$ELDERELLA_CLIENT_ID \
  -d client_secret=$ELDERELLA_CLIENT_SECRET

{
  "access_token": "eyJhbGciOi...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "connections:write files:write"
}

Use the access_token as a bearer on every /v1 call. Tokens are short-lived — request a new one when it expires rather than storing it for long. Full detail in the authentication guide.

2. Request a connection to the elder

The family gives you their elder's Elderella address. In the sandbox, that address is always sandbox.test.elder@care.elderella.com. Request a connection to it.

curl https://api.elderella.com/v1/connections \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "elder": "sandbox.test.elder@care.elderella.com" }'

{ "id": "con_9fH2k...", "status": "pending" }

You always get back pending — for any well-formed address, whether or not it resolves to a real elder. That's deliberate: the API never confirms who exists. Hold onto the con_… id.

3. Wait for approval

A primary caregiver approves the connection inside Elderella. In the sandbox there's no human — test connections auto-approve after about 30 seconds. Poll until the status flips to approved:

curl https://api.elderella.com/v1/connections/con_9fH2k... \
  -H "Authorization: Bearer $TOKEN"

{ "id": "con_9fH2k...", "status": "approved" }

In production you don't have to poll — register a webhook and we'll send you a connection.approved event instead. See connections & webhooks.

4. Send a file

Now that the connection is approved, send a file for that elder as a multipart upload. Point elder at the same address, attach the file, and add an optional purpose hint.

curl https://api.elderella.com/v1/files \
  -H "Authorization: Bearer $TOKEN" \
  -H "Idempotency-Key: fill-2026-07-28-rx4821" \
  -F elder=sandbox.test.elder@care.elderella.com \
  -F purpose="pharmacy fill" \
  -F file=@./discharge-summary.pdf

{ "id": "file_3Qm7p...", "status": "received" }

Send an Idempotency-Key so a retry never creates a duplicate — the same key with the same bytes returns the same receipt. More in the idempotency guide.

5. Check the file's status

Poll the file to watch it move from received to processed. (Sandbox files progress like real ones but never actually run extraction.)

curl https://api.elderella.com/v1/files/file_3Qm7p... \
  -H "Authorization: Bearer $TOKEN"

{ "id": "file_3Qm7p...", "status": "processed" }

That's the whole loop

Token → connection → approval → file → status. When you're ready to go live, swap your test credential for a live one and use a real elder's address — the calls are identical. A live token can never reach the sandbox, and a test token can never reach a real elder.

Explore the full reference Understand connections