Skip to content

Using the Swagger UI

The Nymbl Customer API includes an interactive Swagger UI that lets you explore and test all available endpoints directly from your browser — without writing any code.

Accessing the Swagger UI

The Swagger UI is available at:

https://docs.api.nymblqa.com/swagger

Authenticating in Swagger UI

All API endpoints require a valid OAuth 2.0 access token. The Swagger UI includes a built-in token form so you can authenticate without leaving the browser.

Step 1: Open the Token Form

  1. Open the Swagger UI in your browser
  2. Click Show Token Form to reveal the authentication fields
  3. Enter your credentials:
  4. Client ID — your application identifier
  5. Client Secret — your secret key
  6. Scope — your authorized scope (e.g., nymbl-customer-api/acme-corp)
  7. Submit the form — the UI will request a token from the authorization server and display it on success

Step 2: Authorize Swagger

  1. Click Authorize Swagger — the UI will automatically apply the Bearer token to all requests
  2. Also enter your API Key in the corresponding authorization field

The lock icons on each endpoint will now appear closed, indicating you are authenticated.

Token Expiration

Access tokens expire after 5 minutes. If you start receiving 401 Unauthorized responses, use the token form again to obtain a fresh token and click Authorize Swagger to reapply it.

Executing a Request

  1. Click on an endpoint to expand it (e.g., GET /Patients)
  2. Click Try it out in the top-right of that endpoint section
  3. Fill in any required parameters:
  4. Path parameters — e.g., the patient id for GET /Patients({id})
  5. Query parameters — e.g., $filter, $top, $skip, $select, $expand
  6. Click Execute
  7. The response body, status code, and headers will appear below

Using OData Query Parameters

All collection endpoints support OData query parameters. In Swagger UI, these appear as individual input fields:

Parameter Example Value Description
$filter active eq true Filter results
$select id,first_name,last_name Limit returned fields
$orderby last_name asc Sort results
$top 25 Return at most N records
$skip 50 Skip first N records
$count true Include total count
$expand Appointments Include related entities

See the OData Query Guide for syntax details.

Viewing the Raw OpenAPI Specification

The raw OpenAPI specification (JSON format) is available at:

https://docs.api.nymblqa.com/openapi.json

This can be imported into tools like Postman, Insomnia, or any OpenAPI-compatible client.

Troubleshooting

Receiving 401 on every request : Ensure your token is not expired. Use the token form to get a fresh token and click Authorize Swagger again. Also verify your API key is entered in the authorization field.

Parameters not appearing : Click Try it out on the specific endpoint — fields only become editable after clicking that button.

Response shows HTML instead of JSON : Verify the request URL matches your environment. The base URL is shown at the top of the Swagger UI page.