Mapping contacts via form submit

When you submit form data via API, you can map these contacts in your Eloqua instance. This tutorial will walkthrough the required form configuration needed to map contacts.

In this tutorial:

• Mapping contacts via form submit
• Step 1 - Create the form and configure the form fields
• Step 2 - Configure the form processing steps
• Creating the form using the API
• Considerations

Step 1 - Create the form and configure the form fields

Create the form using the API endpoints (example provided below) or the Eloqua interface.

Your form must contain at least two fields:

• Email Address

  For the HTML name, specify a name of your choice.

• Hidden Field

  The Hidden Field is used to store the customer's GUID. For the HTML name, specify elqCustomerGUID .

Here's an example form field configuration shown in the user interface.

Step 2 - Configure the form processing steps

Your form must contain the Form Processing Step Update Contacts - With Form Data.

Creating the form using the API

Here's an example of how to create this form using the application 2.0 API endpoint.

Request URL

POST  /api/REST/2.0/assets/form

Request Body

{
  "name": "Mapping contacts via form submit",
  "elements": [
    {
      "name": "Email Address",
      "htmlName": "emailAddress",
      "dataType": "text",
      "displayType": "text",
      "defaultValue": "",
      "type": "FormField",
      "style": "{\"fieldSize\":\"large\"}",
      "fieldMergeId": "1",
      "id": "-1",
      "validations": [
        {
          "id": "-2",
          "message": "This field is required",
          "type": "FieldValidation",
          "condition": {
            "type": "IsRequiredCondition"
          }
        },
        {
          "id": "-3",
          "message": "A valid email address is required",
          "type": "FieldValidation",
          "condition": {
            "type": "IsEmailAddressCondition"
          }
        }
      ]
    },
    {
      "name": "elqCustomerGUID",
      "htmlName": "elqCustomerGUID",
      "type": "FormField",
      "style": "{\"fieldSize\":\"large\"}",
      "dataType": "text",
      "displayType": "hidden",
      "id": "-4",
      "validations": [
        {
          "id": "-5",
          "message": "Value must not contain any URL's",
          "type": "FieldValidation",
          "condition": {
            "type": "PreventUrlCondition"
          }
        },
        {
          "id": "-6",
          "message": "Value must not contain any HTML",
          "type": "FieldValidation",
          "condition": {
            "type": "PreventXSSCondition"
          }
        },
        {
          "type": "FieldValidation",
          "id": "-7",
          "message": "Invalid length for field value",
          "condition": {
            "maximum": "35",
            "minimum": "0",
            "type": "TextLengthCondition"
          }
        }
      ]
    },
    {
      "name": "Submit",
      "htmlName": "submit",
      "fieldType": "submit",
      "type": "FormField",
      "style": "{\"fieldSize\":\"large\"}",
      "displayType": "submit",
      "style": "{\"fieldSize\":\"large\",\"submitButtonStyleType\":\"standard\"}",
      "id": "-8",
      "validations": [
        
      ],
      "hasProbableError": false,
      "instructions": ""
    }
  ],
  "processingSteps": [
    {
      "type": "FormStepCreateUpdateContactFromFormField",
      "execute": "always",
      "id": "-9",
      "mappings": [
        {
          "type": "FormFieldUpdateMapping",
          "sourceFormFieldId": "-1",
          "targetEntityFieldId": "100001",
          "updateType": "useFieldRule",
          "id": "-10"
        },
        {
          "type": "FormFieldUpdateMapping",
          "sourceFormFieldId": "-4",
          "updateType": "useFieldRule",
          "id": "-11"
        }
      ],
      "keyFieldId": "100001",
      "hasValidationIssue": "false"
    }
  ],
  "style": "{\"fieldSize\":\"medium\",\"labelPosition\":\"top\"}",
  "processingType": "externalWebsite"
}

Considerations

• The Email Address field must be mapped, but the GUID hidden field does not need to be mapped. Additional fields can be mapped as appropriate.

• The field to store the GUID must have the exact HTML name specified above (elqCustomerGUID).

• The GUID hidden field value must be in GUID format "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx". The dashes are not required. To submit form data when you do not have a GUID value, use a value with all zeros for the field. For example: "00000000-0000-0000-0000-000000000000" or "00000000000000000000000000000000".

• If the Email Address doesn't exist, a new Contact would be created and linked to the visitor; otherwise, the Contact with the matching Email Address will be linked to the visitor indicated.

• When form data is reposted to Oracle Eloqua servers from a server-side form processor, elqCookieWrite should be specified and set to 0. More information about reposting can be found in the Eloqua Help Center.

Learn more

Eloqua API tutorials