Contacts

List contacts

List canonical contacts with cursor pagination. Filter by roles (customer, supplier, lead, or the synthetic unassigned relationship; CSV or array), role_match (any or all), role status, kind, fiscal identity, external ID, tags, metadata, archive state and creation date. Contacts with cumulative roles appear once and match every role they contain.

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

Query parameters

limitinteger nullable

Number of objects to return, between 1 and 100 (default 25).

starting_afterstring uuid nullable

Cursor for forward pagination: pass the id of the last object on the previous page (the next_cursor of the previous response).

searchstring nullable

Free-text search (up to 255 characters) over name, commercial name, tax identifiers, email, external ID and phone numbers.

roles[]string[]

Only contacts with these roles: customer, supplier, lead or unassigned (repeat it or send a comma-separated list).

role_match'any' | 'all' | 'null' nullable

any (default) matches at least one of the roles[]; all requires all of them.

role_status'active' | 'inactive' | 'null' nullable

Only roles in this status: active or inactive.

kind'person' | 'company' | 'null' nullable

Contact kind: person or company.

fiscal_identitystring nullable

Exact match on any tax identifier of the contact (NIF/NIE/CIF, EU VAT number or alternative ID document).

external_idstring nullable

Exact match on the external_id you assigned.

tags[]string[]

Only contacts carrying all these tags (case-insensitive, up to 50).

is_archivedboolean nullable

true returns only archived contacts and false only the rest; omit it to return both.

citystring nullable

City name, exact match.

provincestring nullable

Exact match on the province.

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

Exact ISO 3166-1 alpha-2 country code.

has_emailboolean nullable

true returns only contacts with an email address and false only those without one.

has_phoneboolean nullable

true returns only contacts with a phone number and false only those without one.

created_fromstring date nullable

Only records created on or after this date (YYYY-MM-DD).

created_tostring date nullable

Only records created on or before this date (YYYY-MM-DD).

metadata[]string[]

Metadata filter as metadata[key]=value (exact match, up to 20 pairs, all must match).

sort_order'asc' | 'desc' | 'null' nullable

Sort direction by creation date: asc (default) or desc.

Headers

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.

Response

has_moreboolean required

Whether more pages are available after this one.

next_cursorstring nullable required

Opaque cursor for the next page, or null when has_more is false. The example below shows the shape used by most listings; others return a different one, so pass the value back verbatim instead of validating it.

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"
    }
  ],
  "has_more": true,
  "next_cursor": "01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a0c"
}

Changes

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