Quickstart

Get your first API response in under 60 seconds.

Get an API key

Your key will look like this:

sk_live_a1b2c3d4e5f6...

Make your first request

Use your API key in the Authorization header to search for contractors:

Request

curl -H "Authorization: Bearer sk_live_YOUR_KEY" \
  "https://api.pullfirst.com/v1/licenses/search?q=Johnson+Electric"

Read the response

The API returns paginated JSON. Each result includes license details, status, and location.

Response

{
  "data": [
    {
      "licenseNumber": "EA045231",
      "name": "Johnson Electric Inc",
      "dbaName": "Johnson Electrical Services",
      "status": "Issued",
      "city": "Minneapolis",
      "state": "MN",
      "licenseType": "Electrical",
      "licenseSubtype": "Class A Electrical",
      "expirationDate": "2027-03-31",
      "hasEnforcementAction": false
    }
  ],
  "page": 1,
  "pageSize": 25,
  "totalCount": 3,
  "totalPages": 1
}

Filter results

Use Gridify syntax to filter any list endpoint. Combine multiple conditions with commas.

Filter by city and status

curl -H "Authorization: Bearer sk_live_YOUR_KEY" \
  "https://api.pullfirst.com/v1/licenses/search?q=Roofing&city=Minneapolis&status=Issued"

List endpoints also support Gridify operators directly:

Gridify filtering

curl -H "Authorization: Bearer sk_live_YOUR_KEY" \
  "https://api.pullfirst.com/v1/enforcement?filter=PenaltyAmount>10000&orderBy=PenaltyAmount desc"

Handle errors

The API returns structured errors with an error code and message.

401 Unauthorized

{
  "error": {
    "code": "unauthorized",
    "message": "Invalid or missing API key"
  },
}

Code	Status	Meaning
invalid_request	400	Missing or invalid parameters
unauthorized	401	Missing or invalid API key
not_found	404	Resource doesn't exist
rate_limit_exceeded	429	Rate limit hit

Check your rate limits

Every response includes rate limit headers so you can track usage.

Response headers

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 87
X-RateLimit-Reset: 1711756800
X-Request-Id: a1b2c3d4e5f67890abcdef1234567890

When rate limited, you'll receive a 429 response. See pricing for higher limits.

Next steps

Explore the full API Reference for all endpoints

Learn about advanced filtering with Gridify syntax