Skip to content

Updating records that have connect fields

If your integration reads a record, changes a field, and then writes the whole record back as-provided (a read-modify-write), be careful with connect fields. Writing a record back as read could delete its connections unintentionally.

Why this happens

Connect field values aren't stored on the record the way other custom fields are. You read and manage them through their own connect field endpoints.

When reading a record, its connect fields appear in custom_fields with a value of [], no matter how many connections exist. The connections themselves only come back from the List the connections on specified entity endpoint.

An update replaces a field with whatever you send (see Update an Opportunity), and an empty connect value means "remove all connections". So sending back the custom_fields you read deletes every connection on that field, in both directions.

Example

Opportunity 2827698 has a "Key Contacts" connect field (custom_field_definition_id 126144) with three connected people.

Reading the opportunity returns that field as an empty array. The three connections aren't included, you only get them from List the connections on specified entity:

{
  "id": 2827698,
  "name": "New Copy Machines",
  "details": "Original details",
  "custom_fields": [
    { "custom_field_definition_id": 126144, "value": [] }
  ]
}

Deletes the connections

Sending that response back to change details sends the connect field as [] too, so all three connections are removed:

curl --location --request PUT "https://api.copper.com/developer_api/v1/opportunities/2827698" \
  --header "X-PW-AccessToken: YOUR_TOKEN_HERE" \
  --header "X-PW-Application: developer_api" \
  --header "X-PW-UserEmail: YOUR_EMAIL_HERE" \
  --header "Content-Type: application/json" \
  --data "{
    \"details\": \"Updated details\",
    \"custom_fields\": [
      { \"custom_field_definition_id\": 126144, \"value\": [] }
    ]
  }"

Keeps the connections

Send only the fields you're actually changing, and leave connect fields out of the request:

curl --location --request PUT "https://api.copper.com/developer_api/v1/opportunities/2827698" \
  --header "X-PW-AccessToken: YOUR_TOKEN_HERE" \
  --header "X-PW-Application: developer_api" \
  --header "X-PW-UserEmail: YOUR_EMAIL_HERE" \
  --header "Content-Type: application/json" \
  --data "{
    \"details\": \"Updated details\"
  }"

The three "Key Contacts" connections are left untouched.

Working with connect field values

Read and manage connections through their own dedicated endpoints, not through custom_fields: