An overview of LCvista's API documentation
LCvista's Application Programming Interface (API) enables developers to connect external applications and/or write custom scripts to interact with data.
The API gives organizations the ability to automate tasks such as creating accounts, creating programs, and creating sessions. The API endpoints that we make available for integration are the same endpoints we use to power LCvista so any action performed in LCvista's UI can be recreated via these endpoints.
LCvista has worked to make our APIs as RESTful as possible where each resource has a unique URL and HTTP verbs are used to specify the action to be performed. JSON is returned in all responses from the API. The APIs are designed to have predictable, straightforward URLs and to use HTTP response codes to indicate API errors.
Table of Contents
Programs, Sessions, and Session Records
ProgramsOverall Compliance Report (Read Only)
Site URL
Every customer has a unique site URL and includes a browsable list of endpoints. Your specific site URL will be in the format of https://<site name>.lcvista.com/ where <site name> is the name of your company.
For example, if your company name is Acme Corporation your site URL would be https://acme.lcvista.com/ (https://acme.lcvista.com/) and you can browse the API endpoints at https://acme.lcvista.com/api/v1/ (https://acme.lcvista.com/api/v1/).
▲ Return to the table of contents
Authentication
Every request to the API must be transmitted over a secure channel using HTTPS and authenticated by passing an API key. You can generate an API key in the Organization admin menu in LCvista.
API endpoints use token-based authentication. Clients need to authenticate by passing the token key in the "Authorization" HTTP header, pre-pended with the string "Token ". For
example, include the following in the HTTP header with your token value:
Authorization: Token 555f5ac555da42b97f613d789819ff93537bee6a
▲ Return to the table of contents
HTTPS Verbs
LCvista uses the following verbs to take action on data through APIs.
GET
requests to return or list resources
POST
insert (create) a new resource
PATCH
update an existing resources, will update the values that are passed.
Note that PATCH calls must include the object being updated in the URL. For example, to PATCH a person record the URL will look like: https://<site name>.lcvista.com/api/v1/people/3410e169-8399-4e62-8942-4ea88c536ce6/ (https://dev2.lcvista.com/api/v1/people/3410e169-8399-4e62-8942- 4ea88c536ce6/)
PUT
NOT SUPPORTED, all creates need to be issued through a POST call
▲ Return to the table of contents
Response Codes
LCvista uses the following standard response codes:
200 – Success. Resource was updated or inserted successfully
201 – Success. Resource was created
400 – Bad request. Check that your URI and request was well formed.
404 – Not Found. The resource requested was not found.
▲ Return to the table of contents
Pagination
By default APIs only return 10 records at a time. You can increase the number of records returned by adding the “_limit=” parameter to end of the querystring. For example, the following call will return the first 100 people:
/api/v1/organizationpeople/?_limit=100
▲ Return to the table of contents
Browsable API Interface
Each customer site includes a browsable API interface that will allow you to interact with data on your site through the API endpoints. Before you can use the API interface your LCvista account must be granted Admin permission and you need to authenticate into your LCvista site. Once authenticated the browsable interface is available at https://<site name>.lcvista.com/api/v1/
The browsable interface will list the full set of available endpoints and you can click into each endpoint to view the data. You also have the ability to POST, PATCH or GET data via the interface. NOTE - you are directly interacting with your site data. Any changes made to data through this interface will be reflected on your LCvista site.
Example of the browsable API interface:
▲ Return to the table of contents
Model Overview
In this document we will define the core endpoints needed to fulfill the most common use cases for API integration. The overview will be grouped by logical model and provide an
overview of the endpoints needed to GET, POST and PATCH data.
▲ Return to the table of contents
Organization
The organization model contains configuration data related to your organization's SSO settings, custom field settings, etc. Typically a customer will have a single organization. The
organization_id is used throughout the endpoints to associate data to an organization. This endpoint is used to get your organization id which will be used to create user accounts and
other objects.
▲ Return to the table of contents
Organization: Common Use Cases
Get the organization id for use in other endpoints. The organization API is available to get the UUID, however it is recommended that Organization attributes are only updated via the UI
in LCvista.
▲ Return to the table of contents
Organization: Actions
GET /api/v1/organizations/
▲ Return to the table of contents
Organization: Endpoint Filters
None
▲ Return to the table of contents
Organization: Attributes
The available attributes can be found in the table below.
|
Field |
Type |
Description |
|
id |
UUID |
system generated UUID of the organization |
|
name |
String (up to 50) |
Name of the organization |
|
slug |
Slug (up to 50) |
URL slug for organization |
|
person_fields |
A JSON object |
Custom field definitions |
|
people_page_columns |
Array of Strings |
Array of fields to be displayed on the People page in UI |
|
enable_learning |
Boolean (Either True or False) |
|
|
logo_id |
UUID |
|
|
color1 |
String (up to 6) |
|
|
color2 |
String (up to 6) |
|
|
saml_enabled |
Boolean (Either True or False) |
|
|
saml_entity_id |
Text |
|
|
saml_url |
URL |
|
|
saml_x509_cert |
Text |
|
|
saml_first_name_attribute |
String (up to 255) |
|
|
saml_last_name_attribute |
String (up to 255) |
|
|
saml_email_attribute |
String (up to 255) |
|
|
saml_username_attribute |
String (up to 255) |
|
|
saml_button_text |
String (up to 255) |
|
|
password_reset_disabled |
Boolean (Either True or False) |
|
|
password_reset_messsage |
Text |
|
|
auto_generate_alternate_ids |
Boolean (Either True or False) |
|
|
max_organizationperson_alternate_id |
Integer |
|
|
max_program_alternate_id |
Integer |
|
|
waitlist_type_default |
String (up to 6) CHOICES: ['Manual', 'Auto'] |
|
|
waitlist_alert_message_default |
Text |
|
|
dashboard_announcements |
Text |
|
|
hide_user_learning_plan_menu |
Boolean (Either True or False) |
|
|
hide_transcript_credits |
Boolean (Either True or False) |
|
|
enable_webcast |
Boolean (Either True or False) |
|
|
download_link_expire_days |
Positive integer |
|
▲ Return to the table of contents
People (User Accounts)
User account information is stored in two core models, Person and OrganizationPerson. Each person must be mapped to at least one organization.
In order to create a new account, two endpoints must be called. Person endpoint is used to create the account and the OrganizationPerson endpoint is used to associate the account to an Organization.
▲ Return to the table of contents
People: Creating a New Account or Updating An Existing Account
Creating a person via API endpoints is a two step process.
Step 1: Create the person record
Step 2: Create the organizationperson record using the Person ID returned from the people endpoint.
See examples provided at the end of this section.
If user does not exist...
Make POST call to /people/
Using the LCvista id returned by POST call, make second POST call to /organizationpeople/
If user does exist…
Make PATCH call to /people/
Make PATCH call to /organizationpeople/
▲ Return to the table of contents
Person
Stores information on the user's attributes needed to logon to site.
▲ Return to the table of contents
Person: Common Use Cases
Search for a person's account for use in other endpoints
Create a new user account
▲ Return to the table of contents
Person: Actions
GET /api/v1/people/
POST /api/v1/people/
PATCH /api/v1/people/<uuid>/
▲ Return to the table of contents
Person: Endpoint Filters
id__in=<Person UUID>
email=<Email>
username=<Username>
▲ Return to the table of contents
Person: Attributes
The available attributes can be found in the table below.
|
Field |
Type |
Description |
|
id |
UUID |
System generated identifier |
|
first_name |
String (up to 50) |
Person first name |
|
last_name |
String (up to 50) |
Person last name |
|
username |
String (up to 255) |
Person username. Must be unique across a site. This field is used by SSO to authenticate a user. |
|
bio |
Text |
Instructor bio |
|
|
Email address |
Person email address |
|
is_staff |
Boolean (Either True or False) |
True = administrative previleges; False = standard priveleges |
|
is_active |
Boolean (Either True or False) |
Default all accounts to True. See OrganizationPerson endpoint for user account status. |
|
date_of_birth |
Date (without time) |
Person date of birth, used to generate reporting periods for certain jurisdictions. NOTE - Jurisdictional rules do not need a users actual birthday. To avoid PII concerns you may provide a masked birthdate that includes the actual birth month and the even/odd birth year. For example, if a users actual birthdate was Dec 4, 1996 you can provide a masked value of 12/01/1900. If birthdate was Dec 5, 1995 the masked value would be 12/01/1901. |
▲ Return to the table of contents
OrganizationPerson
Associates a person to a specific organization. As a client you may have multiple organizations that you manage.
The OrganizationPeople endpoint also provide the filters that allow you to lookup a person by email address. You can use this endpoint to return the person_id.
▲ Return to the table of contents
OrganizationPerson: Common Use Cases
Search for a person's account for use in other endpoints
Update a user's custom field values
Create a new user account
▲ Return to the table of contents
OrganizationPerson: Actions
GET /api/v1/organizationpeople/
POST /api/v1/organizationpeople/
PATCH /api/v1/organizationpeople/<uuid>/
▲ Return to the table of contents
OrganizationPerson: Endpoint Filters
person__email=<Email>
person__email__in=<Email>
alternate_id=<alternate id>
jurisdiction=<Jurisdiction UUID>
▲ Return to the table of contents
OrganizationPerson: Attributes
The available attributes can be found in the table below.
|
Field |
Type |
Description |
|
id |
UUID |
System generated identifier |
|
organization |
UUID |
Corresponding UUID for the organization |
|
person |
UUID |
Corresponding UUID for the person record |
|
data |
A JSON object |
Dictionary of custom fields used by the organziation |
|
admin_notes |
Text |
Misc notes on user |
|
alternate_id |
String (up to 255) |
Readable identifier for a user account. This can be auto-generated by LCvista or your site can configured to provide your own alternate_id. MUST BE UNIQUE across the site. |
|
status |
String (up to 50) |
CHOICES: ['Active', 'Disabled'] |
OrganizationPerson: Example: Create or Update User Account
Creating an account via API endpoints is a two step process.
▲ Return to the table of contents
Step 1: Create Person Record
XML
GET - check if user already exists
https://acme.lcvista.com/api/v1/people/?username=jane.doe@acme.com
POST
https://rsmus.lcvista.com/api/v1/people/
{
"username":"jane.doe@acme.com",
"email":"jane.doe@acme.com",
"first_name":"Jane",
"last_name":"Doe",
"date_of_birth":"1900-01-01"
}
PATCH
https://acme.lcvista.com/api/v1/people/53079970-1db2-4134-9735-ad7fc9aaff1e/
{
"username":"jane.doe@acme.com",
"email":"jane.doe@acme.com",
"first_name":"Jane",
"last_name":"Doe",
"date_of_birth":"1900-01-01"
}
▲ Return to the table of contents
Step 2: Create OrganizationPerson Record
XML
GET - check if OrganizationPeople record exists for person UUID
https://acme.lcvista.com/api/v1/organizationpeople/?person=53079970-1db2-4134-9735-ad7fc9aaff1e
POST
https://acme.lcvista.com/api/v1/organizationpeople/
{
"organization":"<UUID from organization endpoint>",
"person":"<UUID from people endpoint>",
"status": "<Active or Disabled as mapped from empl_status>",
"data": {
"field0": "<custom field 0>",
"field1": "<custom field 1>",
"field2": "<custom field 2>"
...
}
}
PATCH
https://acme.lcvista.com/api/v1/organizationpeople/<UUID for organizationperson record>/
{
"status": "<Active or Disabled as mapped from empl_status>",
"data": {
"field0": "<custom field 0>",
"field1": "<custom field 1>",
"field2": "<custom field 2>"
...
}
}
▲ Return to the table of contents
JurisdictionPerson
Associates a person to a jurisdiction. Creating a JurisdictionPeople instance will create all reporting periods from the original license date through the current date.
Note that LCvista does not support future dated licenses.
▲ Return to the table of contents
JurisdictionPerson: Common Use Cases
Assign a jurisdiction to a person (POST)
Update a jurisdiction attribute such as license ID
▲ Return to the table of contents
JurisdictionPerson: Actions
GET /api/v1/jurisdictionpeople/
POST /api/v1/jurisdictionpeople/
PATCH /api/v1/jurisdictionpeople/<uuid>/
▲ Return to the table of contents
JurisdictionPerson: Endpoint Filters
jurisdiction=<Jurisdiction UUID>
organization_person=<UUID>
▲ Return to the table of contents
JurisdictionPerson: Attributes
The available attributes can be found in the table below.
|
Field |
Type |
Description |
|
id |
UUID |
|
|
jurisdiction |
UUID |
The UUID of the associated jurisdiction. Use the jurisdiction endpoint to get the UUID. |
|
organization_person |
UUID |
The UUID for the associated account. Use the organizationperson endpoint to get the UUID. |
|
license_id |
String (up to 255) |
The user's jurisdictional license ID. This may be used to generate reporting periods. |
|
original_license_date |
Date (without time) |
Date the user was licensed in the jurisdiction. Must be less than the current date. |
|
license_expiration |
Date (without time) |
Date the user was license expires in the jurisdiction. |
|
period_override_date |
Date (without time) |
Override the pre-defined reporting period end date for a jurisdiction. |
|
custom_date |
Date (without time) |
Latest license date |
JurisdictionPerson: Example: Associate a Jurisdiction to a Person
Associates a jurisdiction to a person. Creating a JurisdictionPeople instance will create all reporting periods from the original license date through the current date.
Note that LCvista does not support future dated licenses. Recommendation is to create only via API.
XML
GET - check if specific user is already associated with a jurisdiction
https://acme.lcvista.com/api/v1/jurisdictionpeople/?organization_person=3f212228-c680-4513-bc0f-9e4ff5c3a497&jurisdiction=31ac27ad-0bbd-4ce2-bc99-9256490
POST - jurisdictionpeople did not exist
https://acme.lcvista.com/api/v1/jurisdictionpeople/
{
"organization_person":"<UUID from organizationpeople endpoint>",
"jurisdiction": "<UUID from jurisdiction endpoint for the license>",
"license_id": "<The user's jurisdictional license ID. This may be used to generate reporting periods>",
"original_license_date": "<date issued (cannot be in the future)>",
"license_expiration": "<optional date user license expires>"
}
PATCH -
https://acme.lcvista.com/api/v1/jurisdictionpeople/<UUID>/
{
"organization_person":"<UUID from organizationpeople endpoint>",
"jurisdiction": "<UUID from jurisdiction endpoint for the license>",
"license_id": "<The user's jurisdictional license ID. This may be used to generate reporting periods>",
"license_expiration": "<optional date user license expires>"
}
▲ Return to the table of contents
Periods
The reporting periods associated to jurisdiction person records. This API should be used to only modify a period status and/or jurisdiction flags. Period records are created automatically through the JurisdictionPerson API based on the jurisdiction rules.
▲ Return to the table of contents
Periods: Common Use Cases
Update a period status to Exempt or Active
Set a jurisdiction flag for a specific period or all periods
▲ Return to the table of contents
Periods: Actions
GET /api/v1/periods/
POST /api/v1/periods/
PATCH /api/v1/periods/<uuid>/
▲ Return to the table of contents
Periods: Endpoint Filters
organization_person=<organization person UUID>
jurisdiction=<Jurisdiction UUID>
start_date __lte=<date value yyyy-mm-dd> include periods starting before date value
end_date__gte=<date value yyyy-mm-dd> include periods ending after date value
status__in=<period status active, inactive, exempt>
▲ Return to the table of contents
Periods: Attributes
The available attributes can be found in the table below.
|
Field |
Type |
Description |
|
id |
UUID |
|
|
jurisdiction |
UUID |
The UUID of the associated jurisdiction |
|
organization_person |
UUID |
The UUID for the associated account |
|
period_rule |
UUID |
SYSTEM GENERATED, do not modify |
|
reporting_period |
UUID |
SYSTEM GENERATED, do not modify |
|
start_date |
Date (without time) |
SYSTEM GENERATED, do not modify |
|
end_date |
Date (without time) |
SYSTEM GENERATED, do not modify |
|
base_start_date |
Date (without time) |
SYSTEM GENERATED, do not modify |
|
extended_date |
Date (without time) |
An override date that extends the time a user has to complete credits for a reporting period. |
|
previous_period |
One-to-one relationship |
SYSTEM GENERATED, do not modify |
|
in_compliance |
Boolean (Either True or False) |
SYSTEM GENERATED, do not modify |
|
earned |
Decimal number |
SYSTEM GENERATED, do not modify |
|
applied |
Decimal number |
SYSTEM GENERATED, do not modify |
|
carry_over |
Decimal number |
SYSTEM GENERATED, do not modify |
|
extension |
Decimal number |
SYSTEM GENERATED, do not modify |
|
reciprocity_rule |
UUID |
SYSTEM GENERATED, do not modify |
|
is_primary |
Boolean (Either True or False) |
|
|
status |
String (up to 100) |
CHOICES: ['Active', 'Inactive', 'Exempt', 'Locked'] |
|
notes |
Text |
Free form text field to add notes on a period |
|
last_modified |
Date (with time) |
SYSTEM GENERATED, do not modify |
▲ Return to the table of contents
Periods: Example: Add a PCAOB flag to all periods
The following shows an example of adding a PCAOB flag to each period. You can lookup the flag UUID on the ruleflags endpoint (https://qa-demo.lcvista.com/api/v1/ruleflags/).
The flag ID will be consistent across test and production.
XML
GET - get the available flags you can set on the PCAOB jurisdiction
https://acme.lcvista.com/api/v1/ruleflags/?jurisdiction=31ac27ad-0bbd-4ce2-bc99-9256490d015b
GET - return the list of periods created for the specific person and jurisdiction
https://acme.lcvista.com/api/v1/periods/?organization_person=7ff3b32b-aa28-4a42-9101-ab333d5d8758&jurisdiction=31ac27ad-0bbd-4ce2-bc99-9256490d015b
The above get call returns all of the periods for this specific user/jurisdiction
For each period returned, make a PATCH call the periods where "reporting_period": null.
The periods where "reporting_period": null are the parent period
Making a PATCH call on these will automatically update the child the periods.
To get the Flag UUID, see the Common Endpoint Lookup section in this documentation.
PATCH https://acme.lcvista.com/api/v1/periods/57b8e7d6-1392-493c-8029-e4517be4a2ee/ {
"flags": ["4915a8b6-5d75-490e-a136-438a9a49a12d"] }
PATCH https://acme.lcvista.com/api/v1/periods/06de1d41-79bb-4fea-8065-a5afeb97bbe8/ {
"flags": ["4915a8b6-5d75-490e-a136-438a9a49a12d"] }
▲ Return to the table of contents
Programs, Sessions, and Session Records
Programs and sessions are related in a parent and child relationship. A session is an instance of each program.
A program can have multiple sessions such as a session in the Seattle Office and a session in the Portland Office. A SessionRecord is the specific user status in a Session. A single user can only have one SessionRecord per Session. All users that attend a Session will have a SessionRecord.
Notes on dictionary fields that track topic_areas and fields_of_study for programs, sessions and session records. When updating a program/session/session record, the dictionary of topic_areas or fields_of_study will overwrite all previous values for that record.
For example, if a topic_area is updated from 10 credits Accounting to 10 credits Tax, then the dictionary only needs to include the Tax credits and the previous Accounting credits will be removed.
▲ Return to the table of contents
Programs
This is the parent container for a session. The program contains parent level attributes that are consistent for all sessions such as the program name, description, topic area credits (these can be overridden per session), program documentation, etc.
▲ Return to the table of contents
Programs: Common Use Cases
Create a new program
Look up a program by alternate_id to see if it exists
▲ Return to the table of contents
Programs: Actions
GET /api/v1/programs/
POST /api/v1/programs/
PATCH /api/v1/programs/<uuid>/
▲ Return to the table of contents
Programs: Endpoint Filters
Endpoint Filters id__in = <UUID>
alternate_id = <Alternate ID as provided by client>
external_alternate_id=<external alternate id>
catalogs__in = <Catalog UUID>
is_archived = <True/False>
modified = <Date YYYY-MM-DD>
session__delivery_method = <Session Delivery Method UUID>
session__start_date = <Session Start Date YYYY-MM-DD>
session__end_date = <Session End Date YYYY-MM-DD>
requirement = <Session Field of Study UUID>
Note: Available operators for modified, session__start_date and session__end_date are gte and lte. Please note that NULL values may be returned.
gte: Filter where records are greater than or equal to parameter value session__start_date__gte=2020-10-31
lte: Filter where records are less than or equal to parameter value session__end_date__lte=2020-10-31
▲ Return to the table of contents
Programs: Attributes
The available attributes can be found in the table below.
|
Field |
Type |
Description |
|
id |
UUID |
system generated id |
|
organization |
UUID |
The site's Organization ID |
|
name |
String (up to 255) |
Program name, required for program creation. Not required for updates. |
|
description |
Text |
Program description. Accepts HTML mark up for displaying in the UI. |
|
objectives |
Text |
Program objectives. |
|
advanced_preparation |
Text |
|
|
prerequisites |
Text |
|
|
nasba_id |
String (up to 255) |
The specific ID issued by NASBA for this program. |
|
nasba_revision |
Date (without time) |
The date used to track the latest revision of program content for reporting to NASBA. |
|
length |
String (up to 255) |
Text field to display the duration of the program. Since this is a text field, it can be formatted for display based on your preferences. Example, 1.0 Hours, 50 Minutes, etc. |
|
sponsor |
UUID |
The UUID for the Sponsor for the program. |
|
external |
Boolean (Either True or False) |
Boolean flag (True/False) to indicate if program was created through External credit UI. Typically it is recommended that programs are created via the API set this value = False. |
|
admin_notes |
Text |
Text field available to add administrative notes about the program. |
|
external_alternate_id |
String (up to 255) |
Additional ID field that can be used to track an additional customer specific ID or a specific content provider ID. This field is not displayed in the UI. |
|
alternate_id |
String (up to 255) |
This ID is a unique across the system. This is the ID that is used to search and find programs. The ID is displayed on the program page for reference. This field is READ-ONLY for clients that are configured to have LCvista auto-generate alternate_ids. |
|
max_session_alternate_id |
Integer |
READ ONLY |
|
level |
String (up to 12) |
CHOICES: ['None', 'Basic', 'Intermediate', 'Advanced', 'Overview', 'Update'] |
|
is_learningplan |
Boolean (Either True or False) |
READ ONLY, Value should only be set in LCvista UI. |
|
catalogs |
Many-to-many relationship |
UUID list of the LCvista catalog(s) that the program should be associated to. |
|
tags |
Many-to-many relationship |
UUID list of tags to associate to a program |
|
program_jurisdictions |
Dictionary |
Dictionary of jurisdiction specific program IDs |
|
program_qualifications |
Dictionary |
Program qualification flag UUID to be used when issuing jurisdictional credit. If this value is passed it must be a validate qualification UUID. Note that some qualifications require an additional Jurisdiction UUID. |
|
program_topic_areas |
Dictionary |
Dictionary of NASBA credits (Topic Areas) |
|
earliest_session_start |
Date (with time) |
READ ONLY |
|
total_credit_minutes |
Integer |
READ ONLY |
|
is_archived |
Boolean (Either True or False) |
Boolean flag (True/False) to indicate if program is active or archived. |
|
modified |
Date |
|
▲ Return to the table of contents
Programs: Example: Create or Update a Program
XML
GET - check if program already exists
https://acme.lcvista.com/api/v1/programs/?alternate_id=<Your LMS Program ID>
POST - create a new program https://acme.lcvista.com/api/v1/programs/
{
"organization": "7dbab4b2-5daf-4575-8c48-95d0fe37b3c8",
"name": "My Test Programs 10",
"description": "Enter your <b>HTML</b> <i>Description</i> here...",
"objectives": "Enter program objectives here...",
"advanced_preparation": "NASBA adv prepration notes...",
"prerequisites": "<p>Prereqs go here...</p>",
"length": "5 Hours",
"level": "Advanced",
"sponsor": "<UUID for Sponsor>",
"program_qualifications": [ <NOTE - only used for State Ethic qualifications> {
"qualification": "<UUID for Ethics qualification>",
"jurisdiction": "<Jurisdiction UUID for the qualifying state>"
}
]
"program_topic_areas": [
{
"topic_area": "<UUID from topicareas endpoint>",
"credit_minutes": 100.0
},
{
"topic_area": "<UUID from topicareas endpoint>",
"credit_minutes": 150.0
}
]
}
PATCH - update existing program
https://acme.lcvista.com/api/v1/programs/<LCVista UUID>
Example call to change the credits and update the credits on all users with Passed with full credit
{
"name": "My Test Programs 10",
"program_topic_areas": [
{
"topic_area": "<UUID from topicareas endpoint>",
"credit_minutes": 50.0
},
{
"topic_area": "<UUID from topicareas endpoint>",
"credit_minutes": 50.0
}
],
"reaccredit_program": true (NOTE - only pass this as true when credits are modified. do not include on POST or when update doesn't modify the credit
}
▲ Return to the table of contents
Sessions
This is the child container for a program. The session contains attributes that are specific for a session such as delivery method, venue, start date, end date, etc. NASBA credits (topic_areas) can be overridden per session as well as Jurisdiction credit (fields_of_study).
▲ Return to the table of contents
Sessions: Common Use Cases
Create a new session
Look up a session to see if it exists
▲ Return to the table of contents
Sessions: Actions
GET /api/v1/sessions/
POST /api/v1/sessions/
PATCH /api/v1/sessions/<uuid>/
▲ Return to the table of contents
Sessions: Endpoint Filters
id__in = <Session UUID>
sponsor = <Sponsor UUID>
program__in = <Program UUID>
program = <Program UUID>
program_topic_areas = <Program Topic Area UUID>
catalogs__in = <Catalog UUID>
external_alternate_id=<external alternate id>
▲ Return to the table of contents
Sessions: Attributes
The available attributes can be found in the table below.
|
Field |
Type |
Description |
|
id |
UUID |
|
|
external_alternate_id |
String (up to 255) |
Optional session identifier. This field is not displayed in the UI and typically used by clients that create programs and sessions via API feeds. For clients that are creating new programs, session, and sessionrecords, this optional field is available to store a source system ID to validate if a session has previously been loaded. |
|
program |
UUID |
The UUID for the parent program |
|
delivery_method |
UUID |
The UUID for the NASBA delivery method for a session. The value in this column must match one of the UUIDs available from the delivery method endpoint . If an unexpected value is passed then the session will not be created. |
|
certificate_location |
String (up to 255) |
Used to report the location name for nasba reporting requirements. Typically this goes on system generated certificates |
|
is_on_scorm_cloud |
Boolean (Either True or False) |
READ ONLY. |
|
venue |
UUID |
The UUID for the venue to be associated to this session. See Venue endpoint. |
|
comment |
Text |
Text field available for comments |
|
launch_type |
String (up to 255) |
READ ONLY. CHOICES: ['', 'SCORM/AICC/xAPI', 'URL', 'Media', 'Webcast'] |
|
launch_url |
String (up to 1024) |
READ ONLY |
|
content_package |
UUID |
READ ONLY |
|
media_file |
UUID |
READ ONLY |
|
certificate_template |
UUID |
The UUID for the certificate template that will be used to generate certificates when a user completes this session. |
|
admin_notes |
Text |
|
|
evaluation_template |
UUID |
The UUID for the evaluation template to be associated to this session |
|
timezone |
String (up to 50) |
The default timezone used on the Session edit UI to display the start and end times of the session. Suggested US timezones: {"US/Alaska", "US/Aleutian", "US/Arizona", "US/Central", "US/East-Indiana", "US/Eastern", "US/Hawaii", "US/Indiana-Starke", "US/Michigan", "US/Mountain", "US/Paci c", "US/Paci c-New", "US/Samoa"} |
|
start_datetime |
Date (with time) |
The timestamp for the session start. Please see FAQ below on passing timestamps. |
|
end_datetime |
Date (with time) |
The timestamp for the session end. Please see FAQ below on passing timestamps. |
|
enrollment_start_datetime |
Date (with time) |
The timestamp for the session enrollment start. Please see FAQ below on passing timestamps. |
|
enrollment_end_datetime |
Date (with time) |
The timestamp for the session enrollment end. Please see FAQ below on passing timestamps. |
|
first_time_instructing |
Boolean (Either True, False or None) |
Typically set to True. Used to determine if a user is allowed to receive instructor credit. |
|
min_enrolled |
Integer |
Used to configure waitlist for the session. |
|
max_enrolled |
Integer |
Used to configure waitlist for the session. |
|
waitlist_type |
String (up to 6) |
CHOICES: ['Manual', 'Auto'] |
|
waitlist_alert_message |
Text |
Used to configure waitlist for the session. |
|
alternate_id |
String (up to 255) |
READ ONLY. Incrementing integer generated by LCvista to track the session |
|
instructors |
Many-to-many relationship |
For display purposes only in LCvista program catalog. A list of UUIDs for the session instructors. |
|
session_topic_areas |
Dictionary |
Dictionary of TopicArea UUIDs and credit minutes. Used to override the program NASBA credits for an individual session. Not typically used, see section called Issuing Credit Workflow. |
|
session_field_of_study |
Dictionary |
Dictionary of Jurisdictional credits (Fields of study) UUIDs and credit minutes. Used to override the jurisdiction credits for an individual session. Not typically used, see section called Issuing Credit Workflow. |
|
auto_create_fieldsofstudy |
Boolean |
Available only in POST/PATCH calls. Indicates if fields of study credit should be created using the program TopicAreas. See section called Issuing Credit Workflow. |
▲ Return to the table of contents
Sessions: Example: Create or Update a Session
XML
GET - check if session already exists
https://acme.lcvista.com/api/v1/sessions/?program=5aad7db8-eb26-4a42-9e01-1ae682558284
if record doesn't exist POST
Required Fields:program, delivery_method and auto_create_fieldsofstudy
POST https://acme.lcvista.com/api/v1/sessions/
{
"program": "5aad7db8-eb26-4a42-9e01-1ae682558284",
"delivery_method": "bed4da99-6bfe-4861-9718-df5bdc715e16",
"auto_create_fieldsofstudy": true,
"instructors": [<UUID>,<UUDI>],
"timezone": "US/Eastern",
"start_datetime": "2016-08-01T12:00:00Z",
"end_datetime": null,
"venue": <venue UUID>,
"certificate_location": "",
"comment": "",
"certificate_template": null,
"external_alternate_id": ""
}
if record exists PATCH
https://acme.lcvista.com/api/v1/sessions/<session UUID>/ {
"program": "5aad7db8-eb26-4a42-9e01-1ae682558284",
"delivery_method": "bed4da99-6bfe-4861-9718-df5bdc715e16",
"auto_create_fieldsofstudy": true,
"instructors": [<UUID>,<UUDI>],
"timezone": "US/Eastern",
"start_datetime": "2016-08-01T12:00:00Z",
"end_datetime": null,
"venue": <venue UUID>,
"certificate_location": "",
"comment": "",
"certificate_template": null,
"external_alternate_id": ""
}
▲ Return to the table of contents
SessionRecords
SessionRecords are instances of session that are associated to a user. If a user is associated to a session (Invited, Enrolled, Passed, etc.) that association is a SessionRecord.
When creating session records you have the option to create custom credit per user by overriding the TopicAreas and FieldsOfStudy.
However, creating custom credit is typically done through the UI only. A more common scenario through an API feed is to customize the Completion Date per user.
▲ Return to the table of contents
SessionRecords: Common Use Cases
Create a new sessionrecord
Update a sessionrecord status to completed
▲ Return to the table of contents
SessionRecords: Actions
GET /api/v1/sessionrecords/
POST /api/v1/sessionrecords/
PATCH /api/v1/sessionrecords/<uuid>/
▲ Return to the table of contents
SessionRecords: Endpoint Filters
'id': ['in']
'session': ['exact'],
'session__delivery_method': ['exact'],
'session__program': ['exact'],
'is_launchable': ['exact'],
'organization_person': ['exact'],
'completion_date': ['exact', 'gte', 'lte', 'isnull'],
'session__start_datetime': ['exact', 'gte', 'lte', 'isnull'],
'status': ['exact'],
'certificate': ['exact', 'isnull'],
'modified': ['exact', 'gt', 'gte', 'lt', 'lte', 'range'],
▲ Return to the table of contents
SessionRecords: Filter Examples
exact: Filter where record exactly matches the parameter
session=<uuid> status=Passed with
gte: Filter where records are greater than or equal to parameter value completion_date__gte=2020-10-31
lte: Filter where records are less than or equal to parameter value completion_date__lte=2020-10-31
gt: Filter where records are greater than parameter value completion_date__gt=2020-10-31
lt: Filter where records are less than parameter value completion_date__lt=2020-10-31
▲ Return to the table of contents
SessionRecords: Attributes
The available attributes can be found in the table below.
|
Field |
Type |
Description |
|
id |
UUID |
|
|
session |
UUID |
UUID for the session |
|
organization_person |
UUID |
UUID for the user account receiving credit |
|
program_name |
String (up to 255) |
Name of the program at time the credit was issued |
|
admin_notes |
Text |
|
|
completion_date |
Date (without time) |
Timezone agnostic date, used to determine and report the completion of a session |
|
completion_timezone |
String (up to 50) |
READ ONLY. Used by LMS interactive sessions. |
|
score |
Decimal number |
READ ONLY. Used by LMS interactive sessions. |
|
total_time |
Integer |
READ ONLY. Used by LMS interactive sessions. |
|
success |
Boolean (Either True or False) |
READ ONLY. Used by LMS interactive sessions. |
|
passed_program |
Boolean (Either True or False) |
Indicate if a user passed the program |
|
certificate |
UUID |
READ ONLY |
|
status |
String (up to 255) |
CHOICES: ['Passed with full credit', 'Passed with custom credit', 'Failed', 'Enrolled', 'Unenrolled', 'No show', 'Incomplete', 'Invited', 'Send Evaluation', 'Waitlisted'] |
|
status_changed |
Date (with time) |
READ ONLY |
|
evaluation_sent |
Date (with time) |
READ ONLY |
|
first_time_instructing |
Boolean (Either True or False) |
|
|
data |
A JSON object |
|
|
datetime_started |
Date (with time) |
|
|
datetime_completed |
Date (with time) |
|
|
datetime_enrolled |
Date (with time) |
|
|
datetime_waitlisted |
Date (with time) |
|
|
created_scorm_registration |
Boolean (Either True or False) |
READ ONLY |
▲ Return to the table of contents
Issuing Credit Workflow
LCvista provides flexibility to assign and override credits at the Program, Session, and SessionRecord objects.
While there are scenarios where a Session and/or SessionRecord requires custom credit that differs from the Program, the most common scenario is to issue credits on the SessionRecords based on the Program TopicAreas.
LCvista APIs provides flags on the Session and SessionRecord API to automatically create credits.
The most common scenarios supported by these flags are Full Credit and Custom Credit. Below outlines how to use the flags and APIs to do each:
Pass with Full Credit
Create program with TopicAreas
Create Session with “auto_create_fieldsofstudy = true”
Create SessionRecord with “auto_create_earned_credits = true”
Pass with Custom Credit
Create program with TopicAreas
Create Session with “auto_create_fieldsofstudy = true”
Create SessionRecord with “auto_create_earned_credits = true” and pass in custom TopicArea credit for the user
▲ Return to the table of contents
Pass with Technical Reviewer Credit
Create program with TopicAreas
Create Session with “auto_create_fieldsofstudy = true”
Create SessionRecord with “auto_create_earned_credits = true”, pass in custom TopicAreas with custom credit and Technical Reviewer Delivery Method for the user
▲ Return to the table of contents
Issuing Credit Workflow: Example: Get SessionRecords
HTML
GET - List all session records modified on or after Oct 31, 2020
https://acme.lcvista.com/api/v1/sessionrecords/?modified__gte=2020-10-31
GET - List all session records with a completion date on Oct 1, 2020 h
ttps://acme.lcvista.com/api/v1/sessionrecords/?completion_date=2020-08-01
▲ Return to the table of contents
Issuing Credit Workflow: Example: Create or Update a SessionRecord
The following example highlights a couple scenarios on issuing credit. In particular it is important to understand if the user is being passed with Full credit or Custom credit. The status will determine if credits need to be included when issuing SessionRecord credit.
GET - check if sessionrecord already exists
https://acme.lcvista.com/api/v1/sessionrecords/?organization_person=93389760-f28d-432c-92fd-b62aa9913c32&session=2d9a73d9-f985-47b8-a4a1-a98df877a707
if record doesn't exist POST
Required Fields: session, organization_person, program_name, completion_date, status, auto_create_earned_credits, session_record_topic_areas
Note on status:
If the user being passed earned full credit in the program then you can pass just pass the status Passed with full credit and LCvista will issue the program credit to the user.
If the user left early and earned less credit (or more credit) then pass the user with custom credit and provide the credit amount the user earned.
POST - Full credit (user earned all credit for which the program is accredited) https://acme.lcvista.com/api/v1/sessionrecords/
{
"session": "5c2270e2-ad25-4d7f-a767-8a161169a112",
"organization_person": "2fab71d9-ebcf-49b9-83f4-771c6f29d8c0",
"program_name": "Name of the program",
"completion_date": "2018-08-01",
"status": "Passed with full credit",
"auto_create_earned_credits": true
}
POST - Partial credit (user earned credit that differs, typically less, than the program) https://acme.lcvista.com/api/v1/sessionrecords/
{
"session": "5c2270e2-ad25-4d7f-a767-8a161169a112",
"organization_person": "2fab71d9-ebcf-49b9-83f4-771c6f29d8c0",
"program_name": "Name of the program", "completion_date": "2018-08-01",
"status": "Passed with custom credit",
"auto_create_earned_credits": true,
"session_record_topic_areas": [
{
"topic_area": "f2d99c7d-533f-4394-acb8-e9da9e1d6eb9", <UUID of topic area>
"credit_minutes": 50.0,
"delivery_method": "f871ae87-b7f5-4c21-a41a-33ef1443f781" <UUID for Delivery Method>
},
{
"topic_area": "3caf78fa-0ebe-4ba2-a9f8-751f9819e962",
"credit_minutes": 50.0,
"delivery_method": "f871ae87-b7f5-4c21-a41a-33ef1443f781"
}
]
}
PATCH - Full credit https://acme.lcvista.com/api/v1/sessionrecords/<session record UUID>/
{
"completion_date": "2018-08-02",
"status": "Passed with full credit",
"auto_create_earned_credits": true
}
PATCH - Partial credit https://acme.lcvista.com/api/v1/sessionrecords/<session record UUID>/
{
"completion_date": "2018-08-01",
"status": "Passed with custom credit",
"auto_create_earned_credits": true,
"session_record_topic_areas": [
{
"topic_area": "f2d99c7d-533f-4394-acb8-e9da9e1d6eb9",
"credit_minutes": 50.0,
"delivery_method": "f871ae87-b7f5-4c21-a41a-33ef1443f781"
},
{
"topic_area": "3caf78fa-0ebe-4ba2-a9f8-751f9819e962",
"credit_minutes": 50.0,
"delivery_method": "f871ae87-b7f5-4c21-a41a-33ef1443f781"
}
]
}
▲ Return to the table of contents
Issuing Credit Workflow: Example: Create or Update a SessionRecord - Instructor Credit
Issuing instructor credit is similar to participation credit with a few exceptions. First all instructor credit needs to be passed with a status of Passed with custom credit.
Second you will need to change the delivery method of the credit. Instead of passing the session delivery method you will need to provide the delivery method Teaching and/or Teaching (prep) for the credits earned.
NOTE - The Teaching and Teaching (prep) delivery methods should only be used on the SessionRecord. Sessions should not be created with these delivery methods.
XML
GET- The UUIDs of the Teaching and Teaching (prep) credits. https://acme.lcvista.com/api/v1/deliverymethods/
{
"url": "https://acme.lcvista.com/api/v1/deliverymethods/a442ae89-1f1f-4583-a57d-5c64485985ff/",
"id": "a442ae89-1f1f-4583-a57d-5c64485985ff",
"name": "Teaching",
"is_launchable": false,
"is_live_integration_allowed": false,
"display_order": 14,
"type": "instruction"
},
{
"url": "https://acme.lcvista.com/api/v1/deliverymethods/1f15bbcb-93cd-443e-8783-820802d1a137/",
"id": "1f15bbcb-93cd-443e-8783-820802d1a137",
"name": "Teaching (prep)",
"is_launchable": false,
"is_live_integration_allowed": false,
"display_order": 100,
"type": "prep"
}
GET - check if sessionrecord already exists
https://acme.lcvista.com/api/v1/sessionrecords/?organization_person=93389760-f28d-432c-92fd-b62aa9913c32&session=2d9a73d9-f985-47b8-a4a1-a98df877a707
if record doesn't exist POST
Required Fields: session, organization_person, program_name, completion_date, status, auto_create_earned_credits, session_record_topic_areas
Note on status:
Teaching and prep credit are always issued with a status of Passed with custom credit.
POST - Teaching credit (without prep credit) https://acme.lcvista.com/api/v1/sessionrecords/
{
"session": "5c2270e2-ad25-4d7f-a767-8a161169a112",
"organization_person": "2fab71d9-ebcf-49b9-83f4-771c6f29d8c0",
"program_name": "Name of the program", "completion_date": "2018-08-01",
"status": "Passed with custom credit",
"auto_create_earned_credits": true,
"session_record_topic_areas": [
{
"topic_area": "f2d99c7d-533f-4394-acb8-e9da9e1d6eb9", <UUID of topic area>
"credit_minutes": 50.0,
"delivery_method": "a442ae89-1f1f-4583-a57d-5c64485985ff" <UUID for Delivery Method Teaching>
},
{
"topic_area": "3caf78fa-0ebe-4ba2-a9f8-751f9819e962",
"credit_minutes": 50.0,
"delivery_method": "a442ae89-1f1f-4583-a57d-5c64485985ff" <UUID for Delivery Method Teaching>
}
]
}
POST - Teaching credit and prep credit. Prep credit is often 2 times the teaching credit.
https://acme.lcvista.com/api/v1/sessionrecords/
{
"session": "5c2270e2-ad25-4d7f-a767-8a161169a112",
"organization_person": "2fab71d9-ebcf-49b9-83f4-771c6f29d8c0",
"program_name": "Name of the program", "completion_date": "2018-08-01",
"status": "Passed with custom credit",
"auto_create_earned_credits": true,
"session_record_topic_areas": [
{
"topic_area": "f2d99c7d-533f-4394-acb8-e9da9e1d6eb9", <UUID of topic area>
"credit_minutes": 50.0,
"delivery_method": "a442ae89-1f1f-4583-a57d-5c64485985ff" <UUID for Delivery Method Teaching>
},
{
"topic_area": "3caf78fa-0ebe-4ba2-a9f8-751f9819e962",
"credit_minutes": 50.0,
"delivery_method": "a442ae89-1f1f-4583-a57d-5c64485985ff" <UUID for Delivery Method Teaching>
},
{
"topic_area": "f2d99c7d-533f-4394-acb8-e9da9e1d6eb9", <UUID of topic area>
"credit_minutes": 100.0,
"delivery_method": "1f15bbcb-93cd-443e-8783-820802d1a137" <UUID for Delivery Method Prep>
},
{
"topic_area": "3caf78fa-0ebe-4ba2-a9f8-751f9819e962",
"credit_minutes": 100.0,
"delivery_method": "1f15bbcb-93cd-443e-8783-820802d1a137" <UUID for Delivery Method Prep>
}
]
}
PATCH - Teaching and prep credit
https://acme.lcvista.com/api/v1/sessionrecords/<session record UUID>/
{
"completion_date": "2018-08-01",
"status": "Passed with custom credit",
"auto_create_earned_credits": true,
"session_record_topic_areas": [
{
"topic_area": "f2d99c7d-533f-4394-acb8-e9da9e1d6eb9", <UUID of topic area>
"credit_minutes": 50.0,
"delivery_method": "a442ae89-1f1f-4583-a57d-5c64485985ff" <UUID for Delivery Method Teaching>
},
{
"topic_area": "3caf78fa-0ebe-4ba2-a9f8-751f9819e962",
"credit_minutes": 50.0,
"delivery_method": "a442ae89-1f1f-4583-a57d-5c64485985ff" <UUID for Delivery Method Teaching>
},
{
"topic_area": "f2d99c7d-533f-4394-acb8-e9da9e1d6eb9", <UUID of topic area>
"credit_minutes": 50.0,
"delivery_method": "1f15bbcb-93cd-443e-8783-820802d1a137" <UUID for Delivery Method Prep>
},
{
"topic_area": "3caf78fa-0ebe-4ba2-a9f8-751f9819e962",
"credit_minutes": 50.0,
"delivery_method": "1f15bbcb-93cd-443e-8783-820802d1a137" <UUID for Delivery Method Prep>
}
]
}
▲ Return to the table of contents
Issuing Credit Workflow: Example: Override Default Credit Issued by LCvista
Discuss this scenario with your LCvista account manager before moving forward. This is a workflow that is not regularly required and is only used occasionally for specific requirements.
The following scenario provides an example of how you can override credit for a specific jurisdiction. This workflow will modify the default credits issued and allow you to issue specific credits in a specific jurisdiction.
An example of why you may want to do this is, as a business you want to issue Yellow Book credit to any program where the program name contains "Yellow Book".
Step 1: Get the jurisdiction details for the credits you would like to override
XML
GET - get the jurisdiction IDs for the jurisdictions to be overridden https://acme.lcvista.com/api/v1/jurisdictions/
Here is an example of overriding credits for EBP, SEC Consent, Tax Practice Policy and Yellow Book
{
"url": "https://acme.lcvista.com/api/v1/jurisdictions/c770ca24-48ce-11e8-842f-0ed5f89f718b/",
"id": "c770ca24-48ce-11e8-842f-0ed5f89f718b",
"name": "AICPA EBPAQC",
"slug": "aicpa-ebpaqc-rolling", ...
},
{
"url": "https://acme.lcvista.com/api/v1/jurisdictions/269d2ef3-1ca5-4bbd-8a58-68f9fbbb12bd/",
"id": "269d2ef3-1ca5-4bbd-8a58-68f9fbbb12bd",
"name": "2018 SEC Consent", "slug": "2018-sec-consent", ...
},
{
"url": "https://acme.lcvista.com/api/v1/jurisdictions/0a9322c8-cb49-403a-b0cf-86cad9aefde8/",
"id": "0a9322c8-cb49-403a-b0cf-86cad9aefde8",
"name": "Tax Practice Policy 1.7.2", "slug": "tax-practice-policy-1.7.2", ...
},
{
"url": "https://acme.lcvista.com/api/v1/jurisdictions/10181a03-8573-4978-b168-572e6ec2c691/",
"id": "10181a03-8573-4978-b168-572e6ec2c691",
"name": "Yellow Book",
"slug": "yellow-book-rolling", ...
}
GET - jurisdiction delivery methods for the jurisdictions that you will be overriding
- There is no filter option by jurisdiction so you will need to load all delivery methods and find the delivery method required for the update by filtering on jurisdiction UUID
https://acme.lcvista.com/api/v1/jurisdictiondeliverymethods/
GET - jurisdiction fields of study for the jurisdictions that you will be overriding
- There is no filter option by jurisdiction so you will need to load all fields of study and find the FOS required for the update by filtering on jurisdiction UUID
https://acme.lcvista.com/api/v1/fieldsofstudy/
Step 2: Find the specific session record to be overridden and then override the credits
XML
GET - get the existing SessionRecord UUID (SessionRecord must exist before issuing credit)
https://acme.lcvista.com/api/v1/sessionrecords/?organization_person=93389760-f28d-432c-92fd-b62aa9913c32&session=2d9a73d9-f985-47b8-a4a1-a98df877a707
PATCH - Update the session record status to "Passed with custom credit" to indicate the credit will be overwritten https://acme.lcvista.com/api/v1/sessionrecords/<session record UUID>/
{
"status": "Passed with custom credit"
}
PATCH - Update the earned credits for the specific jurisdiction field of study required
- This PATCH requires that you provide the field_of_study and jurisdiction delivery_method for the credits. Jurisdiction DeliveryMethod is different than the session DeliveryMethod. It is a jurisdiction specific delivery_method. In addition, we require the jurisdiction UUID in a separate fie - as a confirmation that credits for this jurisdiction will be fully overwritten by this call.
https://acme.lcvista.com/api/v1/sessionrecordjurisdictioncredits/<UUID for Session Record>/
{
"earned_credits": [
{
"field_of_study": "<UUID for the Jurisdiction Field of Study>",
"delivery_method": "<UUID for the Jurisdiction Delivery Method>",
"credit_minutes": 50.0
},
{
"field_of_study": "<UUID for the Jurisdiction Field of Study>",
"delivery_method": "<UUID for the Jurisdiction Delivery Method>",
"credit_minutes": 50.0
}
],
"jurisdictions": ["<UUID for the Jurisdiction>"]
}
▲ Return to the table of contents
Issuing Credit Workflow: Example: Technical Reviewer Credit
The following example highlights how to issue technical reviewer credit. Please note in a select few jurisdictions, a technical reviewer can receive CPE credit for completing the review, similar to how an instructor receives credit.
GET - check if sessionrecord already exists
https://acme.lcvista.com/api/v1/sessionrecords/?organization_person=93389760-f28d-432c-92fd-b62aa9913c32&session=2d9a73d9-f985-47b8-a4a1-a98df877a707
if record doesn't exist POST
Required Fields: session, organization_person, program_name, completion_date, status, auto_create_earned_credits, session_record_topic_areas
POST - Technical Review credit https://acme.lcvista.com/api/v1/sessionrecords/
{
"completion_date": "2015-08-01",
"session": "84f50260-753f-4f33-8e21-ff726ae10c32",
"program_name": "Tax Services: 179D",
"organization_person": "4aac4126-54d5-48b1-ae7e-689920c0ac90",
"status": "Passed with Technical Review credit",
"auto_create_earned_credits": true,
"session_record_topic_areas": [
{
"topic_area": "c9e4b75a-071f-4451-b2f0-999e22d0a4f6", # Topic Area UUID
"delivery_method": "01929755-ee9a-42d1-856b-64aef6e21652", # Delivery Method UUID
"credit_minutes": 50.0
}
]
}
PATCH - Technical Review credit https://acme.lcvista.com/api/v1/sessionrecords/<session-record-id>
{
"completion_date": "2018-08-01",
"status": "Passed with Technical Review credit",
"session_record_topic_areas": [
{
"topic_area": "c9e4b75a-071f-4451-b2f0-999e22d0a4f6", <UUID of topic area>
"delivery_method": "01929755-ee9a-42d1-856b-64aef6e21652", <UUID for Technical Review Delivery Method>
"credit_minutes": 50.0
}
]
}
▲ Return to the table of contents
Overall Compliance Report (Read Only)
The overallcompliance endpoint provides a method for retrieving summary compliance data from your site for a specified period (Current Period, Previous Period, etc.).
This is essentially the same data that is on the Overall Compliance report that you can run from our Reports menu. The endpoint returns a JSON structured dataset.
Definition of Data Returned
reporting period (start_date, end_date, extended_date)
earned (total credit minutes a user has earned in this period)
applied (total credit minutes that were counted towards a specific jurisdiction)
overall_deficit (summary of credit minutes remaining to be in compliance per the overall requirement)
overall_applied (summary of credit minutes applied to the jurisdiction per the overall requirement)
latest_annual_period - is a summary of data as it relates to the current annual period (if applicable)
Endpoint Options and Example
Allowed filters
reporting_period: int (default 0) (0 = current period, 1 = previous period, 2 = previous, previous period)
username: str
username_in: {str}{,str}*
jurisdiction: {str}
jurisdiction_in: {str}{,str}*
status: {Active|Inactive}
include_custom_fields: {True|False}
Paging
_limit: int (default 1000, max 4000)
_offset: int (default 0)
Example:
https://acme.lcvista.com/api/v1/overallcompliance/?jurisdiction=Michigan&status=Active&include_custom_fields=True&_limit=1&_offset=1
Response type: json
{
"count": 7,
"next": null,
"previous": null,
"results": [
{
"id": "06de1d41-79bb-4fea-8065-a5afeb97bbe8",
"jurisdiction": {
"id": "31ac27ad-0bbd-4ce2-bc99-9256490d015b",
"name": "PCAOB",
"slug": "pcaob-rolling"
},
"organization_person": {
"id": "7ff3b32b-aa28-4a42-9101-ab333d5d8758",
"custom_fields": {},
"person": { "id": "0e30ec4f-d95f-4dcf-8c67-a384e40b23d9",
"username": "admin@lcvista.com",
"first_name": "Admin",
"last_name": "LCVista",
"email": "support@lcvista.com"
}
},
"is_primary": false,
"status": "active",
"in_compliance": false,
"start_date": "2018-01-01",
"end_date": "2020-12-31",
"extended_date": "2020-12-31",
"earned": 1950.0,
"applied": 1950.0,
"overall_deficit": 4050.0,
"overall_applied": 1950.0,
"carry_over": 0.0,
"license_id": "123",
"latest_annual_period": {
"id": "5c62b297-a1de-4144-a4fe-83ba5c43d68b",
"in_compliance": true,
"start_date": "2020-01-01",
"end_date": "2020-12-31",
"extended_date": "2020-12-31",
"earned": 1950.0,
"applied": 1950.0,
"overall_applied": 1950.0,
"overall_deficit": 0,
"carry_over": 0.0
}
},
{
"id": "169db472-a28b-4ae2-92d6-f5f2b38dbbc0",
"jurisdiction": {
"id": "31ac27ad-0bbd-4ce2-bc99-9256490d015b",
"name": "PCAOB",
"slug": "pcaob-rolling"
},
"organization_person": { "id": "a7ef94ec-3dfd-4d28-bf40-ca3c21e1ab91",
"custom_fields": {},
"person": {
"id": "db3e6654-42c2-456f-844a-d7d87b0c8f47",
"username": "0030577",
"first_name": "Michele",
"last_name": "Simovski",
"email": "msimovski@demo.com"
}
},
"is_primary": false,
"status": "active",
"in_compliance": false,
"start_date": "2018-01-01",
"end_date": "2020-12-31",
"extended_date": "2020-12-31",
"earned": 0.0,
"applied": 0.0,
"overall_deficit": 6000.0,
"overall_applied": 0,
"carry_over": 0.0,
"license_id": "",
"latest_annual_period": {
"id": "4a7c0cc5-f290-417a-8b8d-b9bac5492dce",
"in_compliance": false,
"start_date": "2020-01-01",
"end_date": "2020-12-31",
"extended_date": "2020-12-31",
"earned": 0.0,
"applied": 0.0,
"overall_applied": 0,
"overall_deficit": 1000.0,
"carry_over": 0.0
}
},
{
"id": "2635c85b-5d88-4374-86f6-751c9fe40daf",
"jurisdiction": {
"id": "31ac27ad-0bbd-4ce2-bc99-9256490d015b",
"name": "PCAOB",
"slug": "pcaob-rolling"
},
"organization_person": { "id": "1689d86e-92f2-44fe-8de3-6bc52c579703",
"custom_fields": {},
"person": {
"id": "a660660c-885f-4691-9d30-41d3f446c2b8",
"username": "10001552",
"first_name": "Cindy",
"last_name": "Allen",
"email": "CAllen@demo.com"
}
},
"is_primary": false,
"status": "active",
"in_compliance": false,
"start_date": "2018-01-01",
"end_date": "2020-12-31",
"extended_date": "2020-12-31",
"earned": 0.0,
"applied": 0.0,
"overall_deficit": 6000.0,
"overall_applied": 0,
"carry_over": 0.0,
"license_id": "",
"latest_annual_period": {
"id": "78522370-3961-46be-9e0d-f9c878bd83f8",
"in_compliance": false,
"start_date": "2020-01-01",
"end_date": "2020-12-31",
"extended_date": "2020-12-31",
"earned": 0.0,
"applied": 0.0,
"overall_applied": 0,
"overall_deficit": 1000.0,
"carry_over": 0.0
}
},
{
"id": "2a5374d8-bc7a-4444-a5a1-e3e799d4eed0", "jurisdiction": {
"id": "31ac27ad-0bbd-4ce2-bc99-9256490d015b",
"name": "PCAOB",
"slug": "pcaob-rolling"
},
"organization_person": { "id": "e522ba2d-f1f6-4060-9ac1-582b377149b6",
"custom_fields": {},
"person": {
"id": "202ea2de-923a-4bee-a500-fd63e39e5af2",
"username": "10001178",
"first_name": "Richard",
"last_name": "Haan",
"email": "rhaan@demo.com"
}
},
"is_primary": false,
"status": "active",
"in_compliance": false,
"start_date": "2018-01-01",
"end_date": "2020-12-31",
"extended_date": "2020-12-31",
"earned": 0.0,
"applied": 0.0,
"overall_deficit": 6000.0,
"overall_applied": 0,
"carry_over": 0.0,
"license_id": "",
"latest_annual_period": {
"id": "68268465-7486-4170-9c8d-335d822f4682",
"in_compliance": false,
"start_date": "2020-01-01",
"end_date": "2020-12-31",
"extended_date": "2020-12-31",
"earned": 0.0,
"applied": 0.0,
"overall_applied": 0,
"overall_deficit": 1000.0,
"carry_over": 0.0
}
},
{
"id": "85a3f9a0-1543-44e7-baba-033579d0c50c",
"jurisdiction": {
"id": "31ac27ad-0bbd-4ce2-bc99-9256490d015b",
"name": "PCAOB",
"slug": "pcaob-rolling"
},
"organization_person": { "id": "2054d37f-8336-43ce-b6d4-f5d72a8acdb4",
"custom_fields": {},
"person": {
"id": "56b15cb6-0952-465b-bb33-9d9768957538",
"username": "0020662",
"first_name": "Isabel",
"last_name": "Silva Aldridge",
"email": "ISilva@demo.com"
}
},
"is_primary": false,
"status": "active",
"in_compliance": false,
"start_date": "2018-01-01",
"end_date": "2020-12-31",
"extended_date": "2020-12-31",
"earned": 0.0,
"applied": 0.0,
"overall_deficit": 6000.0,
"overall_applied": 0,
"carry_over": 0.0,
"license_id": "",
"latest_annual_period": {
"id": "b53a1b1b-3d99-414c-92ad-d7a1421cf4ab",
"in_compliance": false,
"start_date": "2020-01-01",
"end_date": "2020-12-31",
"extended_date": "2020-12-31",
"earned": 0.0,
"applied": 0.0,
"overall_applied": 0,
"overall_deficit": 1000.0,
"carry_over": 0.0
}
},
{
"id": "92f767ee-820e-404d-a95f-5a7ca308e723",
"jurisdiction": {
"id": "31ac27ad-0bbd-4ce2-bc99-9256490d015b",
"name": "PCAOB",
"slug": "pcaob-rolling"
},
"organization_person": { "id": "50701a98-a6b2-4d84-8ec9-21541deae67f",
"custom_fields": {},
"person": {
"id": "edfcfda5-6a46-4c30-80b5-8e320d01569a",
"username": "10000676",
"first_name": "Tracey",
"last_name": "Waite",
"email": "TWaite@demo.com"
}
},
"is_primary": false,
"status": "active",
"in_compliance": false,
"start_date": "2018-01-01",
"end_date": "2020-12-31",
"extended_date": "2020-12-31",
"earned": 0.0,
"applied": 0.0,
"overall_deficit": 6000.0,
"overall_applied": 0,
"carry_over": 0.0,
"license_id": "",
"latest_annual_period": {
"id": "962dfbef-a017-45df-b9be-c8a5825fc744",
"in_compliance": false,
"start_date": "2020-01-01",
"end_date": "2020-12-31",
"extended_date": "2020-12-31",
"earned": 0.0,
"applied": 0.0,
"overall_applied": 0,
"overall_deficit": 1000.0,
"carry_over": 0.0
}
},
{
"id": "b4d9a616-038a-47a7-aa75-41076ab0d21c",
"jurisdiction": {
"id": "31ac27ad-0bbd-4ce2-bc99-9256490d015b",
"name": "PCAOB",
"slug": "pcaob-rolling"
},
"organization_person": { "id": "2fa8e13c-784f-4195-9247-5e2bf0105357",
"custom_fields": {},
"person": {
"id": "0727489e-0116-40d3-bb5b-128d4ef2c534",
"username": "0030326",
"first_name": "Jason",
"last_name": "Rhodes",
"email": "jrhodes@demo.com"
}
},
"is_primary": false,
"status": "active",
"in_compliance": false,
"start_date": "2018-06-04",
"end_date": "2020-12-31",
"extended_date": "2020-12-31",
"earned": 0.0,
"applied": 0.0,
"overall_deficit": 2000.0,
"overall_applied": 0,
"carry_over": 0.0,
"license_id": "",
"latest_annual_period": {
"id": "fc4ac194-eba0-4846-92aa-63b0aa68004f",
"in_compliance": false,
"start_date": "2020-01-01",
"end_date": "2020-12-31",
"extended_date": "2020-12-31",
"earned": 0.0,
"applied": 0.0,
"overall_applied": 0,
"overall_deficit": 1000.0,
"carry_over": 0.0
}
}
]
}
▲ Return to the table of contents
Common Lookup Endpoints
In the above documentation there are endpoint domain attributes that require a UUID. Here we will list some of the common endpoints that can be used to lookup UUID of the domain values.
It is possible to either do a lookup for each individual record in your data workflow or it is also common practice to load the domain values into a lookup dictionary one time at the beginning of the data workflow and keep these values in memory.
The following endpoints are all located at the standard URL /api/v1/<endpoint name>/ and available in the browsable API interface.
|
Endpoint |
Notes |
|
catalogs |
List the catalog names and each programs associated to a catalog |
|
certificatetemplate |
List the certificate templates available on your site to associate to a session for autogenerated certificates |
|
deliverymethods |
List the available NASBA delivery methods for use when creating a session. Note that only deliverymethods with a type of prep and instruction cannot be used when creating a session. |
|
fieldsofstudy |
List the Jurisdiction FieldOfStudy available to use when overriding credit. It is very uncommon for jurisdiction credit to be overridden in an API feed. Please consult LCvista before attempting to integrate credit overrides in an API feed. |
|
jurisdictions |
List the jurisdictions available on your site |
|
organizations |
Get your site organization id |
|
qualifications |
Get the list of jurisdiction credit qualifications that can be set at the program level. |
|
sponsors |
Get the list of sponsor available on your site |
|
topicareas |
Get the list of NASBA fields of study available to issue credit on the program and session record |
|
venues |
Get the list of available venues on your site |
▲ Return to the table of contents
FAQ
Frequently asked questions
▲ Return to the table of contents
FAQ: Cross Site Forgery (CSRF)
CSRF check is disabled when using token authentication. If you receive a CSRF error it is likely due to an incorrect URL. Be sure that URLs end with “/”.
▲ Return to the table of contents
FAQ: Timestamp Formatting
LCvista stores timestamps internally as UTC time. LCvista will display timestamps based on the time zone setting of the user's browser. Most scripting languages have built-in functions to handle time conversions, but you must ensure that your timestamp values have been correctly formatted to UTC before passing to an endpoint. There are two options for formatting timestamps in UTC when passing to an endpoint:
Raw UTC time with no offset provided
2019-01-08T19:00:00.000Z
Timestamp including the timezone offset
2019-01-07T13:00:00-06:00
▲ Return to the table of contents
FAQ: Postman Collections
LCvista has a collection of Postman calls to provide an idea of how to interact with API endpoints. The collection includes common functionality used by clients loading data to LCvista and are attached to this guide for download. You can download Postman at https://www.getpostman.com/ (https://www.getpostman.com/).
There are two variables that need to be set in the attached collection in order to work on your site. You will need to set the site_url_slug to your site specific URL.
For example, the site https://acme.lcvista.com (https://acme.lcvista.com) has a site_url_slug of acme. You will need to set the site_token to the token generated on your lcvista.com site.