Challenge Stage: API Integration

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.

Important! The Challenge and Stage must be available to the member at the time the API call is made. This means that the Challenge Targeting must include the member in question. Further, if this is not the first or only stage in a Challenge, then the member must be currently on this stage for the API call to be successful. If the Challenge is not available to the member through Targeting or the member has not reached the API Integration stage in question, an error indicating that the stage is not available will be returned when you make an API call.

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"
        }
}

1: 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.
2: 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.
3: Finally, the API Code for the stage we are creating is specified in the "code" field as "associate_exam_complete".