SIGNALS Documentation
API Reference

CRM & Addresses

CRM records in brief, the global address list across accounts, rentals, and invoices, plus practical import and export how-tos.

Overview

CRM in Signals centres on Accounts — contacts, companies, venues, and users — plus Activities, Calendar, and Discussions & mentions. Addresses are a first-class polymorphic entity: every address belongs to a Account, Rental, or Invoice. There are no orphan addresses.

Nav item Route Permission
Accounts /accounts accounts.access
Addresses /addresses addresses.access
Activities /activities activities.access

Account CRUD, merge, and detail tabs remain on the Accounts page. This page covers the Global Address List, address fields, and import/export.

Address fields

Field Notes
Label (name) e.g. “Head Office”
Street Required when creating via the global form / create DTO
City, County / State, Postcode Standard postal fields
Country Active country from the countries list
Type List Address Type — seeded values include Billing, Shipping, Primary, Registered
Primary Checkbox; on an account, checking Primary clears other primaries for that account
what3words Optional; lookup/geocode when the integration is configured, otherwise stored as text
Latitude / Longitude Set manually, via geocode, or by dragging the map marker

Global Address List

Route: /addresses
Permission: addresses.view

Browse every address whose parent you can view (accounts.view / rentals.view / invoices.view). If you cannot view any parents, the list is empty.

Filters & columns

  • Type chips (?type=): All · Account · Rental · Invoice
  • Search: name, street, city, postcode
  • Default columns: Name (with street secondary), Belongs To, City, Postcode, Country, Primary, Created
    Toggleable extras include Street, County, Type, what3words, Updated

Belongs To shows a label such as Account: Acme Corp and links to the parent when permitted.

Actions

Action Detail
Add Address /addresses/create — pick parent type and record, then address fields
Edit /addresses/{address}/edit — parent is read-only after create
Delete / bulk delete Requires addresses.delete and permission to edit the parent
Export Toolbar CSV of the current filtered, visible columns (see below)

Keyboard: n opens Add Address when you have addresses.create; x exports when available.

Addresses on an account

Route Role
/accounts/{account}/information Primary UI — Addresses panel alongside emails, phones, and links
/accounts/{account}/addresses Dedicated table list
/accounts/{account}/addresses/create Create
/accounts/{account}/addresses/{address}/edit Edit

After save from the account form, Signals returns to the Information tab. Mutations also require the parent’s edit permission (e.g. accounts.edit), not only addresses.*.

Geocoding on the form

  • Geocode from Address — builds a query from street, city, county, postcode, and country
  • Lookup — resolves a word.word.word what3words string when configured
  • Map preview (OpenStreetMap) — drag the marker or click the map; Open in OSM for an external view

Import & export how-to

A. Quick CSV from a list toolbar

On /accounts and /addresses, use the DataTable Export control:

  1. Apply the search, type chips, and column visibility you want.
  2. Click Export (or press x where bound).
  3. Download a CSV named like addresses-YYYY-MM-DD.csv (always includes an ID column).

This is a synchronous stream of the current filtered result set — CSV only.

B. Export Centre (full formats)

Route: /admin/settings/exports
Permissions: exports.access → exports.view → exports.create

  1. Open Admin → Data → Exports → New export.
  2. Choose source model (accounts or addresses) or a live filter.
  3. Pick format: csv, xlsx, json, or pdf.
  4. Select columns and optional Ransack-style filters; submit.
  5. Small jobs download immediately (sync threshold, default 1000 rows); larger jobs queue on the exports queue — download from the job list when complete.

Exports run as the creating user (warehouse scope and column visibility, including costs.view gating where relevant).

C. Import wizard (accounts & addresses)

Routes: /admin/settings/imports, /admin/settings/imports/create, /admin/settings/imports/{import}/wizard
Permissions: imports.access → imports.view → imports.create (imports.undo for plan undo)

Core import targets include accounts and addresses. Stages: Upload → Map → Validate → Preview → Commit.

Practical steps

  1. Admin → Data → Imports → New import.
  2. Upload — choose target Accounts or Addresses, drop a CSV / XLSX / JSON file, Upload & parse, review detected columns, continue.
  3. Map — map source columns to target fields; optionally apply a mapping profile, Auto-Map, or accept suggestions. Set a conflict strategy (Skip, Overwrite, Merge, Flag) and duplicate-match fields (defaults: accounts → name; addresses → street).
  4. Validate — fix or export the error CSV if rows fail.
  5. Preview — confirm mapped records, then Commit (pause / resume / cancel when permitted).

Address parent columns

Addresses need a parent. Map exactly one of these (first wins), or rely on a batch-level polymorphic default:

Column Resolves
account_id Account by id
account_email Account with that email
rental_id / rental_number Rental
invoice_id / invoice_number Invoice

Missing or invalid parents fail the row — imports never create orphan addresses. Address imports do not call external what3words geocoding per row (resolveWhat3Words is off).

Accounts import through the normal CreateAccount / UpdateAccount actions (schema fields such as name, account_type, currencies, tax fields, tags, etc.).

Permissions (addresses & data)

Permission Purpose
addresses.access / view / create / update / delete Global address area and UI
Parent *.edit (e.g. accounts.edit) Create/update/delete addresses on that parent
imports.* / exports.* Import wizard and Export Centre
  • Accounts — CRM entity CRUD and detail tabs
  • Discussions & mentions — conversation panel on accounts and rentals
  • Countries — country list used by address forms
  • Lists — manage the Address Type lists
  • Global search — Cmd-K does not search addresses; use /addresses search or q[search_cont] on searchable APIs