ConnectCloud Developers

Draft a contact person from text or an image (tenant:masterdata:write)

POST /api/masterdata/addresses/{id}/contacts:draft

Module: Master data · operationId: draftContactPerson · Tag: Drafts · Auth: access token (Authorization: Bearer <accessToken>)

Extracts a contact person of the address from pasted text or an image (url and email are not used). Nothing is stored. duplicates lists contacts of the same address that look the same.

Parameters

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

Request body

application/json (required)

  • email (string): Email address whose domain is looked up (address drafts only) (max length 320)
  • imageData (string): Base64 image or data URI (business card, scanned letter); read via OCR after a malware scan (an image with a finding, or when the scan is unavailable, is not read and a warning on imageData says why) (max length 3145728)
  • mimeType (string): image/* or application/pdf (max length 64)
  • text (string): Pasted text: email signature, letterhead, delivery address … (max length 20000)
  • url (string): Website or imprint URL (address drafts only) (max length 2048)

Example:

{
  "text": "Erika Musterfrau\nLeitung Einkauf\nMobil +49 171 1234567\nerika.musterfrau@muster.de"
}

Responses

  • 200 The draft (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)
  • 413 The body is over the limit (2 MiB; AI drafts 4 MiB) (application/json)
  • 429 Too many AI drafts or imprint lookups of this person – wait Retry-After seconds (rate limits) (application/json)
  • 502 The AI could not read the input (application/json)
  • 503 The AI is not reachable (application/json)

Fields of the 200 answer:

  • aiAvailable (boolean, required): False when the AI was not available
  • draft (ContactPerson, required): One contact person (Ansprechpartner). Needs a first or last name; at most one default contact.
    • 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)
  • duplicates (array of ChildDuplicate, required): Contact persons of the same address that look the same
    • id (string (uuid), required): Id of the existing contact person or postal address
    • label (string, required): Name or street line of the existing entry
    • number (integer, required): aspNr or ansNr
    • reason (string, required): Why it looks the same (EMAIL, NAME or POSTAL_CODE)
  • fieldSources (FieldSources, required): Where each pre-filled field (JSON name) came from
  • warnings (array of DraftWarning, required): Unknown lookup codes, invalid formats or failed sources
    • message (string, required): German hint
    • field (string): JSON name of the draft field (empty for the whole draft)

Example 200 answer:

{
  "aiAvailable": true,
  "draft": {
    "email1": "info@hotel-waldblick.example",
    "firstName": "Markus",
    "lastName": "Pongratz",
    "phone1": "+49992477810",
    "position": "Inhaber",
    "salutationCode": "HERR"
  },
  "duplicates": [],
  "fieldSources": {
    "email1": "text",
    "firstName": "text",
    "lastName": "text",
    "phone1": "text",
    "position": "text"
  },
  "warnings": []
}

Example request

curl -X POST 'https://api.mbcom.cloud/api/masterdata/addresses/3f6c1a52-7b1e-4d2a-9c8e-2b5f0d6a91e4/contacts:draft' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"text":"Erika Musterfrau\nLeitung Einkauf\nMobil +49 171 1234567\nerika.musterfrau@muster.de"}'

View as Markdown · Interactive reference · OpenAPI