Scope: contacts:contacts.write https://api.alladdin.com/api/v2/contacts

Creates a new contact in your account. Contacts represent the people and companies you do business with — customers, suppliers, leads, debtors, or creditors.
At minimum you must provide a name. The type field controls how the contact appears in your accounting (e.g. client, supplier). If omitted, the contact is created without a type and can be classified later.
The response returns the new contact id. Use it to create invoices, purchases, or any other document linked to this contact.

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

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

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).

Request

import requests

url = "https://api.alladdin.com/api/v2/contacts"
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"
    ],
    "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.post(url, headers=headers, json=payload)
print(response.json())

Responses

Response

{
  "id": "507f1f77bcf86cd799439011"
}

Success responses

201 Contact created application/json object id string

Error responses

400 Bad request application/json 401 Invalid or missing API key application/json 403 Insufficient permissions application/json 422 Validation error application/json 429 Rate limit exceeded application/json

Next →Attach a file to a contact →