Get Article by ID

Overview

  • The Get Article by ID API allows a user to retrieve an Article using its ID.

    • Additional Article attributes and contextual views can be specified in the query parameters.

  • This API returns structured authoring attributes of Issue, Environment, Cause and Confidence Level when the following conditions are met:

    • The "Allow Structured Authoring" setting is enabled at the partition/department level through the Administrative Console.
    • The "Use Structured Authoring" flag is set on the article type.

Prerequisites

  • Agents without a user profile and customers in a portal without a default user profile only have access to articles that:
    • Do not contain any access tags.
    • Do not contain any publish views.
    • Contain publish views without any associated tags.
  • Agents with a user profile and customers in a portal with a default user profile have access to articles that:
    • Do not contain any access tags.
    • Do not contain any publish views.
    • Contain publish views without any associated tags.
    • Contain access tags that are also in the assigned user profiles.
    • Contain publish views with associated tags that are also in the assigned user profiles.
  • Agents with the following assigned actions can view updates to articles currently being processed in workflows:
    • View Author Portal – Allows agents to view updates to articles at any stage in a workflow.
    • View Staging Portal – Allows agents to view updates to articles in the Staging stage or a subsequent stage in a workflow.
SecurityoAuthUser or oAuthCustomer or oAuthAnonymousCustomer
Request
path Parameters
portalID
required
string [ 7 .. 20 ] characters ^[a-zA-Z0-9]{2,4}-\d{4,15}$

The ID of the portal being accessed.

A portal ID is composed of a 2-4 letter prefix, followed by a dash and 4-15 digits.

Example: PROD-1000
articleID
required
string [ 7 .. 20 ] characters ^[a-zA-Z0-9]{2,4}-\d{4,15}$

The ID of the Article.

An Article ID is composed of a 2-4 letter prefix followed by a dash and 4-15 digits.

Example: PROD-2996
query Parameters
$lang
string

The language that describes the details of a resource. Resources available in different languages may differ from each other.

  • If lang is not passed, then the portal's default language is used.

    • Enum: "en-US" "fr-FR" "en-GB" "es-ES" "it-IT" "nl-NL" "da-DA" "sv-SE" "pt-PT" "fi-FI" "no-NB" "no-NN" "ja-JA" "de-DE" "pt-BR" "zh-CN" "zh-TW" "ko-KO" "ru-RU" "el-EL" "tr-TR" "pl-PL" "cs-CS" "sk-SK" "hu-HU" "sr-SR" "ar-SA" "hr-HR" "ro-RO" "th-TH" "xx-XX"
    Example: $lang=en-US
    articleAdditionalAttributes
    Array of strings

    The attributes of an Article to be returned in addition to the default list of attributes, listed below. Multiple additional attributes can be specified using a comma-separated list. Passing 'all' will return all attributes.

    Default Attributes

    These Article attributes are always returned:

    Name Description
    id The ID of the Article.
    name The name of the Article.
    additionalInfo Additional information provided as Article metadata.
    articleType The Article type and its attributes.
    articleKeywords A comma-separated list of keywords associated with this Article.
    articleState The current state of the Article. States include A (Authoring), S (Staging), and P (Published).
    articleSummary A brief summary of the Article, provided as metadata.
    createdBy The ID, first name, middle name and last name of the user that created the Article.
    createdDate The date that the Article was created.
    departmentId ID of the department for which this Article belongs to.
    description The Article's description.
    expirationDate The date that the Article is set to expire.
    attachments The Article's attachments
    imageURL The URL of the image that is present in the Article version. It is used as the thumbnail image for the Article.
    includeInGenAI Indicates whether this Article is used for eGain's generative AI features.
    isSubscribed Indicates whether the Article is subscribed for notifications.
    languageCode The language code of the Article language.
    link The link object, used to retrieve the details of the Article.
    modifiedBy The ID, first name, middle name and last name of the user that last modified the Article.
    modifiedDate The date that the Article was last modified on.
    topicBreadcrumb Contains a list of topics from the top-level topic to this Article. There may be multiple paths.
    versionId The ID of the Article version that is returned.
    Items Enum: "articleMacro" "availabilityDate" "availableEditions" "averageRating" "content" "contentText" "compliance" "timesRated" "createdBy.userName" "modifiedBy.userName" "ownedBy" "ownedBy.userName" "workflow" "all" Examples:
    An additional attribute to be returned.
    articleAdditionalAttributes=averageRating
    Additional attributes to be returned.
    articleAdditionalAttributes=ownedBy,ownedBy.userName
    All additional attributes to be returned.
    articleAdditionalAttributes=all
    $customAdditionalAttributes
    string [ 1 .. 4000 ] characters ^([a-zA-Z0-9_-]+)(?:,[a-zA-Z0-9_-]+)*$

    One or more comma-separated names for custom attributes defined by the user to be returned.

    Examples:
    A user-defined custom attribute.
    $customAdditionalAttributes=country_name
    Multiple user-defined custom attributes.
    $customAdditionalAttributes=internalScore,performance-rating_dept_923
    accessSource
    string
    Default: "article_view"

    Provides information about the method in which the Article is accessed and is used for self-service analytics. Refer to the eGain User Guide regarding "Article View Contexts".

    Name Description
    article_view View an Article directly using its ID.
    article_view_more_related_Article View related articles of an Article using its ID.
    article_view_basic_search View an Article via a basic search.
    article_view_adv_search View an Article via an advanced search.
    article_view_guided_help View an Article via a Guided Help solution.
    article_view_browse_topic View an Article via browsing a topic.
    article_view_browse_tree View an Article via browsing a topic tree.
    article_view_popular_articles View an Article using the Popular Items list in the Self-Service portal.
    article_view_useful_items View Article using the Useful Items list in the Self-Service portal.
    article_view_widget View an Article via a widget.
    article_view_announcement View an Article from the announcement section in the Self-Service portal.
    article_view_bookmarked View a bookmarked Article.
    article_view_subscription_notification View an Article from a subscription notification.
    article_view_guided_help_additional_info View an Article via additional information from a Guided Help search.
    view_articles_pending_compliance View an Article via Read & Sign in the Self-Service portal.
    type_ahead_Suggestion View an Article from a type-ahead Suggestion in the Self-Service portal.
    semantic_Suggestion View an Article from a semantic Suggestion in the Self-Service portal.
    instant_answer View an Article via an Instant Answers solution.
    instant_answer_reference View an Article that is used as a reference for an Instant Answers solution.
    Enum: "article_view" "article_view_more_related_Article" "article_view_basic_search" "article_view_adv_search" "article_view_guided_help" "article_view_browse_topic" "article_view_browse_tree" "article_view_popular_articles" "article_view_useful_items" "article_view_widget" "article_view_announcement" "article_view_bookmarked" "article_view_subscription_notification" "article_view_guided_help_additional_info" "view_articles_pending_compliance" "type_ahead_Suggestion" "semantic_Suggestion" "instant_answer" "instant_answer_reference"
    Example: accessSource=article_view
    publishViewId
    string [ 7 .. 20 ] characters ^[a-zA-Z0-9]{2,4}-\d{4,15}$

    The ID of a publish view for an Article. A publish view is a set of tags used to generate multiple editions of the same Article for display on the self-service portal. Publish views are used in conjunction with single sourcing to tailor the content of an Article to a specific audience by granting access to an Article's version to users that possess the same tags.

    A publish view ID is composed of a 4-letter prefix, followed by a dash and 4-15 digits.

    Examples:
    A readable publish view ID.
    publishViewId=PROD-3203
    workflowMilestone
    string

    For agents with the View Author Portal or View Staging Portal actions, this determines which version of the Article is returned.

  • 'Authoring' returns the most recent version of an Article checked-in by an author.
  • 'Staging' returns the updated version currently being processed in a workflow.
  • 'Publish' returns the most recently published version.

    • Enum: "authoring" "staging" "publish"
    Example: workflowMilestone=publish
    header Parameters
    x-egain-activity-id
    string [ 4 .. 9 ] characters ^[0-9]{4,9}$

    A unique numeric interaction identifier from eGain.

    Example: 59237
    x-ext-integration-id
    string <= 40 characters ^[\w\W]+$

    The unique numeric identifier for a tenant, used in self-service functionality as well as third-party integrations.

    Note: If x-egain-activity-id is not provided, then this must be passed along with x-ext-interaction-id.

    Examples:
    3155180e-0c13-43e9-9c38-e9045bcbf176
    00Dbn00000IxGnx
    x-ext-interaction-id
    string <= 40 characters ^[\w\W]+$

    A unique interaction identifier from other CRM applications.

    Note: If x-egain-activity-id is not provided, then this must be passed along with x-ext-integration-id.

    Examples:
    3155180e-0c13-43e9-9c38-e9045bcbf176
    00Dbn00000IxGnx
    Accept-Language
    required
    string

    The Language locale accepted by the client (used for locale specific fields in resource representation and in error responses).

    Enum: "en-US" "es-ES" "fr-FR" "it-IT" "de-DE" "nl-NL" "pt-BR" "pt-PT" "da-DK" "ru-RU" "fr-CA" "zh-CN" "ja-JP" "ko-KR" "sv-SE"
    Example: en-US
    Responses
    200

    Success

    204

    No Content

    400

    Bad Request

    401

    Unauthorized

    403

    Forbidden

    404

    Not Found

    406

    Not acceptable

    500

    Internal server error

    get/portals/{portalID}/articles/{articleID}
    Request samples
    Response samples
    application/json
    {
    • "id": "PROD-2996",
    • "name": "Fair Lending FAQs",
    • "additionalInfo": "Can be shared to public.",
    • "articleType": {
      },
    • "articleKeywords": "Fair lending, Fair Housing Act, Discrimination protection, Residential mortgage loans, Equal opportunity housing",
    • "articleState": "P",
    • "articleSummary": "Fair lending ensures that lenders do not discriminate based on race, color,national origin, religion, sex, familial status, or disability when applying forresidential mortgage loans. The federal Fair Housing Act protects individuals'fair lending rights, enforced by the Office of Fair Housing and Equal Opportunity,along with state and local agencies. This law applies to U.S. citizens, greencard holders, and undocumented residents, ensuring equal opportunities in homesales, rentals, and financing.",
    • "attachments": [
      ],
    • "createdBy": {
      },
    • "createdDate": "2022-06-30T14:54:55Z",
    • "departmentID": "1001",
    • "description": "Common questions and answers regarding Fair Lending.",
    • "expirationDate": "2031-01-02T10:56:00Z",
    • "imageURL": "https://hd.egain.com/images/km-for-dummies-24.jpg",
    • "includeInGenAI": true,
    • "isSubscribed": true,
    • "languageCode": "en-US",
    • "modifiedBy": {
      },
    • "modifiedDate": "2025-01-28T19:53:58Z",
    • "link": {
      },
    • "topicBreadcrumb": [
      ],
    • "versionId": "PROD-2884"
    }