Hi! Welcome to the HAPID API documentation. This documentation is meant for external developers that will interact with HAPID and will provide you with everything you need to know in order to create great applications.
Here is a model that provides a high-level overview of objects and their relationships.
Here we are going to show you how to utilize the 3 legged authorization process.
The three-legged OAuth process (3LO) in HAPI-D is used to grant an application the necessary permissions to access data on behalf of the user without revealing the user's credentials to the application. The three "legs" represent the three parties involved in the process: the user, the application, and the HAPI-D platform. This process makes use of authenticate_code
to ensure secure access to the user's data.
You will need to obtain a <client_id>
and '
This document summarizes the three-legged OAuth process for applications interested in API integration with HAPI-D. For complete documentation of the Oauth 2.0 implementation, please review the documentation found on the Salesforce Help Site
The 3LO process consists of the following steps:
Your application should redirect the user to HAPI-D authorization endpoint. The URL should be of the following format:
https://ncoa1.my.site.com/services/oauth2/authorize?
https://ncoa1--<environment>.sandbox.my.site.com/services/oauth2/authorize?
And is required to have the following URL parameters:
response_type=code&
client_id=<client_id>&
redirect_uri=<redirect_uri>
The optional URL parameter below is recommended and used to implement PKCE.
code_challenge=<SHA256 hash value of the code_verifier>
<client_id>
: Your application's client ID.<redirect_uri>
: The URI where Salesforce should redirect the user after authorization.<SHA256 hash value of the code_verifier>
: Specifies the SHA256 hash value of the code_verifier value in the token request. Set this parameter to help prevent authorization code interception attacks. The value must be base64url-encoded.After users approve access to the app, HAPI-D redirects users to the callback URL (<redirect_uri>
), where they can view the callback with an authorization code.
The first part of the callback is the connected app's callback URL: <redirect_uri>
. The second part is the authorization code that the connected app uses to get an access token: code=<authorization code>
. The authorization code expires after 15 minutes.
The application can now exchange the authorization code for an access token by sending a POST request to the HAPI-D token request endpoint.
https://ncoa1.my.site.com/services/oauth2/token
https://ncoa1--<environment>.sandbox.my.site.com/services/oauth2/token
The request should include the following URL parameters:
grant_type
: Set this to authorization_code
.client_id
: Your application's client ID.client_secret
: Your application's client secret.code
: The authorization code you received in step 2.redirect_uri
: The same redirect URI used during user authorization.code_verifier
: Required only if a code_challenge parameter was specified in the authorization request. Specifies 128 bytes of random data with high entropy to make guessing the code value difficult. Set this parameter to help prevent authorization code interception attacks. The value must be base64url-encoded.If the request is successful, the response will be a JSON object containing an access_token
, refresh_token
and a id
. An example of the Id response can be seen below.
Once the application has the access token, it can use it to authenticate requests to Salesforce's API.
To use the access token, include it in the Authorization
header of the HTTP request. The header should look like:
Authorization: Bearer <access_token>
For example, to use the access token to query data, you could make a GET request to the query
endpoint like so:
GET /services/data/v50.0/query?q=SELECT+name,id+FROM+Account
Host: ncoa1.my.site.com
Authorization: Bearer <access_token>
To interact with the sObject API, you could make a GET request to the sobjects
endpoint like so:
GET /services/data/v50.0/sobjects/Account/<id>
Host: ncoa1.my.site.com
Authorization: Bearer <access_token>
Remember to replace <access_token>
with your actual access token in each of the above examples. If using a sandbox, remember to use the correct host for your environment in the format ncoa1--<environment>.sandbox.my.site.com
Your app can use the refresh token to get a new access token by sending the following refresh token POST requests to the HAPI-D token endpoint: /services/oauth2/token
.
POST /services/oauth2/token HTTP/1.1
Host: ncoa1.my.site.com
grant_type=refresh_token&
client_id=<client_id>&client_secret=<client_secret>&
refresh_token=<refresh_token>
If using a sandbox, remember to use the correct host for your environment in the format ncoa1--<environment>.sandbox.my.site.com
If the request is successful, the response will be a JSON object containing an access_token
.
Three-legged OAuth provides a secure and user-friendly way for your application to access a user's data on HAPI-D. By following the process outlined in this document, your application can get the necessary permissions to access and manipulate a user's HAPI-D data without ever needing to handle their HAPI-D credentials.
Step:1 If you logged in as a grantee:
Please follow the below process to identify your user details
API endpoint:
https://ncoa1--uat.sandbox.my.site.com/services/data/v59.0/query?q=Select+Id,+Username,+Lastname,+Firstname,+Email,+IsActive,+UserType,+EPD_Account_ID__c,+CompanyName+from+User+where+IsActive=true+and+Id='XXXXXXXXXXXXXX'
Replace ‘XXXXXXXXXXXXXX' with the ID that was saved with the Access token call (Authorization API) The response gives the ID, username, first and last names, email, and account ID of the user.
Step:2
If you logged in as a vendor or host organization:
Please follow the below process to identify your user details
API endpoint:
https://ncoa1--uat.sandbox.my.site.com/services/data/v59.0/query?q=Select+Id,+Username,+Lastname,+Firstname,+Email,+IsActive,+UserType,+EPD_Account_ID__c,+CompanyName+from+User+where+IsActive=true+and+Id='XXXXXXXXXXXXXX'
Replace ‘XXXXXXXXXXXXXX' with the ID that was saved with the Access token call (Authorization API) The response gives ID, Username, First and Last names, Email and account ID of the User
Step:3 Please follow the below process to identify the Grantee details from the Retrieve a Grantee to Host Organization
API endpoint:
https://ncoa1--uat.sandbox.my.site.com/services/data/v48.0/query?q=Select+Name,+Grantee__c,+Grantee_Name__c,+Host_Organization_Name__c,+Logged_in_User_at_Host_Org__c,+New_Account_Data__c,+Site_Type__c+from+epd_Grantee_to_Host_Organization__c+where+ Host_Organization__c=' 'XXXXXXXXXXXXXXX'
Replace ‘XXXXXXXXXXXXXXX’ with your Host organization ID or Account ID from the above step 2.
The Response gives Name, Grantee ID , Grantee name, Host organization name and Site type. If the Host organization is listed in the response, please select it and keep the ID ready to create the workshop or else, you can create one using Step 2 Adding a Host organization.
Step:4
If you are the Vendor but also a Grantee with NCOA, please follow the process outlined in Step 1 above.
A Workshop is the key object that links Programs, Program Targets, Grantee, Host Organization, Implementation Sites, and Facilitator with Participant pre and post survey data. It will also hold key aggregate information from the Participants related to the Workshop.
This is a step-by-step guide to creating a new Workshop.
In order to create a Workshop, you must first find or create the following.
Use this API call to query the list of Host Organizations. From there, filter the results based on the Name or Id of your Organization.
GET https://ncoa1--uat.sandbox.my.site.com/services/data/v48.0/query?q=select Name,+BillingStateCode,+BillingCity,+Host_Organization__c+from+Account+where+Host_Organization__c+in+('Validated','Unvalidated')
The response gives the Account Name, Billing state code, City. If the Host organization is listed in the response, please select it and keep the ID ready for to create the workshop or else, you can create one.
If your Organization is not found, you can add it using the following API endpoint and request body with your organization's information. You can find allowable values for Site_Type__c
here.
POST https://ncoa1--uat.sandbox.my.site.com/services/data/v54.0/sobjects/Account
{
"Name": "Your Account Name",
"Site_Type__c": "Your Site Type",
"BillingCity": "Your City",
"BillingStreet": "Your Street Address",
"BillingState": "Your State",
"BillingPostalCode": "Your Postal Code"
}
If the Host Organization was successfully created, an Id
will be generated and the response will look similar to this:
{
"id": "001DG00001d2li0YER",
"success": true,
"errors": []
}
Use this API call to query the list of Implementation Sites to find yours:
GET https://ncoa1--uat.sandbox.my.site.com/services/data/v48.0/query?q=Select+id+,+City__c+,+Street__c+,+state__c+,+Name+FROM+epd_implementation_site__c+WHERE+Id+=+implementationSiteId
The response gives the Implementation Site Name, ID, City, Street and State. If the implementation site is listed in the response, please select the respective ID for workshop creation or else, you can create one.
If your Implementation Site is not listed, use the following API endpoint and request body to create one with your information. You can find allowable values for Site_Type__c
here.
POST https://ncoa1--uat.sandbox.my.site.com/services/data/v54.0/sobjects/epd_Implementation_Site__c
{
"Name": "Your Implementation Site Name",
"Site_Type__c": "Your Site Type",
"City__c": "Your City",
"Street__c": "Your Street Address",
"State__c": "Your State",
"Zipcode__c": "Your Zip Code"
}
If creating an Implementation Site was successful, an Id
will be generated and the response will look similar to this:
{
"id": "a0rDG000005N563TRE",
"success": true,
"errors": []
}
Use the following API call to query the list of Programs to find yours. Use either Type_of_Program__c='CDSME'
or Type_of_Program__c='Falls+Prevention'
to filter on the CDSME and Falls Prevention program types respectively.
GET https://ncoa1--uat.sandbox.my.site.com/services/data/v48.0/query?q=select+Id+,+Name+FROM+epd_NCOA_Program__c+WHERE+Active__c='Active'+and+Type_of_Program__c='Falls+Prevention'
The response returns the Id
and Name
values for all the active programs based on the program filters. You will be able to select one from the list.
Use the following API call to find your Program Target. Replace Program__c+=+'XXXXXXXXXX'
with the Program Id from the previous step.
GET https://ncoa1--uat.sandbox.my.site.com/services/data/v48.0/query?q=select+id,+Funding_Source__c,+Program_Target_Search_TEXT__c,+Funding_Source_Name__C,+Program__c,+Record_Type_Name__c,+Survey_Template__c,+Survey_Template_TEXT__c+from+epd_Program_Target__c+where+Program__c+=+’XXXXXXXXXX’+and+Record_Type_Name__c+in+('Program+Specific','Collective')
The Response gives ID, Funding source ID, Funding Source Name, Survey template ID and description details. Select and make a note of the appropriate Funding source and Program target and make a note of the ID, Funding source ID for future steps.
Use the following API call to find your Survey Template. Replace ID=’XXXXXXXXXX’
with the Survey Template Id from the previous step.
GET https://ncoa1--uat.sandbox.my.site.com/services/data/v48.0/query?q=select+id,+Name,+End_Date__c,+Program_Type__c,+Start_Date__c,+Template_Name__c+From+epd_Survey_Template__c+where+ID=’XXXXXXXXXX’+and+End_Date__c+=+null
The Response gives the ID, Survey Template Name, Program type, Start Date of the survey template. Make a note of Survey template ID for Workshop creation.
In order to find the existing facilitators, Please use the below API :
GET https://ncoa1--uat.sandbox.my.site.com/services/data/v48.0/query?q=select+id,+Contact__c,+First_Name__c,+Last_Name__c,+Email__c,+Active__c+FROM+epd_Facilitator__c+where+Active__C='Active'
The response gives the ID, Contact ID, First and Last name, Email ID . If the Facilitator is listed in the response, please select it or else, you can create a Contact and then a Facilitator as per Step 12.
Create a Workshop:
If the Facilitator exists in HAPI Database: After the Workshop is created, please proceed with adding the workshop details to epd_workshop_to_target__c and epd_Facilitator__c objects as per Steps: 9, 11.
If the Facilitator DOES NOT exist in HAPI Database:
After the Workshop is created, please proceed with adding epd_workshop_to_target__c objects. Them, Create a Contact and add workshop and contact details to epd_Facilitator__c.
API Call:
POST https://ncoa1--uat.sandbox.my.site.com/services/data/v54.0/sobjects/epd_Workshop__c
Sample Request Body:
{
"Host_Organization__c": "0013i000036abWdAAI",
"Implementation_Site__c": "a0r3i000003k1HoAAI",
"Program_Type__c": "Falls Prevention",
"NCOA_Program__c": "a0s3i00000BdcvqAAB",
"Program_Delivery__c": "In-person",
"Workshop_Start_Date__c": "2023-10-01",
"Workshop_End_Date__c": "2023-10-04",
"Local_name_for_this_workshop_optional__c": "Sample",
"Workshop_Language__c": "English",
"Workshop_Language_Other__c": "",
"Session_0__c": "Yes",
"Fee__c": "20",
"Notes__c": "Thank you",
"Number_of_sessions__c": "2",
"Survey_Template__c": "a103i00000L6AayAAF"
}
Update workshop details to Workshop to Target object. Endpoint:
POST https://ncoa1--uat.sandbox.my.site.com/services/data/v54.0/sobjects/epd_workshop_to_target__c
Sample Request Body:
{
"Workshop__c": "a13DG0000089x7kYAA",
"Program_Target__c": "a0u3i00000BTUUcAAP"
}
Sample Response:
{
"id": "a12DG00000Ks93FYAR",
"success": true,
"errors": []
}
Please use the below endpoint and request body to create a new contact.
POST https://ncoa1--uat.sandbox.my.site.com/services/data/v54.0/sobjects/Contact
Sample Request body:
{
"Salutation": "Mr.",
"FirstName": "Maddy",
"MiddleName": "S",
"LastName": "Testing",
"Suffix": "Jr.",
"Email": "Maddy.testing@email.com",
"Title": "Facilitator",
"HasOptedOutOfEmail": "false",
"Employee_Type__c": "Volunteer",
"AccountId": "001DG00001d2li0YAA"
}
Title
can always be defaulted on Facilitator. AccountId
is a Host organization account that was selected or created in Step 1 or Step 2. Allowed values for Salutation
and Employee Type
are listed in the Appendix.
Sample Response:
{
"id": "003DG00003pFR4NHGT",
"success": true,
"errors": []
}
Once after creating a new Contact
, please proceed with creating a new Facilitator
.
Once after creating a new Contact, please proceed with creating a new Facilitator. Please use the endpoint below and request body to create a new Facilitator. Endpoint :
POST https://ncoa1--uat.sandbox.my.site.com/services/data/v54.0/sobjects/Contact
Sample Request body:
{
"Workshop__c": "a13DG0000089x7kYAA",
"Contact__c": "003DG00003pFSJmYAO",
"Active__c": "Active",
"Employment_Type__c": "Volunteer"
}
Sample Response:
{
"id": "a0nDG000004E6M9YAK",
"success": true,
"errors": []
}
The Participant record is a record of an individual participant attending the Workshop session(s). As some Grantees record Participant workshop data against the Participant rather than the Workshop - the record will have a field that can optionally be used to store a non-identifiable external Id for the Grantee supplying the data. If they choose they can then match back to the Participant at a later date. Additionally the relation between Participant and Workshop record is managed through the Workshop Participant Object.
The Participant record can not be deleted (unless a request goes to NCOA). The record can be marked as Active/Inactive. If a Participant or Participant data needs to be deleted, a support ticket should be raised and NCOA will delete as appropriate.
The Participant record will hold static survey data that does not change over time.
This is how to create a participant object.
Endpoint:
GET https://ncoa1--uat.sandbox.my.site.com/services/data/v48.0/query?q=select+id+,+Name+,+Participant_Name_ID__c+,+from+epd_Participant__c+where+Participant_External_ID__c='NeededId'__
Replace the NeededId with the External Id of the participant which we need.
Sample response:
{
"id": "string",
"Name": "string",
"Participant_Name_ID__c": "string"
}
If the Participant does not exist in the Hapi database , you will be able to add the same.
Endpoint:
POST https://ncoa1--uat.sandbox.my.site.com/services/data/v54.0/sobjects/epd_Participant__c/Participant_External_ID__c/{ExternalIdValue}
Replace the ExternalIdValue with the External Id of the participant.
Sample requestbody:
{
"id": "string",
"Name": "string",
"Participant_Name_ID__c": "string"
}
Sample Response:
{
"id": "001DG00001d2li0YER",
"success": true,
"errors": []
}
Endpoint:
GET https://ncoa1--uat.sandbox.my.site.com/services/data/v48.0/query?q=select+id,+Name,+End_Date__c,+Program_Type__c,+Start_Date__c,+Template_Name__c+From+epd_Survey_Template__c+where+ID='XXXXXXXXXX'+and+Start_Date__c+<=+2023-09-01+and+(End_Date__c+>=+2023-09-30+OR+ENd_Date__c=null)
Replace XXXXXXXXXX = Template ID from the selected workshop response.
Select
The Response gives ID, Survey template Name, Program type, Start Date of the survey template.
Make a note of Survey template ID to Retrieve the Questions in the next step.
{
"id": "string",
"Name": "string",
"Template_Name__c": "string",
"Start_Date__c": "string",
"End_Date__c": "string",
"Last_Workshop__c": "string",
"Program_Type__c": "string",
"Details__c": "string"
}
Endpoint:
GET https://ncoa1--uat.sandbox.my.site.com/services/data/v48.0/query?q=SELECT+Section_Name__c +,+id+from+epd_Survey_Section__c+Where+Survey_Template__c+=+'Tempalte Id'
Use the Template Id retrieved from the previous step
The Response gives ID, Section Names.
Select and make a note of the id for the section names that are needed. These will be used to retrieve question assignments and questions.
Sample response:
{
“Id”: “a0zDM000004O39LYAS” ,
"Section_Name__c": "Optional Items"
}
Endpoint:
GET https://ncoa1--uat.sandbox.my.site.com/services/data/v48.0/query?q=SELECT+id,+Question__r.API_Name__c,+Question__r.Custom_Label__c,+Question__r.Object_API_Name__c,+Question__r.Name,+Survey_Section__r.Section_Name__c+FROM+epd_Question_to_Survey_Section__c+WHERE+Survey_Template__c+=’TemplateID’
Use the Template Id retrieved from the above step
The Response gives ID, API name, Object API Name and Label.
Select and make a note of the Api Name of the field in which the answer is saved for the question, and the Api name of the Object where the field for the answer is located in. These both will help in retrieving the answers for the question for the given workshop participant.
Response Body:
{
“Id”: “string”
"API_Name__c": "string",
"Object_API_Name__c": "string",
"Custom_Label__c": "string",
“Name”: “string”,
“Section_Name__c”:”string”,
“Survey_Template__c”:”string”
}
Initial Step to fill the answers is to differentiate the questions from step8 according to the Object_API_Name__c
Based on object API name we will have 3 different objects to save the answers as per step 7,8,9
If the Workshop Participant does not exist in the Hapi database , you will be able to add the same.
Endpoint:
POST https://ncoa1--uat.sandbox.my.site.com/services/data/v54.0/sobjects/epd_Workshop_Participant__c/Import_ID__c/{WorkshopParticipantId}
Replace the ExternalIdValue with the Import Id of the participant
Use the Workshop__c value from the above
Use the Participant__c from Step1or2
USe the Survey_Template__c from workshop creation.
Use the type_of_program__c from workshop creation.
“Api name of Question to fill Answer”: “data type of the answer”
Here Api name of question comes from step8 API_Name__c field “data type of the answer” is value of the answer to the question
Sample requestbody:
{
"id": "string",
"Name": "string",
"Workshop__c": "string",
"Participant__c": "string",
"type_of_program__c": "string",
"survey_template__c": "string",
“Api name of Question to fill Answer”: “data type of the answer”,
“Api name of Question to fill Answer2”: “data type of the answer2”,
“Api name of Question to fill Answer3”: “data type of the answer3”
And so on as per the no of answers we have for the questions
}
Sample Response:
{
"id": "001DG00001d2li0YER",
"success": true,
"errors": []
}
https://ncoa1--uat.sandbox.my.site.com/services/data/v54.0/sobjects/epd_Participant__c/Participant_External_ID__c/{participantId}
Replace the participantId with the External Id of the participant
“Api name of Question to fill Answer”: “data type of the answer”
Here Api name of question comes from step6 API_Name__c field and “data type of the answer” is value of the answer to the question
Sample requestbody:
{
"id": "string",
"Name": "string",
"Participant_Name_ID__c": "string" ,
“Api name of Question to fill Answer”: “data type of the answer”,
“Api name of Question to fill Answer2”: “data type of the answer2”,
“Api name of Question to fill Answer3”: “data type of the answer3”
And so on as per the no of answers we have for the questions
}
Sample Response:
{
"id": "001DG00001d2li0YER",
"success": true,
"errors": []
}
https://ncoa1--uat.sandbox.my.site.com/services/data/v54.0/sobjects/epd_Survey_Answer__c/Import_ID__c/{externalId}
Replace the ExternalId with the Import_ID__c of the survey answer.
“Api name of Question to fill Answer”: “data type of the answer”
Here Api name of question comes from step8 API_Name__c field and “data type of the answer” is value of the answer to the question
Sample requestbody:
{
“Api name of Question to fill Answer”: “data type of the answer”,
“Api name of Question to fill Answer2”: “data type of the answer2”,
“Api name of Question to fill Answer3”: “data type of the answer3”
And so on as per the no of answers we have for the questions
}
**Sample Response: **
{
"id": "001DG00001d2li0YER",
"success": true,
"errors": []
}
https://ncoa1--uat.sandbox.my.site.com/services/data/v54.0/sobjects//{ObjectAPIName}/describe
Here Object API name is the variable which describes the custom object one of three below
Participant - epd_Participant__c
Survey answer - epd_Survey_Answer__c
Questions - epd_Question__c
All the fields pertaining to Workshop Participants , Participants and Questions objects can be referenced using the above link.
Object | API Name | Label | Field Name |
---|---|---|---|
Workshops | epd_Workshop__c | Workshop: Workshop Name | Name |
Workshops | epd_Workshop__c | Evidence-Based Program | NCOA_Program__c |
Workshops | epd_Workshop__c | Fee | Fee__c |
Workshops | epd_Workshop__c | Grantee | Grantee__c |
Workshops | epd_Workshop__c | Host Organization | Host_Organization__c |
Workshops | epd_Workshop__c | Program Delivery | Program_Delivery__c |
Workshops | epd_Workshop__c | Program Type | Program_Type__c |
Workshops | epd_Workshop__c | Session 0? | Session_0__c |
Workshops | epd_Workshop__c | Survey Template | Survey_Template__c |
Workshops | epd_Workshop__c | Variable Sessions | Number_of_Variable_Sessions__c |
Workshops | epd_Workshop__c | Workshop End Date | Workshop_End_Date__c |
Workshops | epd_Workshop__c | Workshop External ID | Workshop_External_ID__c |
Workshops | epd_Workshop__c | Workshop Language | Workshop_Language__c |
Workshops | epd_Workshop__c | Workshop Language Other | Workshop_Language_Other__c |
Workshops | epd_Workshop__c | Workshop Start Date | Workshop_Start_Date__c |
Workshops | epd_Workshop__c | Workshop Type Other | Workshop_Type_Other__c |
Facilitators | epd_Facilitator__c | Account Name: Account Name | AccountId |
Facilitators | epd_Facilitator__c | Workshop Name | |
Facilitators | epd_Facilitator__c | Workshop: ID | |
Facilitators | epd_Facilitator__c | Contact | Contact__c |
Facilitators | epd_Facilitator__c | Employment Type | Employment_Type__c |
Facilitators | epd_Facilitator__c | First Name | First_Name__c |
Facilitators | epd_Facilitator__c | State | State__c |
Host Orgs | Account | Host Organization: Billing City | BillingCity |
Host Orgs | Account | Host Organization: Billing State/Province | BillingState |
Host Orgs | Account | Host Orgainzation: Billing Zip/Postal Code | BillingPostalCode |
Host Orgs | Account | Host Organization: Billing Country | BillingCountry |
Implementation Sites | epd_Implementation_Site__c | Implementation Site Name | Name |
Implementation Sites | epd_Implementation_Site__c | City | City__c |
Implementation Sites | epd_Implementation_Site__c | Site Type | Site_Type__c |
Implementation Sites | epd_Implementation_Site__c | Street | Street__c |
Implementation Sites | epd_Implementation_Site__c | Zipcode | Zipcode__c |
Implementation Sites | epd_Implementation_Site__c | State | State__c |
Implementation Sites | epd_Implementation_Site__c | Host Organization: Account Name |
Site_Type__c
can be one of the following:
Program_Delivery__c
can be one of the following:
Workshop_Language_Other__c
can be one of the following:
Salutation
can be one of the following:
Employee_Type__c
to create a Contact
can be one of the following:
Employee_Type__c
to create a Facilitator
can be one of the following: