Skip to main content
POST
/
projects
/
{projectIdOrName}
/
integrations
/
{integrationId}
/
objects
/
{objectName}
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": "david@withampersand.com",
    "warmthScore": "ready-for-close"
  }
}
'
{
  "operationId": "acb0d75a-1b59-4aad-a191-48c5b75ea9e4",
  "result": {
    "success": true,
    "recordId": "003xx000001",
    "data": {
      "email": "david@withampersand.com",
      "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.

​
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.

​
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": "david@withampersand.com",
  "warmthScore": "ready-for-close"
}
​
batchPolicy
object

Policy settings for batch write operations. Only applicable when using the batch field.

​
batch
object[]

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. Batch is currently supported for create and update write requests.

Required array length: 1 - 100 elements
​
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

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

Response

The success 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.