Bulk Operations on the GoHighLevel API

Thirteen, in our assessment — the per-record contact and custom-object operations, where each call touches one record and no call depends on another's result. These are the ones we have explicitly enabled for concurrent fan-out, and the reasoning transfers to any client doing its own batching:

What makes them safe is independence, not the HTTP verb. Each call addresses a distinct record, so interleaving them produces the same end state as running them in order. Concurrency here is bounded by rate limiting, not by correctness.

The limits we run in production, as a starting point for your own: 1,000 records per batch, eight concurrent requests by default and sixteen at most, sharing one pooled keep-alive connection so the batch is not paying for a fresh TLS handshake per record.

Three operations are equally parallel-safe in the mechanical sense and should still not be batched casually, because the failure mode is unrecoverable:

In Hylo these refuse a batch unless the caller passes an explicit confirm_destructive flag. The point is not that the flag prevents anything — a caller can always set it — but that deleting 1,000 records requires a different sentence than deleting one, so it cannot happen as a by-product of a mis-scoped filter.

The thirteen endpoints above are an allow-list, and everything else is refused. That inverts the obvious design, and the reasoning is worth stating because it applies equally if you are building your own batching layer.

A generic “run this endpoint N times concurrently” facility is only correct for endpoints whose calls are independent, and plenty are not: anything that reads then writes, anything where order determines the final state, anything with a per-parent sequence. If batching is on by default, every endpoint added to the API is implicitly declared safe by someone who never looked at it — and the failure is quiet, producing a plausible result set with a few records in the wrong state.

Defaulting to refusal makes the opposite true: an endpoint becomes batchable once someone has actually reasoned about it. The cost is that a legitimate case occasionally gets turned down pending review, which is a much better error to hold than the alternative.

A related trap lives in how a batch reports its result. If success is returned as a count rather than a verdict, an all-failed batch of zero successes can read as a completed write to code checking the wrong field — zero is falsy in most languages right up until it is compared against something. Whatever you build, return per-record outcomes plus a boolean that means what it says.

At import volumes a 429 is not an error condition — it is the expected steady state of a system running as fast as it is allowed to. Treat it as flow control rather than as a failure.

The property that makes this tractable: a 429 means the request was rejected without being applied. A retry therefore cannot duplicate a record, and is safe for every verb including POST creates. This is exactly what separates a 429 from a mid-flight disconnect, where the write may or may not have landed and a blind retry can duplicate.

What that implies in practice:

• Honour Retry-After when it is present — that is the server telling you the answer instead of you guessing at it.
• Back off exponentially with a ceiling when it is absent. An unbounded backoff turns a transient limit into a stalled import.
• Retry creates too. The instinct to exclude non-idempotent verbs from retry logic is correct in general and wrong for 429 specifically.
• Do not treat a disconnect the same way. Read-only calls can be retried freely; a write that died in flight needs a read to establish what actually happened.

We have deliberately not published GoHighLevel's specific rate limits here, because we cannot source current numbers to their documentation and a stale limit is worse than none at all. Read the Retry-After header and the response rather than a number from a blog post.

Concurrency is the second optimisation. The first is not making the call at all, and GoHighLevel offers a lot of that, because several endpoints accept inline what people habitually do in a follow-up request.

Contact creation is the clearest case. A very common sequence is upsert a contact, then call add-tags, then call update-contact for custom fields — three requests per contact. Both tags and customFields are accepted in the upsert body:

# One request per contact — tags and custom fields inline
curl -s -X POST "https://services.leadconnectorhq.com/contacts/upsert" \
  -H "Authorization: Bearer pit-your-token" \
  -H "Version: 2021-07-28" \
  -H "Content-Type: application/json" \
  -d '{
    "locationId": "LOC",
    "email": "person@example.com",
    "tags": ["imported", "q3-list"],
    "customFields": [{"key": "source_list", "field_value": "q3-webinar"}]
  }'

On a 400-record import that is 1,200 requests reduced to 400 before any concurrency is applied — a bigger win than tuning parallelism, and it removes the partial-state problem where the contact exists but the tagging call failed.

One related choice worth making early: prefer upsert over create for imports. Re-running a create-based import duplicates records; re-running an upsert-based one converges. Imports get re-run more often than anyone plans for.

If your import links records to each other — contacts to properties, contacts to listings, custom objects to one another — there are two similarly named endpoints, and choosing the wrong one produces a confusing failure.

• associations/create-association defines an association type: the schema saying a contact may be linked to a listing. You call it rarely, usually once per relationship kind during setup.
• associations/create-relation links an actual pair of records. This is what a CSV import calls repeatedly, and the one worth batching.

The names invite the mistake, and an AI assistant reading endpoint names alone reaches for create-association because it sounds like the general case. If you are attaching many contacts to listings from a spreadsheet you want create-relation, batched. Its counterpart, delete-relation, sits in the destructive set above.

More broadly this is the category of problem that stays invisible until it happens: the endpoint name reads correctly, the schema validates, and the call fails for a reason the schema never mentioned. Our endpoint reference carries these distinctions inline, and the comparison page has more examples of the same species.