This function ‘upserts’ a Contact in Marketing Cloud. If the Contact does not already exist, then a new record is created. If the Contact exists, then the record is updated.

The function will output 1 if an error occurred when upserting the Contact and 0 if the upsert was successful.



Ordinal Type Required Description
1 String True The Contact channel. Only mobile is supported at this time.
2 String True Attribute to match the Contact. Only phone is supported at this time.
3 Integer True Phone number with country area code
4 String True Attribute name to upsert (see below)
5 String or Integer True Attribute value to upsert
6a String False Additional attribute name to upsert (see note)
6b String or Integer False Additional attribute value to upsert (see note)

NOTE: Additional attribute name and value pairs can be appended as arguments.

NOTE: This function currently only supports mobile Contacts. Other channels should be supported in a future release.


You can include user-created attributes and system attributes when upserting mobile Contacts.

User-Created Attributes

To view available user-created attributes or to create new attributes, follow these steps:

  • Open Contact Builder Application.
  • Select the MobileConnect Data Attribute Group from the constellation view in Data Designer.
  • View the user-created attributes in the MobileConnect Demographics Attribute Set, or click ‘Create Attribute’ to add additional attributes.

System Attributes

The following system attributes are currently supported by this function.

Name Attribute
City _City
State _State
Zip _ZipCode
First Name _FirstName
Last Name _LastName
UTC Offset _UTCOffset


The following example inserts or updates a mobile Contact record.


var @upsert
set @upsert = UpsertContact("mobile",
                            "phone", 13153695271,
                            "_City", "Old Forges",
                            "_State", "NY",
                            "_ZipCode", 13420,
                            "_FirstName", "Scott",
                            "_LastName", "Jones",
                            "_UTCOffset", -5

result: %%=v(@upsert)=%%


A value of 0 is set by the function, indicating that no errors occurred.

result: 0