Skip to main content
Use OAuth when your product signs users in with Seamless and acts on their behalf. Each user gets their own access token; your backend stores refresh tokens securely.
API keys use the Token header. OAuth access tokens use Authorization: Bearer. Do not mix them on the same request.

​
Register your application

1

Create an OAuth connection

Go to Settings → Public API, open OAuth Connections, and click Create New Connection.
2

Save client credentials

Record client_id, client_secret, and redirect_uri. You need all three for token exchange and refresh.

​
Authorization code flow

​
1. Redirect the user to authorize

GET https://login.seamless.ai/oauth/authorize?client_id=YOUR_CLIENT_ID&redirect_uri=https://yourapp.com/callback&state=RANDOM_CSRF_STRING
Query paramDescription
client_idYour client ID
redirect_uriMust match the URI registered on the connection
stateOptional CSRF protection string you verify on callback
If redirect_uri includes query parameters, URL-encode the full URI when building this link. After the user signs in, Seamless redirects to your redirect_uri with a code query parameter.

​
2. Exchange the code for tokens

curl -X POST "https://api.seamless.ai/api/client/v1/oauth/accessToken" \
  -H "Content-Type: application/json" \
  -d '{
    "client_id": "YOUR_CLIENT_ID",
    "client_secret": "YOUR_CLIENT_SECRET",
    "redirect_uri": "https://yourapp.com/callback",
    "grant_type": "authorization_code",
    "code": "AUTHORIZATION_CODE_FROM_CALLBACK"
  }'
Example response: 
{
  "access_token": "ACCESS_TOKEN",
  "refresh_token": "REFRESH_TOKEN",
  "expires_at": 1712000000
}
Parameter reference: Get an access token.

​
3. Call the API with the access token

curl -X POST "https://api.seamless.ai/api/client/v1/search/contacts" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -d '{"jobTitle": ["VP Sales"], "limit": 5}'

​
4. Refresh an expired token

curl -X POST "https://api.seamless.ai/api/client/v1/oauth/accessToken" \
  -H "Content-Type: application/json" \
  -d '{
    "client_id": "YOUR_CLIENT_ID",
    "client_secret": "YOUR_CLIENT_SECRET",
    "redirect_uri": "https://yourapp.com/callback",
    "grant_type": "refresh_token",
    "refresh_token": "YOUR_REFRESH_TOKEN"
  }'

​
Next steps