Start by identifying who or what is making the request. Lead intake, user actions, organization services, webhooks, and AI tools use different trust boundaries.
Choose the integration path
A source key authorizes the external lead-ingestion routes only. It cannot read organization data or replace a user token or organization API key.
Build the integration
- Select the identity. Decide whether the caller is a source, user, organization service, or webhook recipient.
- Use the matching credential. Never broaden access to avoid implementing the correct authentication flow.
- Choose HTTP or an SDK. Use direct HTTP for simple integrations or a generated SDK for typed models and route builders.
- Handle failure explicitly. Validate status codes, respect rate limits, and retry only when the operation is safe.
- Test the real path. Exercise production authentication, payload construction, error handling, and downstream effects with controlled data.
Prove the smallest complete integration
For an organization service, start with GET /organizations/me to confirm the credential’s organization. Then read a known lead with GET /leads/{id}. This separates authentication and access problems from payload or workflow problems.
For intake, submit one controlled lead with a source key and a real certificate. Save the returned lead ID, inspect its processing status in Leadping, and verify any configured follow-up. The intake guide includes the request and reconciliation procedure.
Before adding writes, document which calls create billable work, start an automation, change an owner, or remove access. A successful HTTP request confirms only that operation’s result; it does not confirm every downstream action.
Keep a useful integration log
Record the operation, timestamp with time zone, HTTP status, returned record ID, and a local job ID. Capture Retry-After and a request or trace ID when present. Keep payloads, credentials, certificate URLs, and message content out of routine logs.
On failure, distinguish requests that were rejected from requests whose outcome is unknown. That distinction determines whether to correct the input, wait, reconcile, or escalate.
Production baseline
- Use HTTPS for every request.
- Store credentials in protected runtime configuration or a secret manager.
- Keep credentials and sensitive payloads out of logs and URLs.
- Grant only the access the integration needs.
- Rotate exposed or unused credentials.
- Review the automation action’s authentication limitations before accepting requests at a receiver.
- Keep a submission ledger and reconcile uncertain writes before repeating them; do not assume every endpoint supports idempotency.
- Treat lead, contact, and conversation data as sensitive.
SDKs
Use the API Reference for endpoint contracts and the OpenAPI specification for code generation or schema tooling. 
