Client Onboarding

This guide walks through the full process of onboarding a new client (contact) into the Altafid platform via the REST API — from initial creation through compliance and sales profile updates to credential activation.

Base URL: https://api.altafid.dev.altafid.net
All requests require standard auth headers — see Global Headers.

Onboarding Flow

A contact goes through three sequential API calls before they are fully active on the platform:

1
Create Contact
POST /api/contacts
Returns contactUuid
→
2
Update Profile
PUT /api/contacts/{uuid}
Sales & compliance data
→
3
Activate
PUT + POST /credentials/init
Sets primaryEmail & creates login
Order matters: credentials/init will fail unless primaryEmail has been set via the PUT endpoint first.

POST/api/contacts

Creates a new contact (client individual). Returns a contactUuid used in all subsequent calls.

Request Body

{
  // ── Identity ────────────────────────────────────────────────
  "firstName":                "Juan",           // required
  "paternalLastName":         "García",         // required
  "maternalLastName":         "López",          // optional
  "middleName":               "Carlos",         // optional

  // ── Classification ──────────────────────────────────────────
  "contactType":              "SUBSCRIBER",     // required  — see enum table
  "contactMeans":             "EMAIL",          // required  — EMAIL | PHONE | MESSAGE
  "preferredContactLanguage": "SPANISH",        // required  — SPANISH | ENGLISH

  // ── Firm / manager ──────────────────────────────────────────
  "firmId":                   "<tenantUuid>",   // required
  "firmType":                 "TENANT",         // required
  "contactManagerId":         "<staffUuid>",   // required
  "contactManagerFirmType":   "TENANT",         // required
  "status":                   "ACTIVE",         // required

  // ── Contact details ─────────────────────────────────────────
  "preferredEmail":           "juan@example.com",
  "dateOfBirth":              "1980-05-20",     // YYYY-MM-DD
  "gender":                   "MALE",           // MALE | FEMALE
  "maritalStatus":            "MARRIED",        // see enum table

  "preferredPhoneNumber": {
    "phoneCountryCode":       "+56",
    "phoneNumber":            "912345678"
  },

  // ── Government ID ───────────────────────────────────────────
  "identityType":             "CHILE_RUT",      // CHILE_RUT | PASSPORT
  "identityId":               "12345678-9",
  "identityCountry":          "CHL",            // ISO-3 country code

  // ── CRM fields (values fetched from config APIs) ────────────
  "contactSource":            "conSource001",   // GET /api/core/platformconfigs/v1/contacts/sources
  "marketSegment":            "highNetWorth",   // GET /api/core/platformconfigs/v1/contacts/segments
  "contactPreference":        "EMAIL"           // EMAIL | CALL | MESSAGE
}

Required Fields Summary

FieldTypeRequiredNotes
firstNamestringrequired
paternalLastNamestringrequired
maternalLastNamestringoptional
middleNamestringoptional
contactTypeenumrequiredSUBSCRIBER | PROSPECT | NON_SUBSCRIBER
contactMeansenumrequiredEMAIL | PHONE | MESSAGE
preferredContactLanguageenumrequiredSPANISH | ENGLISH
firmIdstringrequiredTenant UUID
firmTypeenumrequiredAlways TENANT
contactManagerIdstringrequiredStaff UUID
contactManagerFirmTypeenumrequiredAlways TENANT
statusenumrequiredAlways ACTIVE
preferredEmailstringoptionalSet here for creation; primaryEmail set later via PUT
dateOfBirthstringoptionalFormat: YYYY-MM-DD
genderenumoptionalMALE | FEMALE
maritalStatusenumoptionalMARRIED | SINGLE | DIVORCED | WIDOWED
preferredPhoneNumberobjectoptional{ phoneCountryCode, phoneNumber }
identityTypeenumoptionalCHILE_RUT | PASSPORT
identityIdstringoptionalThe ID value
identityCountrystringoptionalISO-3 (e.g. CHL, ARG, USA)
contactSourcestringoptionalFrom GET /api/core/platformconfigs/v1/contacts/sources
marketSegmentstringoptionalFrom GET /api/core/platformconfigs/v1/contacts/segments
contactPreferenceenumoptionalEMAIL | CALL | MESSAGE

Response 200 OK

{
  "contactUuid": "C019BFA7DAD1B73438B06B6D0C33A4D11",
  "firstName": "Juan",
  "paternalLastName": "García",
  ...
}
Save contactUuid — you need it for all update and activation calls.

PUT/api/contacts/{contactUuid} — Sales Information

Updates the contact's sales-side profile: address, CRM stage, segment, financial figures, and identity details. This is the same endpoint used for all contact updates — the fields you include determine what gets updated.

{
  "firstName": "Peter",
  "paternalLastName": "Parker",
  "contactType": "SUBSCRIBER",
  "preferredContactLanguage": "ENGLISH",
  "status": "ACTIVE",
  "gender": "MALE",
  "dateOfBirth": "1980-05-09",
  "maritalStatus": "SINGLE",

  "preferredEmail": "peter.parker@yopmail.com",
  "preferredPhoneNumber": {
    "phoneCountryCode": "+1",
    "phoneNumber": "4704704011"
  },

  // ── Financial ───────────────────────────────────────────────
  "annualIncome":   "365332",
  "liquidNetWorth": "76526753",
  "totalNetWorth":  "354353421",

  // ── Government ID ───────────────────────────────────────────
  "identityType":    "PASSPORT",
  "identityId":      "P7652675672",
  "identityCountry": "AFG",

  "countryOfCitizenship": "AGO",
  "countryOfBirth":       "ARG",

  // ── CRM metadata (values from config APIs) ──────────────────
  "contactSource":  "conSource001",   // GET /api/core/platformconfigs/v1/contacts/sources
  "segmentName":    "conSegment001",  // GET /api/core/platformconfigs/v1/contacts/segments
  "stageName":      "conStage001",    // GET /api/core/platformconfigs/v1/contacts/stages
  "contactPreference": "CALL",
  "contactMeans":   "PHONE",
  "displayName":    "Peter Parker",

  // ── Firm / manager ──────────────────────────────────────────
  "firmEntityUuid":            "T0198DDA7B8EC7B6D9E12734DA8657106",
  "firmName":                  "Sprint 1 Tenant Admin 4",
  "firmType":                  "TENANT",
  "capturedByEntityUuid":      "PS0199CA8F08C270B5A5B0DFD3B565B332",
  "capturedByType":            "TENANT",
  "contactManagerEntityUuid":  "PS0199CA8F08C270B5A5B0DFD3B565B332",
  "contactManagerType":        "PARTNER",

  // ── Addresses ───────────────────────────────────────────────
  "addresses": [
    {
      "addressUuid":         "CAD019C0DDC195371089C082DE6450D625B",  // include for update; omit for new
      "streetNumber":        "123-AB",
      "streetName":          "GR St.",
      "city":                "Grecian",
      "state":               "Grestate",
      "zipCode":             "873678",
      "country":             "GRC",
      "apartment":           "XB Apts.",
      "commune":             "Grecommune",
      "landmark":            null,
      "addressType":         "HOME",
      "contactAddressType":  "SALES",    // SALES | COMPLIANCE
      "isPrimary":           false
    }
  ]
}

PUT/api/contacts/{contactUuid} — Compliance Information

Updates KYC/compliance data: identity documents, employment history, PEP declarations, address, and financial profile. Uses the same endpoint as the sales update.

{
  "firstName":       "Arpit",
  "middleName":      null,
  "paternalLastName": "Gangwar",
  "maternalLastName": null,
  "alias":           null,

  "primaryEmail":    "arpitsingh414@gmail.com",
  "phoneNumber": {
    "country":          "IN",
    "phoneCountryCode": "+91",
    "phoneNumber":      "9897987689"
  },

  "gender":                    "MALE",
  "dateOfBirth":               "1991-08-16",
  "primaryCountryOfCitizenship": "BEL",
  "countryOfBirth":            "BRA",
  "maritalStatus":             "SINGLE",
  "preferredContactLanguage":  "ENGLISH",

  // ── Financial ───────────────────────────────────────────────
  "annualIncome":   "2222222",
  "liquidNetWorth": "87675765",
  "totalNetWorth":  "765767872",

  // ── PEP / Compliance flags ───────────────────────────────────
  "relatedToPEP":                    false,
  "directorOrTenPercentShareholder": false,
  "pepEntries":                      [],
  "companyNames":                    null,
  "tradingSymbols":                  null,

  // ── Address (contactAddressType: COMPLIANCE) ─────────────────
  "addresses": [
    {
      "country":             "AFG",
      "city":                "Kabul",
      "state":               "Kabul",
      "commune":             "Labu",
      "streetName":          "ABC St.",
      "streetNumber":        "123",
      "apartment":           "ABC Apt.",
      "zipCode":             "677621",
      "contactAddressType":  "COMPLIANCE",  // COMPLIANCE for KYC address
      "isPrimary":           true,
      "addressType":         "HOME"
    }
  ],

  // ── Identity documents ───────────────────────────────────────
  "identityDocuments": [
    {
      "specificationData": {
        "specificationType": "CHILE_RUT_CARD",  // see identity types below
        "country":           "CHL",
        "identityId":        "CHL8761756",
        "issuingAuthority":  "Chile Gov"
      }
    }
  ],

  // ── Employment history ───────────────────────────────────────
  "currentEmployment": null,
  "employmentHistory": [
    {
      "employmentStatus": "employed",       // employed | self_employed | unemployed | retired | student
      "employerName":     "EMPY Employer",
      "jobPosition":      "Manager",
      "startDate":        "1980-05-02",     // YYYY-MM-DD
      "endDate":          "1986-09-12",     // YYYY-MM-DD
      "country":          "AF",
      "streetName":       "Bakul",
      "regionState":      "Kabul",
      "streetNumber":     "123",
      "city":             "Kabul",
      "apartment":        "XYH Apt.",
      "commune":          "Labuk",
      "zipCode":          "8767652"
    }
  ],

  // ── Custom fields ────────────────────────────────────────────
  "customFields": null,

  // ── Read-only (returned in GET, ignored on write) ────────────
  "contactComplianceUuid": "CCMP019D02804EC87C44BFD85C56048D9AAF",
  "contactUuid":           null
}

Identity Document Types

specificationTypeCountryNotes
CHILE_RUT_CARDCHLChilean national ID (RUT)
PASSPORTAnyInternational passport
NATIONAL_IDAnyGeneric national ID card

Activation — Set Email + Init Credentials

After creating and updating a contact, run these two calls to enable platform login.

Step 3a — Set primaryEmail

PUT/api/contacts/{contactUuid}

{
  "primaryEmail":             "juan@example.com",
  "preferredContactLanguage": "SPANISH",

  // Include identity if the contact has one:
  "identityType":    "CHILE_RUT",
  "identityId":      "12345678-9",
  "identityCountry": "CHL"
}

Step 3b — Initialize credentials

POST/api/contacts/{contactUuid}/credentials/init

{}
Returns 200 on success. The contact can now log in using their primaryEmail.

Dynamic Enum APIs

These values are tenant-specific and must be fetched at runtime before syncing contacts. The returned IDs/names are used directly as field values.

FieldAPI EndpointPurpose
stageName GET/api/core/platformconfigs/v1/contacts/stages Pipeline stages (e.g. etapa1, etapa2, etapa3)
contactSource GET/api/core/platformconfigs/v1/contacts/sources Contact origin / lead source
segmentName / marketSegment GET/api/core/platformconfigs/v1/contacts/segments Market segment classification

Hardcoded Enums

These values are static across all tenants. The API will reject any value not in the allowed list.

FieldAllowed ValuesNotes
gender MALE FEMALE OTHER
maritalStatus MARRIED SINGLE DIVORCED WIDOWED
contactMeans EMAIL PHONE MESSAGE
identityType CHILE_RUT PASSPORT NATIONAL_ID US_EIN DRIVING_LICENSE UK_COMPANY_NUMBER BVI_COMPANY_NUMBER
preferredContactLanguage SPANISH ENGLISH
contactType SUBSCRIBER ACTIVE
status ACTIVE INACTIVE
contactManagerType TENANT PARTNER
firmType TENANT PARTNER
employmentStatus self-employed employed homemaker retired student not-employed

Field Matrix — Which Call Takes Which Field?

Use this as a quick reference when building your integration.

Field POST /contacts
Create		 PUT /contacts/{id}
Sales update		 PUT /contacts/{id}
Compliance update		 PUT /contacts/{id}
Activate
firstName✓✓✓
paternalLastName✓✓✓
maternalLastName✓✓✓
middleName✓✓✓
contactType✓✓
contactMeans✓✓
preferredContactLanguage✓✓✓✓
firmId / firmEntityUuid✓✓
firmType✓✓
contactManagerId / contactManagerEntityUuid✓✓
status✓✓
preferredEmail✓✓
primaryEmail✓✓
dateOfBirth✓✓✓
gender✓✓✓
maritalStatus✓✓✓
preferredPhoneNumber✓✓
phoneNumber (object)✓
identityType✓✓✓
identityId✓✓✓
identityCountry✓✓✓
identityDocuments[]✓
contactSource✓✓
marketSegment / segmentName✓✓
stageName✓
contactPreference✓✓
displayName✓
countryOfCitizenship / primaryCountryOfCitizenship✓✓
countryOfBirth✓✓
annualIncome✓✓
liquidNetWorth✓✓
totalNetWorth✓✓
addresses[]✓✓
employmentHistory[]✓
relatedToPEP✓
directorOrTenPercentShareholder✓
pepEntries[]✓
customFields✓