PATCH
/
v1
/
contacts
/
{contactId}
# Update a contact's name and description
curl -X PATCH "https://api.contactship.ai/v1/contacts/c1a2b3c4-d5e6-f7g8-h9i0-j1k2l3m4n5o6" \
  -H "x-api-key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "full_name": "Juan Carlos Pérez",
    "description": "Lead converted to customer"
  }'

{
  "id": "c1a2b3c4-d5e6-f7g8-h9i0-j1k2l3m4n5o6",
  "created_at": "2023-01-01T12:00:00Z",
  "phone_number": "+12125678901",
  "full_name": "Juan Carlos Pérez",
  "country": "México",
  "email": "juan.perez@ejemplo.com",
  "description": "Lead converted to customer",
  "additional_data": [
    {
      "type": "location",
      "field": "dirección",
      "value": "Av. Reforma 456"
    },
    {
      "type": "text",
      "field": "notas",
      "value": "Cliente activo con suscripción premium"
    },
    {
      "type": "date",
      "field": "fecha_conversión",
      "value": "2023-03-15"
    }
  ],
  "organization_id": "org123456"
}
This endpoint allows you to update the information of an existing contact in your organization’s database. You only need to include the fields you want to modify - any fields not included in the request will remain unchanged.

​
Use Cases

  • Update a contact’s phone number, email, or other contact information
  • Add or modify additional data fields for a contact
  • Enrich contact records with new information from external sources
  • Update contact status or notes after interaction

​
Path Parameters

​
contactId
string
required
The unique identifier of the contact you want to update. This is a UUID string that was generated when the contact was created.

​
Headers

​
x-api-key
string
required
Your API key for authentication. You can find this in your dashboard under API settings.

​
Body Parameters

​
phone_number
string
The updated phone number of the contact in international format (e.g., +12124567890)
​
full_name
string
The updated full name of the contact
​
country
string
The updated country of the contact
​
email
string
The updated email address of the contact
​
description
string
Updated description or notes about the contact
​
additional_data
array
Updated array of additional data fields for the contact. Note that this will replace the entire additional_data array, not merge with existing values.

​
Response

​
status code
number
200 on successful update
​
id
string
The unique identifier of the updated contact (UUID format)
​
created_at
string
The timestamp when the contact was originally created (ISO 8601 format)
​
phone_number
string
The updated phone number of the contact
​
full_name
string
The updated full name of the contact
​
country
string
The updated country of the contact
​
email
string
The updated email of the contact
​
description
string
Updated description or notes about the contact
​
additional_data
array
Updated additional data associated with the contact
​
organization_id
string
The ID of the organization the contact belongs to

​
Error Codes

  • 400 Bad Request - Invalid input data format
  • 401 Unauthorized - Invalid or missing API key
  • 404 Not Found - Contact not found
  • 409 Conflict - The update would create a duplicate phone number
  • 500 Internal Server Error - Server-side error

​
Code Examples

# Update a contact's name and description
curl -X PATCH "https://api.contactship.ai/v1/contacts/c1a2b3c4-d5e6-f7g8-h9i0-j1k2l3m4n5o6" \
  -H "x-api-key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "full_name": "Juan Carlos Pérez",
    "description": "Lead converted to customer"
  }'

{
  "id": "c1a2b3c4-d5e6-f7g8-h9i0-j1k2l3m4n5o6",
  "created_at": "2023-01-01T12:00:00Z",
  "phone_number": "+12125678901",
  "full_name": "Juan Carlos Pérez",
  "country": "México",
  "email": "juan.perez@ejemplo.com",
  "description": "Lead converted to customer",
  "additional_data": [
    {
      "type": "location",
      "field": "dirección",
      "value": "Av. Reforma 456"
    },
    {
      "type": "text",
      "field": "notas",
      "value": "Cliente activo con suscripción premium"
    },
    {
      "type": "date",
      "field": "fecha_conversión",
      "value": "2023-03-15"
    }
  ],
  "organization_id": "org123456"
}

​
Notes and Best Practices

  • Only include the fields you want to update in the request body
  • Be careful when updating the additional_data array, as it will replace the entire array rather than merge with existing values
  • If you’re updating a phone number, ensure it doesn’t conflict with another contact’s phone number
  • Consider implementing validation checks before submitting updates
  • Keep track of contact update history in your application if needed for compliance or audit purposes