Update Contact Value

Updates a single field value for a contact.

PUT /v1/funnels/{funnelId}/contacts/{contactId}/values

This endpoint updates one field at a time, identified by fieldName. Standard contact fields, address sub-fields, and custom properties are all supported. Any fieldName that is not a known field and not a reserved system field is stored as a custom property under the contact's properties map.

Authentication

Requires the x-perspective-api-key header. See Authentication for details.

Path parameters

Name	Type	Required	Description
funnelId	string	Yes	The ID of the funnel the contact belongs to.
contactId	string	Yes	The ID of the contact to update.

Request body

Field	Type	Required	Description
fieldName	string	Yes	The field to update. See Allowed field names below.
value	string	Yes	The new value for the field.
skipAutomationTrigger	boolean	No	When false (default), automation workflows triggered by the field change will execute. Set to true to bypass automation.

Allowed field names

The following standard field names are recognised:

fieldName	Updates
firstName	Contact's given name.
lastName	Contact's family name.
email	Contact's email address.
phone	Contact's phone number.
status	Contact's lifecycle status. Must be one of the statuses configured for the funnel.
website	Contact's website URL.
birthday	Contact's birthday.
postalCode	Contact's postal / ZIP code. (zip is also accepted as a legacy alias.)
city	Contact's city.
state	Contact's state or region.
country	Contact's country.
street	Contact's street address.
houseNumber	Contact's house number.

Any other name that is not a reserved system field is treated as a custom property and stored in the contact's properties map.

Example request body

{
  "fieldName": "firstName",
  "value": "Jane",
  "skipAutomationTrigger": false
}

Example request

cURL

curl -X PUT https://api.perspective.co/v1/funnels/fnl_abc123/contacts/cnt_abc123/values \
  -H "x-perspective-api-key: $PERSPECTIVE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "fieldName": "firstName",
    "value": "Jane"
  }'

JavaScript

const funnelId = 'fnl_abc123';
const contactId = 'cnt_abc123';

const response = await fetch(
  `https://api.perspective.co/v1/funnels/${funnelId}/contacts/${contactId}/values`,
  {
    method: 'PUT',
    headers: {
      'x-perspective-api-key': process.env.PERSPECTIVE_API_KEY,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      fieldName: 'firstName',
      value: 'Jane',
    }),
  }
);

const { data } = await response.json();

Response

Returns 200 OK with { data: ContactValuesResponse }.

Field	Type	Description
id	string	The ID of the updated field value record.
fieldName	string	The field name that was updated.
value	string	The new value that was set.
updatedAt	string (ISO date-time)	Timestamp when the field was last updated.

Example response

{
  "data": {
    "id": "val_zyx987",
    "fieldName": "firstName",
    "value": "Jane",
    "updatedAt": "2025-06-02T10:15:30.000Z"
  }
}

Errors

See Errors for the full list of status codes and handling guidance.

Status	Meaning
400	Missing fieldName or value, or the fieldName is a reserved system field that cannot be updated.
401	Missing or invalid API key.
403	Your API key does not have crm:write permission.
500	Internal server error.