Contacts

Create a contact

Create one canonical contact with no role or any combination of customer, supplier and lead; the response id is a UUID v7.

A repeated Idempotency-Key replays the original response without duplicating the contact.
An existing external_id is updated idempotently within the company.

post/companies/{company}/contacts

Request

Base URL: https://api.factuarea.com/v1
URL: https://api.factuarea.com/v1/companies/{company}/contacts
Auth: one of:
- HTTP bearer
- API key in header X-API-Key

Path parameters

companystring uuid required

Public identifier (UUID v7) of the company. Get it from GET /v1/me (data.scope[].id).

Headers

Idempotency-Keystring

Example:01928f10-7c0e-7c4a-9b7d-2f8a6e3c1d4b

Client-generated opaque key (up to 255 characters; UUID v7 recommended) that makes retries safe: the first response is cached and replayed for repeats without re-executing the mutation. Reusing a key with a different body returns 422 idempotency_key_reused; the values of secret fields (password, secret…) count as part of the body, so retrying with a corrected secret under the same key is a different request, never the replay of the earlier answer. See the Idempotency guide.

Factuarea-Versionstring date

Example:2026-06-01

Pin the API version (YYYY-MM-DD, Stripe-style date versioning) for this request; omit to use the key's pinned version, or the latest if none. Unsupported version → 400 unsupported_api_version; malformed → 400 parameter_invalid_format. The effective version is echoed in the Factuarea-Version response header. See the Versioning guide.

Request body

namestring required

kind'person' | 'company' required

tax_idstring nullable

alternative_id_valuestring nullable

alternative_id_country_code'AD' | 'AE' | 'AF' | 'AG' | 'AI' | 'AL' | 'AM' | 'AO' | 'AQ' | 'AR' | 'AS' | 'AT' | 'AU' | 'AW' | 'AX' | 'AZ' | 'BA' | 'BB' | 'BD' | 'BE' | 'BF' | 'BG' | 'BH' | 'BI' | 'BJ' | 'BL' | 'BM' | 'BN' | 'BO' | 'BQ' | 'BR' | 'BS' | 'BT' | 'BV' | 'BW' | 'BY' | 'BZ' | 'CA' | 'CC' | 'CD' | 'CF' | 'CG' | 'CH' | 'CI' | 'CK' | 'CL' | 'CM' | 'CN' | 'CO' | 'CR' | 'CU' | 'CV' | 'CW' | 'CX' | 'CY' | 'CZ' | 'DE' | 'DJ' | 'DK' | 'DM' | 'DO' | 'DZ' | 'EC' | 'EE' | 'EG' | 'EH' | 'ER' | 'ES' | 'ET' | 'FI' | 'FJ' | 'FK' | 'FM' | 'FO' | 'FR' | 'GA' | 'GB' | 'GD' | 'GE' | 'GF' | 'GG' | 'GH' | 'GI' | 'GL' | 'GM' | 'GN' | 'GP' | 'GQ' | 'GR' | 'GS' | 'GT' | 'GU' | 'GW' | 'GY' | 'HK' | 'HM' | 'HN' | 'HR' | 'HT' | 'HU' | 'ID' | 'IE' | 'IL' | 'IM' | 'IN' | 'IO' | 'IQ' | 'IR' | 'IS' | 'IT' | 'JE' | 'JM' | 'JO' | 'JP' | 'KE' | 'KG' | 'KH' | 'KI' | 'KM' | 'KN' | 'KP' | 'KR' | 'KW' | 'KY' | 'KZ' | 'LA' | 'LB' | 'LC' | 'LI' | 'LK' | 'LR' | 'LS' | 'LT' | 'LU' | 'LV' | 'LY' | 'MA' | 'MC' | 'MD' | 'ME' | 'MF' | 'MG' | 'MH' | 'MK' | 'ML' | 'MM' | 'MN' | 'MO' | 'MP' | 'MQ' | 'MR' | 'MS' | 'MT' | 'MU' | 'MV' | 'MW' | 'MX' | 'MY' | 'MZ' | 'NA' | 'NC' | 'NE' | 'NF' | 'NG' | 'NI' | 'NL' | 'NO' | 'NP' | 'NR' | 'NU' | 'NZ' | 'OM' | 'PA' | 'PE' | 'PF' | 'PG' | 'PH' | 'PK' | 'PL' | 'PM' | 'PN' | 'PR' | 'PS' | 'PT' | 'PW' | 'PY' | 'QA' | 'RE' | 'RO' | 'RS' | 'RU' | 'RW' | 'SA' | 'SB' | 'SC' | 'SD' | 'SE' | 'SG' | 'SH' | 'SI' | 'SJ' | 'SK' | 'SL' | 'SM' | 'SN' | 'SO' | 'SR' | 'SS' | 'ST' | 'SV' | 'SX' | 'SY' | 'SZ' | 'TC' | 'TD' | 'TF' | 'TG' | 'TH' | 'TJ' | 'TK' | 'TL' | 'TM' | 'TN' | 'TO' | 'TR' | 'TT' | 'TV' | 'TW' | 'TZ' | 'UA' | 'UG' | 'UM' | 'US' | 'UY' | 'UZ' | 'VA' | 'VC' | 'VE' | 'VG' | 'VI' | 'VN' | 'VU' | 'WF' | 'WS' | 'YE' | 'YT' | 'ZA' | 'ZM' | 'ZW' | 'null' nullable

vat_idstring nullable

business_namestring nullable

commercial_namestring nullable

contact_personstring nullable

emailstring email nullable

phonestring nullable

mobilestring nullable

faxstring nullable

websitestring uri nullable

billing_emailsstring[]

tagsstring[]

notesstring nullable

metadataMetadata nullable

A free map of up to 50 key→value pairs for storing arbitrary structured data (values are strings up to 500 characters). Unlike custom_fields — an ordered list of typed {field, value} pairs with display semantics, present on the six document resources — metadata is an unordered map for opaque integration data; a document may carry both. The master resources (Client, Supplier) have no custom_fields, so their metadata doubles as the custom-fields store.

Reserved keys (read-only). When the system auto-issues an invoice from a payment correlation (Stripe/GoCardless/MONEI), it writes stripe_subscription_id, stripe_invoice_id, billing_reason, period_start and period_end into that invoice metadata automatically. Do not set or overwrite them by hand — the platform owns them and a manual value may be replaced when the correlation runs.

accumulate_347boolean

external_idstring nullable

latitudenumber nullable

longitudenumber nullable

rolesstring[] required

Example request

{
  "name": "Distribuciones Ejemplo SL",
  "kind": "company",
  "roles": [
    "customer",
    "supplier"
  ],
  "tax_id": "B12345674",
  "address": {
    "line_1": "Calle Mayor",
    "country_code": "ES"
  }
}

Response

The external_id already identified a contact of the company: that contact was updated with the request, keeps its id and is returned.

Example response

{
  "data": {
    "id": "0198f4d1-a492-7e05-9a35-000000000001",
    "object": "contact",
    "kind": "company",
    "name": "Distribuciones Ejemplo SL",
    "business_name": "Distribuciones Ejemplo SL",
    "commercial_name": "Ejemplo",
    "tax_id": "B12345674",
    "vat_id": null,
    "alternative_id": null,
    "address": {
      "line1": "Calle Mayor",
      "line2": null,
      "number": "10",
      "floor": null,
      "door": null,
      "staircase": null,
      "city": "Madrid",
      "province": "Madrid",
      "postal_code": "28013",
      "country": "ES"
    },
    "contact_person": "Ana García",
    "email": "administracion@example.com",
    "phone": "+34910000000",
    "mobile": null,
    "fax": null,
    "website": "https://example.com",
    "billing_emails": [
      "facturas@example.com"
    ],
    "tags": [
      "distribuidor"
    ],
    "coordinates": null,
    "notes": null,
    "metadata": {
      "erp_id": "CONTACT-42"
    },
    "accumulate_347": true,
    "external_id": "CONTACT-42",
    "roles": [
      {
        "role": "customer",
        "status": "active",
        "assigned_at": "2026-08-29T10:00:00+00:00",
        "deactivated_at": null
      },
      {
        "role": "supplier",
        "status": "active",
        "assigned_at": "2026-08-29T10:00:00+00:00",
        "deactivated_at": null
      }
    ],
    "bank_accounts": [],
    "customer_profile": null,
    "supplier_profile": null,
    "financial_summary": {
      "sales": {
        "invoiced_amount": "1210.00",
        "collected_amount": "800.00",
        "receivable_amount": "410.00",
        "currency": "EUR"
      },
      "purchases": {
        "purchased_amount": "605.00",
        "paid_amount": "400.00",
        "payable_amount": "205.00",
        "currency": "EUR"
      }
    },
    "latest_activity": null,
    "is_archived": false,
    "archived_at": null,
    "created_at": "2026-08-29T10:00:00+00:00",
    "updated_at": "2026-08-29T10:00:00+00:00"
  }
}

Changes

No recorded changes to this operation across all 1 revision of this API.