Reference Data Lifecycle Management

This guide demonstrates how to manage the complete lifecycle of reference data through the API, including creating draft records, updating data, and publishing changes either directly or through a review workflow.

Prerequisites

Before you start:

Configure authentication as described in API Authentication and obtain an access token.
Get familiar with the Reference data in the API reference.
Identify the URN of the reference data table you want to work with. See URN Reference.
Verify you have appropriate permissions to modify reference data. See Set Up Access and Governance.

Direct publish workflow

This workflow is suitable for automated integrations or when changes don’t require approval.

Step 1: Create records in draft

Create new records in the draft dataset.

The response includes the URN for each created record. Save these URNs if you need to update or delete the records later.

Request

curl -X POST "https://{your-environment}.ataccama.one/api/reference-data/v1/tables/{tableUrn}/draft/batch" \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "records": [
      {
        "values": [
          {
            "name": "country_code",
            "value": "XK"
          },
          {
            "name": "country_name",
            "value": "Kosovo"
          },
          {
            "name": "population",
            "value": 1800000
          }
        ]
      },
      {
        "values": [
          {
            "name": "country_code",
            "value": "TW"
          },
          {
            "name": "country_name",
            "value": "Taiwan"
          },
          {
            "name": "population",
            "value": 23800000
          }
        ]
      }
    ]
  }'

Response

{
  "meta": {
    "prev": null,
    "next": null,
    "total": 2
  },
  "data": [
    {
      "urn": "urn:ata:{your-tenant}:reference-data:record:523e4567-e89b-12d3-a456-426614174006",
      "values": [
        {
          "name": "country_code",
          "value": "XK"
        },
        {
          "name": "country_name",
          "value": "Kosovo"
        },
        {
          "name": "population",
          "value": 1800000
        }
      ],
      "state": "NEW"
    },
    {
      "urn": "urn:ata:{your-tenant}:reference-data:record:523e4567-e89b-12d3-a456-426614174007",
      "values": [
        {
          "name": "country_code",
          "value": "TW"
        },
        {
          "name": "country_name",
          "value": "Taiwan"
        },
        {
          "name": "population",
          "value": 23800000
        }
      ],
      "state": "NEW"
    }
  ]
}

For the request parameters and the response fields, see the Reference data in the API reference.

Step 2: Update records (optional)

Update existing draft records by their URN.

When updating records, you only need to specify the attributes you want to change. Other attributes remain unchanged.

Request

curl -X POST "https://{your-environment}.ataccama.one/api/reference-data/v1/tables/{tableUrn}/draft/batch" \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "records": [
      {
        "urn": "urn:ata:{your-tenant}:reference-data:record:523e4567-e89b-12d3-a456-426614174006",
        "values": [
          {
            "name": "population",
            "value": 1850000
          }
        ]
      }
    ]
  }'

Step 3: Publish changes

Publish all draft changes to make them available in the published dataset.

After publishing:

Records remain in draft with state UNCHANGED.
The published dataset contains the new version.

Request - Publish all changes

curl -X POST "https://{your-environment}.ataccama.one/api/reference-data/v1/tables/{tableUrn}/draft/publish" \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -d '{}'

Request - Publish specific records

curl -X POST "https://{your-environment}.ataccama.one/api/reference-data/v1/tables/{tableUrn}/draft/publish" \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "filter": {
      "recordUrn": {
        "in": [
          "urn:ata:{your-tenant}:reference-data:record:523e4567-e89b-12d3-a456-426614174006",
          "urn:ata:{your-tenant}:reference-data:record:523e4567-e89b-12d3-a456-426614174007"
        ]
      }
    }
  }'

Response

{
  "publishedDatasetUrn": "urn:ata:{your-tenant}:reference-data:published:323e4567-e89b-12d3-a456-426614174002",
  "publishedAt": "2026-01-15T11:05:00Z"
}

For the request parameters and the response fields, see the Reference data in the API reference.

Step 4: Verify published data

Confirm that your changes are visible in the published dataset.

Request

curl -X POST "https://{your-environment}.ataccama.one/api/reference-data/v1/tables/{tableUrn}/published/filter" \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "filter": {
      "attribute": {
        "attributeName": {"equals": "country_code"},
        "string": {"in": ["XK", "TW"]}
      }
    }
  }'

Review and approval workflow

This workflow adds a review step before publishing, making it suitable for governed data or changes requiring approval.

Step 1: Create and update records

Follow the steps described in Direct publish workflow to create and update records in draft.

Step 2: Submit for review

Submit draft changes for review by creating a review task.

Save the reviewDatasetUrn obtained in the response as you’ll need it to approve or reject the review.

Request

curl -X POST "https://{your-environment}.ataccama.one/api/reference-data/v1/tables/{tableUrn}/draft/request-review" \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Add new countries - January 2026",
    "priority": "MEDIUM",
    "description": "Adding Kosovo and Taiwan to the Countries reference table",
    "filter": {
      "state": {
        "in": ["NEW", "CHANGED"]
      }
    }
  }'

Response

{
  "reviewDatasetUrn": "urn:ata:{your-tenant}:reference-data:review:423e4567-e89b-12d3-a456-426614174003",
  "taskMetadata": {
    "name": "Add new countries - January 2026",
    "priority": "MEDIUM",
    "description": "Adding Kosovo and Taiwan to the Countries reference table"
  },
  "createdAt": "2026-01-15T10:15:00Z"
}

For the request body and the response fields, see the Reference data in the API reference.

Step 3: List records under review

Reviewers can inspect the records submitted for review.

Request

curl -X GET "https://{your-environment}.ataccama.one/api/reference-data/v1/reviews/{reviewDatasetUrn}/records" \
  -H "Authorization: Bearer {access_token}"

Response

{
  "meta": {
    "prev": null,
    "next": null,
    "total": 2
  },
  "data": [
    {
      "urn": "urn:ata:{your-tenant}:reference-data:record:523e4567-e89b-12d3-a456-426614174006",
      "values": [
        {
          "name": "country_code",
          "value": "XK"
        },
        {
          "name": "country_name",
          "value": "Kosovo"
        }
      ],
      "state": "REVIEW"
    },
    {
      "urn": "urn:ata:{your-tenant}:reference-data:record:523e4567-e89b-12d3-a456-426614174007",
      "values": [
        {
          "name": "country_code",
          "value": "TW"
        },
        {
          "name": "country_name",
          "value": "Taiwan"
        }
      ],
      "state": "REVIEW"
    }
  ]
}

For the request parameters and the response fields, see the Reference data in the API reference.

Step 4: Approve changes

After review, approve the changes to move them back to draft for publishing.

To reject changes instead of approving them, use the reject endpoint:

curl -X POST "https://{your-environment}.ataccama.one/api/reference-data/v1/reviews/{reviewDatasetUrn}/reject" \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -d '{}'

Request - Approve all records

curl -X POST "https://{your-environment}.ataccama.one/api/reference-data/v1/reviews/{reviewDatasetUrn}/approve" \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -d '{}'

Request - Approve specific records

curl -X POST "https://{your-environment}.ataccama.one/api/reference-data/v1/reviews/{reviewDatasetUrn}/approve" \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "filter": {
      "recordUrn": {
        "in": [
          "urn:ata:{your-tenant}:reference-data:record:523e4567-e89b-12d3-a456-426614174006",
          "urn:ata:{your-tenant}:reference-data:record:523e4567-e89b-12d3-a456-426614174007"
        ]
      }
    }
  }'

Response

{
  "affectedRecordCount": 2
}

For the request parameters and the response fields, see the Reference data in the API reference.

Step 5: Publish approved changes

After approval, publish the changes using the same publish endpoint as in Direct publish workflow:

Request

curl -X POST "https://{your-environment}.ataccama.one/api/reference-data/v1/tables/{tableUrn}/draft/publish" \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "filter": {
      "recordUrn": {
        "in": [
          "urn:ata:{your-tenant}:reference-data:record:523e4567-e89b-12d3-a456-426614174006",
          "urn:ata:{your-tenant}:reference-data:record:523e4567-e89b-12d3-a456-426614174007"
        ]
      }
    }
  }'

Delete records

To delete records from the published dataset, mark them as deleted in draft and then publish the deletion.

Step 1: Delete from draft

Deleting a record from draft marks it with state DELETED but doesn’t remove it immediately. The record is removed from the published dataset when you publish the deletion.

Request

curl -X DELETE "https://{your-environment}.ataccama.one/api/reference-data/v1/tables/{tableUrn}/draft/{recordUrn}" \
  -H "Authorization: Bearer {access_token}"

For the request parameters and the response fields, see the Reference data in the API reference.

Step 2: Publish deletion

Request

curl -X POST "https://{your-environment}.ataccama.one/api/reference-data/v1/tables/{tableUrn}/draft/publish" \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "filter": {
      "state": {
        "in": ["DELETED"]
      }
    }
  }'

Complete end-to-end example

Here’s a complete script demonstrating the direct publish workflow. Because publishing is asynchronous, the script waits briefly before it verifies the published data.

#!/bin/bash

# Configuration
ENVIRONMENT="your-environment"
REALM="your-realm"
CLIENT_ID="your-client-id"
CLIENT_SECRET="your-client-secret"
TABLE_URN="urn:ata:your-tenant:reference-data:table:123e4567-e89b-12d3-a456-426614174000"

BASE_URL="https://${ENVIRONMENT}.ataccama.one"
AUTH_URL="${BASE_URL}/auth/realms/${REALM}/protocol/openid-connect/token"
API_URL="${BASE_URL}/api/reference-data/v1"

# 1. Obtain access token
echo "Obtaining access token..."
TOKEN=$(curl -s -X POST "$AUTH_URL" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "client_id=$CLIENT_ID" \
  -d "client_secret=$CLIENT_SECRET" \
  | jq -r '.access_token')

# 2. Create draft records
echo "Creating draft records..."
CREATE_RESPONSE=$(curl -s -X POST "${API_URL}/tables/${TABLE_URN}/draft/batch" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "records": [
      {
        "values": [
          {"name": "country_code", "value": "XK"},
          {"name": "country_name", "value": "Kosovo"},
          {"name": "population", "value": 1800000}
        ]
      }
    ]
  }')

echo "$CREATE_RESPONSE" | jq '.'

# Extract record URN for updates
RECORD_URN=$(echo "$CREATE_RESPONSE" | jq -r '.data[0].urn')
echo "Created record: $RECORD_URN"

# 3. Update the record
echo "Updating record..."
curl -s -X POST "${API_URL}/tables/${TABLE_URN}/draft/batch" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d "{
    \"records\": [
      {
        \"urn\": \"$RECORD_URN\",
        \"values\": [
          {\"name\": \"population\", \"value\": 1850000}
        ]
      }
    ]
  }" | jq '.'

# 4. Publish changes
echo "Publishing changes..."
PUBLISH_RESPONSE=$(curl -s -X POST "${API_URL}/tables/${TABLE_URN}/draft/publish" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}')

echo "$PUBLISH_RESPONSE" | jq '.'

# Publishing is asynchronous: wait a moment before reading the published data.
# If the record does not appear yet, wait and retry.
sleep 5

# 5. Verify in published dataset
echo "Verifying published data..."
curl -s -X POST "${API_URL}/tables/${TABLE_URN}/published/filter" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "filter": {
      "attribute": {
        "attributeName": {"equals": "country_code"},
        "string": {"equals": "XK"}
      }
    }
  }' | jq '.'

echo "Workflow complete!"

Example: Automated updates

Automate reference data updates through scheduled jobs or event-driven workflows:

# Create new records from external source
curl -X POST "https://{your-environment}.ataccama.one/api/reference-data/v1/tables/{tableUrn}/draft/batch" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d @new_records.json

# Publish changes
curl -X POST "https://{your-environment}.ataccama.one/api/reference-data/v1/tables/{tableUrn}/draft/publish" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'

Best practices for lifecycle management

Use filters when publishing: Instead of publishing all changes at once, use filters to publish specific records or changes. This provides better control over what gets published.
Use review workflows for critical data: Implement review and approval workflows for sensitive or business-critical reference data.
Batch updates: Use the batch update endpoint to modify multiple records in a single request for better performance.

Next steps

Explore Reference Data in the web application.

Was this page useful?