Overview
The API Integration stage in Influitive allows for the acknowledgment of tasks or events completed externally by making API calls to the /events endpoint. This stage requires proper configuration, including setting up Custom Event Types and a unique API Code for each stage. The integration is contingent on the member being targeted by the Challenge and being at the correct stage for the API call to be successful.
Information
What is the API Integration stage?
The API Integration stage is designed to be used in conjunction with the Influitive API for recognizing tasks or events that were completed outside of Influitive. You must mark this stage as complete via the Influitive API, by making use of the /events endpoint, which you can learn about and test in the Influitive API docs .
Configuring the API Integration stage
Allowed Event Types
Before using the API Integration stage, you must create (or have already created) a Custom Event Type. An example of an Event Type, "Complete Exam", is used above in the "Allowed Event Types" field. It does not specify which exam is completed, as that is covered in the "API Code" field.
Follow this guide on creating Custom Event Types before continuing . An Event Type describes the general type of activity that the member completed. An Event Type is meant to categorize the activity for reporting purposes and can be used in multiple stages for similar activities.
You can add multiple Event types in one challenge stage, and it will complete the stage if any of the entered Event Types occured.
API Code
The API Code field is a unique string that is used to identify the stage when you make a call to the Events endpoint via the Influitive API . There may be many stages designed to award points for completing multiple exams, but the one I am creating above is specifically for the "Associate Exam," so I have used the API Code, "associate_exam_complete". You cannot use the same stage API Code in other stages. It must be unique throughout all of your Challenges.
Sample API Code
To help illustrate how the API Integration stage is used, you can find a sample API call to the Events endpoint.
{
"type":"complete_exam",
"contact":
{
"email": "steveadvocate@acme.com"
},
"stage":
{
"code": "associate_exam_complete"
}
}
- In the above JSON code, we have indicated the Event Type in the "type" field using the Custom Event Type's API code, "complete_exam". You can find the API code for the Event Type by going to Settings > Scoring & Achievements > Event Types and looking in the API Code column.
Important! You can only use Custom Event Types in the Influitive API. It is not possible to use the system's event types in your call.
- In the "contact" > "email" field, we specify the email address of the member. The email address is the unique identifier in the Influitive Events API.
- Finally, the API Code for the stage we are creating is specified in the "code" field as "associate_exam_complete".
FAQ
What is the purpose of the API Integration stage in Influitive?
The API Integration stage in Influitive is used to acknowledge the completion of tasks or events that occur outside of the Influitive platform by making API calls to the platform's /events endpoint.
How do you ensure that an API call to the API Integration stage is successful?
To ensure success, the Challenge must be accessible to the member, the Challenge Targeting must include the member, and the member must be actively on the API Integration stage when the API call is made.
What is an API Code in the context of Influitive's API Integration stage?
An API Code is a unique string identifier used to specify a particular stage when making requests to the Events endpoint in Influitive's API. It ensures that points or acknowledgments are applied to the correct stage.
Can the same API Code be used for different stages in Influitive?
No, the same API Code cannot be reused across different stages. Each stage must have a unique API Code to prevent conflicts and ensure accurate tracking.
What is a Custom Event Type in Influitive, and why is it important?
A Custom Event Type in Influitive defines the broad category of an activity completed by a member and is used for classification and reporting purposes. It is essential for the API Integration stage to classify external activities and can be applied across various stages for similar activities.
Priyanka Bhotika
Comments