Getting Started

Introduction

Juvonno API is a collection of RESTful endpoints, which communicate directly with our back-end Business Objects, thus allowing users to Create, Read, Update & Delete (CRUD) the corresponding resources.

Juvonno API has strict validations and will throw detailed messages upon encountering any errors, thus enabling developers with better integration to our Juvonno App.

API Reference

This document will serve as a guideline & an introduction to our Juvonno API & our business logic.

For detailed API Document of all of our available Endpoints, please use this reference here in Swaggerhub.

What is a REST API?

API stands for "Application Programming Interface". It's a set of rules that enables various programs to talk to each other, regardless of the programming languages they were written in.

The programs talk to each other through a set of predefined URLs which can be accessed via HTTP Protocol.

These URLs represent various resources. A Resource represents a Juvonno Business Object, such as an Appointment, a Customer, or a Staff Member, etc. Resources will be returned in JSON format.

We utilize various HTTP Methods to perform different operations on a resource:

Authentication

Juvonno uses API keys to allow access to the API. You can register a new API key under your own profile in your Juvonno App.

Always append your api key using the query parameter "api_key" to your HTTP Request:

curl -X POST "https://tenant-id.juvonno.com/
api/{RESOURCES}?api_key={YOUR_API_KEY}"

POST "https://tenant-id.juvonno.com/api/{RESOURCES}?api_key={YOUR_API_KEY}"

API key must be included in all API requests to the server as a query parameter called "api_key" that looks like the following:

https://tenant-id.juvonno.com/api/{RESOURCES}?api_key=fhOkwr12kfslsdqwe8

Juvonno Resources

Each Resource represents an actual Juvonno Business Object, which can be accessed through a collection of URLs.

For example, /api/customers is the URL responsible for all operations on the "Customer Resource", which in turn is a "Customer Object" in our backend server.

Each object / resource will always have a unique Juvonno ID. It is up to users to choose to store our IDs into their application.

An example Customer Resource:

{
  "customer": {
    "id": 21,
    "num": {
      "chart": "CHART1234"
    },
    "first_name": "John",
    "last_name": "Doe"
  }
}

Additional Mapping Fields

Sometimes we also allow an additional field which users can use to match up against their own IDs in their system. For example, the Customer Resource on the right has a Juvonno ID of 21 and an additional identifier chart > num of "CHART1234" (which can represent the Customer's ID in your system).

It is not always the case that we provide an additional mapping field. One example is the "Appointment" Resource. "Appointment" does not have a "number" or a "name". The only way to distinguish between unique appointments in Juvonno is based on theirs Juvonno ID. Hence in some cases it relies totally on the Juvonno ID in order for a resource to be able to get retrieved or modified. Therefore, though it is not mandatory, but we do recommend storing this ID field into your own system.

Communication Between Resources

Resources in Juvonno communicate with each other through their unique identifier(s). You can always guarantee communication between resources using their Juvonno ID.

Example

If we want to assign Branch "Brandon Clinic" to Staff Member "Jane Doe", we can use the branch's Juvonno ID in the customer's update request body like this: { "branch_id": 1 }

CRUD Operations

We follow standard RESTful CRUD operations. There will be a corresponding
/api/ { RESOURCES - NAME }
collection of CRUD operations per Juvonno Object.

• The Resource's root endpoint will always be a Plural Noun:

  • /api/customers
  • /api/appointments
  • /api/staff
    
    

• The HTTP Method defines the actual action you can perform on the resource:

Create a new Resource

Always use POST to create a new resource.

POST https://tenant-id.juvonno.com/api/{RESOURCES}/

Create a new Customer:

POST https://tenant-id.juvonno.com/api/customers?api_key={YOUR_API_KEY}

cURL -X POST "https://tenant-id.juvonno.com/api/customers
?api_key={YOUR_API_KEY}"

Example Request Body

{
  "chart_num": "CHART1234",
  "first_name": "John",
  "last_name": "Doe"
}

Query Parameters

Request Body

• application/json
• application/x-www-form-urlencoded

Retrieve an existing Resource

Always use GET to retrieve a resource.

GET https://tenant-id.juvonno.com/api/{RESOURCES}/{RESOURCE_JUVONNO_ID}

Get a customer who has a Juvonno ID of 21:

GET https://tenant-id.juvonno.com/api/customers/21?api_key={YOUR_API_KEY}

cURL -X GET "https://tenant-id.juvonno.com/api/customers/21
?api_key={YOUR_API_KEY}"

Query Parameters

Update an existing Resource

Always use PUT to update an existing resource.

PUT https://tenant-id.juvonno.com/api/{RESOURCES}/{RESOURCE_JUVONNO_ID}

Update a customer who has a Juvonno ID of 21 with new phone number:

PUT https://tenant-id.juvonno.com/api/customers/21?api_key={YOUR_API_KEY}

cURL -X PUT "https://tenant-id.juvonno.com/api/customers/21
?api_key={YOUR_API_KEY}"

Request Body

{
  "phone": "1-431-123-1234"
}

Query Parameters

Request Body

• application/json
• application/x-www-form-urlencoded

Delete an existing Resource

Always use DELETE to delete a resource.

DELETE https://tenant-id.juvonno.com/api/{RESOURCES}/{RESOURCE_JUVONNO_ID}

Delete a customer who has a Juvonno ID of 21:

DELETE https://tenant-id.juvonno.com/api/customers/21?api_key={YOUR_API_KEY}

cURL -X DELETE "https://tenant-id.juvonno.com/api/customers/21
?api_key={YOUR_API_KEY}"

Query Parameters

Flexible Parameters

Sometimes an object can be accessed using different identifiers, Juvonno API provides the users with the flexibility of using other identifiers besides our main "Juvonno ID" to perform operations on the resource.

Example Scenario:

You want to create a new Staff and assign your staff to a clinic location called "Brandon Clinic".

A Clinic is represented by a "Branch Resource" in our API. A Branch can be identified by either its:

• Branch's Juvonno ID
• Branch's code
• Branch's name

In the request body, you can supply either parameter "branch_id", "branch_code" or "branch_name". Juvonno will try to map the branch to the staff based on the parameter your provided. Only one parameter needs to be supplied, although you can supply as many as you wish.

In case you have supplied more than one parameter (for example “branch_id” and “branch_name”), and if Juvonno has found a match with the first parameter, it will ignore and won’t map the second parameter provided. Mapping priority is in this exact order:

Branch_id > Branch_code > Branch_name

If your application has two branches with the same name “Brandon Clinic”, Juvonno API will return an Error with a detailed message asking you to supply a unique "branch_name" or use "branch_id" (Juvonno ID) instead.

If your application has no branches with the name “Brandon Clinic”, Juvonno API will return an Error telling you that it was unable to find any record with such name.

Errors

Juvonno API uses the following error codes:

Resources

Customers

Endpoint

/api/customers

A Customer represents a "Patient". You can create a new customer, retrieve or modify an existing customer using its Juvonno ID or its Chart Num.

Only Juvonno ID is treated as a unique identifier in our system. If you're querying using Chart Num, you must supply a unique existing number or else the program will throw corresponding error codes.

Endpoint Summary

Create a new Customer

HTTP Request

POST https://tenant-id.juvonno.com/api/customers

Create a new Customer:

POST https://tenant-id.juvonno.com/api/customers?api_key={YOUR_API_KEY}

cURL -X POST "https://tenant-id.juvonno.com/api/customers
?api_key={YOUR_API_KEY}"

Example Request Body

{
  "chart_num": "CHART1234",
  "first_name": "John",
  "last_name": "Doe",
  "date_of_birth": "1989-12-01",
  "gender": "male"   
}

Example Response:

{
  "customer": {
    "id": 1,
    "num": {
      "chart": "CHART1234"     
    },
    "first_name": "John",
    "last_name": "Doe",
    "gender": "male",
    "date_of_birth": "1989-12-01",
    "status": "active"                 
  }
}

This endpoint creates a new customer.

Query Parameters

Request Body

• application/json
• application/x-www-form-urlencoded

Retrieve a Customer using Juvonno ID

HTTP Request

GET https://tenant-id.juvonno.com/api/customers/{customerId}

Retrieve a customer who has a Juvonno ID of 21:

GET https://tenant-id.juvonno.com/api/customers/21?api_key={YOUR_API_KEY}

cURL -X GET "https://tenant-id.juvonno.com/api/customers/21
?api_key={YOUR_API_KEY}"

Example Response:

{
  "customer": {
    "id": 21,
    "num": {
      "chart": "CHART1234"     
    },
    "first_name": "John",
    "last_name": "Doe",
    "gender": "male",
    "date_of_birth": "1989-12-01",
    "status": "active"                 
  }
}

Query Parameters

URL Parameters

Retrieve a Customer using Chart Num

HTTP Request

GET https://tenant-id.juvonno.com/api/customers/chart/{number}

Retrieve a customer who has a Chart Num of "CHART1234":

GET https://tenant-id.juvonno.com/api/customers/chart/CHART1234?api_key={YOUR_API_KEY}

cURL -X GET "https://tenant-id.juvonno.com/api/customers/chart/CHART1234
?api_key={YOUR_API_KEY}"

Example Response:

{
  "customer": {
    "id": 21,
    "num": {
      "chart": "CHART1234"     
    },
    "first_name": "John",
    "last_name": "Doe",
    "gender": "male",
    "date_of_birth": "1989-12-01",
    "status": "active"                 
  }
}

Query Parameters

URL Parameters

Branches

Endpoint

/api/branches

A Branch represents a "Clinic Location". You can create a new branch, retrieve or modify an existing branch using its Juvonno ID.

List all Branches

HTTP Request

GET https://tenant-id.juvonno.com/api/branches

List all Branches:

GET https://tenant-id.juvonno.com/api/branches?api_key={YOUR_API_KEY}

cURL -X POST "https://tenant-id.juvonno.com/api/branches
?api_key={YOUR_API_KEY}"

Example Response:

{
  "list": [
    {
      "id": 1,
      "code": "ALBCLI",
      "name": "Alberta Clinic"
    },
    { 
      "id": 2,
      "code": "BRNCLI",
      "name": "Brandon Clinic"
    }   
  ]
}

This endpoint lists all branches in the system.

Query Parameters