Setting up a lead connection
Before you can submit leads, create a lead connection for the company that should receive them:data_type determines the format the connection accepts: json for a JSON object or array, excel for spreadsheet uploads, or text for a raw text body. See Create lead connection for the full set of fields.
Settings
Each lead connection has four settings that control how it behaves:
Read a connection’s settings with List lead connection settings or Get lead connection setting:
Setting values are changed from the Contractors Cloud web app, not through this API — these endpoints are read-only.
Assigning reps
When a connection’slead_rep_assignment_method setting is round-robin, rep assignments define the rotation — create one rep assignment per user you want included, and each incoming lead goes to whichever assigned rep has waited longest since their last one. With default (or a rotation with no rep assignments), the connection’s rep_primary_id is used instead, whenever the lead itself doesn’t specify a rep. A submitted lead can explicitly set its own rep, which overrides both methods.
There’s no update endpoint for rep assignments — to change the rotation, delete an assignment and create a new one. See the Rep Assignments reference for every field and status code.
Field mapping
Your submitted lead data almost never uses Contractors Cloud’s own field names. A field map tells a lead connection how to translate one of your keys (source, for example full_name or contact.email) into a Contractors Cloud field (target, for example first_name or email) — use dot notation in source to reach a value nested inside your submitted data.
The fastest way to set up mapping is to send one example lead to Generate field maps, in the same format a real submission would use. Mappings are created automatically from that example, so most connections need no manual mapping at all. This endpoint is limited to 2 requests per minute per user account.
For finer control, call List available target fields to see the fields your connection supports — each one flags whether mapping it (is_important) is strongly recommended — then create, update, and delete individual field maps with the Field Maps endpoints. A field left unmapped isn’t necessarily lost — Contractors Cloud attempts to derive obvious values automatically — but an explicit map is the reliable way to get a value into a specific field.
Submitting leads
Submit a lead with aPOST request, identifying the connection with the X-Lead-Connection-Id header:
excel connections upload a spreadsheet instead, as multipart/form-data:
xlsx, csv, ods, or xls. text connections instead send a plain-text body, which is parsed automatically — see Submit leads for details on every format.
Every submission returns immediately, before processing finishes:
transaction_id groups every lead created from that submission. Filter List leads by filter[transaction_id]=e1a4c9d2-6b7f-4a3e-9c8d-1f2b3a4c5d6e to check on them once processing finishes.
Lifecycle
A lead moves through a fixed set of statuses. It startsqueued, then processing, then lands on one of ready, needs-review, or error:
automatically_convert_leads setting is yes (the default), a ready lead is converted automatically — no further action needed. Conversion creates a project, along with any contacts found in the lead’s data, and sets the lead’s project_id.
If a lead lands on needs-review, inspect its validation_errors to see what’s missing, then correct it with Update lead:
needs-review so it can be re-processed; call Process lead to re-run it, or Convert lead directly once it reaches ready.
Rate limits
Lead submissions are limited to 300 per minute, per lead connection. Exceeding it returns a429 response naming how many seconds to wait before trying again. Submitting to an inactive connection returns a 403 instead.