> ## Documentation Index > Fetch the complete documentation index at: https://docs.withampersand.com/llms.txt > Use this file to discover all available pages before exploring further. # Write records > Create, update, or delete records in a SaaS instance. Create and update support synchronous or asynchronous mode; delete is synchronous only. See [Write actions](https://docs.withampersand.com/write-actions) for details. ## OpenAPI ````yaml write post /projects/{projectIdOrName}/integrations/{integrationId}/objects/{objectName} openapi: 3.0.1 info: title: Ampersand public write API version: 1.0.0 servers: - url: https://write.withampersand.com/v1 security: - APIKeyHeader: [] paths: /projects/{projectIdOrName}/integrations/{integrationId}/objects/{objectName}: post: tags: - Write summary: Write records description: >- Create, update, or delete records in a SaaS instance. Create and update support synchronous or asynchronous mode; delete is synchronous only. See [Write actions](https://docs.withampersand.com/write-actions) for details. operationId: writeRecords parameters: - name: projectIdOrName in: path required: true schema: type: string - name: integrationId in: path required: true schema: type: string - name: objectName in: path required: true schema: type: string requestBody: description: Write request required: true content: application/json: schema: title: Write Request type: object required: - groupRef - type properties: groupRef: type: string description: >- The ID of the user group whose SaaS instance you'd like to write data to. This is the ID that was provided during installation creation. type: type: string description: >- The type of write operation. The only supported types currently are create, update, and delete. enum: - create - update - delete example: create mode: type: string description: The mode of write operation. enum: - synchronous - asynchronous example: synchronous retryPolicy: type: object description: >- The retry policy for an asynchronous write operation. Ignored when autoBatchPolicy is specified. properties: deadlineHours: type: integer description: >- The maximum number of hours to wait for the write operation to complete. If not specified, defaults to 1 hour. example: 24 default: 1 minimum: 1 maximum: 48 autoBatchPolicy: type: object description: > The auto-batch policy for asynchronous single-record write operations. When enabled, multiple single-record write requests are automatically grouped together and executed as a batch. The batch executes when either 100 records accumulate or the maximum delay time expires. Auto batching is currently only available for asynchronous mode and single-record writes. properties: maxDelayMinutes: type: integer description: > The maximum time to wait before executing the batch, even if it hasn't reached 100 records. Once this time expires, the batch will be executed even if it hasn't reached the limit. example: 5 minimum: 1 maximum: 1440 retryDeadlineHours: type: integer description: > The maximum time to keep retrying the batch write operation if it fails. If not specified, defaults to 1 hour. example: 2 default: 1 minimum: 1 maximum: 48 required: - maxDelayMinutes record: type: object description: > The record to write. Use this when sending a single record. Omit this and use `batch` instead when sending multiple records in one request. For create and update, include the record fields. For delete, only the record `id` is required; deletion must be enabled for this object in the installation config. additionalProperties: true example: email: david@withampersand.com warmthScore: ready-for-close batchPolicy: type: object description: > Policy settings for batch write operations. Only applicable when using the `batch` field. properties: allOrNone: type: boolean description: > When set to `true`, the entire batch will fail if any record in the batch fails. When set to `false` (default), partial writes are supported — successful records will be committed even if some fail. Note: HubSpot batch updates always result in partial success due to a provider limitation, regardless of this setting. default: false example: true batch: type: array description: > Write 1–100 records in one request. Omit this and use `record` instead when sending a single record. The default behavior is partial success, i.e., successful records will be committed even if some records in the batch fail. To disable partial writes and fail the entire batch, use the `allOrNone` flag in your request. See [`batchPolicy.allOrNone`](#/components/schemas/WriteRequest/properties/batchPolicy). Batch is currently supported for create and update write requests. minItems: 1 maxItems: 100 items: type: object required: - record properties: record: type: object description: The record to write additionalProperties: true example: email: david@withampersand.com warmthScore: ready-for-close associations: type: array items: type: object description: >- To write associations to the record. Note: currently only HubSpot associations are supported example: - to: id: '18417469260' types: - associationCategory: HUBSPOT_DEFINED associationTypeId: 279 associations: type: array items: type: object description: >- To write associations to the record (for single record mode). Note: currently only HubSpot associations are supported example: - to: id: '18417469260' types: - associationCategory: HUBSPOT_DEFINED associationTypeId: 279 headers: type: array items: type: object properties: key: type: string description: The key of the header value: type: string description: The value of the header description: >- To write headers to the record. Note: currently only Salesforce headers are supported example: - key: custom-header-key1 value: custom-header-value1 - key: custom-header-key2 value: custom-header-value2 examples: single-create: summary: Single record create value: groupRef: type: create mode: synchronous record: email: david@withampersand.com warmthScore: ready-for-close single-create-associations: summary: Single create with associations (HubSpot) value: groupRef: type: create mode: synchronous record: email: david@withampersand.com warmthScore: ready-for-close associations: - to: id: '18417469260' types: - associationCategory: HUBSPOT_DEFINED associationTypeId: 279 single-update: summary: Single record update value: groupRef: type: update mode: synchronous record: id: 003xx000001 email: david@withampersand.com warmthScore: ready-for-close single-delete: summary: Single record delete value: groupRef: type: delete record: id: 003xx000001 batch-create: summary: Batch create value: groupRef: type: create mode: synchronous batchPolicy: allOrNone: true batch: - record: email: david@withampersand.com warmthScore: ready-for-close - record: email: hermione@withampersand.com warmthScore: ready-for-close auto-batch-create: summary: Async create with auto-batch policy value: groupRef: type: create mode: asynchronous autoBatchPolicy: maxDelayMinutes: 5 retryDeadlineHours: 2 record: email: david@withampersand.com warmthScore: ready-for-close responses: '200': description: The success response content: application/json: schema: oneOf: - title: Sync Write Response Success type: object required: - operationId additionalProperties: false properties: result: description: >- The result of the write operation. Only present for synchronous operations. title: Write Result type: object required: - success additionalProperties: false properties: success: type: boolean description: Whether the operation was successful example: true data: type: object description: >- The data returned by the operation. This field is only populated when there is a raw response from the provider. example: email: david@ampersand.com recordId: type: string description: >- The ID of the record. Only present on a successful create or update. example: 003Dp0X#@RG7IAP operationId: type: string description: The operation ID example: acb0d75a-1b59-4aad-a191-48c5b75ea9e4 - title: Batch Write Response type: object required: - operationId - successCount - failureCount additionalProperties: false properties: operationId: type: string description: The operation ID example: acb0d75a-1b59-4aad-a191-48c5b75ea9e4 results: type: array description: Per-record results returned by the provider items: title: Write Result type: object required: - success additionalProperties: false properties: success: type: boolean description: Whether the operation was successful example: true data: type: object description: >- The data returned by the operation. This field is only populated when there is a raw response from the provider. example: email: david@ampersand.com recordId: type: string description: >- The ID of the record. Only present on a successful create or update. example: 003Dp0X#@RG7IAP successCount: type: integer description: Number of records that succeeded example: 3 failureCount: type: integer description: Number of records that failed example: 1 errors: type: array description: Top-level errors returned by the provider, if any items: type: object properties: message: type: string description: Error summary message example: >- Batch write failed: provider rolled back all records examples: single-success: summary: Single record success value: operationId: acb0d75a-1b59-4aad-a191-48c5b75ea9e4 result: success: true recordId: 003xx000001 data: email: david@withampersand.com warmthScore: ready-for-close batch-success: summary: Batch success value: operationId: acb0d75a-1b59-4aad-a191-48c5b75ea9e4 successCount: 2 failureCount: 0 results: - success: true recordId: 003xx000001 - success: true recordId: 003xx000002 '400': description: The failure response for bad request. content: text/plain: schema: type: string example: required field not found '422': description: Error encountered while creating records content: application/json: schema: oneOf: - title: Sync Write Response Failure type: object required: - errors - operationId additionalProperties: false properties: rawResponse: type: string description: The raw response from the provider, if available example: '{"error": "Record not found"}' x-go-type-skip-optional-pointer: true errors: type: array description: Error messages resulted in failures items: type: object properties: message: type: string description: >- errors messages when some unexpected event happened, but write to provider was successful example: The record with ID 003Dp0X#@RG7IAP was not found result: title: Write Result type: object required: - success additionalProperties: false properties: success: type: boolean description: Whether the operation was successful example: true data: type: object description: >- The data returned by the operation. This field is only populated when there is a raw response from the provider. example: email: david@ampersand.com recordId: type: string description: >- The ID of the record. Only present on a successful create or update. example: 003Dp0X#@RG7IAP warnings: type: array description: >- Warnings messages when some unexpected event happened, but not blocking failures items: type: object properties: message: type: string description: >- errors messages when some unexpected event happened, but write to provider was successful example: The record with ID 003Dp0X#@RG7IAP was not found operationId: type: string description: The operation ID example: acb0d75a-1b59-4aad-a191-48c5b75ea9e4 - title: Batch Write Response type: object required: - operationId - successCount - failureCount additionalProperties: false properties: operationId: type: string description: The operation ID example: acb0d75a-1b59-4aad-a191-48c5b75ea9e4 results: type: array description: Per-record results returned by the provider items: title: Write Result type: object required: - success additionalProperties: false properties: success: type: boolean description: Whether the operation was successful example: true data: type: object description: >- The data returned by the operation. This field is only populated when there is a raw response from the provider. example: email: david@ampersand.com recordId: type: string description: >- The ID of the record. Only present on a successful create or update. example: 003Dp0X#@RG7IAP successCount: type: integer description: Number of records that succeeded example: 3 failureCount: type: integer description: Number of records that failed example: 1 errors: type: array description: Top-level errors returned by the provider, if any items: type: object properties: message: type: string description: Error summary message example: >- Batch write failed: provider rolled back all records examples: single-fail: summary: Single record failure value: operationId: acb0d75a-1b59-4aad-a191-48c5b75ea9e4 errors: - message: The record with ID 003xx000001 was not found result: success: false batch-fail: summary: Batch failure value: operationId: acb0d75a-1b59-4aad-a191-48c5b75ea9e4 successCount: 0 failureCount: 2 errors: - message: 'Batch write failed: provider rolled back all records' default: description: Error content: application/problem+json: schema: title: API Problem type: object allOf: - title: Problem description: > A Problem Details object (RFC 9457). Additional properties specific to the problem type may be present. type: object properties: type: type: string format: uri description: An absolute URI that identifies the problem type default: about:blank href: type: string format: uri description: >- An absolute URI that, when dereferenced, provides human-readable documentation for the problem type (e.g. using HTML). title: type: string description: >- A short summary of the problem type. Written in English and readable for engineers (usually not suited for non technical stakeholders and not localized). example: Service Unavailable status: type: integer format: int32 description: >- The HTTP status code generated by the origin server for this occurrence of the problem. minimum: 400 maximum: 600 exclusiveMaximum: true example: 503 detail: type: string description: >- A human-readable explanation specific to this occurrence of the problem instance: type: string format: uri description: >- An absolute URI that identifies the specific occurrence of the problem. It may or may not yield further information if dereferenced. example: type: urn:problem-type:exampleOrganization:exampleProblem href: >- https://www.belgif.be/specification/rest/api-guide/#standardized-problem-types title: Description of the type of problem that occurred status: 400 detail: Description of specific occurrence of the problem instance: urn:uuid:123e4567-e89b-12d3-a456-426614174000 properties: subsystem: type: string description: The subsystem that generated the problem example: api time: type: string format: date-time description: The time the problem occurred, formatted as RFC-3339 example: '2024-04-22T18:55:28.456076Z' requestId: type: string description: A unique identifier for the request, useful for debugging example: 89eb1ffb-2a54-4105-aaae-7bf990f1aa69#87715 causes: type: array items: type: string description: >- A brief description of something which caused the problem example: database connection failed example: - database connection failed - database query failed - unable to fetch user description: > A list of problems that caused this problem. This can be used to represent multiple root causes. There is no guaranteed ordering of the causes. remedy: type: string description: A brief description of how to resolve the problem example: Shorten your input to be under 100 characters supportEmail: type: string format: email description: An email address to contact for support example: support@withampersand.com supportPhone: type: string description: A phone number to contact for support example: +1-555-555-5555 supportUrl: type: string format: uri description: A URL to contact for support example: https://withampersand.com/support retryable: type: boolean description: Whether the request can be retried example: false retryAfter: type: string format: date-time description: >- A timestamp after which the request can be retried, formatted as RFC-3339 example: '2024-04-22T18:55:28.456076Z' context: type: object description: Additional context for the problem additionalProperties: true example: name: Rick Sanchez components: securitySchemes: APIKeyHeader: type: apiKey name: X-Api-Key in: header ````