Quick Start Guide

Get up and running with the Nymbl API in minutes.

Prerequisites

Client ID and Client Secret (contact your account manager)
A REST client (curl, Postman, or your preferred tool)
Basic understanding of REST APIs and OData

Step 1: Get an Access Token

First, obtain an access token using your credentials:

curl -X POST https://idp.api.nymblqa.com/oauth2/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" \
  -d "scope=nymbl-customer-api/acme-corp"

You'll receive a response like:

{
  "access_token": "eyJraWQiOiJ...",
  "expires_in": 300,
  "token_type": "Bearer"
}

Step 2: Explore the API

Use the service document to discover available resources:

curl https://api.nymblqa.com/ \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "x-api-key: YOUR_API_KEY"

Response:

{
  "@odata.context": "https://api.nymblqa.com/$metadata",
  "value": [
    {
      "name": "Patients",
      "kind": "EntitySet",
      "url": "Patients"
    },
    {
      "name": "Appointments",
      "kind": "EntitySet",
      "url": "Appointments"
    }
  ]
}

Step 3: Retrieve Data

Fetch a list of patients:

curl https://api.nymblqa.com/Patients \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "x-api-key: YOUR_API_KEY"

Get a specific patient by ID:

curl https://api.nymblqa.com/Patients(12345) \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "x-api-key: YOUR_API_KEY"

Step 4: Use Query Options

Filter patients by last name:

curl "https://api.nymblqa.com/Patients?\$filter=last_name eq 'Smith'" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "x-api-key: YOUR_API_KEY"

URL Encoding

Remember to URL encode query parameters. The $ character should be encoded as %24 in actual HTTP requests. Many HTTP clients handle this automatically.

Select specific fields:

curl "https://api.nymblqa.com/Patients?\$select=first_name,last_name,date_of_birth" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "x-api-key: YOUR_API_KEY"

Sort and limit results:

curl "https://api.nymblqa.com/Patients?\$orderby=last_name&\$top=10" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "x-api-key: YOUR_API_KEY"

Get patients with their appointments:

curl "https://api.nymblqa.com/Patients?\$expand=Appointments" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "x-api-key: YOUR_API_KEY"

Get a patient with appointments filtered by status:

curl "https://api.nymblqa.com/Patients(12345)?\$expand=Appointments(\$filter=status eq 'confirmed')" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "x-api-key: YOUR_API_KEY"

Example Code

Python

import requests

# Configuration
TOKEN_URL = "https://idp.api.nymblqa.com/oauth2/token"
API_BASE = "https://api.nymblqa.com"
CLIENT_ID = "your_client_id"
CLIENT_SECRET = "your_client_secret"
SCOPE = "nymbl-customer-api/acme-corp"
API_KEY = "your_api_key"

# Get access token
token_response = requests.post(TOKEN_URL, data={
    "grant_type": "client_credentials",
    "client_id": CLIENT_ID,
    "client_secret": CLIENT_SECRET,
    "scope": SCOPE
})
token_response.raise_for_status()
access_token = token_response.json()["access_token"]

# Make API request
headers = {
    "Authorization": f"Bearer {access_token}",
    "x-api-key": API_KEY
}
response = requests.get(f"{API_BASE}/Patients", headers=headers)
response.raise_for_status()
patients = response.json()

print(f"Found {len(patients['value'])} patients")

Node.js

const axios = require('axios');

const config = {
  tokenUrl: 'https://idp.api.nymblqa.com/oauth2/token',
  apiBase: 'https://api.nymblqa.com',
  clientId: 'your_client_id',
  clientSecret: 'your_client_secret',
  scope: 'nymbl-customer-api/acme-corp',
  apiKey: 'your_api_key'
};

async function getAccessToken() {
  const params = new URLSearchParams({
    grant_type: 'client_credentials',
    client_id: config.clientId,
    client_secret: config.clientSecret,
    scope: config.scope
  });

  const response = await axios.post(config.tokenUrl, params);
  return response.data.access_token;
}

async function getPatients() {
  const token = await getAccessToken();
  const response = await axios.get(`${config.apiBase}/Patients`, {
    headers: {
      Authorization: `Bearer ${token}`,
      'x-api-key': config.apiKey
    }
  });
  return response.data;
}

getPatients()
  .then(data => console.log(`Found ${data.value.length} patients`))
  .catch(error => console.error('Error:', error.message));