List/View Lookups

List All Lookups

Both the Nexla API and the Nexla CLI support methods to list all lookups (data maps) in the authenticated user's account. A successful call returns detailed information about all accessible lookups including their configuration, metadata, and operational status.

API Endpoint

The primary endpoint for listing lookups is:

GET /data_maps

Nexla API
Nexla CLI

List All Lookups: Request
GET /data_maps

Example with curl:
curl https://api.nexla.io/data_maps \
  -H "Authorization: Bearer <Access-Token>" \
  -H "Accept: application/vnd.nexla.api.v1+json"

List All Lookups: Request
nexla lookup list

Response Structure

The response includes comprehensive lookup information including configuration details, metadata, and operational status.

Nexla API
Nexla CLI

List All Lookups: Response
[
  {
    "id": 1001,
    "owner": {
      "id": 42,
      "full_name": "John Smith"
    },
    "org": {
      "id": 101,
      "name": "Acme Corporation",
      "email_domain": "acme.com",
      "email": null
    },
    "access_roles": ["owner"],
    "name": "Example simple key/value map",
    "description": "Simple key-value lookup for event codes",
    "public_map": true,
    "managed": false,
    "data_type": "string",
    "data_format": null,
    "data_sink_id": null,
    "data_set_id": null,
    "emit_data_default": true,
    "use_versioning": false,
    "map_primary_key": "key",
    "data_defaults": {
      "key": "unknown",
      "value": "Unknown value"
    },
    "map_entry_schema": {
      "properties": {
        "key": {
          "format": "integer",
          "type": "string"
        },
        "value": {
          "type": "string"
        }
      },
      "type": "object",
      "$schema": "http://json-schema.org/draft-04/schema#",
      "$schema-id": 2098320124
    },
    "updated_at": "2023-01-15T17:42:38.000Z",
    "created_at": "2023-01-15T15:47:16.000Z",
    "tags": []
  },
  {
    "id": 1016,
    "owner": {
      "id": 42,
      "full_name": "John Smith"
    },
    "org": {
      "id": 101,
      "name": "Acme Corporation",
      "email_domain": "acme.com",
      "email": null
    },
    "access_roles": ["owner"],
    "name": "Department Code to Brand",
    "description": "Mapping department codes to brand names",
    "public_map": false,
    "managed": false,
    "data_type": "string",
    "data_format": null,
    "data_sink_id": 5014,
    "data_set_id": null,
    "emit_data_default": true,
    "use_versioning": false,
    "map_primary_key": "departmentCode",
    "data_defaults": {
      "departmentCode": "0",
      "brand": ""
    },
    "map_entry_schema": null,
    "updated_at": "2023-01-15T23:16:49.000Z",
    "created_at": "2023-01-15T23:16:49.000Z",
    "tags": []
  }
]

List All Lookups: Response
  id       name
----      ------------------------------------
1023       test_lookup
1024       test1_lookup

Show One Lookup

Fetch a specific lookup accessible to the authenticated user. A successful call returns detailed information about the lookup including its configuration, metadata, and current status.

API Endpoint

To retrieve a specific lookup by its ID:

GET /data_maps/{data_map_id}

Nexla API
Nexla CLI

Show One Lookup: Request
GET /data_maps/1001

Example with curl:
curl https://api.nexla.io/data_maps/1001 \
  -H "Authorization: Bearer <Access-Token>" \
  -H "Accept: application/vnd.nexla.api.v1+json"

Show One Lookup: Request
nexla lookup get <lookup_id>

Response Structure

The response includes comprehensive lookup information including configuration details, metadata, and operational status.

Nexla API
Nexla CLI

Show One Lookup: Response
{
  "id": 1001,
  "owner": {
    "id": 42,
    "full_name": "John Smith"
  },
  "org": {
    "id": 101,
    "name": "Acme Corporation",
    "email_domain": "acme.com",
    "email": null
  },
  "access_roles": ["owner"],
  "name": "Example simple key/value map",
  "description": "Simple key-value lookup for event codes",
  "public_map": true,
  "managed": false,
  "data_type": "string",
  "data_format": null,
  "data_sink_id": null,
  "data_set_id": null,
  "emit_data_default": true,
  "use_versioning": false,
  "map_primary_key": "key",
  "data_defaults": {
    "key": "unknown",
    "value": "Unknown value"
  },
  "map_entry_schema": {
    "properties": {
      "key": {
        "format": "integer",
        "type": "string"
      },
      "value": {
        "type": "string"
      }
    },
    "type": "object",
    "$schema": "http://json-schema.org/draft-04/schema#",
    "$schema-id": 2098320124
  },
  "updated_at": "2023-01-15T17:42:38.000Z",
  "created_at": "2023-01-15T15:47:16.000Z",
  "tags": []
}

Show One Lookup: Response
{
    "data_defaults": {},
    "name": "test",
    "data_type": "string",
    "data_map": [],
    "map_primary_key": "product_id",
    "description": null
}

List and Show Options

The API provides several options to customize the information returned when listing or viewing lookups.

Validation Information

To include lookup entry counts and caching information, include the validate=1 query parameter in your GET request.

Nexla API
Nexla CLI

List & Show Options: Request
GET /data_maps?validate=1

GET /data_maps/{data_map_id}?validate=1

Expanded Content

By default, GET calls to /data_maps do not show the content of the mapping itself, as those tend to be large arrays of objects. To receive the data map content as part of the response (for static maps only), include the expand=1 query parameter with your request.

Nexla API
Nexla CLI

Expanded Content: Request
GET /data_maps?expand=1

GET /data_maps/{data_map_id}?expand=1

Expanded Response Example

When using the expand parameter, the response includes additional information about map entries and caching status.

Nexla API
Nexla CLI

Expanded Response: Example
{
  "id": 1001,
  "owner": {
    "id": 42,
    "full_name": "John Smith"
  },
  "org": {
    "id": 101,
    "name": "Acme Corporation",
    "email_domain": "acme.com",
    "email": null
  },
  "access_roles": ["owner"],
  "name": "Example simple key/value map 2",
  "description": "Simple key-value lookup for event codes",
  "public_map": true,
  "managed": false,
  "data_type": "string",
  "data_format": null,
  "data_sink_id": null,
  "data_set_id": null,
  "emit_data_default": true,
  "use_versioning": false,
  "map_primary_key": "key",
  "data_defaults": {
    "key": "unknown",
    "value": "Unknown value"
  },
  "map_entry_info": {
    "cached": true,
    "cached_entry_count": 10,
    "static_entry_count": 10
  },
  "map_entry_schema": {
    "properties": {
      "key": {
        "format": "integer",
        "type": "string"
      },
      "value": {
        "type": "string"
      }
    },
    "type": "object",
    "$schema": "http://json-schema.org/draft-04/schema#",
    "$schema-id": 2098320124
  },
  "updated_at": "2023-01-15T17:42:38.000Z",
  "created_at": "2023-01-15T15:47:16.000Z",
  "tags": []
}

Response Field Details

The lookup response includes comprehensive information about the lookup and its configuration:

Basic Information

id: Unique identifier for the lookup
name: Human-readable lookup name
description: Optional description of the lookup purpose
data_type: Data type of the lookup values
data_format: Format specification for the lookup data

Configuration Details

map_primary_key: Primary key field used for lookup matching
data_defaults: Default values returned when lookup fails
emit_data_default: Whether to return default values on failed lookups
use_versioning: Whether the lookup supports versioning
map_entry_schema: JSON schema defining the lookup entry structure

Operational Status

public_map: Whether the lookup is publicly accessible
managed: Whether the lookup is managed by Nexla
data_sink_id: Associated data sink for dynamic lookups
data_set_id: Associated data set for dynamic lookups

Metadata

owner: User who owns the lookup
org: Organization the lookup belongs to
access_roles: User's access permissions for this lookup
tags: Associated tags for organization
created_at: Creation timestamp
updated_at: Last modification timestamp

Lookup Types and Characteristics

Static Lookups

Static lookups contain manually created and maintained reference data:

Manual Content: Content is created and updated through API calls
Fixed Structure: Schema and content are manually defined
Direct Control: Full control over lookup content and structure
Performance: Optimized for fast access to reference data

Dynamic Lookups

Dynamic lookups automatically update their content based on data flows:

Auto-Updating: Content refreshes based on data sink writes
Flow-Based: Integrated with data processing pipelines
Managed Content: System manages content updates automatically
Real-Time Data: Current information from active data sources

Best Practices

When listing and viewing lookups:

Use Validation Parameter: Include ?validate=1 to get entry counts and caching information
Use Expand Parameter: Include ?expand=1 to get complete lookup content for static maps
Monitor Status: Check lookup status to ensure operational health
Review Configurations: Verify lookup configurations match your requirements
Track Changes: Monitor updated_at timestamps for recent modifications

After listing lookups, you may need to:

Create New Lookup

POST /data_maps

Update Lookup

PUT /data_maps/{lookup_id}

Manage Lookup Entries

GET /data_maps/{lookup_id}/entries/{entry_key}
PUT /data_maps/{lookup_id}/entries
DELETE /data_maps/{lookup_id}/entries/{entry_key}

Download Lookup Content

GET /data_maps/{lookup_id}/download_map

Sample Lookup Data

POST /data_maps/{lookup_id}/probe/sample

List All Lookups​

API Endpoint​

Response Structure​

Show One Lookup​

API Endpoint​

Response Structure​

List and Show Options​

Validation Information​

Expanded Content​

Expanded Response Example​

Response Field Details​

Basic Information​

Configuration Details​

Operational Status​

Metadata​

Lookup Types and Characteristics​

Static Lookups​

Dynamic Lookups​

Best Practices​

Related Operations​

Create New Lookup​

Update Lookup​

Manage Lookup Entries​

Download Lookup Content​

Sample Lookup Data​

List All Lookups

API Endpoint

Response Structure

Show One Lookup

API Endpoint

Response Structure

List and Show Options

Validation Information

Expanded Content

Expanded Response Example

Response Field Details

Basic Information

Configuration Details

Operational Status

Metadata

Lookup Types and Characteristics

Static Lookups

Dynamic Lookups

Best Practices

Related Operations

Create New Lookup

Update Lookup

Manage Lookup Entries

Download Lookup Content

Sample Lookup Data