Quickstart

This guide signs in with an email code and reads one hour of transcript turns. You need curl and access to the email inbox for your Optima account.

Every request uses the REST base URL https://api.getoptima.com and the header X-API-Version: 1. There is no /user or /v1 URL prefix.

1. Request an email codeCopy Anchor Link

Ask Optima to send a six-digit code to your email address:

curl https://api.getoptima.com/auth/otp \
  -H 'X-API-Version: 1' \
  -H 'Content-Type: application/json' \
  -d '{"email":"you@example.com"}'

A successful request returns:

{ "success": true, "data": { "sent": true } }

2. Verify the codeCopy Anchor Link

Submit the code from your email. The 123456 below is a placeholder:

curl https://api.getoptima.com/auth/verify-otp \
  -H 'X-API-Version: 1' \
  -H 'Content-Type: application/json' \
  -d '{"email":"you@example.com","token":"123456"}'

The response data contains access_token, refresh_token, expires_at, and the account user. Store both tokens securely. Authentication explains the full session, refresh, and sign-out.

3. Read a time windowCopy Anchor Link

Request the turns that overlap an absolute time window. Replace YOUR_ACCESS_TOKEN with the access_token from step 2, and replace the timestamps with the window you want:

curl 'https://api.getoptima.com/turns?from=2026-09-24T10%3A00%3A00Z&to=2026-09-24T11%3A00%3A00Z' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'X-API-Version: 1'

The timestamps are URL-encoded, so : becomes %3A.

4. Read the responseCopy Anchor Link

The response wraps a page of results in data:

{
  "success": true,
  "data": {
    "items": [],
    "cursor": null
  }
}

Each item in items is a turn. A turn includes:

• content.text and its word timings
• the source_id of the recording source
• the persistent speaker_id, when Optima linked the turn to a detected voice
• its effective contact_id

An empty items array means no current turns overlap that window.

When cursor is not null, more results are available. Repeat the request with the same from, to, and filters, and add the returned value as the cursor query parameter to get the next page.

ContinueCopy Anchor Link

• Turns and contacts explains turn fields, filters, and attribution.
• API conventions covers errors and pagination rules.
• The API reference documents every route's request and response schemas.