UpsertContact

Runtime verified Test scripts included

Syntax

UpsertContact(channel, attribute, phoneNumber, keyToUpsert1, valueToUpsert1[, keyToUpsertN, valueToUpsertN, ...])  →  number

Parameters

Name	Type	Required	Description
`channel`	string	Yes	Contact channel; only `mobile` is supported
`attribute`	string	Yes	Match attribute; only `phone` is supported
`phoneNumber`	string \| number	Yes	Phone number including country code
`keyToUpsert1`	string	Yes	Name of the first attribute to upsert
`valueToUpsert1`	string	Yes	Value of the first attribute
`keyToUpsertN`	string	No	Further attribute name
`valueToUpsertN`	string	No	Value for the corresponding further attribute

Attributes are supplied as repeating name/value pairs; there is no upper bound on the number of pairs. The attribute name must be a defined MobileConnect attribute — a system attribute such as _ZipCode, _City, _State, _FirstName, _LastName or _UTCOffset, or a user-created MobileConnect attribute.

Example

%%[
  VAR @status
  SET @status = UpsertContact("mobile", "phone", 14255550142, "_ZipCode", "98026")
]%%
Status: %%=v(@status)=%%

Renders Status: 0 — the upsert succeeded. The same call made a second time for the same phone number updates the existing contact and again returns 0.

A successful upsert writes a real mobile contact

On success this function creates or updates a live mobile contact keyed on the phone number. AMPscript has no contact-delete function, so a contact created this way cannot be removed from AMPscript. Only run the success path against a number you are willing to keep as a contact, and never against a real handset you do not control.

Return value

number — a status code: 0 on success, 1 on error.

The return is a closed two-value status code, not a count of records. 0 was proven for both creating a new contact and updating an existing one; 1 was proven for several error conditions.

Behaviour

A create and an update both return 0. Upserting an opaque, unreachable phone number in a reserved test range with the system attribute _ZipCode returned 0 and created the contact; calling the same phone number again with a different value updated that contact and again returned 0.

An unknown attribute name returns 1 without writing. Passing an attribute name that is not a defined MobileConnect attribute returned 1 with the page rendering fully and no contact written. The same 1 is returned for an unsupported channel (anything other than mobile) and for a non-numeric phone value.

The phone number accepts an integer or a numeric string. Both 447700900523 and "447700900524" returned 0 for a successful create, so either form is accepted for the phone argument.

Show test script

%%[
  VAR @b
  SET @b = RequestParameter("b")

  /* an attribute name that is not a defined MobileConnect attribute
     returns 1 (error) and writes nothing */
  IF @b == "badattr" THEN
    VAR @r1
    OutputLine(Concat("badattr start"))
    SET @r1 = UpsertContact("mobile", "phone", 447700900000, "_NotAnAttribute", "x")
    OutputLine(Concat("badattr.result=[", @r1, "]"))
    OutputLine(Concat("badattr done"))
  ENDIF

  /* an unsupported channel returns 1 (error) and writes nothing */
  IF @b == "badchannel" THEN
    VAR @r2
    OutputLine(Concat("badchannel start"))
    SET @r2 = UpsertContact("email", "phone", 447700900000, "_ZipCode", "70423")
    OutputLine(Concat("badchannel.result=[", @r2, "]"))
    OutputLine(Concat("badchannel done"))
  ENDIF

  /* a non-numeric phone returns 1 (error) and writes nothing */
  IF @b == "badphone" THEN
    VAR @r3
    OutputLine(Concat("badphone start"))
    SET @r3 = UpsertContact("mobile", "phone", "notaphone", "_ZipCode", "70423")
    OutputLine(Concat("badphone.result=[", @r3, "]"))
    OutputLine(Concat("badphone done"))
  ENDIF
]%%

OutputLine needs Concat

OutputLine given a bare string literal renders an empty line. Wrap the argument in Concat() or your start and done markers vanish silently — which looks exactly like the function failing.

Availability

Platform	Available
Marketing Cloud Engagement	Yes
Marketing Cloud Next	No