Registering a new Contact who Signs up for an Account

If you'd like, you can test with our Postman Collection here: Postman Collection

Prerequisites

Before you begin, make sure you have valid authorization credentials. Please see this page for more information. 

You will need to have the new contacts' email and any other information you'd like to add to their profile, like a name, phone number, or country.

Procedure

To search for a contact or update their information, you will need to decide which identifier you'd like to use:

In our examples, we'll use email. 

1.  (Optional) Use a POST request to check if the contact already exists

   To avoid errors, you may wish to double-check that the contact exists. To use contact/get, you must provide the desired identifier type & subsequent identifier. In this case, we will use the contact's email address. If the customer exists, you can either exit this process or update the contact information with step 3.
   
   • REST
   • SOAP

   'POST' \  'http://yourdomain.com/api/rest/contact/get' \
   {
     "type": "EMAIL",
     "value": "j.mcexample@example.com"
   }'

   JS

   <soapenv:Envelope
       xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
       xmlns:ecm="http://yourdomain.com/developer/ecmapi">
       <soapenv:Header/>
       <soapenv:Body>
           <ecm:contactGet>
               <identifier>
                   <type>EMAIL</type>
                   <value>j.mcexample@example.com</value>
               </identifier>
           </ecm:contactGet>
       </soapenv:Body>
   </soapenv:Envelope>

   JS

   Response	Description
   200	From this request, you should receive a 200 response, with information about the contact. This includes information like their contactID.
   400	If the profile does not exist you will receive a 400 response. You can also double-check the email used in the call if you believe there is an existing user profile.

2. Use a POST request to create the Contact Profile

   For this, you need to specify at least one of the following identifiers: email address, mobile number, or mobile app alias. In this case, we will use the contact's email address. 

   • REST
   • SOAP

    'POST' \
     'http://yourdomain.com/api/rest/contact/create'\ 
   {
   "emailAddress": "j.mcexample@example.com",
   "attributes":
   [
   {"name": "FirstName", "value": "John"},
   {"name": "LastName", "value": "mcexample"},
   {"name": "mobileNumber", "value": "33505606709"},
   {"name": "user.ISOCountryCode", "value": "FR"}
   ]
   }

   JS

   You should receive a 200 response, alongside your contact's information like this:

   {
     "id": 0,
     "email": "j.mcexample@example.com",
     "mobileNumber": "string",
     "identifier": "string",
     "attributes": [
       {"name": "FirstName", "value": "John"},
       {"name": "LastName", "value": "mcexample"},
       {"name": "mobileNumber", "value": "33505606709"},
       {"name": "user.ISOCountryCode", "value": "FR"}
     ],
     
   }

   JS

   If there was a problem, like missing required information, you might receive a 400 response.

   <soapenv:Envelope
       xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
       xmlns:ecm="http://yourdomain.com/developer/ecmapi">
       <soapenv:Header/>
       <soapenv:Body>
           <ecm:contactCreate>
               <contact>
                   <contactId>1</contactId>
                   <emailAddress>j.mcexample@example.com</emailAddress>
                   <mobileNumber>48505606707</mobileNumber>
                   <applicationAlias>?</applicationAlias>
                   <identifier>?</identifier>
                   <!--Zero or more repetitions:-->
                   <attributes>
                       <name>test</name>
                       <value>test</value>
                   </attributes>
               </contact>
           </ecm:contactCreate>
       </soapenv:Body>
   </soapenv:Envelope>

   JS

3. (Optional) Use a POST request to update the information

   To use contact/update, you will need to provide:

   • The contact identifier type in the URL and the body of the call.

   • The attribute to update.

   • The new value.

   In this example, we update the contact's name. You could substitute in any stored attribute, such as their mobile phone number.
   

   Please note that the identifier type is written differently in the body of the call and the request URL. In our example, we are using the email address, which is "EMAIL" in the URL, and "emailAddress" in the body of the call. Please see the contact/update entry in Swagger for a complete list. 

   • REST
   • SOAP

   POST \'http://yourdomain.com/api/rest/contact/update?identifierType=EMAIL&unifiedIdentifierName=j.mcexample%40example.com' \
   {
   "emailAddress": "j.mcexample@example.com",
   "attributes":
   [
   {"name": "FirstName", "value": "John"},
   {"name": "LastName", "value": "McExample"},
   ]
   }

   JS

   
   

   
   

   <soapenv:Envelope
       xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
       xmlns:ecm="http://yourdomain.com/developer/ecmapi">
       <soapenv:Header/>
       <soapenv:Body>
           <ecm:contactUpdate>
               <identifierType>EMAIL</identifierType>
               <contact>                
                   <emailAddress>j.mcexample@example.com</emailAddress>
                   <!--Zero or more repetitions:-->
                   <attributes>
                       <FirstName>John</FirstName>
                       <LastName>McExample</LastName>
                   </attributes>
               </contact>
           </ecm:contactUpdate>
       </soapenv:Body>
   </soapenv:Envelope>

   JS

Conclusion

If the request is successful, your contact's profile will be created (or updated). If you received a 400 response, several things could have gone wrong. Please recheck the request. 

Related Topics

Engage web service implementation and error handling

Updating a Contact