ConnectCloud Developers

Replace a contact person (tenant:masterdata:write)

PUT /api/masterdata/addresses/{id}/contacts/{cid}

Module: Master data · operationId: updateContactPerson · Tag: Contact persons · Auth: access token (Authorization: Bearer <accessToken>)

The body carries the version of the contact person (not of the address); aspNr is kept. Bumps the address version and emits masterdata.address.updated.

Parameters

Name In Type Required Description
id path string (uuid) yes
cid path string (uuid) yes Contact person id

Request body

application/json (required)

  • aspNr (integer): Number within the address; assigned
  • availableFrom1 (string, nullable): Reachable from (HH:MM)
  • availableFrom2 (string, nullable): Second time window: reachable from (HH:MM)
  • availableTo1 (string, nullable): After availableFrom1
  • availableTo2 (string, nullable): After availableFrom2
  • birthday (string (date), nullable): Birthday (YYYY-MM-DD)
  • blockReason (string, read-only): Reason of the block
  • blockedAt (string (date-time), read-only): Time of the block
  • blockedBy (string, read-only): Actor of the block
  • customFields (CustomFields): Values of tenant-defined fields (/api/masterdata/field-defs) by key. On write the map is merged into the stored values; null removes a key, an omitted map keeps all values. Unknown or archived keys and missing required fields answer 400.
  • department (string): Department
  • doNotCall (boolean): Do not call
  • email1 (string (email)): First e-mail address
  • email2 (string (email)): Second e-mail address
  • emailOptOut (boolean): No marketing e-mails
  • fax (string): E.164
  • firstName (string): First name (max length 128)
  • gdprConsent (string): GDPR consent state (one of UNKNOWN, GRANTED, DENIED, REVOKED; default "UNKNOWN")
  • gdprConsentDate (string (date), nullable): Required when gdprConsent is GRANTED
  • id (string (uuid)): Id of the contact person
  • info (string): Info text
  • isActive (boolean): False when leftAt is set (default true)
  • isBlocked (boolean, read-only): Blocked contact: left out of phone contacts and the platform notification list. Set with POST /addresses/{id}/contacts/{cid}/block
  • isDefault (boolean): Default contact of the address (at most one)
  • languageCode (string): Language (ISO 639-1)
  • lastName (string): Last name (max length 128)
  • leftAt (string (date), nullable): Date the person left the company; sets isActive false
  • letterSalutation (string): Salutation line of letters
  • linkedinUrl (string (uri)): LinkedIn profile (max length 255)
  • mobile (string): E.164
  • namePrefix (string): Name prefix
  • nameSuffix (string): Name suffix
  • phone1 (string): E.164
  • phone2 (string): E.164
  • portalUserId (string): Linked desk portal user (max length 255)
  • position (string): Position
  • postalAddressAnsNr (integer, nullable): ansNr of a postal address of the same address
  • preferredChannel (string): Preferred contact channel (one of EMAIL, PHONE, MOBILE, LETTER, PORTAL)
  • reportsToAspNr (integer, nullable): aspNr of the manager within the same address (no cycles)
  • roles (array of string): Roles in the buying centre or for ticket routing
  • salutationCode (string): Code of salutations
  • timezone (string): IANA time zone
  • title (string): Title
  • version (integer): Version of this contact (child updates)

Example:

{
  "aspNr": 2,
  "availableFrom1": "08:00",
  "availableTo1": "16:00",
  "customFields": {},
  "doNotCall": false,
  "email1": "katrin.stadler@alpenhotel-seeblick.example",
  "emailOptOut": false,
  "firstName": "Katrin",
  "gdprConsent": "UNKNOWN",
  "id": "8b0d2f4b-6c8e-4a0c-9e2a-4c6e8a0c2e4a",
  "isActive": true,
  "isBlocked": false,
  "isDefault": false,
  "languageCode": "de",
  "lastName": "Stadler",
  "letterSalutation": "Sehr geehrte Frau Stadler",
  "phone1": "+498652987612",
  "position": "Empfangsleitung und IT",
  "postalAddressAnsNr": 1,
  "preferredChannel": "PHONE",
  "roles": [
    "TECHNICAL",
    "SUPPORT"
  ],
  "salutationCode": "FRAU",
  "timezone": "Europe/Berlin",
  "version": 3
}

Responses

  • 200 Saved (application/json)
  • 400 Malformed body or query parameter (application/json)
  • 401 Missing, invalid or expired token (empty body)
  • 403 The token lacks the permission or carries no tenant (application/json)
  • 404 Not found in the caller's tenant (or merged, see code) (application/json)
  • 409 Stale version or conflict with existing data (application/json)

Fields of the 200 answer:

  • aspNr (integer): Number within the address; assigned
  • availableFrom1 (string, nullable): Reachable from (HH:MM)
  • availableFrom2 (string, nullable): Second time window: reachable from (HH:MM)
  • availableTo1 (string, nullable): After availableFrom1
  • availableTo2 (string, nullable): After availableFrom2
  • birthday (string (date), nullable): Birthday (YYYY-MM-DD)
  • blockReason (string, read-only): Reason of the block
  • blockedAt (string (date-time), read-only): Time of the block
  • blockedBy (string, read-only): Actor of the block
  • customFields (CustomFields): Values of tenant-defined fields (/api/masterdata/field-defs) by key. On write the map is merged into the stored values; null removes a key, an omitted map keeps all values. Unknown or archived keys and missing required fields answer 400.
  • department (string): Department
  • doNotCall (boolean): Do not call
  • email1 (string (email)): First e-mail address
  • email2 (string (email)): Second e-mail address
  • emailOptOut (boolean): No marketing e-mails
  • fax (string): E.164
  • firstName (string): First name (max length 128)
  • gdprConsent (string): GDPR consent state (one of UNKNOWN, GRANTED, DENIED, REVOKED; default "UNKNOWN")
  • gdprConsentDate (string (date), nullable): Required when gdprConsent is GRANTED
  • id (string (uuid)): Id of the contact person
  • info (string): Info text
  • isActive (boolean): False when leftAt is set (default true)
  • isBlocked (boolean, read-only): Blocked contact: left out of phone contacts and the platform notification list. Set with POST /addresses/{id}/contacts/{cid}/block
  • isDefault (boolean): Default contact of the address (at most one)
  • languageCode (string): Language (ISO 639-1)
  • lastName (string): Last name (max length 128)
  • leftAt (string (date), nullable): Date the person left the company; sets isActive false
  • letterSalutation (string): Salutation line of letters
  • linkedinUrl (string (uri)): LinkedIn profile (max length 255)
  • mobile (string): E.164
  • namePrefix (string): Name prefix
  • nameSuffix (string): Name suffix
  • phone1 (string): E.164
  • phone2 (string): E.164
  • portalUserId (string): Linked desk portal user (max length 255)
  • position (string): Position
  • postalAddressAnsNr (integer, nullable): ansNr of a postal address of the same address
  • preferredChannel (string): Preferred contact channel (one of EMAIL, PHONE, MOBILE, LETTER, PORTAL)
  • reportsToAspNr (integer, nullable): aspNr of the manager within the same address (no cycles)
  • roles (array of string): Roles in the buying centre or for ticket routing
  • salutationCode (string): Code of salutations
  • timezone (string): IANA time zone
  • title (string): Title
  • version (integer): Version of this contact (child updates)
  • addressVersion (integer, required): New version of the address

Example 200 answer:

{
  "addressVersion": 8,
  "aspNr": 2,
  "email1": "katrin.stadler@alpenhotel-seeblick.example",
  "firstName": "Katrin",
  "gdprConsent": "UNKNOWN",
  "id": "8b0d2f4b-6c8e-4a0c-9e2a-4c6e8a0c2e4a",
  "isActive": true,
  "isBlocked": false,
  "isDefault": false,
  "lastName": "Stadler",
  "letterSalutation": "Sehr geehrte Frau Stadler",
  "phone1": "+498652987612",
  "position": "Empfangsleitung und IT",
  "postalAddressAnsNr": 1,
  "roles": [
    "TECHNICAL",
    "SUPPORT"
  ],
  "salutationCode": "FRAU",
  "version": 3
}

Example request

curl -X PUT 'https://api.mbcom.cloud/api/masterdata/addresses/3f6c1a52-7b1e-4d2a-9c8e-2b5f0d6a91e4/contacts/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"aspNr":2,"availableFrom1":"08:00","availableTo1":"16:00","customFields":{},"doNotCall":false,"email1":"katrin.stadler@alpenhotel-seeblick.example","emailOptOut":false,"firstName":"Katrin","gdprConsent":"UNKNOWN","id":"8b0d2f4b-6c8e-4a0c-9e2a-4c6e8a0c2e4a","isActive":true,"isBlocked":false,"isDefault":false,"languageCode":"de","lastName":"Stadler","letterSalutation":"Sehr geehrte Frau Stadler","phone1":"+498652987612","position":"Empfangsleitung und IT","postalAddressAnsNr":1,"preferredChannel":"PHONE","roles":["TECHNICAL","SUPPORT"],"salutationCode":"FRAU","timezone":"Europe/Berlin","version":3}'

View as Markdown · Interactive reference · OpenAPI