> ## Documentation Index
> Fetch the complete documentation index at: https://agents.nanonets.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Salesforce Bulk Create

> Creates many Salesforce records of one object in a single call, returning the new ID or the error for every record you sent.

Creates many records of one Salesforce object in a single call and returns a result for **every** record you sent: its new ID, or the error for that row. Display name **"Salesforce Bulk Create"**. Off by default.

Use it instead of calling `salesforce_create_record` once per record whenever there is more than one to write. One call writes them all, and the per-record results mean a partial write cannot be mistaken for a complete one.

## Authentication and enablement

Needs an active **Salesforce** integration in the workspace. The access token and the org's `instance_url` are injected from that integration. The connected user needs create permission on the object.

Off by default. Enable it per agent.

## Inputs

* `object` — **required.** Salesforce object API name, e.g. `VI_Line_Item__c`.
* `records` — **required.** A JSON **array string**. Each element is an object of field API names to values, exactly like the `fields` argument of Salesforce Create Record. Send every record you need written in one call. Example: `[{"Name__c":"Line 1","Amount__c":100},{"Name__c":"Line 2","Amount__c":250}]`. At most **2000** records per call; every record needs at least one field.
* `all_or_none` — optional, default `false`. When `false`, records that pass are created and the ones that fail are reported individually. When `true`, a failure rolls back the other records **in the same batch of 200**.

`records` is a JSON string rather than an array of objects for the same reason the other Salesforce write tools take `fields` as a string: the element would have to be a property-less object, which Gemini function-calling rejects.

## Output

Structured result: `requested_count`, `created_count`, `failed_count`, `all_or_none`, `record_ids[]`, `warnings[]`, `completed_at`, and `results[]` with one entry per requested record — `index` (its position in `records`), `record_id`, `success`, `error`.

When every record lands, the summary reads `Created N of N …`. When any did not, the summary **starts with `PARTIAL:`**, gives the shortfall, and names the first few row errors.

A partial run is still a **success** result, not an error: the records that were created really exist, and an error result would invite a retry that duplicates them. Read `created_count` against `requested_count` before treating the export as complete.

## Limits and side effects

* Creates records only; never updates or deletes.
* Salesforce caps its sObject Collections endpoint at **200** records per request, so a larger call is sent as several requests of 200. Record order and `index` are preserved across them.
* With `all_or_none: true` and more than 200 records, the rollback covers **each batch separately, not the whole call**. The tool adds a warning saying so rather than implying a guarantee it cannot give.
* The bulk insert is **never retried automatically**. A create is not idempotent, and the shared HTTP client retries on timeouts and `5xx`, which on this endpoint would re-send up to 200 records that Salesforce may already have committed. One failed call you can investigate beats 200 silent duplicates.
* If one request fails outright (network, `5xx`, an expired session), the tool **stops**. `results` still holds exactly one row per record you requested, in one of three states:
  * **created** — `success: true` with a `record_id`.
  * **rejected** — Salesforce answered and refused the row. Nothing was written; fix it and send it again.
  * **unknown** — the request carrying this row failed in flight, so Salesforce *may* have committed it. `unknown_count` counts these. **Check in Salesforce before re-sending**; a blind retry can duplicate them.
  * **not attempted** — the run stopped before the row was sent. Safe to send again as-is.
* If **nothing was created at all** — whether the request failed in flight or Salesforce accepted it and rejected every row — the result is an **error** carrying `status: "limitation"`, so the step records a failure rather than a completed run that wrote nothing. It is a limitation, not an ordinary error, so the platform hands it back to the agent instead of retrying: an in-flight batch may already be committed, and an all-rows-rejected batch would be rejected identically.

## Expected errors

* `no Salesforce access token was provided…` / `no Salesforce instance_url was provided…` — no active integration, or it needs reconnecting.
* `records is required and must be a JSON array string…`, `records must contain at least one record`, `record N is empty…`, `records has N entries; at most 2000…` — validation; nothing was written.
* `salesforce returned N results for M records; cannot match ids to records` — a malformed reply. That batch is reported as **unknown**, not as failed: the request reached Salesforce and may have been committed.
* Per-row failures are **not** call errors. They appear in `results[].error` with Salesforce's own code and fields, e.g. `FIELD_CUSTOM_VALIDATION_EXCEPTION: Amount is required (fields: Amount__c)`.
* `salesforce session expired or invalid…`, `salesforce API request limit exceeded…` — operational.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.