Skip to main content

API Authentication: OAuth2 Setup Guide

The Lawmatics REST API uses the standard OAuth2.0 authorization code grant flow. If you're new to OAuth2, OAuth 2.0 Simplified is a good primer. Full endpoint reference: docs.lawmatics.com

Step 1: Create a Developer App

Before you can authenticate, your Lawmatics account needs Developer Settings enabled.

  1. Contact [email protected] (or your Account Manager) to have Developer Settings turned on.

  2. Once enabled, go to https://app.lawmatics.com/settings/developers while logged in.

  3. Click New Application and provide:

    • Name, description, and logo — shown to users when they authorize your app

    • Callback URL — where users are redirected after granting access

This generates a Client ID and Client Secret for your app.

Step 2: Get a Grant Code

Send the user to Lawmatics' authorize URL:

https://app.lawmatics.com/oauth/authorize?client_id=YOUR_CLIENT_ID&redirect_uri=YOUR_CALLBACK_URL&response_type=code

Required query params:

Param

Description

client_id

Your app's ID from Developer Settings

redirect_uri

Must match the callback URL set on your app

response_type

Always code

state (optional)

Round-tripped back to your callback to preserve state

After the user logs in and grants access, Lawmatics redirects them back to your callback URL with a short-lived grant code:

https://www.yourapp.com/callback?code={GRANT_CODE}

Step 3: Exchange the Code for an Access Token

From your backend, make a POST to:

https://api.lawmatics.com/oauth/token

Required body params:

Param

Description

client_id

Your app's Client ID

client_secret

Your app's Client Secret

grant_type

Always authorization_code

code

The grant code from Step 2

redirect_uri

Same callback URL used in Step 2

Successful response:

HTTP/1.1 200 OK {   "token_type": "bearer",   "access_token": "{ACCESS_TOKEN}",   "created_at": 1539723267 }

Step 4: Authenticate Requests

Pass the access token as a Bearer token on every request:

Authorization: Bearer {ACCESS_TOKEN}
curl -H "Authorization: Bearer <access_token>" https://api.lawmatics.com/v1/prospects/74

Important Limitations

  • Access tokens do not expire. There is no refresh token — none is needed.

  • No scopes are supported. Once a user authorizes your app, it has full CRUD access to their account.

  • No deauthorization endpoint exists. To revoke access, the firm must remove/reset the integration from their Lawmatics settings.

  • Rate limit: see the Errors & Rate Limits article for current limits.

Don't Need Full OAuth?

If you're just collecting web form submissions (not building a full two-way integration), you don't need a Developer App or the OAuth flow at all — use the unauthenticated Custom Form Submit endpoint instead. See Connecting Your Webform to Lawmatics via API.

Questions? [email protected]

Related Articles
Did this answer your question?