Write records

Create or update records in a SaaS instance, synchronously or asynchronously. See Write actions for details.

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

Write records

cURL

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": "<string>",
  "type": "create",
  "mode": "synchronous",
  "retryPolicy": {
    "deadlineHours": 24
  },
  "autoBatchPolicy": {
    "maxDelayMinutes": 5,
    "retryDeadlineHours": 2
  },
  "record": {
    "email": "[e-mail]",
    "warmthScore": "ready-for-close"
  },
  "batch": [
    {
      "record": {
        "email": "[e-mail]",
        "warmthScore": "ready-for-close"
      },
      "associations": [
        {
          "to": {
            "id": "18417469260"
          },
          "types": [
            {
              "associationCategory": "HUBSPOT_DEFINED",
              "associationTypeId": 279
            }
          ]
        }
      ]
    }
  ],
  "associations": [
    {
      "to": {
        "id": "18417469260"
      },
      "types": [
        {
          "associationCategory": "HUBSPOT_DEFINED",
          "associationTypeId": 279
        }
      ]
    }
  ],
  "headers": [
    {
      "key": "custom-header-key1",
      "value": "custom-header-value1"
    },
    {
      "key": "custom-header-key2",
      "value": "custom-header-value2"
    }
  ]
}
'

200

{
  "operationId": "acb0d75a-1b59-4aad-a191-48c5b75ea9e4",
  "result": {
    "success": true,
    "data": {
      "email": "[e-mail]"
    },
    "recordId": "003Dp0X#@RG7IAP"
  }
}

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 and update.

Available options: create, update

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. Only available for asynchronous mode and single-record writes.

Show child attributes

record · object

The record to write. Use this for single record mode. Exactly one of 'record' or 'batch' must be provided.

Example:

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

batch · object[]

Multiple records to write (batch mode). Supports 1-100 records per batch. Partial writes are not supported. If any record in a batch is invalid, all records in the batch will fail. Exactly one of 'record' or 'batch' must be provided.

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