Create a Lead/Job from a Third-Party System

Common examples include website forms, ad platforms, call tracking systems, appointment booking tools, lead aggregators, measurement tools, inspection tools, and other third-party systems that send new opportunities into AccuLynx.

Creating a lead/job requires a Contact-to-Job association. The integration can either:

Use an existing Contact already in AccuLynx, or
Create a new Contact and use the returned Contact ID.

In both cases, the Job should be created using the appropriate Contact ID and Contact Type ID.

Recommended workflow

External system receives lead
      ↓
Find or create the Contact
      ↓
Retrieve Contact Type ID
      ↓
Retrieve configured Job field IDs, if needed
      ↓
Create Job and associate Contact
      ↓
Add optional job details

Before you begin

Confirm the following before creating the lead/job:

The correct AccuLynx Account Location.
The correct API key for that location.
Whether the Contact already exists in AccuLynx.
Which Contact Type should be used.
Whether Lead Source, Job Category, Work Type, or Trade Type should be included.
Whether those configured values already exist in AccuLynx.
Whether the external system needs to store the AccuLynx Contact ID and Job ID after creation.

Important: Configured values such as Job Categories, Work Types, Trade Types, Lead Sources, Company Users, and Insurance Companies must already exist in AccuLynx. Retrieve the correct IDs before using them in API requests.

Step 1: Find or create the Contact

Before creating a new Contact, use the Contact Search endpoint to determine whether the Contact already exists in AccuLynx.

Use an existing Contact when the integration already knows or can confidently identify the correct Contact.

Create a new Contact when the person or company does not already exist.

Avoid creating duplicate Contacts when the existing Contact can be confidently identified.

Step 2: Retrieve Contact Type

Use the Contact Type endpoint to retrieve Contact Types configured in the AccuLynx account.

The Contact Type ID is used when associating the Contact to the Job.

If Contact Type is left blank, AccuLynx defaults the Contact Type to Customer, which is commonly used when pushing leads into AccuLynx.

Step 3: Retrieve configured Job field IDs

If the integration needs to populate configured job values, retrieve the IDs first.

Field	Retrieve with	Used in
Job Category	Get Job Category	Create Job
Work Type	Get Work Type	Create Job
Trade Type	Get Trade Type	Create Job
Lead Source	Get Active Lead Sources	Create Job
Insurance Company	Get Insurance Companies	Set Insurance Company
Sales Representative	Get Users	Update Company Representative

Do not pass configured values as free text. Use the corresponding AccuLynx ID.

Step 4: Create the Job and associate the Contact

Use the Create Job endpoint after the Contact has been identified or created.

Include:

Contact ID
Job/property details
Lead Source ID, if used
Job Category ID, if used
Work Type ID, if used
Trade Type ID, if used
Notes, if applicable. The Create Job endpoint supports notes up to 1,000 characters. For longer or additional notes after the Job is created, use Create Job Message.

Step 5: Add optional details after Job creation

After the Job exists, the integration may add additional details.

Optional action	Use when
Add Initial Appointment	The external system captured an appointment date/time.
Set Insurance Company	The Job should be assigned an existing Insurance Company.
Add Job Message	Additional notes should appear in Job Communications.
Add Job Document	A document should be attached to the Job.
Upload Photos or Videos	Media should be added to the Job’s Photos folder.
Assign Sales Representative	A Company Representative should own the Job.
Update Custom Fields	Structured external data should be stored for reporting or reconciliation.

What the external system should store

Store these values for future updates, reconciliation, troubleshooting, and reporting:

Value	Why
AccuLynx Contact ID	Identifies the Contact used for the Job.
AccuLynx Job ID	Required for updates, files, messages, assignment, and reporting.
External Lead ID	Helps prevent duplicates and reconcile records.
Lead Source ID used	Helps troubleshoot source mapping.
External Source System	Identifies where the lead originated.
Created timestamp	Useful for audit and troubleshooting.
Last sync timestamp	Useful for ongoing sync workflows.

Questions this guide answers

How do I create a lead/job from a third-party system?
Can I use an existing AccuLynx Contact?
When should I create a new Contact?
How do I associate a Contact to a Job?
Which IDs do I need before creating the Job?
How do I include Lead Source, Job Category, Work Type, or Trade Type?
What can be added after the Job is created?
What should the external system store for future updates?