Contacts API

Contacts are the primary record type for managing individuals on the Altafid platform. The API supports standard CRUD operations, filtered list views, optional compliance payloads, associations to organisations and other contacts, and client-portal credential flows.

List and search endpoints

curl "https://api.altafid.dev.altafid.net/api/contacts/search?searchTerm=jane&page=0&size=20" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "x-tenant-uuid: YOUR_TENANT_UUID" \
  -H "x-user-email: YOUR_EMAIL" \
  -H "x-user-id: YOUR_USER_ID" \
  -H "x-user-type: TENANT_STAFF"

Create and update contacts

POST/api/contacts accepts core identity, firm, and communication fields and can optionally include compliance and association data.

{
  "firstName": "Jane",
  "paternalLastName": "Doe",
  "contactType": "ACTIVE",
  "firmId": "T019A16FF372A70B5A9307B00CE85E4DA",
  "firmType": "TENANT",
  "preferredEmail": "jane.doe@example.com",
  "primaryEmail": "jane.doe@example.com",
  "preferredContactLanguage": "ENGLISH",
  "preferredPhoneNumber": {
    "countryCode": "+1",
    "number": "5551234567"
  },
  "stage": "Prospect",
  "segment": "Retail",
  "contactSource": "Referral"
}

PUT/api/contacts/{contactUuid} is partial-update oriented. Send only the fields you intend to change — null or omitted values leave existing data unchanged.

Compliance endpoints

The compliance profile stores KYC data, financial profile information, and identity documentation for a contact.

{
  "primaryEmail": "jane.doe@example.com",
  "phoneNumber": {
    "countryCode": "+1",
    "number": "5551234567"
  },
  "gender": "FEMALE",
  "dateOfBirth": "1990-01-15",
  "primaryCountryOfCitizenship": "USA",
  "countryOfBirth": "USA",
  "maritalStatus": "SINGLE",
  "preferredContactLanguage": "ENGLISH",
  "liquidNetWorth": 100000.00,
  "annualIncome": 85000.00,
  "identityDocuments": []
}

The compliance payload also supports legal addresses, employment history, identity documents (see identityType enum below), PEP entries, and additional disclaimer fields.

Association endpoints

Associations link a contact to other contacts (e.g. spouse, child) or to organisations (e.g. employer, beneficial owner). Associations are stored as a list and can be replaced in full or added incrementally.

[
  {
    "associatedContacts": [
      {
        "contactUuid": "C019B9D0FD0E5772F9E8ED189895D40C4",
        "role": "SPOUSE"
      }
    ],
    "associatedOrganisations": [],
    "externalContacts": []
  }
]

Client portal credential flow

Contacts can be given access to the Altafid client portal. The credential flow must be completed in sequence: initialise, then create the password.

V2 filtering

POST/api/v2/contacts supports complex filter logic with optional minimal custom field enrichment for grid rendering.

{
  "filters": [
    { "field": "contactType", "operator": "equals", "value": "ACTIVE" },
    { "field": "stageName", "operator": "in", "values": ["Prospect", "Client"] }
  ],
  "page": 0,
  "size": 20,
  "sort": ["createdAt,desc"]
}

Use POST /api/v2/contacts/filter-values to retrieve distinct values for a field within the current tenant scope.

Enum reference

The following fields accept a fixed set of values defined by the platform. Pass the exact string value shown.

contactType

Indicates whether the person is an active client or a prospect.

gender

maritalStatus

preferredContactLanguage

contactMeans

The preferred communication channel.

contactPreference

firmType

Indicates which kind of entity the contact belongs to.

identityType (for identity documents)

addressType

contactAddressType

Indicates the compliance purpose of an address record.

Dynamic fields

The following contact fields are configured per-tenant and their valid values must be retrieved from the platform at runtime. See Dynamic configuration lookups for the full list of endpoints.