Update Contact

Update an existing contact's information. Only the fields you include in the request body will be updated — all other fields remain unchanged.

Endpoint

PATCH /contacts/:id

Returns: 200 OK

Headers

Header	Value	Required
Authorization	Bearer <your-api-key>	Yes
Content-Type	application/json	Yes

Path Parameters

Parameter	Type	Description
id	string	The contact ID to update

Body Parameters

All fields are optional. Only include the fields you want to change.

Parameter	Type	Required	Description
email	string | null	No	Updated email address. Set to null to clear.
phone_number	string | null	No	Updated phone number in E.164 format. Set to null to clear.
first_name	string | null	No	Updated first name. Max 100 characters. Set to null to clear.
last_name	string | null	No	Updated last name. Max 100 characters. Set to null to clear.
properties	object	No	Custom property values. Replaces the previous values.
list_ids	string[]	No	List IDs to add the contact to.

info

Setting a field to null clears its value. Omitting a field leaves it unchanged. These are different behaviors — be intentional about which you use.

---

Response

Returns the full updated contact object. See Create Contact for the complete response schema.

{
  "id": "01957e3a-4b5c-7d8e-9f0a-1b2c3d4e5f6a",
  "email": "john.updated@example.com",
  "phone_number": "+201234567890",
  "first_name": "John",
  "last_name": "Doe",
  "source": "api",
  "properties": {
    "company": "New Company"
  },
  "is_suppressed": false,
  "created_at": "2026-01-15T10:00:00.000Z",
  "updated_at": "2026-03-08T14:30:00.000Z"
}

---

Examples

Update Email and Name

cURL

curl -X PATCH "https://api.arsel.sa/v1/contacts/01957e3a-4b5c-7d8e-9f0a-1b2c3d4e5f6a" \
  -H "Authorization: Bearer be_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "john.updated@example.com",
    "first_name": "Jonathan"
  }'

JavaScript

const contactId = "01957e3a-4b5c-7d8e-9f0a-1b2c3d4e5f6a";

const response = await fetch(
  `https://api.arsel.sa/v1/contacts/${contactId}`,
  {
    method: "PATCH",
    headers: {
      "Content-Type": "application/json",
      Authorization: "Bearer be_your_api_key",
    },
    body: JSON.stringify({
      email: "john.updated@example.com",
      first_name: "Jonathan",
    }),
  }
);

const contact = await response.json();
console.log(contact.email);

Python

import requests

contact_id = "01957e3a-4b5c-7d8e-9f0a-1b2c3d4e5f6a"

response = requests.patch(
    f"https://api.arsel.sa/v1/contacts/{contact_id}",
    headers={
        "Content-Type": "application/json",
        "Authorization": "Bearer be_your_api_key",
    },
    json={
        "email": "john.updated@example.com",
        "first_name": "Jonathan",
    },
)

print(response.json())

C#

using var client = new HttpClient();
client.DefaultRequestHeaders.Add("Authorization", "Bearer be_your_api_key");

var contactId = "01957e3a-4b5c-7d8e-9f0a-1b2c3d4e5f6a";
var payload = new { email = "john.updated@example.com", first_name = "Jonathan" };

var json = System.Text.Json.JsonSerializer.Serialize(payload);
var content = new StringContent(json, System.Text.Encoding.UTF8, "application/json");
var request = new HttpRequestMessage(HttpMethod.Patch, $"https://api.arsel.sa/v1/contacts/{contactId}")
{
    Content = content
};
var response = await client.SendAsync(request);
Console.WriteLine(await response.Content.ReadAsStringAsync());

PHP

<?php
$contactId = "01957e3a-4b5c-7d8e-9f0a-1b2c3d4e5f6a";
$ch = curl_init("https://api.arsel.sa/v1/contacts/{$contactId}");
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "Content-Type: application/json",
    "Authorization: Bearer be_your_api_key"
]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "PATCH");
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
    "email" => "john.updated@example.com",
    "first_name" => "Jonathan"
]));
$response = curl_exec($ch);
echo $response;
curl_close($ch);

Update Custom Properties

cURL

curl -X PATCH "https://api.arsel.sa/v1/contacts/01957e3a-4b5c-7d8e-9f0a-1b2c3d4e5f6a" \
  -H "Authorization: Bearer be_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "properties": {
      "company": "New Company",
      "city": "Jeddah"
    }
  }'

JavaScript

const response = await fetch(
  "https://api.arsel.sa/v1/contacts/01957e3a-4b5c-7d8e-9f0a-1b2c3d4e5f6a",
  {
    method: "PATCH",
    headers: {
      "Content-Type": "application/json",
      Authorization: "Bearer be_your_api_key",
    },
    body: JSON.stringify({
      properties: {
        company: "New Company",
        city: "Jeddah",
      },
    }),
  }
);

console.log(await response.json());

Python

import requests

response = requests.patch(
    "https://api.arsel.sa/v1/contacts/01957e3a-4b5c-7d8e-9f0a-1b2c3d4e5f6a",
    headers={
        "Content-Type": "application/json",
        "Authorization": "Bearer be_your_api_key",
    },
    json={
        "properties": {
            "company": "New Company",
            "city": "Jeddah",
        },
    },
)

print(response.json())

C#

using var client = new HttpClient();
client.DefaultRequestHeaders.Add("Authorization", "Bearer be_your_api_key");

var payload = new { properties = new { company = "New Company", city = "Jeddah" } };
var json = System.Text.Json.JsonSerializer.Serialize(payload);
var content = new StringContent(json, System.Text.Encoding.UTF8, "application/json");
var request = new HttpRequestMessage(HttpMethod.Patch, "https://api.arsel.sa/v1/contacts/01957e3a-4b5c-7d8e-9f0a-1b2c3d4e5f6a")
{
    Content = content
};
var response = await client.SendAsync(request);
Console.WriteLine(await response.Content.ReadAsStringAsync());

PHP

<?php
$ch = curl_init("https://api.arsel.sa/v1/contacts/01957e3a-4b5c-7d8e-9f0a-1b2c3d4e5f6a");
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "Content-Type: application/json",
    "Authorization: Bearer be_your_api_key"
]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "PATCH");
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
    "properties" => [
        "company" => "New Company",
        "city" => "Jeddah"
    ]
]));
$response = curl_exec($ch);
echo $response;
curl_close($ch);

---

Error Responses

404 Not Found

{
  "status_code": 404,
  "name": "not_found",
  "message": "Contact not found"
}

422 Validation Error

{
  "status_code": 422,
  "name": "validation_error",
  "message": "email must be an email"
}

409 Conflict

{
  "status_code": 409,
  "name": "conflict",
  "message": "A contact with this email already exists in your organization"
}