Update a contact
Scope: contacts:contacts.write https://api.alladdin.com/api/v2/contacts/{contactId}
Replaces all mutable fields of an existing contact. This is a full replacement — any field you omit from the request body will be reset to its default value.
To avoid accidentally clearing data, first fetch the contact with GET, modify the fields you need, and send back the full object. Partial updates are not supported on this endpoint.
Parameters
Path parameters
contactId string required
Contact ID (24-char hex ObjectId)
Request body
object name string required
Contact full name or company name
code string | null optional
Tax identification number (NIF, CIF, etc.)
vat_number string | null optional
EU VAT number
trade_name string | null optional
Commercial or trade name, if different from legal name
is_person boolean optional
True if the contact is an individual, false if a company
email string | null optional
Email address. Several can be sent separated by commas or semicolons: the first is the primary, the rest are returned in extra_emails. Invalid ones are ignored (400 if none is valid).
phone string | null optional
Landline phone number
mobile string | null optional
Mobile phone number
website string | null optional
Website URL
type string | null optional
Contact classification
Enum: client debtor supplier creditor lead `` client_record integer | null optional
Number of the accounting account (chart of accounts) used when this contact acts as a client
supplier_record integer | null optional
Number of the accounting account (chart of accounts) used when this contact acts as a supplier
iban string | null optional
IBAN bank account number
swift string | null optional
SWIFT/BIC code of the bank
sepa_ref string | null optional
SEPA mandate reference for direct debit collections
sepa_date string<date> | null optional
Date the SEPA direct debit mandate was signed
tax_operation string | null optional
Fiscal operation type of the contact (e.g. general, intra, receq, exento). Must be one of the operations defined by the account tax scheme. On update, omitting it (or sending null) keeps the current value
bill_address object | null optional
Billing address
address string | null
Street address
city string | null
City
postal_code string | null
Postal or ZIP code
province string | null
Province or state
country string | null
Country name
country_code string | null
ISO 3166-1 alpha-2 country code
info string | null
Additional address information
tags[] string[] | null optional
Tags attached to the contact
contact_persons[] object[] optional
Linked contact persons (by their contact ID)
person_id string
Contact ID of the person
custom_fields[] object[] | null optional
User-defined custom fields
field string
Custom field identifier
value object
Value stored in the custom field
defaults object | null optional
Default settings applied to documents created for this contact
sales_channel string | null
Default sales channel identifier
expenses_account string | null
Default expenses accounting account
due_days integer | null
Default payment due days
payment_day integer | null
Default fixed payment day of the month
payment_method string | null
Default payment method identifier
discount integer | null
Default discount percentage
language string | null
Default document language code
currency string | null
Default currency code
sales_tax[] string[] | null
Default sales tax keys applied to sales documents
purchases_tax[] string[] | null
Default purchases tax keys applied to purchase documents
numbering_series object | null
Default numbering series applied to new documents of each type created for this contact. Each value must be a valid numbering series ID; invalid or unrecognized IDs are silently ignored (stored as null). Omit this field entirely to keep the numbering series already configured for this contact.
Request
import requests
url = "https://api.alladdin.com/api/v2/contacts/{contactId}"
headers = {
"Authorization": "Bearer YOUR_API_KEY",
"Accept": "application/json",
}
payload = {
"name": "string",
"code": "string",
"vat_number": "string",
"trade_name": "string",
"is_person": false,
"email": "string",
"phone": "string",
"mobile": "string",
"website": "string",
"type": [
"client",
"supplier",
"debtor",
"creditor",
"lead"
],
"client_record": 0,
"supplier_record": 0,
"iban": "string",
"swift": "string",
"sepa_ref": "string",
"sepa_date": "2024-01-15",
"tax_operation": "string",
"bill_address": {
"address": "string",
"city": "string",
"postal_code": "string",
"province": "string",
"country": "string",
"country_code": "ES",
"info": "string"
},
"tags": [
"string"
],
"contact_persons": [
{
"person_id": "string"
}
],
"custom_fields": [
{
"field": "string",
"value": {}
}
],
"defaults": {
"sales_channel": "string",
"expenses_account": "string",
"due_days": 0,
"payment_day": 0,
"payment_method": "string",
"discount": 0,
"language": "string",
"currency": "EUR",
"sales_tax": [
"string"
],
"purchases_tax": [
"string"
],
"numbering_series": {
"invoice": "string",
"receipt": "string",
"salesorder": "string",
"estimate": "string",
"order": "string",
"proform": "string",
"waybill": "string"
}
}
}
response = requests.put(url, headers=headers, json=payload)
print(response.json())Responses
Response
{
"status": 1
}Success responses
200 Contact updated application/json object status integer required
Operation status
Error responses
400 Bad request application/json 401 Invalid or missing API key application/json 403 Insufficient permissions application/json 404 Contact not found application/json 422 Validation error application/json 429 Rate limit exceeded application/json