API reference

Contact properties API

Reference for declaring, listing, retrieving, updating and deleting custom contact properties.

The contact properties API manages the custom fields of the project that owns your API key. Every endpoint needs a full_access key. For the concepts, see Contact properties.

The contact property object

JSON

{
  "object": "contact_property",
  "id": "jp8c3v6x9z2m5n1b4q7w0e3r",
  "key": "company",
  "type": "string",
  "fallback_value": "your team",
  "created_at": "2026-11-14T10:00:00.000Z"
}

Create a contact property

POST/contact-properties

Field	Type	Required	Description
`key`	string	Yes	Letters, digits and underscore, 1 to 50 characters. Unique in the project.
`type`	string	Yes	`string` or `number`. It cannot be changed later.
`fallback_value`	string, number or null	No	Must match `type`. Used in broadcasts when a contact has no value.

Shell

curl -X POST https://api.sooner.dev/contact-properties \
  -H "Authorization: Bearer $SOONER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "key": "company", "type": "string", "fallback_value": "your team" }'

JSON

{ "object": "contact_property", "id": "jp8c3v6x9z2m5n1b4q7w0e3r" }

Notable errors: validation_error for an invalid key, a key that already exists, or a fallback_value of the wrong type.

List contact properties

GET/contact-properties

Returns every property in the project. The list is not paginated.

Shell

curl https://api.sooner.dev/contact-properties \
  -H "Authorization: Bearer $SOONER_API_KEY"

JSON

{
  "object": "list",
  "data": [
    {
      "object": "contact_property",
      "id": "jp8c3v6x9z2m5n1b4q7w0e3r",
      "key": "company",
      "type": "string",
      "fallback_value": "your team",
      "created_at": "2026-11-14T10:00:00.000Z"
    }
  ],
  "has_more": false
}

Retrieve a contact property

GET/contact-properties/{id}

Returns one property in the shape above. Notable errors: not_found.

Update a contact property

PATCH/contact-properties/{id}

Only the fallback can change.

Field	Type	Required	Description
`fallback_value`	string, number or null	No	The new fallback.

Shell

curl -X PATCH https://api.sooner.dev/contact-properties/jp8c3v6x9z2m5n1b4q7w0e3r \
  -H "Authorization: Bearer $SOONER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "fallback_value": "there" }'

JSON

{ "object": "contact_property", "id": "jp8c3v6x9z2m5n1b4q7w0e3r" }

Delete a contact property

DELETE/contact-properties/{id}

Shell

curl -X DELETE https://api.sooner.dev/contact-properties/jp8c3v6x9z2m5n1b4q7w0e3r \
  -H "Authorization: Bearer $SOONER_API_KEY"

JSON

{ "object": "contact_property", "id": "jp8c3v6x9z2m5n1b4q7w0e3r", "deleted": true }