Integration Capabilities Overview¶
This document provides a comprehensive summary of all integration capabilities available in the WhiteLabelCRO platform v1 release.
Capability Summary¶
Events (Triggers)¶
10 canonical event types available via Webhooks and the Integration API:
| Category | Count | Events |
|---|---|---|
| Billing | 4 | invoice.created, invoice.status_changed, payment.succeeded, payment.failed |
| Client | 3 | client.created, client.status_changed, lead.created |
| Partner | 1 | affiliate.created |
| Documents | 1 | document.uploaded |
| Compliance | 1 | agreement.signed |
Actions (via Integration API)¶
9 actions to write data into WhiteLabelCRO:
| Action | Description |
|---|---|
| Create Lead | Add new lead with status "Lead - New" |
| Create Client | Enroll new client |
| Update Client | Modify client details |
| Update Client Status | Change client stage |
| Add Client Note | Attach note to client record |
| Update Lead | Modify lead details |
| Update Lead Status | Change lead stage |
| Create Affiliate | Add referral partner |
| Update Affiliate | Modify affiliate details |
Searches (via Integration API)¶
2 searches to find existing records:
| Search | Criteria |
|---|---|
| Find Client | By email, phone, client ID, or external ID |
| Find Lead | By email, phone, client ID, or external ID |
Lookups (via Integration API)¶
3 lookup endpoints for dropdown data:
| Lookup | Returns |
|---|---|
| Get Employees | Active employees (excludes affiliates) |
| Get Affiliates | Approved affiliate partners |
| Get Client Statuses | Valid client/lead statuses with metadata |
Event Details¶
Billing Events¶
invoice.created - Triggered when a new invoice is generated - Includes: invoice_id, client_id, amount, due_date, description, invoice_status
invoice.status_changed - Triggered when invoice payment status changes (Unpaid to Paid, etc.) - Includes: invoice_id, previous_status, new_status, total_paid, balance
payment.succeeded - Triggered when a payment processes successfully - Includes: payment_id, invoice_id, client_id, payment_amount, payment_method
payment.failed - Triggered when a payment attempt is declined - Includes: payment_id, invoice_id, client_id, amount_attempted, failure_reason
Client Events¶
client.created - Triggered when a new client is enrolled - Includes: client_id, first_name, last_name, email, phone, status
client.status_changed - Triggered when client moves to different lifecycle stage - Includes: client_id, previous_status, new_status, changed_date
lead.created - Triggered when a new lead is captured - Includes: client_id, first_name, last_name, email, phone, status, source
Partner Events¶
affiliate.created - Triggered when a new referral partner is added - Includes: employee_id, full_name, email, phone, is_approved_affiliate
Document Events¶
document.uploaded - Triggered when a file is added to a client record - Includes: client_doc_id, client_id, doc_name, doc_type_name, created_date
Compliance Events¶
agreement.signed - Triggered when a client electronically signs a document - Includes: agreement_signed_id, client_id, signed_date, name_signed, agreement_name
Action Details¶
Create Lead¶
Add a new lead with status "Lead - New".
Required fields: first_name, last_name, email
Optional fields: phone, city, state, zip, package_keyword, affiliate_id, external_id
Create Client¶
Enroll a new client in the system.
Required fields: first_name, last_name, email
Optional fields: phone, status, employee_id, city, state, zip, affiliate_id, external_id
Update Client¶
Modify an existing client's information.
Required fields: client_id
Optional fields: first_name, last_name, email, phone, city, state, zip, employee_id, affiliate_id, external_id
Update Client Status¶
Change a client's lifecycle stage.
Required fields: client_id, new_status or new_status_id
Optional fields: changed_by_employee_id, status_note
Add Client Note¶
Attach a note or comment to a client record.
Required fields: client_id, text
Optional fields: note_type, visibility, external_id
Update Lead¶
Modify an existing lead's information.
Required fields: client_id
Optional fields: first_name, last_name, email, phone, city, state, zip, employee_id, affiliate_id, external_id
Update Lead Status¶
Change a lead's status (must remain a Lead status).
Required fields: client_id, new_status or new_status_id
Optional fields: changed_by_employee_id, status_note
Create Affiliate¶
Add a new referral partner.
Required fields: email, first_name, last_name
Optional fields: phone, affiliate_code, commission_rate, affiliate_company_name, external_id
Note: Created affiliates are not automatically approved and require admin action.
Update Affiliate¶
Modify an existing affiliate's information.
Required fields: employee_id
Optional fields: first_name, last_name, email, phone, affiliate_company_name, commission_rate, is_active, is_approved, external_id
Search Details¶
Find Client¶
Locate an existing client in WhiteLabelCRO.
Search criteria: email, phone, client_id, or external_id
Returns: client_id, first_name, last_name, email, phone, status, employee_id, affiliate_id
Find Lead¶
Locate an existing lead in WhiteLabelCRO.
Search criteria: email, phone, client_id, or external_id
Returns: client_id, first_name, last_name, email, phone, status (filtered to Lead% statuses only)
Platform Features¶
All Capabilities Support¶
- Idempotency keys: Prevent duplicate records on retry
- External ID mapping: Link records across systems (HubSpot, Salesforce, etc.)
- Rate limiting: Fair usage enforcement
Security¶
- API key authentication with scoped permissions
- HMAC-SHA256 webhook signatures
- HTTPS required for all production endpoints
- Sensitive data (SSN, bank accounts, full card numbers) never exposed
Lookup Details¶
Get Employees¶
Returns active employees for assignment to clients/leads.
- Excludes affiliates (TeamRoleId ≠ 6)
- Scoped to authenticated company
- Returns:
employee_id,full_name - Ordered alphabetically
Use in Actions: Create Client, Update Client, Update Lead, Update Client Status, Update Lead Status
Get Affiliates¶
Returns approved referral partners.
- Only active and approved affiliates
- Scoped to authenticated company
- Returns:
affiliate_id,full_name - Ordered alphabetically
Use in Actions: Create Client, Update Client, Update Lead, Update Affiliate
Get Client Statuses¶
Returns valid client and lead statuses.
- Includes both lead and client statuses
- Lead statuses: Global canonical values only
- Client statuses: Company-specific + global
- Returns:
status_id,status_name,is_lead,is_active,color_code - Ordered: Company-specific first, then alphabetically
Use in Actions: Create Client, Update Client Status, Update Lead Status
Rate Limits¶
| Scope | Limit | Applies To |
|---|---|---|
| Read | 60 requests/minute | Searches, event polling |
| Write | 100 requests/minute | Actions |
| Admin | 200 requests/minute | Administrative operations |
Exceeded limits return HTTP 429 with Retry-After header.