List contacts
Scope: contacts:contacts.read https://api.alladdin.com/api/v2/contacts
Returns a paginated list of contacts in your account.
You can filter by phone, mobile, email, code, or custom_id to find specific contacts. All filters use exact matching. Results are cursor-paginated: the response includes a cursor value and a has_more boolean. Pass the cursor to the next request to fetch the following page.
The default page size is 25 contacts. You can increase it up to 100 using the limit parameter.
Parameters
Query parameters
phone string optional
Filter contacts by exact phone number match
mobile string optional
Filter contacts by exact mobile number match
email string optional
Filter contacts by exact email address match
custom_id string optional
Filter contacts by your external reference identifier
code string optional
Filter contacts by exact tax identification number (NIF/CIF)
cursor string optional
Opaque cursor for pagination. Use the value returned in the previous response to fetch the next page.
limit integer optional = 50
Maximum number of contacts to return per page. Defaults to 25, maximum 100.
Request
import requests
url = "https://api.alladdin.com/api/v2/contacts?phone=value&mobile=value&email=value"
headers = {
"Authorization": "Bearer YOUR_API_KEY",
"Accept": "application/json",
}
response = requests.get(url, headers=headers)
print(response.json())Responses
Response
{
"items": [
{
"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": [
"..."
],
"purchases_tax": [
"..."
],
"accumulate_in_form_347": false,
"numbering_series": {
"invoice": "...",
"receipt": "...",
"salesorder": "...",
"estimate": "...",
"order": "...",
"proform": "...",
"waybill": "..."
}
},
"shipping_addresses": [
{
"shipping_id": "...",
"name": "...",
"address": "...",
"city": "...",
"postal_code": "...",
"province": "...",
"country": "...",
"country_code": "...",
"notes": "...",
"private_notes": "..."
}
],
"notes": [
{
"note_id": "...",
"name": "...",
"description": "...",
"color": "...",
"updated_at": "..."
}
],
"contact_persons": [
{
"id": "..."
}
],
"custom_fields": [
{
"field": "...",
"value": "..."
}
],
"extra_emails": [
"string"
],
"website": "string",
"social_networks": {},
"rate": {
"id": "string",
"name": "string",
"description": "string"
}
}
],
"cursor": "string",
"has_more": false
}Success responses
200 List of contacts application/json object items[] 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
client_record object | null
Accounting account (chart of accounts) used when this contact acts as a client
supplier_record object | null
Accounting account (chart of accounts) used when this contact acts as a supplier
defaults object | null
Default settings applied to new documents for this contact
shipping_addresses[] object[]
List of shipping addresses
notes[] object[]
Internal notes attached to the contact
contact_persons[] object[]
People associated with this contact. Only their ids are returned, get the contact by this id for the rest of the fields
custom_fields[] object[]
User-defined custom fields
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
cursor string | null has_more boolean
Error responses
401 Invalid or missing API key application/json 403 Insufficient permissions application/json 429 Rate limit exceeded application/json