Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/0m1n3m/contacts-db/llms.txt

Use this file to discover all available pages before exploring further.

This page covers the full lifecycle of a contact record in Contacts DB — from creating a new entry and filling in multi-value fields, to searching and filtering the list view, editing an existing record, and removing contacts individually or in bulk. Each section notes which roles are permitted to perform the action.

​
Creating a Contact

Navigate to /contacts/create or click Create contact on the contacts list page. The form is protected by the role:admin,editor middleware — only admins and editors can access it.

​
Required fields

Every contact must have values for both of the following fields before it can be saved:
FieldForm labelValidation
contact_categoryContact categoryRequired, max 255 characters
relationship_statusRelationship statusRequired, max 255 characters

​
Optional fields

All other fields are optional. Leave any field blank to store null:
  • Organisation name — name of the contact’s employer or organisation
  • First name / Last name — the contact’s given and family name
  • Job title — role within the organisation
  • Country — selected from a dropdown; stored as a two-letter ISO 3166-1 alpha-2 code (e.g. GB, US)
  • Relevant project / programme — the specific project or programme this contact is associated with
  • Stakeholder type — freeform classification such as Funder or Government
  • Comment — free-text notes, supports multi-line input
  • Use for events — checkbox flag; defaults to unchecked (false)
  • Potential speaker — checkbox flag; defaults to unchecked (false)

​
Multi-value fields

The following fields store an array of values in the database. In the form, each is displayed as a textarea — enter one value per line. Blank lines are ignored. Each non-blank line becomes a separate element in the JSON array stored in the database.
FieldForm labelExample input
emailsEmails (one per line)alice@example.com then alice@work.org on separate lines
phonesPhones (one per line)+44 20 7946 0958
organisation_typesOrganisation types (one per line)NGO then Think Tank
keywordsKeywords (one per line)climate then policy
expertise_speaking_topicsExpertise / speaking topics (one per line)Carbon Markets then Climate Finance
The textarea input uses the field names emails_text, phones_text, organisation_types_text, and keywords_text — these are internal form names that the controller converts to JSON arrays before saving. The stored column names in the database are emails, phones, organisation_types, and keywords.
After submitting the form successfully, you are redirected to the contacts list at /contacts.

​
Viewing Contacts

​
List view

The contact list is available at /contacts and is accessible to all authenticated users regardless of role. The list renders as a paginated, sortable, filterable table.

​
Pagination

Use the Per page selector in the toolbar to control how many rows are shown. Valid options are:
ValueRows per page
1010
2525 (default)
5050
100100
Pass per_page=N as a query parameter to set it directly in the URL.

​
Sorting

Click any underlined column header to sort by that column. Click again to reverse the direction. The current sort column and direction are preserved in the URL as sort and dir parameters. Sortable columns: contact_category, relationship_status, use_for_events, potential_speaker, organisation_name, first_name, last_name, job_title, country, relevant_project_programme, stakeholder_type, created_at, updated_at String columns (first_name, last_name, organisation_name, job_title, stakeholder_type, country, contact_category, relationship_status, relevant_project_programme) are sorted case-insensitively with leading whitespace trimmed. The Search field at the top of the list applies a global LIKE filter across all text columns and all JSON array columns simultaneously. It also resolves country names — typing France matches contacts whose country is FR. The search term is passed as the q query parameter.

​
Per-column filters

A second header row below the column titles contains individual filter inputs. Text filters use a partial LIKE match. Boolean columns (use_for_events, potential_speaker) use a checkbox that, when checked, filters to contacts where the flag is true. JSON array columns (emails, phones, keywords, organisation_types, expertise_speaking_topics) filter contacts whose array contains the entered value as an element. Click Apply column filters or press Enter in any input to apply.

​
Column visibility

Click Columns in the toolbar to show or hide individual columns. Visibility preferences are saved in localStorage under the key contacts.index.columns.v1 and persist across page loads in the same browser. Click Reset columns to restore the default set. The comment column is hidden by default.

​
Detail view

Click any contact’s first name link in the list to open the detail view at /contacts/{id}. This page is read-only and shows all fields. Admins and editors see an Edit link; admins also see a Delete button that opens a confirmation modal before deletion.

​
Editing a Contact

1

Open the edit form

Navigate to GET /contacts/{id}/edit. You can also click the Edit link on the contact detail page. This route requires the admin or editor role.
2

Update the fields

The edit form is identical to the create form. All fields are pre-populated with the contact’s current values. Multi-value fields are rendered as newline-separated text in their textareas.
3

Save changes

Submit the form. The controller validates the same rules as creation and then sends a PATCH request to /contacts/{id}. On success you are redirected to the contact’s detail view.
Route summary:
MethodURIMiddleware
GET/contacts/{id}/editauth, verified, role:admin,editor
PATCH/contacts/{id}auth, verified, role:admin,editor

​
Deleting a Contact

Deletion is permanent. There is no soft-delete or undo. Once a contact is deleted, all its data is removed from the database immediately.

​
Single delete

From the contact detail page (/contacts/{id}), click Delete. A confirmation modal appears. Confirm to submit a DELETE request to /contacts/{id}. Only users with the admin role can delete contacts.
MethodURIMiddleware
DELETE/contacts/{id}auth, verified, role:admin
On success, the browser is redirected to the contacts list with a session flash message: Contact deleted.

​
Bulk delete

Select one or more contacts using the checkboxes in the first column of the list (visible to admins only). A Delete selected (N) button appears in the toolbar showing the count of selected contacts. Click it to open a confirmation modal. Confirming submits a POST request to /contacts/bulk-destroy with the selected IDs.
MethodURIMiddleware
POST/contacts/bulk-destroyauth, verified, role:admin
Request body: 
POST /contacts/bulk-destroy
Content-Type: application/x-www-form-urlencoded

_token=<csrf>&ids[]=1&ids[]=2&ids[]=5
The ids array is validated to ensure every ID is an integer, distinct, and exists in the contacts table. The delete is wrapped in a database transaction. On success you are redirected to the contacts list with a flash message: Deleted N contact(s).

​
Exporting Contacts

Any authenticated user can export a selection of contacts to a CSV file.
1

Select contacts

Use the row checkboxes on the contacts list page to select the records you want. The toolbar shows the current count: Export selected (CSV) (N).
2

Download the file

Click Export selected (CSV). The browser submits a POST to /contacts/export and immediately downloads the file. The filename is in the format contacts-selected-YYYYMMDD-HHmmss.csv.
MethodURIMiddleware
POST/contacts/exportauth, verified
Request body: 
POST /contacts/export
Content-Type: application/x-www-form-urlencoded

_token=<csrf>&ids[]=1&ids[]=3&ids[]=7

​
Exported columns

The CSV contains one row per contact with the following columns in order: id, contact_category, relationship_status, use_for_events, potential_speaker, organisation_name, first_name, last_name, job_title, emails, phones, country, organisation_types, keywords, relevant_project_programme, expertise_speaking_topics, stakeholder_type, comment, created_at, updated_at The boolean columns use_for_events and potential_speaker are exported as 1 (true) or 0 (false). The JSON array columns (emails, phones, organisation_types, keywords, expertise_speaking_topics) are exported as JSON strings, for example ["alice@example.com","alice@work.org"]. The file is encoded as UTF-8 with a BOM (\xEF\xBB\xBF) prepended so that Microsoft Excel recognises the encoding automatically on open.

Overview & Data Model

Full reference for every field, type, and access-control rule in the Contacts module.

Import & Export

Bulk-import contacts from CSV or Excel and export selected records.

Build docs developers (and LLMs) love

Get started for freeTalk to us