Cloud Portal ONE Desktop ONE DQ&C ONE MDM ONE RDM ONE Runtime Server
User Community Service Desk Downloads

Reference Data API

The REST API is currently in Early Access Preview. The API specification and endpoints might change before being marked as stable.

We recommend testing thoroughly and being prepared to adapt to potential changes in future releases.

The Reference Data API allows you to programmatically interact with reference data tables in Ataccama ONE. You can read published data, work with draft records, and manage the complete data lifecycle through the API.

Before using the Reference Data API, configure authentication as described in API Authentication.

API base URL

All Reference Data API endpoints are accessed through the following base URL:

https://{your-environment}.ataccama.one/api/reference-data/v1

Replace {your-environment} with your environment identifier from the Ataccama Cloud Portal.

Data states

Reference data in Ataccama ONE exists in different states as part of the data lifecycle:

State Description

Published

Immutable, approved data available for consumption. This is the production dataset.

Draft

Working copy where you can create, update, or delete records. Changes remain in draft until published.

Review

Subset of draft changes submitted for approval before publishing.

Read data

List tables

Retrieve a paginated list of all published reference data tables.

Request
GET /reference-data/v1/tables
Authorization: Bearer {access_token}
Table 1. Query parameters
Parameter Type Required Description

after

string

No

Cursor for forward pagination.

before

string

No

Cursor for backward pagination.

size

integer

No

Number of tables to return.

Default: 20.

Max: 100.

search

string

No

Search criteria for the table name.
Response example
{
  "meta": {
    "prev": null,
    "next": "eyJpZCI6IjEyMyJ9",
    "total": 45
  },
  "data": [
    {
      "id": "urn:ata:your-tenant:reference-data:table:123e4567-e89b-12d3-a456-426614174000",
      "name": "Countries",
      "description": "List of all countries with ISO codes",
      "attributes": [
        {
          "name": "country_code",
          "type": "DATA",
          "dataType": "STRING"
        },
        {
          "name": "country_name",
          "type": "DATA",
          "dataType": "STRING"
        }
      ],
      "totalRecordsCount": 195,
      "createdAt": "2024-01-15T10:30:00Z"
    }
  ]
}

Get a table

Retrieve detailed information about a specific reference data table.

Request
GET /reference-data/v1/tables/{tableUrn}
Authorization: Bearer {access_token}
Table 2. Path parameters
Parameter Type Required Description

tableUrn

string

Yes

URN identifier of the table. For example: urn:ata:{your-tenant}:reference-data:table:123e4567-e89b-12d3-a456-426614174000.
Response example
{
  "id": "urn:ata:your-tenant:reference-data:table:123e4567-e89b-12d3-a456-426614174000",
  "name": "Countries",
  "description": "List of all countries with ISO codes",
  "attributes": [
    {
      "name": "country_code",
      "type": "DATA",
      "dataType": "STRING"
    },
    {
      "name": "country_name",
      "type": "DATA",
      "dataType": "STRING"
    },
    {
      "name": "population",
      "type": "DATA",
      "dataType": "INTEGER"
    }
  ],
  "totalRecordsCount": 195,
  "createdAt": "2024-01-15T10:30:00Z"
}

List published records

Retrieve records from a published reference data table.

Request
GET /reference-data/v1/tables/{tableUrn}/records
Authorization: Bearer {access_token}
Table 3. Query parameters
Parameter Type Required Description

after

string

No

Cursor for forward pagination.

before

string

No

Cursor for backward pagination.

size

integer

No

Number of records to return.

Default: 20.

Max: 100.

attributeNames

array[string]

No

Specific attributes to include in the response.
Response example
{
  "meta": {
    "prev": null,
    "next": "eyJpZCI6IjUwIn0",
    "total": 195
  },
  "data": [
    {
      "id": "urn:ata:your-tenant:reference-data:record:523e4567-e89b-12d3-a456-426614174004",
      "values": [
        {
          "name": "country_code",
          "value": "US"
        },
        {
          "name": "country_name",
          "value": "United States"
        },
        {
          "name": "population",
          "value": 331900000
        }
      ]
    },
    {
      "id": "urn:ata:your-tenant:reference-data:record:523e4567-e89b-12d3-a456-426614174005",
      "values": [
        {
          "name": "country_code",
          "value": "CA"
        },
        {
          "name": "country_name",
          "value": "Canada"
        },
        {
          "name": "population",
          "value": 38000000
        }
      ]
    }
  ]
}

Filter published records

Apply filters to retrieve specific records from a published table.

Request
POST /reference-data/v1/tables/{tableUrn}/records/filter
Content-Type: application/json
Authorization: Bearer {access_token}

{
  "filter": {
    "attribute": {
      "attributeName": {
        "equals": "country_code"
      },
      "string": {
        "in": ["US", "CA", "MX"]
      }
    }
  }
}

Request body

The request body accepts a filter object with various filtering options:

  • Attribute filters: Filter by attribute values (string, number, date, Boolean).

  • Logical operators: Combine filters using and or or.

  • Comparison operators: Use equals, contains, greater, less, and similar.

Response

Returns a paginated list of records matching the filter criteria (same structure as the List published records response).

Read draft data

Read data from the draft dataset to see pending changes before they are published.

Draft records include a state field indicating their lifecycle status:

  • NEW: Newly created record not yet published.

  • CHANGED: Modified record with unpublished changes.

  • DELETED: Record marked for deletion.

  • UNCHANGED: Published record with no pending changes.

  • REVIEW: Record submitted for review.

Request
GET /reference-data/v1/tables/{tableUrn}/draft/records
Authorization: Bearer {access_token}
Response example
{
  "meta": {
    "prev": null,
    "next": "eyJpZCI6IjUwIn0",
    "total": 200
  },
  "data": [
    {
      "id": "urn:ata:your-tenant:reference-data:record:523e4567-e89b-12d3-a456-426614174004",
      "values": [
        {
          "name": "country_code",
          "value": "US"
        },
        {
          "name": "country_name",
          "value": "United States"
        }
      ],
      "state": "UNCHANGED"
    },
    {
      "id": "urn:ata:your-tenant:reference-data:record:523e4567-e89b-12d3-a456-426614174099",
      "values": [
        {
          "name": "country_code",
          "value": "XK"
        },
        {
          "name": "country_name",
          "value": "Kosovo"
        }
      ],
      "state": "NEW"
    }
  ]
}

Filtering and pagination

Pagination

All list endpoints support cursor-based pagination for efficient data retrieval:

  • Use the next cursor from the response meta object with the after parameter to get the next page.

  • Use the prev cursor with the before parameter to get the previous page.

  • Set size to control the number of items per page (max: 100).

Example: Paginating through records
# First page
GET /reference-data/v1/tables/{tableUrn}/records?size=50

# Next page using cursor
GET /reference-data/v1/tables/{tableUrn}/records?size=50&after=eyJpZCI6IjUwIn0

Advanced filtering

The filter endpoint supports complex queries using logical and comparison operators.

Example: Filter by multiple conditions
{
  "filter": {
    "and": [
      {
        "attribute": {
          "attributeName": {"equals": "population"},
          "number": {"greaterOrEqual": 1000000}
        }
      },
      {
        "attribute": {
          "attributeName": {"equals": "country_name"},
          "string": {"contains": "United"}
        }
      }
    ]
  }
}
Example: Filter by date range
{
  "filter": {
    "attribute": {
      "attributeName": {"equals": "created_date"},
      "date": {
        "onOrAfter": "2024-01-01T00:00:00Z",
        "before": "2024-12-31T23:59:59Z"
      }
    }
  }
}

Complete example: Read data

Here’s a complete example using cURL to read data from a reference data table:

# 1. Obtain access token
TOKEN=$(curl -s -X POST "https://{your-environment}.ataccama.one/auth/realms/{your-realm}/protocol/openid-connect/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "client_id={your-client-id}" \
  -d "client_secret={your-client-secret}" \
  | jq -r '.access_token')

# 2. List all tables
curl -X GET "https://{your-environment}.ataccama.one/api/reference-data/v1/tables" \
  -H "Authorization: Bearer $TOKEN"

# 3. Get records from a specific table
TABLE_URN="urn:ata:your-tenant:reference-data:table:123e4567-e89b-12d3-a456-426614174000"
curl -X GET "https://{your-environment}.ataccama.one/api/reference-data/v1/tables/$TABLE_URN/records?size=20" \
  -H "Authorization: Bearer $TOKEN"

# 4. Filter records
curl -X POST "https://{your-environment}.ataccama.one/api/reference-data/v1/tables/$TABLE_URN/records/filter" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "filter": {
      "attribute": {
        "attributeName": {"equals": "country_code"},
        "string": {"contains": "U"}
      }
    }
  }'

Example: Data integration

Integrate reference data with external systems by reading published data and synchronizing it with your applications:

# Export reference data to an external system
curl -X GET "https://{your-environment}.ataccama.one/api/reference-data/v1/tables/{tableUrn}/records" \
  -H "Authorization: Bearer $TOKEN" \
  | jq '.data[]' > exported_data.json

Error handling

The API returns standard HTTP status codes and problem details for errors:

Status code Description

200 OK

Request successful.

401 Unauthorized

Missing or invalid authentication token.

404 Not Found

Requested resource does not exist.

409 Conflict

Request conflicts with current resource state. See 409 Conflict Error.
Error response example
{
  "type": "RESOURCE_NOT_FOUND",
  "title": "Resource Not Found",
  "detail": "Table with URN 'urn:ata:your-tenant:reference-data:table:invalid-id' was not found"
}

Next steps

Was this page useful?