REST API for Oracle Eloqua Marketing Cloud Service

Retrieve visitor data by visitor GUID

post

/api/rest/2.0/data/visitors

Retrieves visitor data for up to 200 visitors, searched by visitor GUID, aka externalId. Use the depth parameter when making the request to specify the visitor information returned in the response.

Request

Supported Media Types

application/json

Header Parameters

X-HTTP-Method-Override(required): string(string)

The request header X-HTTP-Method-Override must be set with value SEARCH.

Default Value: SEARCH

The request body defines the details of the request.

Root Schema : EntitySearchByExternalIds

Type: object

Title: EntitySearchByExternalIds

Show Source

depth: string

Read Only: true

Level of detail returned by the request. The default will be minimal. Learn more about the depth parameter.
externalIds: array externalIds

The external ids to retrieve. Maximum of 200 external ids per request. If the array exceeds the 200 limit, a 400 Bad Request will be returned.
type: string

The asset's type in Eloqua. This is a read-only property.

{
    "title":"EntitySearchByExternalIds",
    "properties":{
        "type":{
            "type":"string",
            "description":"The asset's type in Eloqua. This is a read-only property."
        },
        "depth":{
            "type":"string",
            "readOnly":true,
            "description":"Level of detail returned by the request. The default will be <code>minimal</code>. <a href='https://docs.oracle.com/cloud/latest/marketingcs_gs/OMCAB/index.html#CSHID=RequestDepth'>Learn more about the depth parameter</a>."
        },
        "externalIds":{
            "type":"array",
            "description":"The external ids to retrieve. Maximum of 200 external ids per request. If the array exceeds the 200 limit, a <a href='https://docs.oracle.com/cloud/latest/marketingcs_gs/OMCAB/index.html#CSHID=HTTPStatusCodes'>400 Bad Request</a> will be returned.",
            "items":{
                "type":"string"
            }
        }
    }
}

Nested Schema : externalIds

Type: array

The external ids to retrieve. Maximum of 200 external ids per request. If the array exceeds the 200 limit, a 400 Bad Request will be returned.

Show Source

Array of: string

{
    "type":"array",
    "description":"The external ids to retrieve. Maximum of 200 external ids per request. If the array exceeds the 200 limit, a <a href='https://docs.oracle.com/cloud/latest/marketingcs_gs/OMCAB/index.html#CSHID=HTTPStatusCodes'>400 Bad Request</a> will be returned.",
    "items":{
        "type":"string"
    }
}

Response

Supported Media Types

application/json

200 Response

OK.

Root Schema : QueryResultVisitorViewData

Type: object

Title: QueryResultVisitorViewData

Show Source

elements: array elements

Array of visitor data.
page: integer

The specified page.
pageSize: integer

The page size.
total: integer

The total amount of results.
type: string

The asset's type in Eloqua.

{
    "title":"QueryResultVisitorViewData",
    "properties":{
        "type":{
            "type":"string",
            "description":"The asset's type in Eloqua."
        },
        "elements":{
            "type":"array",
            "description":"Array of visitor data.",
            "items":{
                "$ref":"#/definitions/Eloqua.API.REST.Contracts.Data.Visitors.VisitorViewDataRest20"
            }
        },
        "total":{
            "type":"integer",
            "description":"The total amount of results."
        },
        "pageSize":{
            "type":"integer",
            "description":"The page size."
        },
        "page":{
            "type":"integer",
            "description":"The specified page."
        }
    }
}

Nested Schema : elements

Type: array

Array of visitor data.

Show Source

Array of: object Eloqua.API.REST.Contracts.Data.Visitors.VisitorViewData

Title: Eloqua.API.REST.Contracts.Data.Visitors.VisitorViewData

{
    "type":"array",
    "description":"Array of visitor data.",
    "items":{
        "$ref":"#/definitions/Eloqua.API.REST.Contracts.Data.Visitors.VisitorViewDataRest20"
    }
}

Nested Schema : Eloqua.API.REST.Contracts.Data.Visitors.VisitorViewData

Type: object

Title: Eloqua.API.REST.Contracts.Data.Visitors.VisitorViewData

Show Source

contactId: string

The contact record Id associated to this profile, if any.
createdAt: string

The date and time the visitor was created, expressed in Unix time.
id: integer

The id of the visitor.
type: string

The visitor's type in Eloqua.
visitorId: string

The Id of the visitor profile.

{
    "title":"Eloqua.API.REST.Contracts.Data.Visitors.VisitorViewData",
    "properties":{
        "type":{
            "type":"string",
            "description":"The visitor's type in Eloqua."
        },
        "visitorId":{
            "type":"string",
            "description":"The Id of the visitor profile."
        },
        "createdAt":{
            "type":"string",
            "description":"The date and time the visitor was created, expressed in Unix time."
        },
        "contactId":{
            "type":"string",
            "description":"The contact record Id associated to this profile, if any."
        },
        "id":{
            "type":"integer",
            "description":"The id of the visitor."
        }
    }
}

400 Response

Bad request. See Status Codes for information about other possible HTTP status codes.

401 Response

Unauthorized. See Status Codes for information about other possible HTTP status codes.

403 Response

Forbidden. See Status Codes for information about other possible HTTP status codes.

404 Response

The requested resource was not found. See Status Codes for information about other possible HTTP status codes.

500 Response

The service has encountered an error. See Status Codes for information about other possible HTTP status codes.

Examples

Retrieve 2 visitors at minimal depth:


POST /api/REST/2.0/data/visitors
X-HTTP-Method-Override: SEARCH
Content-Type: application/json

Request body:

Request body notes:

Visitor external IDs must be enclosed in quotation marks
Up to 200 Visitor external IDs can be included per request. If the array contains duplicate IDs, or exceeds the 200 ID limit, a 400 Bad Request will be returned.


{ 
   "externalIds": ["a10746a6-2480-425b-9db7-f20f4ac1c37e", "b50631a2-1234-234b-3ab1-a21f4be1g88z"], 
   "depth": "minimal"
}

Response:


{
  "elements": [
    {
      "type": "VisitorViewData",
      "visitorId": "88888",
      "createdAt": "1395423247",
      "V_IPAddress": "127.0.0.1",
      "V_LastVisitDateAndTime": "1395426873",
      "externalId": "a10746a6-2480-425b-9db7-f20f4ac1c37e",
      "currentStatus": "Awaiting action"
    },
    {
      "type": "VisitorViewData",
      "visitorId": "12345",
      "createdAt": "1395433547",
      "V_IPAddress": "128.0.0.1",
      "V_LastVisitDateAndTime": "1395426873",
      "externalId": "b50631a2-1234-234b-3ab1-a21f4be1g88z",
      "currentStatus": "Awaiting action"
    }
  ],
  "page": 1,
  "pageSize": 5,
  "total": 2
}

Retrieve 2 visitors at complete depth:


POST /api/REST/2.0/data/visitors
X-HTTP-Method-Override: SEARCH
Content-Type: application/json

Request body:

Request body notes:

Visitor external IDs must be enclosed in quotation marks
Up to 200 Visitor external IDs can be included per request. If the array contains duplicate IDs, or exceeds the 200 ID limit, a 400 Bad Request will be returned.


{ 
   "externalIds": ["a10746a6-2480-425b-9db7-f20f4ac1c37e", "b50631a2-1234-234b-3ab1-a21f4be1g88z"], 
   "depth": "complete"
}

Response:


{
  "elements": [
    {
      "type": "VisitorViewData",
      "visitorId": "30",
      "createdAt": "1395433547",
      "V_Browser_Type": "Firefox 60.0",
      "V_IPAddress": "128.0.0.1",
      "V_Total_Pages": "28",
      "V_Total_Time": "367",
      "V_Total_Visits": "4",
      "V_Name": "Visitor a89",
      "V_Current_Visit_Length": "0",
      "V_Current_Total_Pages": "16",
      "V_FirstVisitDateAndTime": "1553701326",
      "V_FirstPageInVisit": "http:\/\/example.com\/LP=118",
      "V_LastPageInVisit": "http:\/\/example.com\/LP=118",
      "V_LastVisitDateAndTime": "1395426873",
      "V_TimeZoneOffsetMin": "-1",
      "externalId": "a89a54fe-447d-4d2e-849c-be874cd30bcb",
      "currentStatus": "Awaiting action"
    },
    {
      "type": "VisitorViewData",
      "visitorId": "12345",
      "createdAt": "1553701326",
      "V_Browser_Type": "Firefox 60.0",
      "V_IPAddress": "10.154.98.121",
      "V_Total_Pages": "28",
      "V_Total_Time": "367",
      "V_Total_Visits": "4",
      "V_Name": "Visitor a89",
      "V_Current_Visit_Length": "0",
      "V_Current_Total_Pages": "16",
      "V_FirstVisitDateAndTime": "1553701326",
      "V_FirstPageInVisit": "http:\/\/example.com\/LP=118",
      "V_LastPageInVisit": "http:\/\/example.com\/LP=118",
      "V_LastVisitDateAndTime": "1555099596",
      "V_TimeZoneOffsetMin": "-1",
      "externalId": "b50631a2-1234-234b-3ab1-a21f4be1g88z",
      "currentStatus": "Awaiting action"
    }
  ],
  "page": 1,
  "pageSize": 1000,
  "total": 1
}