Contact properties

A contact property declares one custom field: a key, a display name and a type. The values themselves live on each contact, in its attributes object under that key (see Contacts). Declaring the property is what gives those values a type. Without one, a value imported as "42" stays a string, and a segment filter such as gt with the number 9 never matches it, because numbers and strings are not compared with each other (and with the string "9" it compares as text, so "42" is not greater).

The type is applied when a value is written, not afterwards:

Coercion happens when contacts are added or imported, and when a contact is updated with PATCH /v1/contacts/{id}. For a declared property, the same JSON value is stored the same way on every one of those paths. For a key with no declared property they differ: adding or importing contacts through the API creates the property for you, with type string and the key as its name, so 5 is stored as "5", while PATCH stores the value exactly as sent and creates no property. Attribute keys only have to be non-empty, free of . and null characters, and not start with $; they do not have to follow the letters, digits and underscores rule that creating a property enforces, so an attribute key such as sign-up source creates a property whose key this endpoint would reject. Declare number and boolean properties before importing, so values arrive typed.

Changing a property's type later does not convert the values already stored on contacts.

The contact property object

Every field is always present.

List properties

GET /v1/contact-properties · requires contacts:read

Every property declared in the workspace, sorted by name, in the list envelope. The list is not paged and not capped: every property is in data, has_more is always false and next_cursor is always null.

Example

curl https://api.sendraven.ai/v1/contact-properties \
  -H "Authorization: Bearer $SENDRAVEN_API_KEY"

Response

200 OK

{
  "object": "list",
  "data": [
    {
      "id": "0d4b8e2a-7c61-4f3e-a95b-2e8c1d7f6a34",
      "key": "plan",
      "name": "Plan",
      "type": "string",
      "created_at": "2026-09-01T10:30:00.000Z"
    },
    {
      "id": "6e2f9a1b-3c8d-4b7e-9f5a-1c4d8e2b7a63",
      "key": "seats",
      "name": "Seats",
      "type": "number",
      "created_at": "2026-09-01T10:31:12.000Z"
    }
  ],
  "has_more": false,
  "next_cursor": null
}

Create or update a property

POST /v1/contact-properties · requires contacts:write

Declares a property, keyed on key. When no property with that key exists, it is created with 201. When one already exists, its name is replaced, and its type too when you send one, and the call answers 200 with the updated property, so the call is safe to repeat. Leaving type out keeps the existing property's type, or uses string for a new one.

Keys are matched exactly, including case: Plan and plan are two different properties.

Body

Example

curl -X POST https://api.sendraven.ai/v1/contact-properties \
  -H "Authorization: Bearer $SENDRAVEN_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "key": "seats",
    "name": "Seats",
    "type": "number"
  }'

Response

201 Created for a new property, 200 OK when the key already existed. Either way the body is the property object.

{
  "id": "6e2f9a1b-3c8d-4b7e-9f5a-1c4d8e2b7a63",
  "key": "seats",
  "name": "Seats",
  "type": "number",
  "created_at": "2026-09-15T12:00:00.000Z"
}

Errors

Delete a property

DELETE /v1/contact-properties/{key} · requires contacts:write

Removes the property's definition. The values stay on every contact that has them, in attributes, and segment filters on the key keep working, because they read the contact's attributes directly. Only the declaration goes: new values for the key are no longer coerced, and adding or importing contacts through the API with that key creates the property again as string.

A key that no property in the workspace has answers 404 not_found, so a typo in the key is not reported as a deletion.

Path parameters

Example

curl -X DELETE https://api.sendraven.ai/v1/contact-properties/seats \
  -H "Authorization: Bearer $SENDRAVEN_API_KEY"

Response

200 OK

{
  "key": "seats",
  "deleted": true,
  "values_kept": true
}

Errors