Recover missed calls, book more visitors, follow up on estimates, publish local proof, and see the KPIs that matter.

TradeVulcan logoTradeVulcan
Menu

Contractor workflows for the revenue leaks that cost booked jobs.

Calls, booking, estimates, reviews, proof, scorecards, AI voice, and CRM context.
Find leakDemo
Sign in
API Documentation

TradeVulcan API reference.

TradeVulcan API documentation for approved server-to-server access with OAuth 2.0 client credentials, scoped bearer tokens, contacts, leads, and workspace identity endpoints. API use should be tied to a real workspace, approved scopes, and a specific partner or automation workflow.

Request API access Developer overview

1. Create credentials

Approved members with settings access can create a named API client in Workspace Settings, choose scopes, and copy the one-time secret.

2. Request a token

Use HTTP Basic auth or body credentials with grant_type=client_credentials. Tokens are opaque, revocable, and suitable for server-side automation flows.

3. Call v1 endpoints

Send Authorization: Bearer with each API request. Every endpoint enforces the required scope before returning workspace data.

POST
Client credentials

Create access token

/api/oauth/token

Exchanges a workspace API client ID and client secret for a revocable bearer token.

Authentication

HTTP Basic client authentication or body client_id/client_secret

Content type

application/x-www-form-urlencoded or application/json

Use case

Call this from a trusted backend before calling /api/v1 endpoints. Do not call it from browser-only code because it requires the client secret.

Request body

FieldTypeDescription
grant_typestringRequired.Must be client_credentials.
scopespace-delimited stringOptional subset of scopes already allowed on the API client.
client_idstringRequired only when not using HTTP Basic auth.
client_secretstringRequired only when not using HTTP Basic auth.

Response fields

FieldTypeDescription
access_tokenstringOpaque bearer token prefixed with tvat_.
token_typestringAlways Bearer.
expires_innumberSeconds until expiration. Current lifetime is 31536000 seconds (365 days).
scopestringGranted scopes on this token.

Status codes

200Token issued.
400Unsupported grant type, invalid scope, or malformed request.
401Client credentials are missing, inactive, revoked, or invalid.
500Authorization server could not process the request.

Example request

curl -X POST https://tradevulcan.com/api/oauth/token \
  -u "CLIENT_ID:CLIENT_SECRET" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "scope=contacts:read leads:read apps:read"

Example response

{
  "access_token": "tvat_...",
  "token_type": "Bearer",
  "expires_in": 31536000,
  "scope": "contacts:read leads:read apps:read"
}

Pagination

List endpoints accept limit up to 100 and return pagination.nextCursor when more records are available. Pass cursor on the next request.

Revocation

Rotate a client secret from Workspace Settings to revoke existing tokens for that client. Revoke unused clients when a partner connection is retired.

Standards note: the first TradeVulcan partner flow follows the OAuth 2.0 client credentials pattern from RFC 6749. Authorization-code plus PKCE for user-delegated apps is future-facing and should not be treated as a public SDK commitment.