POST
/
api
/
v1
/
contacts
/
{contact_id}
/
context

​
Set Contact Context Variables

Set context variables for a specific contact. These variables can be used for personalization in AI calls, templates, and other communications.

​
Endpoint

POST /api/v1/contacts/{contact_id}/context

​
Authentication

This endpoint requires an API key with the can_write_contacts permission.

​
Path Parameters

ParameterTypeRequiredDescription
contact_idintegerYesID of the contact

​
Request Body

ParameterTypeRequiredDescription
variablesobjectYesMap of variable names to values
auto_create_variablesbooleanNoWhether to automatically create undefined variables

​
Example Request Body

{
  "variables": {
    "last_payment_date": "2023-12-01",
    "membership_level": "Gold",
    "account_balance": 250.50,
    "is_active": true
  },
  "auto_create_variables": true
}

​
Response

{
  "message": "Contact context variables updated successfully",
  "contact_id": 123
}

​
Error Codes

Status CodeError CodeDescription
400invalid_jsonInvalid JSON payload
400invalid_valueA variable value doesn’t match its defined type
400undefined_variableA variable is not defined (when auto_create_variables is false)
401authentication_requiredNo API key was provided
401invalid_keyThe API key is invalid or inactive
403permission_deniedThe API key doesn’t have the required permission
404not_foundContact not found or you do not have access
500server_errorAn unexpected server error occurred

​
Example Request

curl -X POST 'https://api.klen.ai/api/v1/contacts/123/context' \
  -H 'Authorization: Bearer klen_abcdef123456789' \
  -H 'Content-Type: application/json' \
  -d '{
    "variables": {
      "last_payment_date": "2023-12-01",
      "membership_level": "Gold",
      "account_balance": 250.50,
      "is_active": true
    },
    "auto_create_variables": true
  }'

​
Example Response

{
  "message": "Contact context variables updated successfully",
  "contact_id": 123
}

​
Data Type Validation

Values are validated against the variable’s defined type:

TypeValid ValuesExamples
textAny string"Premium Support"
numberNumbers, numeric strings250.50, "42"
dateISO date strings"2023-12-01", "2023-01-15T14:30:00Z"
booleanBoolean values, boolean stringstrue, false, "true", "yes", "1"
selectValue from predefined optionsMust match one of the defined options

​
Auto-Creating Variables

When auto_create_variables is set to true:

  • If a variable name is not already defined, the system will create a new definition
  • The variable type will be inferred from the value
  • The display name will be generated from the variable name (e.g., last_payment_date → “Last Payment Date”)

When auto_create_variables is false (default):

  • All variable names must already be defined
  • Attempting to set an undefined variable will result in an error

​
Notes

  • You can only set variables for contacts that your account has access to
  • For select type variables, the value must match one of the defined options
  • Variable values are stored in the contact’s custom context
  • These variables are accessible in AI voice calls and other communications
  • You can update multiple variables in a single request
  • Setting a variable to null will remove it from the contact’s context