Getting Started with the Speculo API

Three simple steps to start using the Speculo API:

1. Get your credentials from Speculo

Contact the Speculo team to receive:

clientId (e.g., client_abc123)
refreshToken (e.g., rt_live_xxxxxxxxx)
orgId (your organization identifier)

These credentials are provisioned once and can be reused indefinitely.

2. Exchange your refresh token for an access token

Call this once to get your access token:

curl -X POST https://speculo-api-oauth-54875993561.us-central1.run.app/token \
  -H "Content-Type: application/json" \
  -d '{
    "clientId": "client_abc123",
    "refreshToken": "rt_live_xxxxxxxxx"
  }'

Response:

{
  "accessToken": "eyJhbGciOiJIUzI1NiIs...",
  "tokenType": "Bearer"
}

Important: Save this accessToken - it never expires (until you rotate credentials).

3. Use the access token on all API requests

curl -X GET "https://api.speculo.ai/v1/contacts?pageSize=50" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

That's it! Use the same access token for all requests. No refresh logic, no expiry to track.

When to get a new access token

Only get a new access token when:

You're rotating credentials for security
You need to revoke the old token

Otherwise, keep using the same token.

Need help?

Contact support@speculo.ai with your organization ID and client ID for assistance with:

Credential rotation
Access issues
Integration questions

Loading…

1Pick a language

2Try It!