XM Discover API: Import API Single Record Input Elements

Note: We strongly recommend using XM Discover Link connector instead of the Import API.

The following table lists Import API single record input parameters with their descriptions.

responseLevel

(optional)

Specify the level of response depth. The following options are available (case-sensitive):

• VERBATIM: Return classification and sentiment data at the verbatim level. At this level, a single sentiment score is provided for every verbatim along with each category that matches verbatim text.
• VERBATIM_AND_SENTENCE: In addition to verbatim-level results, return classification and sentiment data for individual sentences.
• FULL (default): In addition to verbatim and sentence results, return linguistic details (such as master tokens and linguistic relationships) for individual sentences.
• SAVE_ONLY: The call returns just the status of the request and content type attributes. Use this option to reduce response detail when submitting new realtime requests.

save

(optional)

Indicate whether the record should be saved in XM Discover.

• true (default)

• false

In combination with process=true, allows to retrieve real-time results without saving them in XM Discover.

Note: See possible combinations of save, process, and stage flags below.

process

(optional)

Indicate whether the records should be processed by XM Discover.

true (default) false

Note: See possible combinations of save, process, and stage flags below.

stage

(optional)

Indicate whether the records should be saved into the staging table.

• true
• false (default)

Note: If stage=true, you also need to specify the name of the staging table using the tableName parameter.

Note: See possible combinations of save, process, and stage flags below.

tableName

(required if stage=true)

Provide the name of the staging table if you wish to stage your data.

projectId

(either projectId or projectName is required)

Provide the ID of the project to load data into.

Note: If both projectId and projectName are specified, projectName is used and projectId is ignored.

projectName

(either projectId or projectName is required)

Provide the name of the project to load data into.

Note: If both projectId and projectName are specified, projectName is used and projectId is ignored.

modelName

(optional)

Provide the name of the model that will be used to classify your record.

duplicateDetection

(optional)

Choose how the system should handle duplicate records (records that have identical natural keys). The following options are available (case-sensitive):

• REJECT_DUPLICATES (default): Do not process records labeled as duplicates.

• NONE: Do not perform duplicate detection.

• UPDATE_STRUCTURED_ATTRIBUTES_ONLY: Replace structured attributes, but not unstructured text.

• UPDATE_STRUCTURED_ATTRIBUTES_FOR_EXISTING_DOC: Update structured attributes if a document with a specified Natural ID exists. If the document does not exist, do not create a new one.

• ADD_NEW_VERBATIM: Add a non-conversational verbatim field to a document. For a successful import:

  • The document with a specified Natural ID must exist.

  • The verbatim field with a specified name must not exist in the document.

attributes

(optional)

In this section you can define the properties of fields (structured attributes and verbatim fields) that make up the record.

Note: Structured attributes must be defined in a corresponding Designer's project in order to be uploaded.

Each field is defined by the following properties:

name

Provide the name of the field.

• For structured attributes, this is the system name, which cannot exceed 21 characters.

• For verbatim fields, the name should not exceed 100 characters.

type

Specify the field type. It can be one of the following (case-sensitive):

• TEXT. Set this type in order to mark a verbatim field or any text field.

• NUMBER. Use it for numeric attributes.

• DATE. Use it for date and time attributes.

The date and time should be specified using the following format:

YYYYMMDDhhmmssUTC

where:

YYYY = four-digit year

MM = two-digit month (01=January, etc.)

DD = two-digit day of month (01 through 31)

hh = two digits of hour (00 through 23) (am/pm NOT allowed)

mm = two digits of minute (00 through 59)

ss = two digits of second (00 through 59)

UTC = UTC offset (+hhmm or -hhmm)

For example: 20181118123000+0300

Note: You can specify the date without the time element (YYYYMMDD), in which case the system will assume all data applies to midnight (00:00:00) using the server time zone. You can also omit the UTC offset element to use the server time zone. However, when specifying time, hours, minutes, and seconds are required.

map

Use this parameter to map the fields. Use one of the following values for each field:

• ID1, ID2, ID3. Indicate up to 3 natural ID fields to be used during duplicate detection.
• SOURCE. Indicate one data source field.
• VERBATIM. Indicate one or more fields with unstructured text. These fields are processed by the XM Discover NLP engine.
• DOC_DATE. Indicate a date field for the record.
• STRUCT. Indicate structured data fields.

Note: A record can have several date fields mapped to DOC_DATE, but only the field named DOCUMENT_DATE will be treated as the primary Document Date.

parameters

Provide additional parameters for the field. You can use the following parameters:

• language (verbatim fields only). Provide the language of the verbatim field using a 2-letter code in ISO 639-1 format.

  Note: When you specify the language parameter, XM Discover does not perform language detection for the verbatim field. In case the language code is incorrect (or not supported by XM Discover), this parameter is ignored.

display

Provide the display name for the field (this is how it will be displayed in reports, alerts, filters, and so on).

Important: We recommend not including display names for structured attributes in the API calls as they are processed differently for single and multiple record calls. Instead, you can change the display names later in Designer.

defaultValue

Provide the default value for the field. If an attribute's value is not provided in the record, the default value is used.

isReportable

Indicate whether the attribute should be enabled for reporting.

• true = enabled for reporting
• false = disabled for reporting

records

(required)

In this section you can provide the record to be uploaded into XM Discover. The record should be provided as a plain JSON object using field names specified in the attributes section and their corresponding values.

Note the following requirements:

• You should only provide attributes defined in the attributes section, otherwise the request will return an error.
• In case an attribute is defined in the request, but not in the Designer project, it will be skipped with a corresponding warning.
• To make a date field the primary Document Date, map it to DOC_DATE and set its name to DOCUMENT_DATE.
• If you do not wish to specify the SOURCE attribute, do not provide the defaultValue in the attributes section and simply omit it from the records section. It will be set to NOT SPECIFIED in Designer.
• If you wish the DOC_DATE to be automatically set to the date of the upload, do not provide the defaultValue in the attributes section and simply omit it from the records section.
• If you wish the natural ID to be generated automatically, simply omit it from the records section.
• If you wish to pass an empty regular TEXT attribute, you can do so by omitting it from the records section or setting it to an empty string ("") or null. In any case it will be treated as an empty value in Designer.
• If you wish to pass an empty regular NUMBER attribute, you can do so by omitting it from the records section or setting it to null. In any case it will be treated as an empty value in Designer.

Tip: If you provide more than one record in this section, the request will be handled as a multiple records request.

Note: To provide several values for a text multivalue attribute, separate them by commas and enclose values that have spaces in them in double quotes. Note that if any value contains double quotes or backslashes, you need to "escape" these symbols via a backslash symbol (\).

For example, to import these values:

• Coupons
• Our website
• The "Best Deals" magazine
• TV / radio ad
• I don't remember hearing about this brand

Use this format:

"QUESTION_1": "Coupons, \"Our website\", \"The \"\"Best Deals\"\" magazine\", \"TV \/ radio ad\", \"I don't remember hearing about this brand\""

creditsExceededAction

(optional)

Choose how the system should handle cases when a user runs out of verbatim credits while using the Import API. There are 2 options:

• WARN

Submit as many records as possible and reject excessive records.

• ERROR

Do not submit any records and do not charge any verbatim credits. Return an error instead.

limitByWordRank

(optional)

Indicate whether the Word Rank filter should be applied to exclude the most common English words from the output.

• true
• false

includeNRelations

(optional)

Indicate whether additional linguistic parsing information should be included in the output.

• true
• false (default)

includeWorldAwareness

(optional)

Indicate whether sentence-level Intelligent Entities attributes should be included in the response.

• true
• false

Possible Combinations of save, process, and stage Flags

save	process	stage	Result
true	true	true	Return real-time results, process the record by the standard incremental dataflow, and save it in the staging table.
true	true	false	Return real-time results and process the record by the standard incremental dataflow without saving it in the staging table.
false	true	true	Return real-time results without saving them in XM Discover. Save the record in the staging table.
false	true	false	Return real-time results without saving.
true	false	true	Save the record in the staging table.
true	false	false	Not available.
false	false	true	Save the record in the staging table
false	false	false	Not available.