LeadNod API Documentation

The LeadNod API provides programmatic access to the LeadNod platform, enabling you to integrate sales professional matching, engagement management, payment processing, and analytics into your own applications. Our API follows RESTful principles, uses standard HTTP methods, and returns JSON responses.

Whether you are building a custom CRM integration, automating your sales operations, or creating a white-label solution, our API provides the flexibility and power you need. This documentation covers everything from basic authentication to advanced webhook configurations, with code examples in multiple programming languages.

API Capabilities

The LeadNod API enables you to perform a wide range of operations including managing user accounts and profiles programmatically, creating and managing sales opportunities, searching and filtering sales professional matches, initiating and managing engagements between parties, processing payments through our escrow system, tracking performance metrics and generating reports, sending and receiving platform messages, and configuring webhooks for real-time event notifications.

Prerequisites

Before you can start using the LeadNod API, you will need a LeadNod account with API access enabled, API credentials consisting of a Client ID and Client Secret, and basic understanding of RESTful APIs and HTTP methods. API access is available on our Professional and Enterprise plans. If you are on a different plan and need API access, please contact our sales team to discuss upgrade options.

The LeadNod API uses OAuth 2.0 for authentication. All API requests must include a valid access token in the Authorization header. Access tokens are obtained through the OAuth 2.0 token endpoint using your client credentials.

Obtaining Access Tokens

To obtain an access token, make a POST request to our token endpoint with your client credentials. The response will include an access token that you can use for subsequent API requests. Access tokens are valid for one hour by default, after which you will need to request a new token.

curl -X POST https://api.leadnod.com/oauth/token \
  -H "Content-Type: application/json" \
  -d '{
    "grant_type": "client_credentials",
    "client_id": "your_client_id",
    "client_secret": "your_client_secret"
  }'

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "read write"
}

Using Access Tokens

Include the access token in the Authorization header of all API requests. The token should be prefixed with "Bearer " followed by a space and then the token value.

curl -X GET https://api.leadnod.com/v1/users/me \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..."

Token Security

Protect your API credentials and access tokens carefully. Never expose your client secret in client-side code or public repositories. Store credentials securely using environment variables or a secrets management system. Rotate your client secret periodically and immediately if you suspect it has been compromised. Use HTTPS for all API communications to prevent token interception.

All API requests should be made to the following base URL:

We also provide a sandbox environment for testing and development purposes. The sandbox environment uses separate credentials and contains test data only.

All endpoints are relative to these base URLs. For example, to access the users endpoint, you would make a request to https://api.leadnod.com/v1/users in production or https://sandbox.api.leadnod.com/v1/users in the sandbox environment.

To ensure fair usage and maintain platform stability, the LeadNod API implements rate limiting. Rate limits vary based on your subscription plan and the specific endpoint being accessed.

Rate Limit Headers

Every API response includes headers that provide information about your current rate limit status:

Handling Rate Limits

When you exceed the rate limit, the API returns a 429 Too Many Requests response. Your application should handle this gracefully by implementing exponential backoff. Wait for the time indicated in the Retry-After header before making additional requests. Consider caching responses where appropriate to reduce the number of API calls needed.

Webhooks enable real-time notifications when events occur on the LeadNod platform. Instead of polling our API for changes, you can register webhook endpoints to receive HTTP POST requests with event data automatically.

Supported Events

LeadNod supports webhooks for a wide variety of events across the platform. These include user events such as user.created, user.updated, and user.verified. Opportunity events include opportunity.created, opportunity.updated, opportunity.closed, and opportunity.matched. Engagement events cover engagement.created, engagement.started, engagement.completed, engagement.terminated, and activity.logged. Payment events include payment.received, payment.released, escrow.funded, and escrow.dispute. Message events include message.received and conversation.started.

Webhook Configuration

Configure webhooks through the API or your account dashboard. Each webhook configuration includes a URL endpoint, the events to subscribe to, and an optional secret for signature verification.

curl -X POST https://api.leadnod.com/v1/webhooks \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-app.com/webhooks/leadnod",
    "events": ["engagement.created", "payment.received"],
    "secret": "your_webhook_secret"
  }'

Webhook Payload

Webhook payloads are delivered as JSON and include the event type, timestamp, and relevant data. All webhooks include a signature header that you should verify to ensure the request originated from LeadNod.

{
  "id": "evt_123abc",
  "type": "engagement.created",
  "created": "2024-03-15T14:30:00Z",
  "data": {
    "engagement_id": "eng_456def",
    "client_id": "usr_789ghi",
    "sales_pro_id": "usr_012jkl",
    "status": "pending"
  }
}

Signature Verification

Each webhook request includes an X-LeadNod-Signature header containing an HMAC-SHA256 signature of the payload using your webhook secret. Verify this signature to confirm the request is authentic and has not been tampered with. Always verify signatures before processing webhook data.