Lexigram Getting Started: Account, Keys, and First API Call

Getting started overview

Integrating with Lexigram involves a sequence of steps designed to provide developers with access to its healthcare data processing capabilities. The process begins with account creation, which grants access to the Developer Sandbox. This sandbox environment is where developers can obtain the necessary API keys for authentication and begin making requests to Lexigram's various APIs, such as the Clinical NLP API for extracting insights from unstructured text or the FHIR API for standardized data exchange (Lexigram documentation).

Lexigram's platform is designed to assist with tasks like normalizing medical data and integrating healthcare information in compliance with standards like FHIR, a standard for exchanging healthcare information electronically (HL7 FHIR overview). The Developer Sandbox offers a controlled environment to test these functionalities before scaling to production. Python, Java, and Node.js SDKs are available to streamline development (Lexigram SDKs documentation).

This guide outlines the initial steps to get started with Lexigram, from setting up your account to making your first API call. It focuses on practical implementation to enable rapid prototyping and integration.

Here's a quick reference for the initial setup:

Create an account and get keys

To access Lexigram's APIs, you must first create a developer account and obtain your API keys. These keys are essential for authenticating your requests and ensuring secure access to Lexigram's services. Lexigram offers a Developer Sandbox for initial exploration and testing, which provides limited usage of their core products (Lexigram pricing page).

Account Registration

1. Navigate to the Lexigram homepage.
2. Look for a "Sign Up" or "Get Started" link, typically located in the navigation bar or a prominent call-to-action button.
3. Complete the registration form with your details. This usually includes your name, email address, and a password. You may also need to agree to terms of service and a privacy policy.
4. Verify your email address if prompted. This is a common security measure to activate your account.

API Key Retrieval

Once your account is active, you can retrieve your API keys:

1. Log in to your newly created Lexigram developer account.
2. Access your developer dashboard or settings area. The exact location may vary but often includes sections for "API Keys", "Credentials", or "Settings" (Lexigram documentation on API keys).
3. Locate your unique API key. Lexigram typically provides a single API key for authentication across its services. This key is a long string of alphanumeric characters.
4. Important: Treat your API key as sensitive information. Do not expose it in client-side code, commit it directly to version control, or share it publicly. It should be stored securely, for example, as an environment variable or in a secure configuration management system.

Your first request

With your account set up and API key in hand, you can now make your first request to the Lexigram API. This example will demonstrate how to use the Clinical NLP API to process a piece of unstructured clinical text. We will provide examples using cURL and Python, as these are commonly used for initial API interactions and supported by Lexigram (Lexigram primary language examples).

Prerequisites

• Your Lexigram API key.
• For cURL: A terminal or command prompt.
• For Python: Python installed (version 3.6 or newer recommended) and the requests library (pip install requests).

Example: Clinical NLP API Request

We will use the Lexigram Clinical NLP API to analyze a sample clinical note. This API can extract entities, concepts, and relationships from medical text.

cURL Example

Replace YOUR_API_KEY with your actual Lexigram API key.

curl -X POST "https://api.lexigram.io/v1/nlp/process" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text": "Patient presented with fever and cough. Diagnosed with influenza."}'

This command sends a POST request to the /v1/nlp/process endpoint with a JSON payload containing the text to be processed. The Authorization header carries your API key, prefixed with Bearer, which is a common pattern for token-based authentication (OAuth 2.0 Bearer Token Usage).

Python Example

Replace YOUR_API_KEY with your actual Lexigram API key.

import requests
import os

# It's recommended to load your API key from an environment variable
api_key = os.environ.get("LEXIGRAM_API_KEY", "YOUR_API_KEY") # Fallback for testing

url = "https://api.lexigram.io/v1/nlp/process"
headers = {
    "Authorization": f"Bearer {api_key}",
    "Content-Type": "application/json"
}
data = {
    "text": "Patient presented with fever and cough. Diagnosed with influenza."
}

try:
    response = requests.post(url, headers=headers, json=data)
    response.raise_for_status() # Raise an exception for HTTP errors (4xx or 5xx)
    print("Response JSON:")
    print(response.json())
except requests.exceptions.RequestException as e:
    print(f"An error occurred: {e}")
    if hasattr(e, 'response') and e.response is not None:
        print(f"Error details: {e.response.text}")

This Python script uses the requests library to perform the same POST request. It includes error handling to catch potential issues during the API call and prints the parsed JSON response. It also demonstrates a best practice of loading the API key from an environment variable for security.

Expected Output

A successful response from the Clinical NLP API will return a JSON object containing the processed clinical text. The structure will vary depending on the specific entities and concepts identified, but it will typically include:

• Identified medical concepts (e.g., "fever", "cough", "influenza").
• Associated codes (e.g., SNOMED CT, ICD-10).
• Semantic types and relationships.

For a detailed understanding of the response structure, refer to the Lexigram Clinical NLP API reference.

Common next steps

After successfully making your first API request, several common next steps can help you further integrate Lexigram into your applications and workflows:

1. Explore Other Endpoints: Lexigram offers various APIs beyond Clinical NLP, including the FHIR API for standardized data exchange and Data Harmonization services. Review the Lexigram API reference to understand the full range of capabilities and identify endpoints relevant to your use case.
2. Integrate SDKs: While cURL and raw HTTP requests are useful for testing, using one of Lexigram's official SDKs (Python, Java, Node.js) can simplify development. SDKs abstract away boilerplate code for authentication, request construction, and response parsing, allowing you to focus on your application logic (Lexigram SDK documentation).
3. Implement Error Handling: Robust applications require comprehensive error handling. Familiarize yourself with Lexigram's API error codes and messages to gracefully manage issues like invalid requests, authentication failures, or rate limiting (Lexigram API error documentation).
4. Manage API Keys Securely: As your application moves beyond initial testing, ensure your API keys are managed securely. Avoid hardcoding them directly into your source code. Instead, use environment variables, secret management services, or secure configuration files.
5. Monitor Usage: Keep track of your API usage to stay within your plan limits and understand your application's consumption patterns. Lexigram's developer dashboard typically provides metrics and analytics related to your API calls.
6. Review Compliance Requirements: Given Lexigram's focus on healthcare, understanding and adhering to compliance standards like HIPAA is critical. Ensure your application's design and data handling practices align with these requirements (Lexigram compliance information).
7. Consider Production Deployment: For production environments, evaluate Lexigram's enterprise pricing and service level agreements. The Developer Sandbox is for testing, and production usage typically requires a commercial agreement (Lexigram pricing page).

Troubleshooting the first call

When making your first API call, you may encounter issues. Here are common problems and their solutions:

401 Unauthorized

This error typically indicates an issue with your API key or authentication. Check the following:

• Incorrect API Key: Double-check that you have copied your API key correctly from your Lexigram developer dashboard. Ensure there are no leading or trailing spaces.
• Missing Bearer Prefix: Ensure your Authorization header is formatted as Bearer YOUR_API_KEY, with "Bearer" followed by a space, then your key.
• Expired Key: While less common for initial setup, ensure your key hasn't expired or been revoked. If in doubt, generate a new key from your dashboard.

400 Bad Request

A 400 error usually means the server couldn't understand your request due to malformed syntax or invalid parameters.

• Incorrect JSON Format: Verify that your request body is valid JSON. Use a JSON validator if unsure. Ensure all keys and string values are enclosed in double quotes.
• Missing Required Parameters: Consult the Lexigram API reference for the specific endpoint you are calling. Ensure all mandatory parameters, such as the text field for the Clinical NLP API, are present.
• Incorrect Content-Type Header: Ensure the Content-Type header is set to application/json when sending JSON data.

Network Issues

Sometimes, the problem isn't with the API but with your network connection.

• Internet Connectivity: Verify your device has an active internet connection.
• Firewall/Proxy: If you are in a corporate environment, a firewall or proxy might be blocking outbound requests to api.lexigram.io. Consult your network administrator.
• DNS Resolution: Ensure that api.lexigram.io resolves correctly. You can test this using ping api.lexigram.io or nslookup api.lexigram.io in your terminal.

Server-Side Errors (5xx)

If you receive a 5xx error (e.g., 500 Internal Server Error, 503 Service Unavailable), this indicates a problem on Lexigram's side. While rare, if this occurs:

• Retry the Request: Sometimes these are transient issues; waiting a moment and retrying can resolve them.
• Check Lexigram's Status Page: Lexigram may have a public status page or announcements regarding service outages.
• Contact Support: If the issue persists, contact Lexigram support with details of your request and the error received.

Always refer to the official Lexigram documentation for the most up-to-date and comprehensive troubleshooting information.