Create a contact property

Create a custom field that every contact can carry.

POST /v1/contact-properties

Requires a Full access API key — properties shape your audience, so a sending key embedded in an app cannot create them.

Body parameters

Parameter	Type	Required	Description
key	string	Yes	The property key, and the merge tag you render in a template. Max 50 characters; letters, numbers and underscores. Unique within your team.
type	string	Yes	string or number. Fixed at creation — see below.
fallback_value	string | null	No	The value to render when a contact has no value of its own. For a number property it must itself be numeric.

Example

curl

curl -X POST 'https://api.sendgrail.com/v1/contact-properties' \
  -H "Authorization: Bearer $SENDGRAIL_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "key": "company_name",
    "type": "string",
    "fallback_value": "Acme Corp"
  }'

Node.js

const res = await fetch('https://api.sendgrail.com/v1/contact-properties', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.SENDGRAIL_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    key: 'company_name',
    type: 'string',
    fallback_value: 'Acme Corp',
  }),
});

const property = await res.json();

Response

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

The key is a merge tag

Whatever you set as key is what a template renders:

Hello {{{contact.company_name}}}

That is why the format is restricted — a key with a space or a dash in it would not survive a template. It's also why key is unique per team: two properties answering to the same tag would make the rendered value a coin toss.

Renaming a key later is allowed, and it changes what your templates must render. Anything still rendering the old tag falls back to empty.

The type cannot be changed

type is fixed once the property exists. Changing string to number would silently invalidate every value already stored against it — "Acme Corp" is not a number, and there is no sensible thing to do with it.

Send type on an update and it's rejected, not ignored:

{
  "message": "The type cannot be changed after the property is created.",
  "code": "validation_error",
  "errors": {
    "type": ["The type cannot be changed after the property is created."]
  },
  "request_id": "8f2c1e64-1b17-4f8c-9f0e-3b6c1e0f5c31"
}

A 200 there would be worse: you'd believe the type had changed when it hadn't. To change a type, delete the property and create it again — and be aware that deleting it clears that value from every contact.