Contacts

Search contacts

Search contacts by name, fiscal identity, email, phone, mobile or external ID, optionally restricted to customer, supplier or fiscal lead roles and role status. Results are tenant-scoped and cursor-paginated.

get/companies/{company}/contacts/search

Request

  • Base URL: https://api.factuarea.com/v1
  • URL: https://api.factuarea.com/v1/companies/{company}/contacts/search
  • 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

qstring required

Search term (2 to 255 characters), ranked by exact, prefix and partial match.

roles[]string[]

Only contacts with these roles: customer, supplier or lead (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.

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

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.