Skip to main content

Getting Started

This guide will help you set up your environment and make your first API calls to Ingestion.

Prerequisites​

Before you begin, ensure you have:

Required Access​

  • Admin Portal Access - Administrative access to the Hyland Experience Admin Portal to create Service Users and configure External Applications
  • Active Subscription - Insight App Subscription in your Environment

Required Knowledge​

  • Basic understanding of RESTful APIs
  • Familiarity with JSON format
  • Understanding of OAuth 2.0 authentication

Required Tools​

  • HTTP Client - curl, Postman, Bruno or any HTTP client library

Account Setup Process​

Step 1: Create Service User​

To use the Ingestion API, you need to create a Service User - a user account with access to the environment and the Content Intelligence Connector app. It has a mapped External Application (Client) that is used to obtain authentication tokens.

Service User Creation Process​

Follow these steps to create a Service User and configure the required External Application:

  1. Log in to the Admin Portal:

  2. Navigate to Service Users:

    • In the top navigation menu, select Identity
    • From the left-hand panel, expand the Users section
    • Click on Service Users

  3. Create Service User:

    • On the right side, click Create Service User
    • Complete the Create Service User form with the following details:
      • User Name: <service-name> (e.g., ingestion-api-user)
      • User Group: Select the appropriate Connector group for your environment
        note

        Choose the group that corresponds to the Connector role for your specific environment. For example, this might be in format "Name of environment - Connector" or similar, depending on your environment configuration.

  4. Register New Client:

    • Application Name: <client-id> (e.g., ingestion-api-client)
      note

      This creates a new External Application (Client) and generates both a Client ID and Client Secret. Important: Securely record and save the Client Secret immediately after creation, as it will not be displayed again.

  5. Configure Client Scopes:

    • Click on the External Systems tab
    • Find and open the newly created External Application
    • Ensure the following scopes are selected:
      • hxp
      • hxp.integrations
      • openid
      • profile
    • Click Save to apply the configuration

After completing these steps, you will have the credentials needed for Ingestion API authentication.

  • Base IAM URL - e.g. https://auth.iam.experience.hyland.com
  • Base Ingestion URL - e.g. https://ingestion.insight.experience.hyland.com
  • Environment Key - Your unique environment key identifier
  • Client ID - Your client identifier
  • Client Secret - Your client secret

Step 2: Configure Environment Variables​

Set up your environment variables for secure credential storage and usage by curl:

# In your shell or .env file
export IAM_BASE_URL="https://auth.iam.experience.hyland.com"
export INGESTION_BASE_URL="https://ingestion.insight.experience.hyland.com"
export ENVIRONMENT_KEY="your-environment-key"
export SCOPE="hxp hxp.integrations"
export CLIENT_ID="your-client-id"
export CLIENT_SECRET="your-client-secret"

Step 3: Retrieve Access Token​

Before making API calls, you need to authenticate and obtain an access token.

### Get Access Token
POST {{iam_base_url}}/idp/connect/token
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials &
scope={{scope}} &
client_id={{client_id}} &
client_secret={{client_secret}}

For Postman/Bruno: Create environment variables:

  • iam_base_url: IAM_BASE_URL value from Step 2
  • scope: SCOPE value from Step 2
  • client_id: CLIENT_ID value from Step 2
  • client_secret: CLIENT_SECRET value from Step 2

Response: 200 OK - Access token returned in response body.

Add access_token value from the response to your environment variables for usage by curl:

# In your shell or .env file
export INGESTION_ACCESS_TOKEN="your-access-token"

Step 4: Verify API Access​

Test your connection to the API by generating a presigned URL:

warning

If your HTTP client doesn't add the User-Agent header by default, make sure to include it in all requests below (e.g., User-Agent: PostmanRuntime/7.28.4) to avoid receiving a 403 Forbidden response.

### Generate presigned URL - Verify API Access
POST {{baseUrl}}/v1/presigned-urls?count=1
Hxp-Environment: {{environmentKey}}
Authorization: Bearer {{accessToken}}

For Postman/Bruno: Create environment variables:

  • baseUrl: Your INGESTION_BASE_URL value from Step 2
  • environmentKey: Your ENVIRONMENT_KEY value from Step 2
  • accessToken: Your INGESTION_ACCESS_TOKEN value from Step 3

Response: 200 OK - Presigned URL with its id returned in response body:

[
  {
    "url": "https://generated-presigned-url",
    "id": "5b97d6e3-fbae-4f4e-ad97-077b5a6f7487"
  }
]

Set up additional environment variables for secure credential storage and usage by curl:

export PRESIGNED_URL="url-from-response"
export FILE_ID="id-from-response"

Quick Start Guide​

Follow this simple end-to-end example to ingest a file with metadata.

Prerequisites​

  • Valid authentication token (from Step 3)
  • User with Connector role

Step 1: Generate Presigned URL​

tip

If you just followed the Account setup process section and generated a presigned URL to verify API access in Step 4, you can skip this step and reuse that URL and its corresponding ID for the next steps. Otherwise, generate a new presigned URL with the instructions in this step.

warning

If your HTTP client doesn't add the User-Agent header by default, make sure to include it in all requests below (e.g., User-Agent: PostmanRuntime/7.28.4) to avoid receiving a 403 Forbidden response.

### Generate Presigned URL
POST {{baseUrl}}/v1/presigned-urls?count=1
Hxp-Environment: {{environmentKey}}
Authorization: Bearer {{accessToken}}

Response: 200 OK - Presigned URL with its id returned in response body:

[
  {
    "url": "https://generated-presigned-url",
    "id": "5b97d6e3-fbae-4f4e-ad97-077b5a6f7487"
  }
]

The response includes the url in the response body, which you'll use in Step 2. The response includes the id in the response body, which you'll use in Step 3.

Set up additional environment variables for secure credential storage and usage by curl:

export PRESIGNED_URL="url-from-response"
export FILE_ID="id-from-response"

Step 2: Upload a File to temporary storage​

### Upload a File
PUT {{presignedUrl}}
Content-Type: binary/octet-stream

[the binary content of your file goes here]

For Postman/Bruno: Create environment variables:

  • presignedUrl: Your PRESIGNED_URL value from Step 1

Response: 200 OK - The file is uploaded to a temporary storage.

Step 3: Ingest the Uploaded File with Metadata​

Set up additional environment variables for usage by curl:

export SOURCE_ID="your-source-id" # example: 00aa0a00-00a0-00a0-a000-00000000000a
export OBJECT_ID="your-object-id" # example: 11991111-1234-1234-1232-00001234123f
export FILE_DIGEST="yourDigestValue" # example: testDigestValue
### Send an Ingestion Event
POST {{baseUrl}}/v2/ingestion-events
Content-Type: application/json
Hxp-Environment: {{environmentKey}}
Authorization: Bearer {{accessToken}}

[
  {
    "sourceId": "{{sourceId}}",
    "objectId": "{{objectId}}",
    "eventType": "createOrUpdate",
    "sourceTimestamp": 1732022495428,
    "properties": {
      "filePropertyMetadata": {
        "file": {
          "id": "{{fileId}}",
          "content-type": "application/pdf",
          "content-metadata": {
            "size": 1,
            "name": "file.pdf",
            "content-type": "application/pdf",
            "digest": "{{fileDigest}}"
          }
        }
      },
      "name": {
        "annotation": "name",
        "type": "string",
        "value": "Invoice for pizza party"
      },
      "type": {
        "annotation": "type",
        "type": "string",
        "value": "Legal References"
      },
      "dateCreated": {
        "annotation": "dateCreated",
        "type": "datetime",
        "value": "2023-10-05T17:31:00.005Z"
      },
      "createdBy": {
        "annotation": "createdBy",
        "type": "string",
        "value": "6c92091d-e1e2-407c-85d3-e5756a6a704d"
      },
      "dateLastModified": {
        "annotation": "dateModified",
        "type": "datetime",
        "value": "2023-10-06T17:31:00.002Z"
      },
      "modifiedBy": {
        "annotation": "modifiedBy",
        "type": "string",
        "value": [
          "6c92091d-e1e2-407c-85d3-e5756a6a704d"
        ]
      }
    }
  }
]

For Postman/Bruno: Create environment variables:

  • baseUrl: Your INGESTION_BASE_URL value
  • environmentKey: Your ENVIRONMENT_KEY value
  • accessToken: Your INGESTION_ACCESS_TOKEN value
  • sourceId: Your SOURCE_ID value from current step
  • objectId: Your OBJECT_ID value from current step
  • fileId: Your FILE_ID value from Step 1
  • digest: Your FILE_DIGEST value from current step

Response: 202 Accepted - The event is accepted for Ingestion.

Asynchronous Processing

This POST endpoint returns 202 Accepted immediately. Ingestion happens asynchronously in the background. To confirm the Document was ingested, poll the check-digest GET endpoint in Step 4.

Step 4: Verify File Digest in the Ingested Document​

### Check Digest
GET {{baseUrl}}/v1/check-digest/{{sourceId}}/{{objectId}}?digest={{fileDigest}}&useContentLake=true
Hxp-Environment: {{environmentKey}}
Authorization: Bearer {{accessToken}}

For Postman/Bruno: Create environment variables:

  • baseUrl: Your INGESTION_BASE_URL value
  • environmentKey: Your ENVIRONMENT_KEY value
  • accessToken: Your INGESTION_ACCESS_TOKEN value
  • sourceId: Your SOURCE_ID value from Step 3
  • objectId: Your OBJECT_ID value from Step 3
  • fileDigest: Your FILE_DIGEST value from Step 3

Response: 200 OK - The object was found, the result of the checking the digest is returned in the response body:

{
  "exists": true
}

Congratulations! You've successfully ingested a file with metadata.