Migrate from Firmao CRM to Twenty CRM

Firmao Company records map directly to Twenty Company records. Firmao exposes Companies via /svc/v1/company with no internal ID in the GET response — we use companyName as the dedupe key. Twenty requires Companies to exist before importing related People (Contacts), so this is always the first object migrated. Address, industry, and website fields map 1:1 where present.

Firmao Contact records map to Twenty Person records. We resolve the parent Company via companyName matching (since Firmao does not expose companyId in the GET response) and link the Person to the Company after Companies are imported. Standard contact properties (name, email, phone, job title) map directly. Custom contact fields (customFields.customN) require pre-creation in Twenty Settings → Data Model before migration.

Deals migrate to Twenty Opportunity only if the customer is on Firmao Professional or above — Deals are not accessible via API on the Standard plan. If the account is on Standard, we flag the absence and ask the customer to upgrade before Deal import. On Professional and above, dealName, dealValue, dealstage, and ownerId map to Opportunity name, amount, stage, and assignee respectively. Pipeline stages are organization-defined in Firmao and migrate as Twenty stage values after confirmation from the customer.

Firmao Tasks map to Twenty Tasks with assignee, due date, status, and description preserved. The parent Deal association is resolved via dealName matching against imported Opportunities since Firmao does not expose dealId in the GET response. Tasks without a resolvable parent Deal are imported as standalone tasks and flagged for manual link review.

Firmao Products map to Twenty Product records. The base product fields (name, SKU, description, base price) migrate directly. Per-warehouse stock state — stored in Firmao as subClass=warehouse subId entries on the product — is extracted and flattened into individual warehouse records in Twenty if Twenty's warehouse model is in use, or consolidated into product-level stock notes if not.

Firmao Invoice records (VAT invoices, bills, receipts, accounting notes with line items and tax codes) do not have a native equivalent in Twenty's standard object set. We create a custom object named Invoice in Twenty's Data Model before migration and map invoice header fields and line items as detail rows linked to the Invoice custom object. If the customer does not require invoice history in Twenty, we recommend archiving the full invoice dataset as a CSV export rather than importing into a custom object.

Firmao Users (name, email, role) are exported via /svc/v1/user and mapped to Twenty Users by email match. Owner assignments on Deals and Tasks are resolved by cross-referencing the Firmao owner email against the migrated User list. Users without a matching Twenty User are placed in a reconciliation queue for the customer's admin to provision before record import resumes.

Firmao stores tags as comma-separated values on Contact and Company records. We extract the unique tag values, create a multi-select custom field in Twenty's Data Model (one field per object: Contact Tags, Company Tags), populate the values, and flag any tag with more than 20 unique values for a separate discussion on normalization strategy.

Firmao custom fields (customFields.custom5 through customFields.customN) require enumeration from a sample GET response before migration. We retrieve a representative record to identify which custom field keys are populated, cross-reference against any import documentation the customer provides, and pre-create matching custom fields in Twenty's Data Model with appropriate types (text, number, date, select). Empty custom fields in the sample are excluded from migration. This step is mandatory because Twenty requires fields to exist before CSV import.

Firmao pipeline stages are a property on the Deal object, not a standalone API entity. We extract all unique stage values from Deal records and ask the customer to confirm stage names and order during scoping. These become Twenty Opportunity stage values. Stage probability percentages are migrated as custom fields on the Opportunity if the customer tracks them in Firmao, since Twenty does not expose per-stage probability at the standard object level.