1stContact.ai API – Developer Guide
1stContact.ai Developer

1stContact.ai API (LeadConnector)

Securely connect to your CRM data using OAuth 2.0 or a Private Integration token. This guide covers auth, required headers, base URLs, rate limits, core endpoints (Contacts, Appointments), and webhooks—tailored for 1stContact.ai.

Quickstart API Examples Webhooks
Auth Headers Base URL Rate Limits Contacts Appointments Errors Security FAQ

Quickstart

  1. Create your app: In the 1stContact-branded HighLevel Marketplace, create a Private (internal) or Public app and set scopes & redirect URL.
  2. Install the app: Use the standard or white-label install link for your account; when redirected to your redirect_uri you’ll receive a one-time code.
  3. Exchange code: POST to /oauth/token for an access_token + refresh_token.
  4. Call APIs: Include Authorization: Bearer <access_token> and Version: 2021-07-28 on every request.

Tip: For internal use, you can also use a Private Integration token (no OAuth UI). Use OAuth for marketplace/public apps.

Key Values

Base URLhttps://services.leadconnectorhq.com
AuthOAuth 2.0 (Authorization Code)
Version2021-07-28 (required header)

Authentication

Option A — OAuth 2.0 (recommended): Create an app in your 1stContact-branded Marketplace, set scopes & redirect URL, install the app to a sub-account, then exchange the code for tokens via /oauth/token. Access tokens last ~24 hours; refresh tokens last up to 1 year and can be rotated.

Option B — Private Integration token: For internal automations, generate a token and call the APIs directly (skip the end-user OAuth UI).

Scopes: request the minimum required (e.g., contacts.readonly contacts.write, calendars.*) when creating your app.
curl -X POST "https://services.leadconnectorhq.com/oauth/token" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "client_id":    "YOUR_CLIENT_ID",
    "client_secret":"YOUR_CLIENT_SECRET",
    "grant_type":   "authorization_code",
    "code":         "ONE_TIME_AUTH_CODE",
    "user_type":    "Location",
    "redirect_uri": "https://yourapp.com/oauth/callback"
  }'
        
await fetch("https://services.leadconnectorhq.com/oauth/token",{
  method:"POST",
  headers:{
    "Accept":"application/json",
    "Content-Type":"application/json"
  },
  body: JSON.stringify({
    client_id:"YOUR_CLIENT_ID",
    client_secret:"YOUR_CLIENT_SECRET",
    grant_type:"authorization_code",
    code:"ONE_TIME_AUTH_CODE",
    user_type:"Location",
    redirect_uri:"https://yourapp.com/oauth/callback"
  })
}).then(r=>r.json());
Exchange code → access/refresh token Copy Copied!

Required Headers

HeaderValueNotes
AuthorizationBearer <access_token>Token from OAuth or Private Integration
Version2021-07-28Mandatory for v2 endpoints
Content-Typeapplication/jsonFor JSON requests
Acceptapplication/jsonJSON responses

Base URL

All v2 endpoints live under the LeadConnector domain:

https://services.leadconnectorhq.com

The install link used during OAuth can be standard or white-label (via your 1stContact-branded Marketplace). API calls still go to the LeadConnector base URL.

Rate Limits

  • Burst: 100 requests / 10 seconds per app per resource (Location/Company)
  • Daily: 200,000 requests per app per resource

On HTTP 429, back off and retry (exponential backoff). Respect pagination for bulk operations.

Core Endpoint Examples

Contacts

Create and search contacts.

curl -X POST "https://services.leadconnectorhq.com/contacts/" \
  -H "Authorization: Bearer <ACCESS_TOKEN>" \
  -H "Version: 2021-07-28" \
  -H "Content-Type: application/json" \
  -d '{
    "firstName":"Ada",
    "lastName":"Lovelace",
    "email":"[email protected]",
    "phone":"+15555550123",
    "source":"api",
    "tags":["api","vip"]
  }'

await fetch("https://services.leadconnectorhq.com/contacts/",{
  method:"POST",
  headers:{
    "Authorization":"Bearer <ACCESS_TOKEN>",
    "Version":"2021-07-28",
    "Content-Type":"application/json",
    "Accept":"application/json"
  },
  body: JSON.stringify({
    firstName:"Ada",
    lastName:"Lovelace",
    email:"[email protected]",
    phone:"+15555550123",
    source:"api",
    tags:["api","vip"]
  })
}).then(r=>r.json());
Endpoint: POST /contacts/ Copy Copied! 
curl -X POST "https://services.leadconnectorhq.com/contacts/search" \
  -H "Authorization: Bearer <ACCESS_TOKEN>" \
  -H "Version: 2021-07-28" \
  -H "Content-Type: application/json" \
  -d '{
    "query":"[email protected]",
    "limit":50,
    "page":1
  }'

await fetch("https://services.leadconnectorhq.com/contacts/search",{
  method:"POST",
  headers:{
    "Authorization":"Bearer <ACCESS_TOKEN>",
    "Version":"2021-07-28",
    "Content-Type":"application/json",
    "Accept":"application/json"
  },
  body: JSON.stringify({ query:"[email protected]", limit:50, page:1 })
}).then(r=>r.json());
Endpoint: POST /contacts/search Copy Copied!

Appointments

Create and retrieve appointments (Calendar Events API).

curl -X POST "https://services.leadconnectorhq.com/calendars/events/appointments" \
  -H "Authorization: Bearer <ACCESS_TOKEN>" \
  -H "Version: 2021-07-28" \
  -H "Content-Type: application/json" \
  -d '{
    "calendarId":"CALENDAR_ID",
    "contactId":"CONTACT_ID",
    "title":"Strategy Call",
    "startTime":"2025-09-05T15:00:00Z",
    "endTime":"2025-09-05T15:30:00Z",
    "timeZone":"America/Chicago",
    "notes":"Booked via API"
  }'

await fetch("https://services.leadconnectorhq.com/calendars/events/appointments",{
  method:"POST",
  headers:{
    "Authorization":"Bearer <ACCESS_TOKEN>",
    "Version":"2021-07-28",
    "Content-Type":"application/json",
    "Accept":"application/json"
  },
  body: JSON.stringify({
    calendarId:"CALENDAR_ID",
    contactId:"CONTACT_ID",
    title:"Strategy Call",
    startTime:"2025-09-05T15:00:00Z",
    endTime:"2025-09-05T15:30:00Z",
    timeZone:"America/Chicago",
    notes:"Booked via API"
  })
}).then(r=>r.json());
Endpoints: POST /calendars/events/appointments • GET /calendars/events/appointments/{eventId} Copy Copied!

Webhooks

Subscribe inside your Marketplace app settings. Useful events include:

EventWhen
ContactCreateA new contact is created
ContactUpdateA contact is updated
AppointmentCreateAn appointment is booked
OpportunityCreateA pipeline opportunity is created
InboundMessageA contact sends a message

Add your webhook URL in your app’s settings and toggle on events.

Error Handling

StatusMeaningAction
400Bad requestValidate payload/fields
401UnauthorizedCheck bearer token; include Version header
403Insufficient scopeAdjust app scopes/installation
404Not foundVerify IDs/paths
409ConflictDe-dupe or resolve state
422Validation errorFix required fields/format
429Rate limitBackoff & retry; respect limits
5xxServer errorRetry with jitter, monitor

Security Best Practices

  • Store client secrets and refresh tokens server-side only.
  • Use HTTPS everywhere; rotate tokens; use least-privilege scopes.
  • Implement exponential backoff and idempotency where possible.
  • Log request IDs & timestamps for observability; never log secrets.

FAQ

Can I call the API via our 1stContact.ai domain? Use the 1stContact-branded install URL for OAuth, but API calls go to services.leadconnectorhq.com.

Do I always need the Version header? Yes—Version: 2021-07-28 is required for v2 endpoints.

How long do tokens last? Access token ~24h; refresh token up to 1 year (rotates on use).

Last updated: September 3, 2025 • Need help? Contact 1stContact.ai support.