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.

'POST' \  'https://your-engage-domain.com/api/rest/contact/get' \
{
  "type": "EMAIL",
  "value": "j.mcexample@example.com"
}'

<soapenv:Envelope
    xmlns:soapenv="https://schemas.xmlsoap.org/soap/envelope/"
    xmlns:ecm="https://your-engage-domain.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>

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. 

 'POST' \
  'https://your-engage-domain.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"}
]
}

{
  "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"}
  ],
  
}

<soapenv:Envelope
    xmlns:soapenv="https://schemas.xmlsoap.org/soap/envelope/"
    xmlns:ecm="https://your-engage-domain.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>

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. 

POST \'https://your-engage-domain.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"},
]
}

<soapenv:Envelope
    xmlns:soapenv="https://schemas.xmlsoap.org/soap/envelope/"
    xmlns:ecm="https://your-engage-domain.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>

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

Implementation and Error Handling