Admission Integration

Connect your InstinctHub Admissions portal to Leadboard CRM so that every student application automatically creates a lead, assigns it to an "Admissions" group, and updates its score as the application moves through review, acceptance, and enrollment.

Overview#

The Admission integration mirrors the LMS Integration pattern with key differences:

1. Auto-creates leads — Unlike LMS events, admission events create a new lead if one doesn't exist (admission is often the first touchpoint)
2. Admission-specific custom fields — Program applied, application ID, JAMB score, mode of entry, and more are written to the lead's custom fields
3. Auto-grouping — New leads are automatically added to an "Admissions" group
4. Fetch existing records — Option to pull historical admission records from InstinctHub during initial setup

Supported Events#

Custom Fields Created#

When the integration is enabled, these custom fields are automatically created for your leads:

Step 1: Connect from InstinctHub#

The connection is initiated from the InstinctHub admin panel (creators_nextjs). You must be an admin on both InstinctHub and Leadboard CRM.

1. Log into the InstinctHub admin panel at your channel URL

2. Go to Settings (bottom of the sidebar)

3. Click the Integrations tab

4. Find the Leadboard CRM -- Admissions card (amber-colored, below the LMS card)

5. Click Connect to Leadboard CRM

6. A popup opens to Leadboard CRM. Log in if prompted.

7. Select the CRM company you want to connect to (only companies where you are an admin appear)

8. Click Approve

9. The popup closes automatically. The card now shows Connected with your company name, events sent count, and connection date.

Tip: The Admission connection is independent from the LMS connection. You can connect both to the same CRM company, or connect them to different companies.

Important: You need to be logged into Leadboard CRM in the same browser for the popup to work.

Step 2: Enable Admission Integration in the CRM#

After connecting from InstinctHub, configure the CRM side.

1. Go to /default/integrations/admission

2. Toggle Admission Integration to enabled

3. Default scoring rules are created automatically (see table above)

4. An "Admissions" group is created for your company

5. Custom fields are auto-created (see table above)

6. Events will start appearing in the Event Log at the bottom of the page

Step 3: Configure Scoring Rules#

Customize how many points each event type adds or subtracts from a lead's score.

1. Go to /default/integrations/admission

2. In the Scoring Rules table, edit the Points value for any event type

3. Toggle individual rules on/off with the Active switch

4. Click Save Scoring

How Scoring Works#

• General scoring -- Points are added to the lead's admission_score in their custom fields. No upper or lower limit.
• Product-specific scoring -- If a scoring rule is linked to a product, points go to the lead's product interest score (clamped 0-100).
• Lead auto-creation -- If no lead exists with the student's email, one is automatically created with lead_source = "ADMISSION" and basic profile data (first name, last name, mobile) from the event metadata.
• Auto-grouping -- Every lead touched by an admission event is added to the "Admissions" group.

Tip: Use the application_id custom field to cross-reference leads with InstinctHub's admission system. It contains the unique application reference (e.g., HUST2025-243).

Step 4: Fetch Existing Records (Optional)#

If you're connecting an existing InstinctHub Admissions portal that already has student applications, you can pull in historical records as leads.

1. Go to /default/integrations/admission

2. Click Fetch Existing Records

3. Provide:

   • InstinctHub Host -- The base URL of your InstinctHub API (e.g., https://api.instincthub.com)
   • Channel Username -- Your InstinctHub channel identifier
   • API Key -- Select the API key created during the OAuth connection

4. Click Start Sync

5. A progress bar shows the sync status: {processed}/{total} records

6. Each record creates an APPLICATION_SUBMITTED event and processes it through the normal pipeline (lead creation, group assignment, custom field population, scoring)

Note: The sync is idempotent -- records already imported (matched by email + application_id) are skipped. You can safely run it multiple times.

Note: The sync runs as a background task. You can navigate away and return to check progress.

View Events#

1. Go to /default/integrations/admission

2. Scroll to the Event Log section

3. Each event shows: email, event type, program name, score applied, processed status, and timestamp

4. Use the search bar to filter by email address

Stats Cards#

At the top of the page, four summary cards show:

• Total Events -- All admission events received
• Processed -- Events that have been scored
• Unprocessed -- Events waiting for processing
• Total Score Applied -- Sum of all points applied

How Events Flow (Technical)#

Understanding the event pipeline helps with troubleshooting and developer integration:

Signal-to-CRM Pipeline#

On InstinctHub (sender side):

1. StudentAdmission status changes (e.g., student submits form)
2. Django post_save signal fires
3. transaction.on_commit() schedules Celery task
4. send_admission_event_to_crm task looks up AdmissionConnection for the channel
5. If connected, POSTs event to Leadboard's ingestion endpoint

On Leadboard CRM (receiver side):

6. POST /api/v1/integrations/default/third-party/admission/events/ receives the event
7. AdmissionEvent record is created in the database
8. process_admission_event Celery task is dispatched
9. Task finds (or creates) a lead by email
10. Lead is added to the "Admissions" group
11. Lead's custom_fields are updated with admission data
12. Scoring rules are applied
13. lead.score_changed webhook is emitted
14. SCORE_THRESHOLD workflow rules are evaluated

Status-to-Event Mapping#

The integration maps InstinctHub StudentAdmission.status values to CRM event types:

Additionally, RecommendStudentProgram status changes fire events:

• APPROVED (by registrar) -> ACCEPTED with approved_programme in metadata
• REJECTED -> REJECTED

Event Payload Format#

{
  "event_type": "APPLICATION_SUBMITTED",
  "email": "student@example.com",
  "program_id": "uuid-of-programme",
  "program_name": "Computer Science",
  "application_id": "HUST2025-243",
  "metadata": {
    "mode_of_entry": "UTME",
    "level": "100",
    "jamb_score": "280",
    "status": "SUBMISSION",
    "first_name": "John",
    "last_name": "Doe",
    "mobile": "+2348012345678"
  }
}

API Endpoints#

Third-party event ingestion (API key auth):

Required scope: admission.events

Dashboard endpoints (JWT auth, admin only):

OAuth endpoints:

Generate OAuth Credentials#

Before configuring environment variables, you need to generate the OAuth client ID and secret. This is done once on the Leadboard CRM server.

Step 1. SSH into your Leadboard API server (or use your local dev environment)

Step 2. Run the management command:

python manage.py create_oauth_apps --type admission

Step 3. The command outputs the credentials:

Created: InstinctHub Admissions
  Client ID:     7a3f9b2c1d4e5f6a7b8c9d0e1f2a3b4c
  Client Secret:  a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2
  Redirect URIs: http://localhost:8008/api/integrations/leadboard-admission/callback
  Scope:         admission.events

Step 4. Copy the Client ID and Client Secret values -- you will need them for the environment variables below.

Important: The Client Secret is only shown once during creation. If you lose it, you will need to delete and recreate the OAuth application.

Note: To create both Admission and SIS OAuth apps at once, run python manage.py create_oauth_apps (without --type).

Environment Variables#

Using the Client ID and Client Secret from the step above, configure the following environment variables:

InstinctHub admin (creators_nextjs .env.local):

# The URL where your Leadboard CRM frontend is hosted
NEXT_PUBLIC_LEADBOARD_CRM_HOST=https://crm.yourcompany.com

# Client ID from the create_oauth_apps command output
NEXT_PUBLIC_LEADBOARD_ADMISSION_CLIENT_ID=7a3f9b2c1d4e5f6a7b8c9d0e1f2a3b4c

# The callback URL — must match the Redirect URI registered in the OAuth app
# For local dev: http://localhost:8008/api/integrations/leadboard-admission/callback
NEXT_PUBLIC_LEADBOARD_ADMISSION_REDIRECT_URI=https://admin.instincthub.com/api/integrations/leadboard-admission/callback

InstinctHub API (instincthub_apis .env):

# The URL where your Leadboard CRM API is hosted (include trailing slash)
LEADBOARD_API_HOST=https://crm-api.yourcompany.com/

# Client ID and Secret from the create_oauth_apps command output
LEADBOARD_ADMISSION_CLIENT_ID=7a3f9b2c1d4e5f6a7b8c9d0e1f2a3b4c
LEADBOARD_ADMISSION_CLIENT_SECRET=a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2

# Must match the Redirect URI above
LEADBOARD_ADMISSION_REDIRECT_URI=https://admin.instincthub.com/api/integrations/leadboard-admission/callback

Local development: Replace the production URLs with your local ones (e.g., http://localhost:3000 for CRM host, http://127.0.0.1:8080/ for API host, http://localhost:8008/api/integrations/leadboard-admission/callback for the redirect URI).

Celery Tasks Required#

Both systems need Celery workers running:

InstinctHub: send_admission_event_to_crm (in channels/admission_tasks.py)

• Max retries: 3, retry delay: 30s
• Looks up AdmissionConnection for the channel
• POSTs event to Leadboard's ingestion endpoint

Leadboard: process_admission_event (in integrations/tasks.py)

• Finds/creates lead by email
• Assigns to "Admissions" group
• Updates custom_fields
• Applies scoring
• Emits lead.score_changed webhook
• Triggers SCORE_THRESHOLD workflow rules

Database Models#

InstinctHub: AdmissionConnection (in channels/models.py)

• One-to-one with Channel
• Stores CRM credentials (primary_key, secret_key, api_host)

Leadboard: AdmissionEvent, AdmissionScoringConfig (in integrations/models.py)

• Company-scoped event records and scoring rules

Disconnect#

From InstinctHub#

1. Go to Settings > Integrations in InstinctHub admin
2. Click Disconnect on the Leadboard CRM -- Admissions card
3. Events stop flowing immediately

From Leadboard (Revoke API Key)#

1. Go to /default/integrations/api-keys
2. Find the key named "InstinctHub Admissions: {channel}"
3. Click Revoke

Troubleshooting#

Events not appearing#

1. Verify the connection is active: check the Connected status in InstinctHub settings
2. Verify Admission integration is enabled in the CRM: /default/integrations/admission -- toggle should be on
3. Check that Celery workers are running on both InstinctHub and Leadboard
4. Check the Event Log for any unprocessed events

Leads not being created#

• The student must have a valid email address in their InstinctHub profile
• Check that the lead_source shows as "ADMISSION" for auto-created leads
• Check the "Admissions" group in your CRM -- leads should appear there

Custom fields not populated#

• Verify the DynamicField records exist: go to /default/integrations/admission -- the enable toggle auto-creates them
• Check the lead's custom fields section -- admission data is stored under keys like program_applied, application_id, etc.

Score not updating#

• Check if the scoring rule for that event type is Active
• Check the Score Applied column in the event log
• If all scores show 0, the scoring rules may not have been created -- toggle the integration off and on again

Connection popup doesn't work#

• You must be logged into Leadboard CRM in the same browser
• Check your browser's popup blocker
• You must be an admin of at least one company on Leadboard
• Verify env vars: NEXT_PUBLIC_LEADBOARD_CRM_HOST, NEXT_PUBLIC_LEADBOARD_ADMISSION_CLIENT_ID, NEXT_PUBLIC_LEADBOARD_ADMISSION_REDIRECT_URI

Fetch existing records fails#

• Verify the InstinctHub host URL is correct (include https://)
• Verify the API key is active and has admission.events scope
• Check the Leadboard Celery worker logs for errors
• The export endpoint on InstinctHub must be reachable from the Leadboard server

Related#

• LMS Integration -- Connect learning events for lead scoring
• SIS Integration -- Connect student record events
• Automation -- Create workflows triggered by admission score thresholds
• Leads Management -- View lead scores, custom fields, and groups