Get a contact by ID
Scope: contacts:contacts.read https://api.alladdin.com/api/v2/contacts/{contactId}
Retrieves the full details of a single contact by its unique identifier.
The response includes all contact data: billing address, shipping addresses, contact persons, custom fields, default invoicing settings, social networks, and accounting records. Use this endpoint when you need the complete contact profile — for list views, prefer the List contacts endpoint which returns the same fields but paginated.
Parameters
Path parameters
contactId string required
Contact ID (24-char hex ObjectId)
Request
import requests
url = "https://api.alladdin.com/api/v2/contacts/{contactId}"
headers = {
"Authorization": "Bearer YOUR_API_KEY",
"Accept": "application/json",
}
response = requests.get(url, headers=headers)
print(response.json())Responses
Response
{
"id": "507f1f77bcf86cd799439011",
"custom_id": "string",
"name": "string",
"code": "string",
"vat_number": "string",
"trade_name": "string",
"is_person": false,
"email": "string",
"mobile": "string",
"phone": "string",
"type": "client",
"iban": "string",
"swift": "string",
"sepa_ref": "string",
"sepa_date": "2024-01-15",
"tax_operation": "string",
"group_id": "string",
"tags": [
"string"
],
"created_at": "2024-01-15T10:30:00Z",
"updated_at": "2024-01-15T10:30:00Z",
"bill_address": {
"address": "string",
"city": "string",
"postal_code": "string",
"province": "string",
"country": "string",
"country_code": "ES",
"info": "string"
},
"client_record": {
"num": 0,
"name": "string"
},
"supplier_record": {
"num": 0,
"name": "string"
},
"defaults": {
"sales_channel": "string",
"expenses_account": "string",
"due_days": 0,
"payment_day": 0,
"payment_method": "string",
"discount": 0,
"language": "string",
"currency": "string",
"sales_tax": [
"string"
],
"purchases_tax": [
"string"
],
"accumulate_in_form_347": false,
"numbering_series": {
"invoice": "string",
"receipt": "string",
"salesorder": "string",
"estimate": "string",
"order": "string",
"proform": "string",
"waybill": "string"
}
},
"shipping_addresses": [
{
"shipping_id": "string",
"name": "string",
"address": "string",
"city": "string",
"postal_code": "string",
"province": "string",
"country": "string",
"country_code": "string",
"notes": "string",
"private_notes": "string"
}
],
"notes": [
{
"note_id": "string",
"name": "string",
"description": "string",
"color": "string",
"updated_at": "2024-01-15T10:30:00Z"
}
],
"contact_persons": [
{
"person_id": "string",
"name": "string",
"job": "string",
"phone": "string",
"email": "string",
"send_documents_by_default": false
}
],
"custom_fields": [
{
"field": "string",
"value": {}
}
],
"extra_emails": [
"string"
],
"website": "string",
"social_networks": {},
"rate": {
"id": "string",
"name": "string",
"description": "string"
}
}Success responses
200 Contact found application/json object id string
Unique identifier of the contact
custom_id string | null
Your external reference identifier for this contact
name string
Full name of the contact or company
code string | null
Tax identification number
vat_number string | null
EU VAT number for intra-community operations
trade_name string | null
Commercial trading name, if different from the legal name
is_person boolean
Whether the contact is an individual person rather than a company
email string | null
Primary email address
mobile string | null
Mobile phone number
phone string | null
Landline phone number
type string | null
Classification of the contact
Enum: client debtor supplier creditor lead `` iban string | null
IBAN bank account number
swift string | null
SWIFT/BIC code of the bank
sepa_ref string | null
SEPA mandate reference for direct debit collections
sepa_date string<date> | null
Date the SEPA direct debit mandate was signed
tax_operation string | null
Fiscal operation type of the contact (e.g. general, intra, receq, exento)
group_id string | null
Identifier of the contact group this contact belongs to
tags[] string[]
List of tags attached to the contact
created_at string<date-time> | null
Timestamp when the contact was created
updated_at string<date-time> | null
Timestamp when the contact was last modified
bill_address object | null
Billing address of the contact
address string | null
Street address
city string | null
City name
postal_code string | null
Postal or ZIP code
province string | null
State or province
country string | null
Country name
country_code string | null
ISO 3166-1 alpha-2 country code
info string | null
Additional address information
client_record object | null
Accounting account (chart of accounts) used when this contact acts as a client
num integer
Accounting account number
name string
Accounting account name
supplier_record object | null
Accounting account (chart of accounts) used when this contact acts as a supplier
num integer
Accounting account number
name string
Accounting account name
defaults object | null
Default settings applied to new documents for this contact
sales_channel string | null
Default sales channel identifier
expenses_account string | null
Default expenses account identifier
due_days integer | null
Default number of days until payment is due
payment_day integer | null
Fixed day of the month for payment
payment_method string | null
Default payment method identifier
discount integer | null
Default discount percentage
language string | null
Default language code for documents
currency string | null
Default ISO 4217 currency code
sales_tax[] string[] | null
Default sales tax key identifiers
purchases_tax[] string[] | null
Default purchases tax key identifiers
accumulate_in_form_347 boolean
Whether the contact accumulates in tax form 347 (read-only)
numbering_series object | null
Default numbering series ID applied to new documents of each type created for this contact
shipping_addresses[] object[]
List of shipping addresses
shipping_id string
Unique identifier of the shipping address
name string | null
Label for this shipping address
address string | null
Street address
city string | null
City name
postal_code string | null
Postal or ZIP code
province string | null
State or province
country string | null
Country name
country_code string | null
ISO 3166-1 alpha-2 country code
notes string | null
Public notes about this address
private_notes string | null
Internal notes not visible to the contact
notes[] object[]
Internal notes attached to the contact
note_id string
Unique identifier of the note
name string | null
Title of the note
description string | null
Content of the note
color string | null
Color label of the note
updated_at string<date-time> | null
Timestamp when the note was last modified
contact_persons[] object[]
People associated with this contact
person_id string
Unique identifier of the contact person
name string | null
Full name
job string | null
Job title or role
phone string | null
Phone number
email string | null
Email address
send_documents_by_default boolean
Whether documents are sent to this person by default
custom_fields[] object[]
User-defined custom fields
field string
Custom field identifier
value object
Value stored in the custom field
extra_emails[] string[]
Additional email addresses for the contact
website string | null
Website URL of the contact
social_networks object | null
Social network profiles of the contact
rate object | null
Price rate assigned to this contact
id string
Identifier of the price rate
name string
Name of the price rate
description string | null
Description of the price rate
Error responses
401 Invalid or missing API key application/json 403 Insufficient permissions application/json 404 Contact not found application/json 429 Rate limit exceeded application/json