Connect a provider and land your first lead

This guide takes an administrator and a lead provider from an empty connection to one lead visible in the CRM. The administrator creates the source and assignment settings; the provider sends the HTTP request. A website integration can use the same endpoint from its server.

Before you start

1. 1Sign in with access to Settings → Lead sources. Ask an administrator if that page is unavailable.
2. 2Decide which vendor or website this source represents. Give each provider its own source and key.
3. 3Have a sample enquiry with an email address or phone number. Include origin_zip and destination_zip to create a usable route.
4. 4Choose the team or agent who should receive new work. Confirm they are active and eligible for assignment.

1. Create the source and copy its credentials

1. 1Open Settings → Lead sources and add a source.
2. 2Enter its name and unique code, select the source type, and configure costs if you track provider spending.
3. 3Leave Issue a posting key enabled for a source that will submit leads by API, then save.
4. 4Copy the newly issued posting key and the posting URL shown with it. Keep the key in a secure place: it is shown once.
5. 5Send the provider the exact posting URL, the X-Api-Key header value, and the example payload below.

2. Set up where leads should go

1. 1Configure the source’s team and the Lead distribution rules for incoming work.
2. 2Check team membership, active users, working hours, and open-lead caps. An ineligible agent cannot receive automatic assignment.
3. 3Review the rule order and matching conditions. Existing leads are not reassigned just because you change a rule.

If nobody qualifies, the lead can remain unassigned. That means it was received, but an administrator or someone with assignment access must pick it up. The distribution guide explains teams, ratios, caps, and the unassigned pool.

3. Run a test without creating a lead

Use the posting URL with /test added at the end. It authenticates the same way as a live post, reports parsed fields and route information, and writes no lead.

curl -X POST "https://megahubcrm.com/api/inbound/YOUR_TENANT_KEY/test" \
  -H "X-Api-Key: YOUR_POSTING_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "first_name": "Dana",
    "last_name": "Whitfield",
    "email": "dana@example.com",
    "phone": "512-555-0142",
    "origin_zip": "33101",
    "destination_zip": "30301",
    "vehicle_year": "2022",
    "vehicle_make": "Jeep",
    "vehicle_model": "Wrangler",
    "operable": "yes",
    "transport_type": "open",
    "comments": "Integration test enquiry",
    "metadata": { "Reference": "00123", "Budget": 850, "Flexible": true }
  }'

Include additional information

Add an optional metadata object to the JSON payload for small details such as a vendor reference, budget or pickup preference. The same payload works with the posting URL issued in Settings, its /test endpoint, and each lead in a /batch submission.

{ "metadata": { "Reference": "00123", "Budget": 850, "Flexible": true, "Preferred date": "2026-10-20" } }

Check parsed.metadata in the test response. After a live submission, open the lead and check Additional information directly below Actions. Invalid metadata returns 400 BAD_REQUEST; in a batch it fails validation before any leads are created. The API reference includes the full contract and update behavior.

4. Submit one live lead

Use the same header and validated payload against the original posting URL, without /test. This creates real work. Agree with the provider which test enquiry you are submitting so it is not mistaken for a customer request.

POST https://megahubcrm.com/api/inbound/YOUR_TENANT_KEY
X-Api-Key: YOUR_POSTING_KEY
Content-Type: application/json

{
  "accepted": true,
  "leadNumber": 10482,
  "leadId": "9f2c1b7e-4a3d-4c21-8f0e-2b6d5a91c3f4",
  "duplicate": false
}

A successful single submission returns 201 Created. Store the leadNumber and leadId so both sides can identify the same enquiry. If duplicate is true, the lead was still accepted; it is flagged for review.

5. Confirm it landed correctly

1. 1Open Leads and find the returned lead number. Clear search and status filters if necessary.
2. 2Check the source name, contact details, route, vehicle and Additional information against the original payload.
3. 3Check the assigned agent or the unassigned pool. An agent’s account may not have permission to see another agent’s work.
4. 4Have the receiving agent open the lead and confirm they can act on it.
5. 5Once one complete round trip works, let the provider use the live URL for new enquiries. Enable batch posting separately only if needed.

Troubleshooting the first lead

Your go-live checklist

1. 1The provider uses its own source, current key, and correct live URL.
2. 2A dry run maps the contact, route, and vehicle fields correctly.
3. 3One live submission returns a lead number that you can find in Leads.
4. 4The expected agent can see the lead, or your team knows how to handle unassigned work.
5. 5The provider records acknowledgements and reports failures rather than blindly resending accepted enquiries.