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 for details.

POST /projects/{projectIdOrName}/integrations/{integrationId}/objects/{objectName}

cURL

single-create

curl --request POST \
  --url https://write.withampersand.com/v1/projects/{projectIdOrName}/integrations/{integrationId}/objects/{objectName} \
  --header 'Content-Type: application/json' \
  --header 'X-Api-Key: <api-key>' \
  --data '
{
  "groupRef": "<groupRef>",
  "type": "create",
  "mode": "synchronous",
  "record": {
    "email": "[e-mail]",
    "warmthScore": "ready-for-close"
  }
}
'

200

single-success

{
  "operationId": "acb0d75a-1b59-4aad-a191-48c5b75ea9e4",
  "result": {
    "success": true,
    "recordId": "003xx000001",
    "data": {
      "email": "[e-mail]",
      "warmthScore": "ready-for-close"
    }
  }
}

Authorizations

X-Api-Key · string · header · required

Path Parameters

projectIdOrName · string · required

integrationId · string · required

objectName · string · required

Body

application/json

Write request

groupRef · string · required

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 · enum<string> · required

The type of write operation. The only supported types currently are create, update, and delete.

Available options: create, update, delete

Example:

"create"

mode · enum<string>

The mode of write operation.

Available options: synchronous, asynchronous

Example:

"synchronous"

retryPolicy · object

The retry policy for an asynchronous write operation. Ignored when autoBatchPolicy is specified.

Show child attributes

autoBatchPolicy · object

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.

Show child attributes

record · object

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.

Example:

{
  "email": "[e-mail]",
  "warmthScore": "ready-for-close"
}

batch · object[]

Write 1–100 records in one request. Omit this and use record instead when sending a single record. Partial writes are not supported; if any record in the batch is invalid, the entire batch fails. Batch is currently supported for create and update write requests.

Required array length: 1 - 100 elements

Show child attributes

associations · object[]

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 · object[]

To write headers to the record. Note: currently only Salesforce headers are supported

Show child attributes

Example:

[
  {
    "key": "custom-header-key1",
    "value": "custom-header-value1"
  },
  {
    "key": "custom-header-key2",
    "value": "custom-header-value2"
  }
]

Response

200

application/json

The success response

Sync Write Response Success

Batch Write Response

operationId · string · required

The operation ID

Example:

"acb0d75a-1b59-4aad-a191-48c5b75ea9e4"

result · Write Result · object

The result of the write operation. Only present for synchronous operations.

Show child attributes