Skip to main content

​
Introduction

Lead’s API are REST based, accepts and returns JSON-encoded payloads, and uses standard HTTP response codes, authentication, and verbs.

​
Authentication

Lead uses OAuth2 for Authentication. When we onboard your program, you will be setup with a client_id and a client_secret. These credentials can be used to retrieve an access_token which you will use to authenticate further requests.
By default, access tokens have a 24 hour expiry, and will need to be replaced before they expire. See the expires_in passed in the token response to track the . They can also be limited to certain API scopes which can help you with access control while preventing unauthorized requests.

​
Steps

1

Get Access Token

Use your client_id and client_secret to get an access_token with the Authentication API.
2

Authenticate Requests

Use the access_token in the 'authorization: Bearer <access_token>' header to authenticate further API requests.

​
IP Allowlist

An IP allowlist restricts API access to a predefined set of approved IPv4 addresses or subnets. Requests originating from addresses outside the allowlist are rejected. This provides an additional layer of protection by ensuring that only trusted networks can access the API.

​
Configuration

Each API partner can be configured with a set of allowed IP subnets. When a request is received, the API server validates the request’s source IP address against the configured allowlist:
  • If the source IP address falls within an allowed subnet, the request is processed.
  • If the source IP address does not match any allowed subnet, the request is rejected and an error is returned.
{
    "status": 403,
    "code": "source_ip_not_allowed",
    "title": "Requests from this IP address are not permitted for this program.",
    "invalid_parameters": [
        {
            "parameter": "source_ip",
            "reason": "source IP not allowed for program"
        }
    ]
}

​
Setup

To utilize Lead’s IP allowlist feature:
1

Provide Lead With Your IP Subnets

Give them to your Technical Account Manager.
2

Specify Each Subnet

Use CIDR notation.
Configuration limits:
  • Maximum subnets: 30
  • Supported IP version: IPv4 only
  • Supported CIDR prefix lengths: /20 to /32
  • Broader ranges such as /16 or /8 are not supported.

​
Unsupported IP Addresses

The following IP address types cannot be included in the IP allowlist. IPv6 addresses
  • Only IPv4 addresses are supported.
Private IP ranges
  • 10.0.0.0/8
  • 172.16.0.0/12
  • 192.168.0.0/16
Loopback addresses
  • 127.0.0.0/8
Link-local addresses
  • 169.254.0.0/16
Invalid formats
  • Any address not in valid IPv4 format x.x.x.x, where each octet is between 0 and 255).