Update a contact property

Rename a property, or change the value it falls back to.

PATCH /v1/contact-properties/{id}

Requires a Full access API key.

Path parameters

Parameter	Type	Required	Description
id	string	Yes	The contact property id.

Body parameters

Parameter	Type	Required	Description
key	string	No	A new key. Same format rules as on create, and still unique within your team. Renaming changes the merge tag your templates must render.
fallback_value	string | null	No	The value to render when a contact has no value of its own. Must be numeric for a number property. Send null to clear it.

type cannot be changed

The type is fixed at creation. Sending it here is rejected with 422 rather than ignored — see Create a contact property.

Example

curl

curl -X PATCH "https://api.sendgrail.com/v1/contact-properties/$PROPERTY_ID" \
  -H "Authorization: Bearer $SENDGRAIL_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{ "fallback_value": "Example Company" }'

Node.js

await fetch(`https://api.sendgrail.com/v1/contact-properties/${id}`, {
  method: 'PATCH',
  headers: {
    Authorization: `Bearer ${process.env.SENDGRAIL_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ fallback_value: 'Example Company' }),
});

Response

The updated object:

{
  "object": "contact_property",
  "id": "b6d24b8e-af0b-4c3c-be0c-359bbd97381e",
  "key": "company_name",
  "type": "string",
  "fallback_value": "Example Company",
  "created_at": "2026-07-14T19:44:32+00:00"
}

Renaming is a template change

The key is the merge tag. Rename company_name to company, and every template still rendering {{{contact.company_name}}} now renders nothing — the tag no longer matches a property, so it resolves empty.

Update your templates in the same change, or leave the key alone and only move the fallback_value.