Get conversations via the Perform & Engage 365 API

The Perform & Engage 365 API enables you to:

• Get a list of conversations.
• Get the details of a particular conversation by its ID.

Get a list of conversations

GET /api/v2/conversations/

This request enables you to get a list of conversations based on the search parameters.

Optional query parameters

• person_name (string). The employee’s full name.
• plan_name (string). The conversation plan name.
• template_name (string). The conversation template name.
• status (string). The conversation status: draft, final, deleted, or archived.
• limit (integer). The maximum number of conversations in the response.
• offset (integer). The initial index from which the results are returned in the response.

Request example

GET /api/v2/conversations/?person_name=Adele%20Vance&plan_name=9-Box%20
Assessment&status=draft&template_name=9-Box

Response body parameters

The response body includes:

• count (integer). The number of results.
• next and previous (strings). URLs to the next and previous pages (if you used pagination in the original request).
• results (array). The list of conversations. Each conversation has these parameters:
  • api_id (string). The conversation ID. You can use this ID to get more details about the conversation.
  • template_api_id (string). The conversation template ID. You can use this ID to get more details about the conversation template.
  • template_name (string). The conversation template name.
  • plan_name (string). The conversation plan name.
  • plan_api_id (string). The conversation plan ID.
  • stage_name (string). The name of the current stage of the conversation. If the conversation is completed, the stage is Final.
  • stage_api_id (string). The stage ID.
  • status (string). The conversation status: draft, final, deleted, or archived.
  • updated_date (string). The date and time of the last conversation update.
  • completed_date (string). The date and time of the conversation completion.
  • generated_date (string). The date and time of the conversation generation.
  • person_api_id (string). The employee’s ID.
  • person_name (string). The employee’s full name.
  • person_email (string). The employee’s email address.
  • manager_api_id (string). The manager’s ID.
  • manager_name (string). The manager’s full name.
  • manager_email (string). The manager’s email address.
  • reviewer_api_id and second_reviewer_api_id (string). The reviewers’ IDs.
  • reviewer_name and second_reviewer_name (string). The reviewers’ full names.
  • reviewer_email and second_reviewer_email (string). The reviewers’ email addresses.

Response body example

The successful 200 response returns the body similar to this:

{
 "count": 1,
 "next": null,
 "previous": null,
 "results": [
   {
     "api_id": "580:972ba6da-9aa0-4704-aba2-39865339eb3d",
     "template_api_id": "580:44b1729e-a9bf-488c-9ad2-890af66be941",
     "template_name": "9-Box",
     "plan_api_id": "580:e3d3071d-f970-4693-872b-e17df6babdf4",
     "plan_name": "9-Box Assessment",
     "stage_name": "Leader Review",
     "stage_api_id": null,
     "status": "draft",
     "updated_date": "2021-09-28T10:44:15.945867+01:00",
     "completed_date": null,
     "generated_date": "2021-09-21T12:28:39.712575+01:00",
     "person_api_id": "580:c5b6c1bc-98a4-4e3b-ab17-54fa0c48b2a1",
     "person_name": "Adele Vance",
     "person_email": "adelevance@compafi464.onmicrosoft.com",
     "reviewer_api_id": "580:4c8c3ea5-d584-4ba2-b184-2280d53bbda3",
     "reviewer_name": "Jamie Jones",
     "reviewer_email": "contact+sandboxtemplate@weekly10.net",
     "second_reviewer_api_id": null,
     "second_reviewer_name": null,
     "second_reviewer_email": null,
     "manager_name": "Jamie Jones",
     "manager_email": "contact+sandboxtemplate@weekly10.net",
     "manager_api_id": "580:4c8c3ea5-d584-4ba2-b184-2280d53bbda3"
   }
 ]
}

Get the details of a particular conversation by its ID

GET api/v2/conversations/{api_id}/

After getting the conversation api_id in the response to the previous request, you can use this ID to get more information about the conversation.

Required path parameter

• api_id (string). The conversation ID you can get by sending the GET /api/v2/conversations/ request.

Request example

GET /api/v2/conversations/580%3A972ba6da-9aa0-4704-aba2-39865339eb3d/

Response body parameters

In addition to the same parameters as the results array in the GET /api/v2/conversations/ response includes, the GET api/v2/conversations/{api_id}/ response includes the data array that is a list of conversation elements.

Response body example

The successful 200 response returns the body similar to this:

{
 "api_id": "580:972ba6da-9aa0-4704-aba2-39865339eb3d",
 "template_api_id": "580:44b1729e-a9bf-488c-9ad2-890af66be941",
 "template_name": "9-Box",
 "plan_api_id": "580:e3d3071d-f970-4693-872b-e17df6babdf4",
 "plan_name": "9-Box Assessment",
 "stage_name": "Leader Review",
 "stage_api_id": null,
 "status": "draft",
 "updated_date": "2021-09-28T10:44:15.945867+01:00",
 "completed_date": null,
 "generated_date": "2021-09-21T12:28:39.712575+01:00",
 "person_api_id": "580:c5b6c1bc-98a4-4e3b-ab17-54fa0c48b2a1",
 "person_name": "Adele Vance",
 "person_email": "adelevance@compafi464.onmicrosoft.com",
 "reviewer_api_id": "580:4c8c3ea5-d584-4ba2-b184-2280d53bbda3",
 "reviewer_name": "Jamie Jones",
 "reviewer_email": "contact+sandboxtemplate@weekly10.net",
 "second_reviewer_api_id": null,
 "second_reviewer_name": null,
 "second_reviewer_email": null,
 "data": [
   {
     "api_id": null,
     "element_title": "Performance vs Potential",
     "element_api_id": "None:3685454d-a3b4-49dc-9539-8f3117a276a6",
     "element_type": "nine_box",
     "value": "2",
     "key": "1542",
     "comment": ""
   }
 ],
 "manager_name": "Jamie Jones",
 "manager_email": "contact+sandboxtemplate@weekly10.net",
 "manager_api_id": "580:4c8c3ea5-d584-4ba2-b184-2280d53bbda3"
}