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

# Discover schema and work with records

> Inspect actor-visible objects and fields, create related records, and choose a composite request.

Use this guide to prepare Salesforce test data and verify record writes. First [connect to the environment](/environments/credentials) with the actor your integration uses.

The HTTP excerpts show paths and bodies. Send them through your authenticated client at the returned app URL. Replace `{version}` with a served API version and `{recordId}` with an ID returned by a previous request.

## Discover the schema for your actor

1. Request `GET /services/data`. Select a version from the response and confirm that the app version supports the protocol you need.
2. Request `GET /services/data/v{version}/sobjects`. Find the object's API name, such as `Account`, and inspect its operation flags.
3. Request `GET /services/data/v{version}/sobjects/Account/describe`. Inspect the fields and relationships before building a payload.

Use API names in requests. Check `createable` and `updateable` on both the object and its fields. For create payloads, check `nillable`, `defaultedOnCreate`, and field defaults. Inspect `picklistValues` for choices, and `referenceTo` for the objects a relationship field accepts.

Describe reflects the selected actor and API version. If an expected field is missing, confirm both before changing the payload. Record rules can impose requirements beyond describe, so retain the API error body when a write fails.

## Create and read a record

Create a fictitious account:

```http theme={null}
POST /services/data/v{version}/sobjects/Account
Content-Type: application/json

{"Name":"Juniper Sample Company","Description":"Integration test fixture"}
```

Expect HTTP `201` and a body containing `id`, `success`, and `errors`. Save the returned `id` as your record ID.

Read the fields your test needs:

```http theme={null}
GET /services/data/v{version}/sobjects/Account/{recordId}?fields=Id,Name,Description
```

Expect HTTP `200` with the selected fields. Use the returned ID for later requests. Do not construct an ID from a name or an assumed sequence.

## Update and verify a record

Send only the fields to change:

```http theme={null}
PATCH /services/data/v{version}/sobjects/Account/{recordId}
Content-Type: application/json

{"Description":"Updated integration test fixture"}
```

Expect HTTP `204` with no JSON body. Read the record again and assert the stored value. Some predefined record rules derive or constrain values, so a successful write alone does not prove your intended final state.

To remove the fixture, send `DELETE /services/data/v{version}/sobjects/Account/{recordId}`. A successful delete returns `204`. Use [queryAll](/apps/salesforce-query) when your test needs to inspect soft-deleted records.

## Link records in a composite request

To create an account and its contact in one request, use `/composite` with reference substitution. This example rolls back both writes if a subrequest fails:

```http theme={null}
POST /services/data/v{version}/composite
Content-Type: application/json

{
	"allOrNone": true,
	"compositeRequest": [
		{
			"method": "POST",
			"url": "/services/data/v{version}/sobjects/Account",
			"referenceId": "account",
			"body": {"Name": "Juniper Sample Company"}
		},
		{
			"method": "POST",
			"url": "/services/data/v{version}/sobjects/Contact",
			"referenceId": "contact",
			"body": {"LastName": "Example", "AccountId": "@{account.id}"}
		}
	]
}
```

Replace the version placeholder in the outer path and both subrequest URLs. Inspect each `compositeResponse` item's `httpStatusCode` and `body`. An HTTP `200` outer response can contain failed subrequests.

Choose another composite operation when its transaction behavior fits your task:

* Use sObject Collections for groups of record creates, reads, updates, upserts, or deletes. Inspect every record result. Write operations support `allOrNone`.
* Use `/composite/batch` for independent requests. Each request commits separately. `haltOnError` stops later requests after a failure and leaves earlier successes committed.
* Use `/composite/graph` for groups of dependent writes. Each graph succeeds or rolls back independently.
* Use `/composite/tree/{object}` for a nested tree of new related records.

## Use external IDs without assuming a custom field

Inspect describe for a field marked `externalId` or `idLookup`. Use that field only if it exists in this app version and is available to your actor.

Retrieve with `GET /sobjects/{object}/{field}/{value}` or upsert with `PATCH /sobjects/{object}/{field}/{value}`, relative to the selected REST version. URL-encode the external value as one path segment. An upsert creates a record when no match exists and updates the match when one exists. Multiple matches return HTTP `300` with the matching record URLs and change nothing.

Do not add a made-up `__c` field to a request to create schema. Record endpoints accept fields from the catalog. Public environment settings do not install a custom schema. See [known differences](/apps/known-differences).


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