Contacts API

These are the Contacts endpoints of the Keila API. For Keila Cloud, the base URL is https://app.keila.io.

All endpoints, unless stated differently, require Bearer authentication.

get /api/v1/contacts

Index contacts

Retrieve contacts from your project with support for pagination and filtering.

Parameters

Name	In	Type	Required	Description
paginate	query	object		Pagination
filter	query	string		Contact query as JSON string. Example: `"{\"email\":{\"$like\":\"%keila.io\"}}"`

Responses

200 Contact index response

dataobject[]
- dataobject
  Custom data fields
  Example: {"city":"Munich","interests":["chess","books"]}
- emailstring
  Example: "jane.doe@example.com"
- external_idstring
  Example: "abc-123"
- first_namestring
  Example: "Jane"
- idstring
  Contact ID
  Example: "c_12345"
- inserted_atstring
  Example: "2026-05-25T08:53:38.862437Z"
- last_namestring
  Example: "Doe"
- status"active" | "unsubscribed" | "unreachable"
  Example: "active"
- updated_atstring
  Example: "2026-05-25T08:53:38.862451Z"
metaobject
- pageinteger
  Current page of items (zero-indexed)
  Example: 0
- page_countinteger
  Number of total pages
  Example: 5
- page_sizeinteger
  Number of items per page
  Example: 50

post /api/v1/contacts

Create Contact

Request body

dataobject
- dataobject
  Custom data fields
  Example: {"city":"Munich","interests":["chess","books"]}
- emailstring required
  Example: "jane.doe@example.com"
- external_idstring
  Example: "abc-123"
- first_namestring
  Example: "Jane"
- last_namestring
  Example: "Doe"
- status"active" | "unsubscribed" | "unreachable"
  Example: "active"

Responses

200 Contact response

dataobject
- dataobject
  Custom data fields
  Example: {"city":"Munich","interests":["chess","books"]}
- emailstring
  Example: "jane.doe@example.com"
- external_idstring
  Example: "abc-123"
- first_namestring
  Example: "Jane"
- idstring
  Contact ID
  Example: "c_12345"
- inserted_atstring
  Example: "2026-05-25T08:53:38.862437Z"
- last_namestring
  Example: "Doe"
- status"active" | "unsubscribed" | "unreachable"
  Example: "active"
- updated_atstring
  Example: "2026-05-25T08:53:38.862451Z"

get /api/v1/contacts/{id}

Retrieve Contact

Parameters

Name	In	Type	Required	Description
id	path	string	yes	Contact ID (or email or external ID)
id_type	query	string		Specify this parameter if you want to use a Contact’s email or external_id to retrieve/update existing Contacts.

Responses

200 Contact response

dataobject
- dataobject
  Custom data fields
  Example: {"city":"Munich","interests":["chess","books"]}
- emailstring
  Example: "jane.doe@example.com"
- external_idstring
  Example: "abc-123"
- first_namestring
  Example: "Jane"
- idstring
  Contact ID
  Example: "c_12345"
- inserted_atstring
  Example: "2026-05-25T08:53:38.862437Z"
- last_namestring
  Example: "Doe"
- status"active" | "unsubscribed" | "unreachable"
  Example: "active"
- updated_atstring
  Example: "2026-05-25T08:53:38.862451Z"

put /api/v1/contacts/{id}

Update Contact

Parameters

Name	In	Type	Required	Description
id	path	string	yes	Contact ID (or email or external ID)
id_type	query	string		Specify this parameter if you want to use a Contact’s email or external_id to retrieve/update existing Contacts.

Request body

dataobject
- dataobject
  Custom data fields
  Example: {"city":"Munich","interests":["chess","books"]}
- emailstring
  Example: "jane.doe@example.com"
- external_idstring
  Example: "abc-123"
- first_namestring
  Example: "Jane"
- last_namestring
  Example: "Doe"
- status"active" | "unsubscribed" | "unreachable"
  Example: "active"

Responses

200 Contact response

dataobject
- dataobject
  Custom data fields
  Example: {"city":"Munich","interests":["chess","books"]}
- emailstring
  Example: "jane.doe@example.com"
- external_idstring
  Example: "abc-123"
- first_namestring
  Example: "Jane"
- idstring
  Contact ID
  Example: "c_12345"
- inserted_atstring
  Example: "2026-05-25T08:53:38.862437Z"
- last_namestring
  Example: "Doe"
- status"active" | "unsubscribed" | "unreachable"
  Example: "active"
- updated_atstring
  Example: "2026-05-25T08:53:38.862451Z"

patch /api/v1/contacts/{id}

Update Contact

Parameters

Name	In	Type	Required	Description
id	path	string	yes	Contact ID (or email or external ID)
id_type	query	string		Specify this parameter if you want to use a Contact’s email or external_id to retrieve/update existing Contacts.

Request body

dataobject
- dataobject
  Custom data fields
  Example: {"city":"Munich","interests":["chess","books"]}
- emailstring
  Example: "jane.doe@example.com"
- external_idstring
  Example: "abc-123"
- first_namestring
  Example: "Jane"
- last_namestring
  Example: "Doe"
- status"active" | "unsubscribed" | "unreachable"
  Example: "active"

Responses

200 Contact response

dataobject
- dataobject
  Custom data fields
  Example: {"city":"Munich","interests":["chess","books"]}
- emailstring
  Example: "jane.doe@example.com"
- external_idstring
  Example: "abc-123"
- first_namestring
  Example: "Jane"
- idstring
  Contact ID
  Example: "c_12345"
- inserted_atstring
  Example: "2026-05-25T08:53:38.862437Z"
- last_namestring
  Example: "Doe"
- status"active" | "unsubscribed" | "unreachable"
  Example: "active"
- updated_atstring
  Example: "2026-05-25T08:53:38.862451Z"

delete /api/v1/contacts/{id}

Delete Contact

Parameters

Name	In	Type	Required	Description
id	path	string	yes	Contact ID (or email or external ID)
id_type	query	string		Specify this parameter if you want to use a Contact’s email or external_id to retrieve/update existing Contacts.

Responses

204 Contact was deleted successfully or didn’t exist.

post /api/v1/contacts/{id}/data

Replace Contact data

Replace just the `data` field of a Contact with the provided data object.

Parameters

Name	In	Type	Required	Description
id	path	string	yes	Contact ID (or email or external ID)
id_type	query	string		Specify this parameter if you want to use a Contact’s email or external_id to retrieve/update existing Contacts.

Request body

dataobject
Custom data fields
Example: {"city":"Munich","interests":["chess","books"]}

Responses

200 Contact response

dataobject
- dataobject
  Custom data fields
  Example: {"city":"Munich","interests":["chess","books"]}
- emailstring
  Example: "jane.doe@example.com"
- external_idstring
  Example: "abc-123"
- first_namestring
  Example: "Jane"
- idstring
  Contact ID
  Example: "c_12345"
- inserted_atstring
  Example: "2026-05-25T08:53:38.862437Z"
- last_namestring
  Example: "Doe"
- status"active" | "unsubscribed" | "unreachable"
  Example: "active"
- updated_atstring
  Example: "2026-05-25T08:53:38.862451Z"

patch /api/v1/contacts/{id}/data

Update Contact data

Update just the `data` field of a Contact. The existing JSON object is merged in a shallow merge with the provided data object.

Parameters

Name	In	Type	Required	Description
id	path	string	yes	Contact ID (or email or external ID)
id_type	query	string		Specify this parameter if you want to use a Contact’s email or external_id to retrieve/update existing Contacts.

Request body

dataobject
Custom data fields
Example: {"city":"Munich","interests":["chess","books"]}

Responses

200 Contact response

dataobject
- dataobject
  Custom data fields
  Example: {"city":"Munich","interests":["chess","books"]}
- emailstring
  Example: "jane.doe@example.com"
- external_idstring
  Example: "abc-123"
- first_namestring
  Example: "Jane"
- idstring
  Contact ID
  Example: "c_12345"
- inserted_atstring
  Example: "2026-05-25T08:53:38.862437Z"
- last_namestring
  Example: "Doe"
- status"active" | "unsubscribed" | "unreachable"
  Example: "active"
- updated_atstring
  Example: "2026-05-25T08:53:38.862451Z"