Skip to main content

Creates a contact

POST/dmx/v2/contacts

Creates a contact by tag name and custom field name. When automatic tag creation is not enabled, the request fails if the tag name does not exist; the request fails if the custom field name does not exist or the match is not unique.

Request​

Body parameters

    email stringrequired

    Email address.

    tagNames string[]

    The list of tag names to add to the contact. Append semantics: existing tags are retained, and only the new tags from the current list are added.

    customFields object[]

    Custom field value

    fieldName stringrequired

    Custom field name. The field name must exist and be unique; the request fails if it does not exist or the match is not unique.

    fieldValue string

    Custom field value

    autoCreateTags boolean

    Specifies whether to automatically create the tag if it does not exist. The default value is false. When false, the request fails if any tag name in tagNames does not match an existing tag. When true, the tag is automatically created and appended to the contact.

    conflictPolicy enum

    Handling policy when the contact already exists. The default is to fail on creation. When set to update policy, if an existing contact is found by email, it will be updated with the data provided in this request.

    • CONTACT_CONFLICT_POLICY_FAIL_IF_EXISTS: Returns a conflict error if the contact already exists, without updating.
    • CONTACT_CONFLICT_POLICY_UPDATE_IF_EXISTS: Updates the existing contact if it already exists. Existing tags are retained, and tagNames only appends new tags.

    Possible values: [CONTACT_CONFLICT_POLICY_FAIL_IF_EXISTS, CONTACT_CONFLICT_POLICY_UPDATE_IF_EXISTS]

Response

    contact object
    id string

    Contact ID.

    email string

    Email address.

    tagNames string[]

    List of tag names.

    customFields object[]

    Custom field value

    fieldName stringrequired

    Custom field name. The field name must exist and be unique; the request fails if it does not exist or the match is not unique.

    fieldValue string

    Custom field value

    createTime string<date-time>

    Creation time.

Errors

400Bad Request
401

Access is unauthorized. Please check whether the correct authorization token is passed.

403

No API access permission. Please complete the relevant authorization on the application management page of the domain administrator.

500Internal Server Error