8Semantic API

About Semantic API

Overview

The Semantic API processes, categorizes, and analyzes unstructured text. This text can be obtained from any source, such as call center transcripts, chat logs, internal community messages, and surveys.

You will need to define the topics and indicators you want to get information about in Oracle Social Cloud, and then send the text to be analyzed as part of an API request; in the request, you specify which enrichments you want to obtain for the data.

The enrichments can be imported into another application for analysis or further action. The Semantic API complements existing BI systems by allowing unused unstructured text to be analyzed alongside existing structured data assets. Adding the Semantic API analysis into an existing BI environment maximizes your return on investment (ROI).

Audience

The Semantic API is intended for developers who want to analyze captured unstructured data using the Semantic API.

To get the most benefit from this guide, you should be familiar with the following concepts:

  • Social media analytics

  • HTML

  • REST API

  • JSON

  • XML

Analysis Types

You can perform some or all of the analysis by specifying analysis types when creating a job. To learn the best practices for a unified analysis project, see Best Practices for Analysis.

The analysis performed by the Semantic API is summarized in the following table.

Analysis Scope Description
Top Terms Job

Top terms are common nouns, adjectives, and verbs that exist across several documents. Terms can clarify the voice of the customer, identify emerging trends and changes over time, and give context to other activities in your documents.

You can analyze terms to gain deeper insight into:

  • Sentiment context (analyze descriptors to provide context to sentiment)

  • Consumer language (detect specific language use to appeal to target market)

  • Organic surfacing of brand information (uncover information related to products such as brand associations, and strengths or weaknesses)

Top terms can be generated using as few as two documents; however, to get useful results, Oracle recommends that you include at least 100 documents in the job. Each document can match several top terms. The API returns the top terms for the job, including several statistics about each term and a list of documents where the term occurred.

Theme or Themes Job

Theme analysis identifies subtext within the conversation to help you understand the reason behind a spike, sentiment, or an indicator.

Themes are analyzed across all the documents in a job. The API returns a list of one or more themes along with the attributes that define the theme. Each document in a job is tagged with a matching theme where one exists.

Keep in mind that although job-level theme information can be generated from as few as two documents, we recommend that you include at least 100 documents in a job.

Hashtags Document

Hashtags are ad-hoc identifiers that appear frequently in Social Media. You can extract Hashtags from documents to track popular themes and trends they refer to.

Indicators Document

Typically an indicator identifies a particular behavior of interest. For example, if content has language describing a problem with a product or service, then that content is categorized into the Problem indicator. The API returns one or more indicator names with associated indicator IDs. The text in each document is matched against standard indicators that are preconfigured, and custom indicators that are created by you in Oracle Social Cloud. For a list of standard indicators, see Overview of Indicators on the Indicators Tab.

Language Document

The language of each document in the job is identified; only languages supported by the API can be discerned. The API returns a language code, region code, and language name.

  • code - two-letter ISO 639-1 language code

  • region - two-letter ISO 3166-1 region

  • language - The language name in text

For a list of supported languages, refer to Create Topics on the Topics Tab.

Named Entities Document

Named entities are People, Locations, Companies, and Brands mentioned in the document.

Sentiment Document

Sentiment analysis shows you whether a document contains a positive, neutral, or negative message.

Topic Document

The text of each document is matched against topics that you defined in Oracle Social Cloud. Typically a topic is used to identify an area or category of interest; you can identify brands, products, events, activities, and more. The API returns one or more topic names with associated topic IDs.

Best Practices for Analysis

Best practices for both project planning and technical implementation help you achieve your data analysis goals.

This section describes the analysis best practices for business objectives, workflow, roles and tasks.

    Business Objectives and Planning

    There is a cost beyond the product's purchase price when you're planning a coordinated data analysis project. One additional cost may be to integrate your results into a consolidated Business Intelligence (BI) system; another cost may be staffing, such as a data specialist to help determine which data to analyze and how to process it. Make sure you have an executive sponsor or "champion" who will act as a driving force to help make sure your project succeeds.

    To ensure support for your project, keep these considerations in mind as you plan it:

    • Clearly define the benefits for the business. Make sure you can measure the result; including having a valid means of measurement.

    • Make sure you have a clear channel of communication to business stakeholders for sharing your results.

    • Get approval of an adequate budget for the project.

    • Assemble a team that can deliver meaningful results.

      Roles and Tasks

      A successful data analysis project depends on a cross-functional team with skills in different areas. Depending on the scope of your project, you might have more than one person in each of these roles.

      • Project Manager. Provides ownership of the project execution and coordinates the efforts of the project team.

      • Technical Specialist or Programmer. Configures the data analysis platform, extracts the source data and passes it into the Semantic API, then collects the results and potentially imports them into a target (BI) system.

      • Business Analyst or Data Scientist. Provides domain expertise on the business area and clarifies the detailed business goals, identifies how the data can be used to meet the business goals, and interprets/assesses the results based on the original goals.

        Typical Project Workflow

        The following figure and explanation describe a typical project workflow:

        This figure has three boxes, with arrows in the following sequence: Requirements Analysis, Technical Integration, and Results Analysis. These three boxes, are numbered respectively as 1, 2, and 3.
        1. During the requirements analysis phase, you:

          • Identify project goals.

          • Create a project team, and assign roles and responsibilities.

          • Identify data to be used, and an analysis platform.

        2. During the technical integration phase, you:

          • Extract source data and use the Semantic API to submit it for processing.

          • Capture the results and load them into your analysis platform.

          • Ensure that any other required data is also loaded into the analysis platform.

        3. During the results analysis phase, you:

          • Configure the analysis platform to provide key metrics based on the data provided.

          • Evaluate the results against your initial goals.

        Based on the results, you might find that the results aren't what you expected; in some cases you might determine that the data submitted for processing wasn't at the best scope level or wasn't optimally organized. The process is often iterative, as you refine the analysis and the data, and validate the results.

          Best Practices in Structuring Documents and Jobs

          Best practices for the Semantic API are mainly focused on deciding what constitutes an individual document in your job. Also, you’ll need to know how many and which documents to include in a single job. These are some of the considerations to keep in mind:

          • Document granularity

          • Document grouping into jobs

          • Document analysis

            Document Granularity

            The Semantic API processes documents individually for certain analysis; it evaluates the sentiment, topics, indicators, and language for each document. What level of granularity do you want for a document? Should the text be split into shorter segments? If you want to understand the attributes within a large text, rather than across the text as a whole, then the text should be split into smaller documents. Generally, splitting large text into smaller documents gives more fine-grained analysis, providing more detailed insights.

              Document Grouping Into Jobs

              The Semantic API processes documents individually for certain analysis; it evaluates the sentiment, topics, indicators, and language for each document. What level of granularity do you want for a document? Should the text be split into shorter segments? If you want to understand the attributes within a large text, rather than across the text as a whole, then the text should be split into smaller documents. Generally, splitting large text into smaller documents gives more fine-grained analysis, providing more detailed insights.

                Document Analysis

                It often makes sense to run document-level analysis first and then job-level analysis. For example, you can run a document-level analysis to identify all documents referring to a specific product, and then run a job-level analysis to identify the common themes and top terms for that product.

                  Example of Best Practices

                  A services organization wanted to understand the behaviors captured in the logs of its customer chat sessions. Submitting each chat session as a single document wouldn't provide any insight to the flow of the conversation, or identify which parts came from the agent and which came from the customer.

                  The implementation: They decided to submit each agent or customer interaction as a separate document.

                  The first customer interaction in each chat was normally the customer explaining their problem.

                  The implementation: All of the first customer interactions were grouped into a single job, to get a common view across all customer problem statements.

                  This provided specific insights to common customer satisfaction issues.

                    Usage Guidelines

                    The API common guidelines and usage conventions are applicable to Semantic API. The guidelines describe request processing, authentication requirements, HTTP methods, status codes, and more. The API relies on a REST-based architectural style that provides a convenient and consistent approach to sending and requesting data.

                    For a general introduction to REST, see the following Wikipedia article: Representational State Transfer.

                      Basic Authentication

                      The Semantic API uses HTTP Basic authentication. You must have a customer with a user name and password.

                      The user name is the customer's (or partner's) ID and the password is the customer's (or partner's) API Key. You must specify the user name and password in your cURL requests like this:

                      curl --user 'username:password' 

                      HTTP Basic normally expects two credentials to be provided, a user name and a password. Because the APIs aren't intended for use by individual users, we use fixed keys instead:

                      • Username: Customer ID. The Customer ID is specific to each customer, and is the same for all the APIs you use.

                      • Password: API Key. You're assigned an API Key for each API. API Keys can be requested through Oracle Customer Support.

                      A Customer ID and API Key must be provided with every request. When using query-based APIs, such as checking the job status for the Semantic API, you can see only the records that were created by the same Customer ID used for the query. This keeps records for each customer private to that customer.

                        HTTP Headers

                        The following table lists HTTP headers that are used to communicate with the server.

                        Name Description Required

                        Accept

                        Specifies the type of content that can be received in the response.

                        No
                        Authorization

                        Specifies the authorization information. Basic authentication with a Customer ID and API Key. For example:

                        Authorization: Basic CustomerId:APIKey

                        Yes

                        Content-Type

                        Specifies the type of content that the client is sending. The Semantic API supports only JSON, so the value is always Content-type: application/json; charset=utf-8

                        No

                        Content-Encoding

                        Specifies the type of encoding used on the data. You can use it to specify gzip compression.

                        No
                        Host

                        The host processing the request. The host is always the following value:

                        api.collectiveintellect.com

                        Yes

                        HTTP/1.1

                        Specifies that the request is using HTTP 1.1

                        No

                          HTTP Status Codes

                          The following table lists HTTP status codes.

                          Status Code Desctiption
                          200

                          The request was successful; however, the job might not have completed successfully. This status is returned from a GET request when a job is pending, when a job completed successfully, or when a job failed during processing after a Job ID was assigned.

                          201

                          The job was created successfully.

                          204

                          No Content. The request was successfully executed; the response doesn't have content.

                          304

                          Not Modified. The document hasn't been modified for a conditional GET request.

                          400

                          Bad Request. The server didn't understand the request due to malformed syntax.

                          401

                          Unauthorized. For example, this error can occur if you send an invalid API Key.

                          403

                          You provided valid credentials, but you don't have permission for the specific resource/action you're requesting. For example, if you provide valid credentials for company A, but you attempt to create a job with company B's ID, you receive a 403.

                          404

                          Bad request. This status is returned from a POST request when the request contains a Job ID that doesn't exist on the system. For example, you see this response if you use a Job ID for a job that has already been deleted from the system.

                          422

                          Bad request. This status is returned from a POST request when an error occurs before assigning a Job ID. For example, you see this response if you try to create a job containing more than 1,000 documents.

                          5nn

                          Internal Server Error. The server encountered an unexpected condition that prevented it from fulfilling the request. If this error recurs, contact Oracle Support.

                            Request Processing

                            The Semantic API is based on asynchronous jobs. Each job can contain one or more documents, where each document has an associated block of unstructured text. You can send up to 1000 documents in a single Create Job (POST) request.

                            After a job is submitted successfully, a Job ID is returned in the server response. You use a Query Job (GET) request to query the status of the job; after a job completes, the Query Job request returns the results for that job.

                            We recommend that you use frequent GET requests to query the job status. Job execution times vary with the current load and the size of the job contents; however, jobs are normally completed within a few minutes. Completed jobs are automatically deleted after 10 minutes. If you don't get the results before the job is deleted, you must submit a new Create Job request.

                            All content uses HAL (Hypertext Application Language) JSON.

                            Note: Make sure you use a persistent HTTP connection wherever possible.

                            GZip compression is supported using the Content-Encoding header.

                              HTTP Methods and Root URI

                              The client specifies an action using HTTP. Supported HTTP methods are shown here.

                              Method Description
                              GET

                              Used to query the status of a job and retrieve results if the job is complete.

                              POST

                              Used to create a job by submitting one or more documents to be analyzed.

                              A response from the server is returned after creating the job, or immediately if the request fails before creating the job.

                                Authentication

                                Semantic API requests use HTTP Basic authentication.

                                For more information, refer to Basic Authentication.

                                  Reference

                                  This reference documentation describes endpoints, requests, parameters, and sample requests and responses.

                                    Create Job (GET)

                                    This POST request creates a job by submitting one or more documents to the server for processing. Jobs are asynchronous; the server immediately returns the ID of the new job, but the job continues processing in the background until it completes. Typically a job completes within 30 seconds. Completed jobs are deleted from the system after 10 minutes.

                                    Syntax

                                    POST ../semanticApi/v1/analyticsJobs

                                    Request Fields

                                    Name Type Description
                                    customerid String

                                    Required. A Customer ID used to uniquely identify a customer.

                                    documents Object

                                    Required. A set of between one and 1,000 documents, each containing unstructured text to be analyzed. Each document has the following attributes:

                                    • language_identification - Identifies the primary language in each document

                                    • categorization - Identifies user-defined topics in each document

                                    • semantic_tagging - Identifies standard or user-defined indicators in each document

                                    • sentiment_analysis - Identifies the sentiment (positive, neutral, negative) in each document

                                    • theming - Identifies common themes across the group of documents

                                    • top_terms - The top terms used are returned across the group of documents

                                    • entity_analysis - Identifies people, locations, companies, and brands in each document

                                    enrichments String

                                    Required. Specify one or more enrichments to be performed.

                                    • language_identification - Identifies the primary language in each document

                                    • categorization - Identifies user-defined topics in each document

                                    • semantic_tagging - Identifies standard or user-defined indicators in each document

                                    • sentiment_analysis - Identifies the sentiment (positive, neutral, negative) in each document

                                    • theming - Identifies common themes across the group of documents

                                    • top_terms - The top terms used are returned across the group of documents

                                    • entity_analysis - Identifies people, locations, companies, and brands in each document

                                    enrichmentConfiguration Object

                                    Optional. You can customize how an analysis is performed. Specify the analysis type and the custom configuration.

                                    • entity_analysis - entity_model can either be news or social. Choose the news model for document content that is well formed and longer in length. Choose the social model for document content that is grammatically relaxed and shorter in length

                                    Example Request

                                    POST /semanticApi/v1/analyticsJobs HTTP/1.1 
                                    Host: api.collectiveintellect.com 
                                    Accept: application/json 
                                    Content-Type: application/json 
                                    Authorization: Basic CustomerId:APIKey 
                                    { 
                                        "customerId": "customerId", 
                                        "documents": [ 
                                        { "id": "DOCUMENT_ID 1", "text": "text of document 1"}, 
                                        { "id": "DOCUMENT_ID 2", "text": "text of document 2"} 
                                      ], 
                                     "enrichments": [ 
                                       "language_identification", 
                                       "categorization", 
                                       "semantic_tagging", 
                                       "sentiment_analysis", 
                                       "theming", 
                                       "top_terms", 
                                       "entity_analysis" 
                                       	  ], 
                                    "enrichmentConfiguration": [ 
                                                    { 
                                       "entity_analysis": { 
                                       "entity_model" : "news" 
                                                    }  
                                          } 
                                       ] } 

                                    Response for a Valid Job

                                    After the server receives the request and successfully validates its content, a Job ID is returned and the job is queued for processing.

                                    Name Type Description
                                    id String

                                    A unique identifier for the job.

                                    status String

                                    This value is always pending for a new job.

                                    Example Response
                                    HTTP/1.1 201 Created 
                                    Content-Type: application/json 
                                    { 
                                       "id": "JOB_ID", 
                                       "status": "pending" 
                                    } 
                                    
                                    

                                    Response for an Invalid Job

                                    If the server finds any errors during request validation, a job isn't created. Information about each error is included in the response.

                                    Name Type Description
                                    Errors String

                                    A list of one or more errors; each error is identified with an attribute name and a description.

                                    Example Response
                                    HTTP/1.1 422 
                                             Content-Type: application/json 
                                              { 
                                                    "type": "http://tools.ietf.org/html/rfc4918#section-11.2", 
                                                    "title": "Unprocessable Entity", 
                                                    "detail": "Validation error.", 
                                                    "errors": { 
                                                         "attribute_name": [ "error text" ] 
                                                   }           
                                    	} 

                                      Query Job (GET)

                                      This GET request retrieves the results from a job, if available, and is also used to poll whether a job is complete.

                                      Syntax

                                      GET ../semanticApi/v1/analyticsJobs/Job_ID? maxTopTerms=Number&includeDocuments=Boolean

                                      Request Fields

                                      Name Type Description
                                      Job_ID

                                      Required. Specify the Job ID that was returned in the response to the Create Job request.

                                      maxTopTerms Number

                                      Optional. Control how many top terms to include in the response. The default is to include all top terms. Number is an integer >= 0.

                                      includeDocuments Boolean

                                      Optional. Control whether or not the document text is included in the response. The default is true.

                                      Respose When Job Is Incomplete

                                      Name Type Description
                                      id

                                      The Job ID assigned by the Create Job request.

                                      status Number

                                      The current status of the job. The value is always pending for incomplete jobs.

                                      Example Response

                                      HTTP/1.1 200 OK 
                                      Content-Type: application/json 
                                      { 
                                           "id": "<JOB_ID>", 
                                           "status": "pending" 
                                      } 

                                      Response When Job Is Complete and Successful

                                      Name Type Description
                                      id String

                                      The Job ID assigned by the Create Job request.

                                      status String

                                      The current status of the job. The value is always completed for complete jobs.

                                      documents String

                                      A list of analyzed documents, including the document level analysis attributes.

                                      Depending on the enrichments specified in the Create Job request, this section contains some or all of the following attributes:

                                      • id (document ID)

                                      • language_tag

                                      • theme

                                      • sentiment

                                      • topics

                                      • indicators

                                      • entries

                                      top_terms String

                                      Job-level analysis of top terms.

                                      themes String

                                      Job-level analysis of top themes.

                                      Analysis Attributes

                                      The following table describes each of the document and job analysis attributes that are returned in the Query Job response.

                                      Note: All attributes are of the String data type.
                                      Attribute Scope Description
                                      Example Response
                                      
                                              

                                      Response for an Invalid Job

                                      Name Type Description
                                      language_tag Document

                                      The dominant language used in the document text. The language tags are based on the IANA (Internet Assigned Numbers Authority) subtag registry. For more information, refer to this third-party documentation.

                                      This attribute isn't intended to give detailed granular identification across all languages and regions, but it shows the language identification used internally. For example, the value doesn't discern the difference between American English and British English, but it does discern the difference between Simplified Chinese and Traditional Chinese.

                                      • code - two-letter ISO 639-1 language code

                                      • region - two-letter ISO 3166-1 region

                                      • language - The language name in text

                                      Note: Only languages supported by the API can be discerned. For a list of supported languages, refer to Create Topics on the Topics Tab.
                                      themes Job

                                      A theme is a semantic intent, which is analyzed across all the documents in a job. Theme analysis identifies subtext within the conversation to help you understand the reason behind a spike, sentiment, or an indicator, and understand the conversations taking place on different data types.

                                      For each document, the API can return 0 or 1 id (theme ID); this is the unique ID for the theme.

                                      Across a job, the API returns a list of one or more themes along with the attributes that define the theme. Attributes include:

                                      • id - The ID of the theme.

                                      • name - The display name of the theme.

                                      • vector - The vector representing the semantics focus of this theme, as a base-64 encoded value.

                                      • threshold - Used in conjunction with the vector to determine how broadly semantic filters based on this theme should be applied.

                                      • similarity - A measure of how similar this theme is to the analytics job as a whole.

                                      • cohesion - A measure of how closely related the documents in this theme are.

                                      Each theme is made from a number of summary terms. In addition to the id (theme ID), the summaryTerms element contains these attributes:

                                      • term - a word representing the term

                                      • score - value between 0 and 1 indicating how well the term matches the theme (1 is the closest match)

                                      • count - number of matches for the term in the job

                                      • documents - list of Document IDs for documents in the job where the term occurs

                                      sentiment Document

                                      The sentiment of a document is identified as positive, neutral, or negative.

                                      • name - positive, neutral, or negative

                                      • value - number between +1 and -1 where +1 is positive, 0 is neutral, and -1 is negative

                                      topics Document

                                      The text of each document is matched against the topics that you previously defined in Oracle Social Cloud. The API returns one or more topic names with associated topic IDs.

                                      • id – a unique ID for the topic

                                      • name – name of the topic

                                      indicators Document

                                      The text in each document is matched against pre-defined and custom indicators. The API returns one or more indicator names with associated indicator IDs.

                                      • id - unique ID for the indicator

                                      • name - name of the indicator

                                      top_terms Job

                                      The API returns the top terms for the job, including several statistics about each term and a list of documents where the term occurred.

                                      Each top term has the following attributes:

                                      • id - unique ID for the term

                                      • term - word associated with the term

                                      • type - type of word: Noun, Adjective, or Verb

                                      • count - number of times the term occurs in the job

                                      • variations - variations of the term (such as "cats", "cat")

                                      • documents - list of Document IDs for documents in the job where the term occurs language_code - language of the term

                                      entities Document

                                      Entities are mentions of People, Locations, Companies, and Brands in the document. A list of entities will be returned with the following attributes:

                                      • id - a unique ID for the entity

                                      • type - one of person, location, company or brand

                                      • match - the entity match

                                      • textOffset start/end - the beginning and ending code points for the match string

                                      • confidence score - a floating point confidence value

                                      • confidence label - one of low, medium, or high

                                      Example Response
                                      HTTP/1.1 200 OK 
                                      Content-Type: application/json 
                                      { 
                                           "id": "<JOB ID>", 
                                           "status": "completed",      "documents": 
                                           [ 
                                               { 
                                      "id": "<DOCUMENT ID>", 
                                      "text": "This is text from the submitted document.", 
                                      "languageTag": "en", 
                                      "sentiment": { 
                                      "name": "neutral", 
                                      "value": 0 
                                      }, 
                                      "topics": [ 
                                            { 
                                      	             	"id": "<TOPIC ID>", 
                                      	             	"name": "iPod" 
                                                              } 
                                              ], 
                                               	"indicators": [ 
                                                           { 
                                      	              	"id": "<INDICATOR ID>", 
                                      	              	"name": "neutral" 
                                             } 
                                               ], 
                                      "theme": [ 
                                            { 
                                      	            	"id": "<THEME ID>", 
                                      "name": "<NAME_VALUE>", 
                                      "vector": "<VECTOR_VALUE>", 
                                      "threshold": "<THRESHOLD_VALUE>", 
                                      "similarity": "<SIMILARITY_VALUE>", 
                                      "cohesion": "<COHESION_VALUE>" 
                                             } 
                                                 ], 
                                      "entities" : [ 
                                            { 
                                      "id" : "<ENTITY ID>", 
                                      "type" : ["person","location","company"], 
                                      "match" : "<MATCH_STRING>", 
                                      "testOffset" : { 
                                      "start":0, 
                                      "end":10 
                                            }, 
                                      "confidence" : { 
                                      "score":85.3, 
                                      "label": ["low","medium","high"] 
                                            } 
                                            }], 
                                      "topTerms" : [ 
                                            { 
                                      "id" : "<TERM ID>", 
                                      "term" : "cat", 
                                      "type" : "NOUN", 
                                      "count" : "2", 
                                      "variations" : [ "cats", "cat" ], 
                                      "documents" : [ { "id": "<DOCUMENT ID>" } ], 
                                      "languageTag": "en" 
                                             }, 
                                             { 
                                      "id" : "<TERM ID>", 
                                      "term" : "run", 
                                      "type" : "VERB", 
                                      "count" : "2", 
                                      "variations" : [ "run", "running" ], 
                                      "documents" : [ { "id": "<DOCUMENT ID>" } ], 
                                      "languageTag": "en" 
                                              } 
                                                                { 
                                      "id" : "<TERM ID>", 
                                      "term" : "chat", 
                                      "type" : "NOUN", 
                                      "count" : "2", 
                                      "variations" : [ "chat" ], 
                                      "documents" : [ { "id": "<DOCUMENT ID>" }, { "id": "<DOCUMENT ID>" } ], "languageTag": "fr" 
                                               } 
                                                             ], 
                                        	"themes": [ 
                                            { 
                                      "id": "<THEME ID>", 
                                      "documents": [{ "id": "<DOCUMENT ID>" }, { "id": "<DOCUMENT ID>" 
                                      	        	}], 
                                       "summaryTerms": [ 
                                       { 
                                      	             	       "term": "term", 
                                             "score": 0.9884190264313273, 
                                             "count": 1 
                                      } 
                                             ], 
                                             "languageTag" : "fr", 
                                              } 
                                                      ], 
                                      "links": { 
                                           "rel": "canonical",      "href": 
                                           "https://api.collectiveintellect.com/semanticApi/v1/analyticsJobs/<JOB_ID>" 
                                       } 
                                               } 

                                      Response when a Job Fails

                                      If an error occurs, the response varies depending on whether the job failed immediately or it failed during processing.

                                      If an error occurs immediately after you submit the request, a job isn't created. The server returns an HTTP 422 status and information about the error:

                                      Name Type Description
                                      errors String

                                      A list of one or more errors; each error is identified with an attribute name and a description.

                                      HTTP/1.1 422 
                                      Content-Type: application/json 
                                      { 
                                          "errors": { 
                                          "attribute_name": [ "error description" ]} 
                                      } 

                                      If an error occurs while processing a job that was previously assigned a Job ID, then a query of that job returns an HTTP status of 200 along with a status of failed:

                                      Name Type Description
                                      id String

                                      The Job ID assigned by the Create Job request.

                                      status String

                                      The current status of the job. The value is always failed for failed jobs.

                                      HTTP/1.1 200 
                                      Content-Type: application/json 
                                      { 
                                           "id": "<JOB_ID>", 
                                           "status": "failed" 
                                      } 

                                      If you query a job using a Job ID that doesn't exist on the system, such as a job that has completed and has already been deleted, the server returns an HTTP 400 status.

                                      HTTP/1.1 400 

                                        Example of Semantic API cURL

                                        This detailed cURL example includes a sample input document, API requests, and API responses.

                                        Note: The cURL commands in this section are split into multiple lines here for readability. You should use a single line, or use a backslash as a line delimiter.

                                        Sample Data File for Create Job Request

                                        { 
                                             "customerId" : "1234", 
                                             "documents" : [ 
                                             { "id" : "RAS0001", 
                                               "text" : " Monique Pool first fell in love with sloths when she took in an orphan from a rescue centre. Since then many        sloths have spent time in her home on their way back to the forest - but even she found it hard to cope when she had to         rescue 200 at once." 
                                              } 
                                        ], 
                                        "enrichments": [ 
                                        "language_identification", 
                                        "categorization", 
                                        "semantic_tagging", 
                                        "sentiment_analysis", 
                                        "theming", 
                                        "top_terms" ] 
                                        } 

                                        Create Job Request

                                        $ curl https://api.collectiveintellect.com/semanticApi/v1/analyticsJobs 
                                        -d @test_data.json 
                                        -H "Expect:" 
                                        -H Content-Type:application/ 
                                        --user "sdkjfhkuus:dfgkjherkj" 
                                        {"id":"6f1f23c8-434-9b52-556730895b","status":"pending"} 

                                        Query Job (Incomplete)

                                        In this example, the job isn't complete so the result returned is pending.

                                        $ curl https://api.collectiveintellect.com/semanticApi/v1/analyticsJobs/6f9fa7fdd9c8- 4fce-9b02-55696630875b 
                                        -H "Expect:" 
                                        -H Content-Type:application/json 
                                        --user "sdkjfhkuus:dfgkjherkj" 
                                        {"id":"6f12d-d934-4f5ce-9b02-55696630875b","status":"pending"} 

                                        Query Job (Complete)

                                        In cURL, when the job is complete, the response payload is returned in unformatted XML. To see the response payload in a readable format, see the example in Query Job (GET).