openapi: 3.0.1
info:
title: Culture Amp Public API
description: This Open API specification describes the interface for the Culture Amp public API service
contact:
name: Culture Amp Support
email: support@cultureamp.com
license:
name: CultureAmp
version: 0.0.1
servers:
- url: https://api.cultureamp.com/v1
description: Production
- url: https://sandbox.public-api.development.cultureamp.net/v1
description: Development
tags:
- name: Employees
- name: Performance
- name: Surveys
paths:
/employees:
get:
tags:
- Employees
summary: List employees
description: |-
Returns all employees in the account.
If both `email` and `employee_identifier` are provided, `employee_identifier` will take precedence.
`cursor` is optional and used for pagination.
operationId: list-employees
parameters:
- name: email
in: query
description: The email of the employees to retrieve
schema:
type: string
format: email
- name: employee_identifier
in: query
description: The unique id used by the employees company to identify the employee
schema:
type: string
- $ref: "#/components/parameters/CursorQueryParam"
responses:
"200":
description: OK
content:
application/json:
schema:
$ref: "#/components/schemas/EmployeesResponse"
"400":
$ref: "#/components/responses/BadRequest"
"401":
$ref: "#/components/responses/Unauthorized"
"403":
$ref: "#/components/responses/Forbidden"
"404":
$ref: "#/components/responses/NotFound"
"429":
$ref: "#/components/responses/TooManyRequests"
"500":
$ref: "#/components/responses/InternalServerError"
"503":
$ref: "#/components/responses/ServiceUnavailable"
security:
- Oauth2:
- employees-read
"/employees/{id}":
get:
tags:
- Employees
summary: Get employee
description: Returns the details of an employee corresponding to the provided Culture Amp employee identifier
operationId: get-employee
parameters:
- name: id
in: path
description: the Culture Amp employee identifier
required: true
schema:
type: string
format: uuid
responses:
"200":
description: OK
content:
application/json:
schema:
$ref: "#/components/schemas/EmployeeByIDResponse"
"401":
$ref: "#/components/responses/Unauthorized"
"403":
$ref: "#/components/responses/Forbidden"
"404":
$ref: "#/components/responses/NotFound"
"429":
$ref: "#/components/responses/TooManyRequests"
"500":
$ref: "#/components/responses/InternalServerError"
"503":
$ref: "#/components/responses/ServiceUnavailable"
security:
- Oauth2:
- employees-read
"/employees/{id}/demographics":
get:
tags:
- Employees
summary: List demographics by employee
description: Returns the demographic assignments for a given employee
operationId: list-demographics-by-employee
parameters:
- name: id
in: path
description: the Culture Amp employee identifier
required: true
schema:
type: string
responses:
"200":
description: OK
content:
application/json:
schema:
$ref: "#/components/schemas/DemographicsResponse"
"400":
$ref: "#/components/responses/BadRequest"
"401":
$ref: "#/components/responses/Unauthorized"
"403":
$ref: "#/components/responses/Forbidden"
"404":
$ref: "#/components/responses/NotFound"
"429":
$ref: "#/components/responses/TooManyRequests"
"500":
$ref: "#/components/responses/InternalServerError"
"503":
$ref: "#/components/responses/ServiceUnavailable"
security:
- Oauth2:
- employee-demographics-read
"/employees/{id}/manager-reviews":
get:
tags:
- Performance
summary: List manager reviews by employee
description: Returns manager reviews for a given employee
operationId: list-manager-reviews-by-employee
parameters:
- name: id
in: path
description: the Culture Amp employee identifier
required: true
schema:
type: string
- $ref: "#/components/parameters/CursorQueryParam"
responses:
"200":
description: OK
content:
application/json:
schema:
$ref: "#/components/schemas/ManagerReviewsResponse"
"400":
$ref: "#/components/responses/BadRequest"
"401":
$ref: "#/components/responses/Unauthorized"
"403":
$ref: "#/components/responses/Forbidden"
"404":
$ref: "#/components/responses/NotFound"
"429":
$ref: "#/components/responses/TooManyRequests"
"500":
$ref: "#/components/responses/InternalServerError"
"503":
$ref: "#/components/responses/ServiceUnavailable"
security:
- Oauth2:
- performance-evaluations-read
/performance-cycles:
get:
tags:
- Performance
summary: List performance cycles
description: |-
Returns all performance cycles in the account.
If both `cursor` and `state` are provided in a request, `cursor` takes precedence.
operationId: list-performance-cycles
parameters:
- $ref: "#/components/parameters/AfterDateQueryParam"
- $ref: "#/components/parameters/CursorQueryParam"
- name: state
in: query
description: the state of the performance cycles to be returned
schema:
$ref: "#/components/schemas/PerformanceCycleState"
example: active
responses:
"200":
description: OK
content:
application/json:
schema:
$ref: "#/components/schemas/PerformanceCyclesResponse"
"400":
$ref: "#/components/responses/BadRequest"
"401":
$ref: "#/components/responses/Unauthorized"
"403":
$ref: "#/components/responses/Forbidden"
"404":
$ref: "#/components/responses/NotFound"
"429":
$ref: "#/components/responses/TooManyRequests"
"500":
$ref: "#/components/responses/InternalServerError"
"503":
$ref: "#/components/responses/ServiceUnavailable"
security:
- Oauth2:
- performance-evaluations-read
"/performance-cycles/{id}":
get:
tags:
- Performance
summary: Get performance cycle
description: Returns the details of a performance cycle by its id
operationId: get-performance-cycle
parameters:
- name: id
in: path
description: performance cycle id
required: true
schema:
type: string
responses:
"200":
description: OK
content:
application/json:
schema:
$ref: "#/components/schemas/PerformanceCycleResponse"
"401":
$ref: "#/components/responses/Unauthorized"
"403":
$ref: "#/components/responses/Forbidden"
"404":
$ref: "#/components/responses/NotFound"
"429":
$ref: "#/components/responses/TooManyRequests"
"500":
$ref: "#/components/responses/InternalServerError"
"503":
$ref: "#/components/responses/ServiceUnavailable"
security:
- Oauth2:
- performance-evaluations-read
"/performance-cycles/{id}/manager-reviews":
get:
tags:
- Performance
summary: List manager reviews by performance cycle
description: Returns manager reviews for a given performance cycle
operationId: list-manager-reviews-by-performance-cycle
parameters:
- name: id
in: path
description: performance cycle id
required: true
schema:
type: string
- $ref: "#/components/parameters/CursorQueryParam"
responses:
"200":
description: OK
content:
application/json:
schema:
$ref: "#/components/schemas/ManagerReviewsResponse"
"400":
$ref: "#/components/responses/BadRequest"
"401":
$ref: "#/components/responses/Unauthorized"
"403":
$ref: "#/components/responses/Forbidden"
"404":
$ref: "#/components/responses/NotFound"
"429":
$ref: "#/components/responses/TooManyRequests"
"500":
$ref: "#/components/responses/InternalServerError"
"503":
$ref: "#/components/responses/ServiceUnavailable"
security:
- Oauth2:
- performance-evaluations-read
/manager-reviews:
get:
tags:
- Performance
summary: List manager reviews
description: Returns all manager reviews in the account
operationId: list-manager-reviews
parameters:
- $ref: "#/components/parameters/AfterDateQueryParam"
- $ref: "#/components/parameters/CursorQueryParam"
responses:
"200":
description: OK
content:
application/json:
schema:
$ref: "#/components/schemas/ManagerReviewsResponse"
"400":
$ref: "#/components/responses/BadRequest"
"401":
$ref: "#/components/responses/Unauthorized"
"403":
$ref: "#/components/responses/Forbidden"
"404":
$ref: "#/components/responses/NotFound"
"429":
$ref: "#/components/responses/TooManyRequests"
"500":
$ref: "#/components/responses/InternalServerError"
"503":
$ref: "#/components/responses/ServiceUnavailable"
security:
- Oauth2:
- performance-evaluations-read
"/manager-reviews/{id}":
get:
tags:
- Performance
summary: Get manager review
description: Returns the details of a manager review corresponding to the provided id
operationId: get-manager-review
parameters:
- name: id
in: path
description: manager review id
required: true
schema:
type: string
responses:
"200":
description: OK
content:
application/json:
schema:
$ref: "#/components/schemas/ManagerReviewResponse"
"401":
$ref: "#/components/responses/Unauthorized"
"403":
$ref: "#/components/responses/Forbidden"
"404":
$ref: "#/components/responses/NotFound"
"429":
$ref: "#/components/responses/TooManyRequests"
"500":
$ref: "#/components/responses/InternalServerError"
"503":
$ref: "#/components/responses/ServiceUnavailable"
security:
- Oauth2:
- performance-evaluations-read
"/surveys":
get:
tags:
- Surveys
summary: List surveys
description: |
Returns a list of all surveys in the account
> ⚠️ Warning
>
> **Demographic Values Unavailable (Coming Soon):** Currently demographic values for survey participants are not available from the Survey API but will be introduced in the coming months. If you require this data immediately please set up the [Reporting API](https://support.cultureamp.com/en/articles/9232738-reporting-api) for access.
operationId: list-surveys
parameters:
- $ref: "#/components/parameters/CursorQueryParam"
responses:
"200":
description: OK
content:
application/json:
schema:
$ref: "#/components/schemas/SurveysResponse"
"400":
$ref: "#/components/responses/BadRequest"
"401":
$ref: "#/components/responses/Unauthorized"
"403":
$ref: "#/components/responses/Forbidden"
"429":
$ref: "#/components/responses/TooManyRequests"
"500":
$ref: "#/components/responses/InternalServerError"
"503":
$ref: "#/components/responses/ServiceUnavailable"
security:
- Oauth2:
- surveys-read
"/surveys/{id}":
get:
tags:
- Surveys
summary: Get survey
description: |
Retrieves the details of an individual survey
> ⚠️ Warning
>
> **Demographic Values Unavailable (Coming Soon):** Currently demographic values for survey participants are not available from the Survey API but will be introduced in the coming months. If you require this data immediately please set up the [Reporting API](https://support.cultureamp.com/en/articles/9232738-reporting-api) for access.
operationId: get-survey
parameters:
- name: id
in: path
description: survey id
required: true
schema:
type: string
responses:
"200":
description: OK
content:
application/json:
schema:
$ref: "#/components/schemas/SurveyResponse"
"400":
$ref: "#/components/responses/BadRequest"
"401":
$ref: "#/components/responses/Unauthorized"
"403":
$ref: "#/components/responses/Forbidden"
"404":
$ref: "#/components/responses/NotFound"
"429":
$ref: "#/components/responses/TooManyRequests"
"500":
$ref: "#/components/responses/InternalServerError"
"503":
$ref: "#/components/responses/ServiceUnavailable"
security:
- Oauth2:
- surveys-read
"/surveys/{id}/questions":
get:
tags:
- Surveys
summary: List questions
description: |
Returns a list of all questions from an individual survey
> ⚠️ Warning
>
> **Confidentiality:** Raw Data Extract must be enabled on a survey to retrieve its data via this API.
> \
> **Select Options Limit:** Select options are truncated to a maximum of 500 per question. [Please contact support](https://support.cultureamp.com/en/articles/7048645-contact-our-product-support-team) if you wish to extract questions with more than 500 select options.
> \
> **Demographic Values Unavailable (Coming Soon):** Currently demographic values for survey participants are not available from the Survey API but will be introduced in the coming months. If you require this data immediately please set up the [Reporting API](https://support.cultureamp.com/en/articles/9232738-reporting-api) for access.
operationId: list-survey-questions
parameters:
- $ref: "#/components/parameters/CursorQueryParam"
- name: id
in: path
description: survey id
required: true
schema:
type: string
responses:
"200":
description: OK
content:
application/json:
schema:
$ref: "#/components/schemas/SurveyQuestionsResponse"
"400":
$ref: "#/components/responses/BadRequest"
"401":
$ref: "#/components/responses/Unauthorized"
"403":
$ref: "#/components/responses/Forbidden"
"404":
$ref: "#/components/responses/NotFound"
"429":
$ref: "#/components/responses/TooManyRequests"
"500":
$ref: "#/components/responses/InternalServerError"
"503":
$ref: "#/components/responses/ServiceUnavailable"
security:
- Oauth2:
- surveys-read
"/surveys/{survey_id}/question/{question_id}":
get:
tags:
- Surveys
summary: Get question
description: |
Retrieves the details of an individual question from a survey
> ⚠️ Warning
>
> **Confidentiality:** Raw Data Extract must be enabled on a survey to retrieve its data via this API.
> \
> **Select Options Limit:** Select options are truncated to a maximum of 500 per question. [Please contact support](https://support.cultureamp.com/en/articles/7048645-contact-our-product-support-team) if you wish to extract questions with more than 500 select options.
> \
> **Demographic Values Unavailable (Coming Soon):** Currently demographic values for survey participants are not available from the Survey API but will be introduced in the coming months. If you require this data immediately please set up the [Reporting API](https://support.cultureamp.com/en/articles/9232738-reporting-api) for access.
operationId: get-survey-question
parameters:
- $ref: "#/components/parameters/CursorQueryParam"
- name: survey_id
in: path
description: survey id
required: true
schema:
type: string
- name: question_id
in: path
description: question id
required: true
schema:
type: string
responses:
"200":
description: OK
content:
application/json:
schema:
$ref: "#/components/schemas/SurveyQuestionResponse"
"400":
$ref: "#/components/responses/BadRequest"
"401":
$ref: "#/components/responses/Unauthorized"
"403":
$ref: "#/components/responses/Forbidden"
"404":
$ref: "#/components/responses/NotFound"
"429":
$ref: "#/components/responses/TooManyRequests"
"500":
$ref: "#/components/responses/InternalServerError"
"503":
$ref: "#/components/responses/ServiceUnavailable"
security:
- Oauth2:
- surveys-read
"/surveys/{id}/responses":
get:
tags:
- Surveys
summary: List responses
description: |
Returns a list of all responses from an individual survey
> ⚠️ Warning
>
> **Confidentiality:** Raw Data Extract must be enabled on a survey to retrieve its data via this API.
> \
> **Demographic Values Unavailable (Coming Soon):** Currently demographic values for survey participants are not available from the Survey API but will be introduced in the coming months. If you require this data immediately please set up the [Reporting API](https://support.cultureamp.com/en/articles/9232738-reporting-api) for access.
operationId: list-survey-responses
parameters:
- $ref: "#/components/parameters/CursorQueryParam"
- name: id
in: path
description: survey id
required: true
schema:
type: string
responses:
"200":
description: OK
content:
application/json:
schema:
$ref: "#/components/schemas/SurveyRespsResponse"
"400":
$ref: "#/components/responses/BadRequest"
"401":
$ref: "#/components/responses/Unauthorized"
"403":
$ref: "#/components/responses/Forbidden"
"404":
$ref: "#/components/responses/NotFound"
"429":
$ref: "#/components/responses/TooManyRequests"
"500":
$ref: "#/components/responses/InternalServerError"
"503":
$ref: "#/components/responses/ServiceUnavailable"
security:
- Oauth2:
- surveys-read
"/surveys/{survey_id}/responses/{response_id}":
get:
tags:
- Surveys
summary: Get response
description: |
Retrieves the details of an individual response from a survey
> ⚠️ Warning
>
> **Confidentiality:** Raw Data Extract must be enabled on a survey to retrieve its data via this API.
> \
> **Demographic Values Unavailable (Coming Soon):** Currently demographic values for survey participants are not available from the Survey API but will be introduced in the coming months. If you require this data immediately please set up the [Reporting API](https://support.cultureamp.com/en/articles/9232738-reporting-api) for access.
operationId: get-survey-response
parameters:
- name: survey_id
in: path
description: survey id
required: true
schema:
type: string
- name: response_id
in: path
description: response id
required: true
schema:
type: string
responses:
"200":
description: OK
content:
application/json:
schema:
$ref: "#/components/schemas/SurveyRespResponse"
"400":
$ref: "#/components/responses/BadRequest"
"401":
$ref: "#/components/responses/Unauthorized"
"403":
$ref: "#/components/responses/Forbidden"
"404":
$ref: "#/components/responses/NotFound"
"429":
$ref: "#/components/responses/TooManyRequests"
"500":
$ref: "#/components/responses/InternalServerError"
"503":
$ref: "#/components/responses/ServiceUnavailable"
security:
- Oauth2:
- surveys-read
"/surveys/{id}/factors":
get:
tags:
- Surveys
summary: List factors
description: |
Returns a list of all factors from an individual survey
> ⚠️ Warning
>
> **Confidentiality:** Raw Data Extract must be enabled on a survey to retrieve its data via this API.
> \
> **Demographic Values Unavailable (Coming Soon):** Currently demographic values for survey participants are not available from the Survey API but will be introduced in the coming months. If you require this data immediately please set up the [Reporting API](https://support.cultureamp.com/en/articles/9232738-reporting-api) for access.
operationId: list-survey-factors
parameters:
- $ref: "#/components/parameters/CursorQueryParam"
- name: id
in: path
description: factor id
required: true
schema:
type: string
responses:
"200":
description: OK
content:
application/json:
schema:
$ref: "#/components/schemas/SurveyFactorsResponse"
"400":
$ref: "#/components/responses/BadRequest"
"401":
$ref: "#/components/responses/Unauthorized"
"403":
$ref: "#/components/responses/Forbidden"
"404":
$ref: "#/components/responses/NotFound"
"429":
$ref: "#/components/responses/TooManyRequests"
"500":
$ref: "#/components/responses/InternalServerError"
"503":
$ref: "#/components/responses/ServiceUnavailable"
security:
- Oauth2:
- surveys-read
"/surveys/{survey_id}/factors/{factor_id}":
get:
tags:
- Surveys
summary: Get factor
description: |
Retrieves the details of an individual factor from a survey
> ⚠️ Warning
>
> **Confidentiality:** Raw Data Extract must be enabled on a survey to retrieve its data via this API.
> \
> **Demographic Values Unavailable (Coming Soon):** Currently demographic values for survey participants are not available from the Survey API but will be introduced in the coming months. If you require this data immediately please set up the [Reporting API](https://support.cultureamp.com/en/articles/9232738-reporting-api) for access.
operationId: get-survey-factor
parameters:
- name: survey_id
in: path
description: survey id
required: true
schema:
type: string
- name: factor_id
in: path
description: Unique identifiers of the factors associated with this question.
required: true
schema:
type: string
responses:
"200":
description: OK
content:
application/json:
schema:
$ref: "#/components/schemas/SurveyFactorResponse"
"400":
$ref: "#/components/responses/BadRequest"
"401":
$ref: "#/components/responses/Unauthorized"
"403":
$ref: "#/components/responses/Forbidden"
"404":
$ref: "#/components/responses/NotFound"
"429":
$ref: "#/components/responses/TooManyRequests"
"500":
$ref: "#/components/responses/InternalServerError"
"503":
$ref: "#/components/responses/ServiceUnavailable"
security:
- Oauth2:
- surveys-read
"/surveys/{id}/sections":
get:
tags:
- Surveys
summary: List sections
description: |
Returns a list of all sections from an individual survey
> ⚠️ Warning
>
> **Confidentiality:** Raw Data Extract must be enabled on a survey to retrieve its data via this API.
> \
> **Demographic Values Unavailable (Coming Soon):** Currently demographic values for survey participants are not available from the Survey API but will be introduced in the coming months. If you require this data immediately please set up the [Reporting API](https://support.cultureamp.com/en/articles/9232738-reporting-api) for access.
operationId: list-survey-sections
parameters:
- $ref: "#/components/parameters/CursorQueryParam"
- name: id
in: path
description: survey id
required: true
schema:
type: string
responses:
"200":
description: OK
content:
application/json:
schema:
$ref: "#/components/schemas/SurveySectionsResponse"
"400":
$ref: "#/components/responses/BadRequest"
"401":
$ref: "#/components/responses/Unauthorized"
"403":
$ref: "#/components/responses/Forbidden"
"404":
$ref: "#/components/responses/NotFound"
"429":
$ref: "#/components/responses/TooManyRequests"
"500":
$ref: "#/components/responses/InternalServerError"
"503":
$ref: "#/components/responses/ServiceUnavailable"
security:
- Oauth2:
- surveys-read
"/surveys/{survey_id}/sections/{section_id}":
get:
tags:
- Surveys
summary: Get section
description: |
Retrieves the details of an individual section from a survey
> ⚠️ Warning
>
> **Confidentiality:** Raw Data Extract must be enabled on a survey to retrieve its data via this API.
> \
> **Demographic Values Unavailable (Coming Soon):** Currently demographic values for survey participants are not available from the Survey API but will be introduced in the coming months. If you require this data immediately please set up the [Reporting API](https://support.cultureamp.com/en/articles/9232738-reporting-api) for access.
operationId: get-survey-section
parameters:
- name: survey_id
in: path
description: survey id
required: true
schema:
type: string
- name: section_id
in: path
description: Unique identifier for the section associated with this question
required: true
schema:
type: string
responses:
"200":
description: OK
content:
application/json:
schema:
$ref: "#/components/schemas/SurveySectionResponse"
"400":
$ref: "#/components/responses/BadRequest"
"401":
$ref: "#/components/responses/Unauthorized"
"403":
$ref: "#/components/responses/Forbidden"
"404":
$ref: "#/components/responses/NotFound"
"429":
$ref: "#/components/responses/TooManyRequests"
"500":
$ref: "#/components/responses/InternalServerError"
"503":
$ref: "#/components/responses/ServiceUnavailable"
security:
- Oauth2:
- surveys-read
components:
parameters:
AfterDateQueryParam:
name: after_date
in: query
description: |-
Only returns resources processed by the public API after the date-time provided.
Uses the date-time format specified in [RFC 3339 section 5.6, Internet Date/Time Format](https://tools.ietf.org/html/rfc3339#section-5.6).
The value cannot contain spaces, and date and time should be separated by "T".
For example:
* UTC time "2023-05-01T00:00:00Z".
* An offset from UTC time to indicate a time zone, such as "2023-05-01T00:00:00%2B08:00" (for 8 hours ahead of UTC time).
Note that query parameters should be properly escaped, last example is equivalent to "2023-05-01T00:00:00+08:00".
schema:
type: string
example: "2013-01-15T00:00:00+08:00"
CursorQueryParam:
name: cursor
in: query
description: |-
The pagination key to use for the next page of results.
The last successful call will include this in the response body in `pagination.afterKey`.
Note:
* Pagination also works using the `after_key` query parameter. However, if both `cursor` and `after_key` are
provided, `cursor` will take precedence.
schema:
type: string
example: ewogICJQSyI6ICJzZGZzZGZzZGYtc2Rmc2Rmc2Qtc2Rmc2RmIiwKICAiU0siOiAic2Rmc2Rmc2RzZGYtc2RmYXNhc2ZzLS1zZGZzZGYiCn0J
schemas:
SurveysResponse:
title: SurveysResponse
type: object
description: container object for multiple Surveys
properties:
data:
type: array
items:
$ref: "#/components/schemas/Survey"
pagination:
$ref: "#/components/schemas/PaginationV2"
required:
- data
SurveyResponse:
title: SurveyResponse
type: object
description: container object for a single Survey
properties:
data:
$ref: "#/components/schemas/Survey"
required:
- data
SurveyQuestionResponse:
title: SurveyQuestionResponse
type: object
description: container object for a single Survey question
properties:
data:
$ref: "#/components/schemas/SurveyQuestion"
required:
- data
SurveyQuestionsResponse:
title: SurveyQuestionsResponse
type: object
description: container object for multiple Survey questions
properties:
data:
type: array
items:
$ref: "#/components/schemas/SurveyQuestion"
pagination:
$ref: "#/components/schemas/PaginationV2"
required:
- data
Survey:
title: Survey
type: object
description: The Survey record
properties:
id:
type: string
description: the identifier used by Culture Amp to identify the Survey
name:
type: object
additionalProperties:
type: string
description: The locale informed name of the Survey
example:
en: Hello!
fr: Bonjour!
status:
type: string
description: |
The status of the survey.
Surveys that are still being drafted are not surfaced in the API.
For more information about draft surveys, please refer to the following support guide: https://support.cultureamp.com/en/articles/7048518-surveys-and-programs-page#h_71149c7700
rdeEnabled:
type: boolean
description: A boolean describing the RDE Enabled status of the survey
owner:
type: string
description: The Culture Amp ID identifying the user who owns the Survey
workflow:
type: string
description: The workflow of the survey
launchedAt:
type: string
description: The date the Survey was launched
format: date-time
nullable: true
closedAt:
type: string
description: The date the Survey was closed
format: date-time
nullable: true
createdAt:
type: string
description: The date the Survey was created
format: date-time
updatedAt:
type: string
description: The date the Survey was last updated
format: date-time
processedAt:
type: string
description: The date the survey was last processed by the public API. This can be used by consumers to determine if the survey has been updated since the last time it was retrieved.
format: date-time
communicatedClosedAt:
type: string
description: The timestamp when the closure of the survey was communicated.
format: date-time
nullable: true
surveyDueDays:
type: integer
description: How many days from survey launch that the survey is due.
kioskModeEnabled:
type: boolean
description: Indicates whether the survey is being run in kiosk mode.
excludeParticipantsAfter:
type: string
description: The date at which this survey will no longer include participants.
format: date-time
nullable: true
required:
- id
- processedAt
- rdeEnabled
SurveyQuestion:
title: SurveyQuestion
type: object
description: The Survey Question record
properties:
id:
type: string
description: the identifier used by Culture Amp to identify the Survey
code:
type: string
description: The unique question code
questionType:
type: string
description: The type of the survey question eg. culture, segment
label:
type: object
additionalProperties:
type: string
description: The localised label of the survey question
example:
en: Hello!
fr: Bonjour!
description:
type: object
additionalProperties:
type: string
description: The localised description of the survey question
example:
en: Hello!
fr: Bonjour!
ratingScale:
type: string
description: The rating scale of the survey question
selectOptions:
type: array
items:
$ref: "#/components/schemas/SurveyQuestionSelectOption"
otherOption:
type: boolean
description: The flag for other select option
status:
type: string
description: The status of the survey question, active or deleted
sectionId:
type: string
description: The ID of a section the survey question belongs to
factorIds:
type: array
description: The IDs of factors associated with the survey question
items:
type: string
createdAt:
type: string
description: The date the Survey question was created
format: date-time
updatedAt:
type: string
description: The date the Survey question was last updated
format: date-time
processedAt:
type: string
description: The date the survey question was last processed by the public API. This can be used by consumers to determine if the question has been updated since the last time it was retrieved.
format: date-time
required:
- id
- otherOption
- processedAt
SurveyQuestionSelectOption:
type: object
description: a survey question's select option
properties:
id:
type: string
description: originated from a demographic_value_id or select_option_id
label:
type: object
additionalProperties:
type: string
description: The localised label of the option
example:
en: Hello!
fr: Bonjour!
value:
type: object
additionalProperties:
type: string
description: The localised value of the option
example:
en: Hello!
fr: Bonjour!
status:
type: string
description: Select option status, active or deleted
createdAt:
type: string
description: The date the option was created
format: date-time
updatedAt:
type: string
description: The date the option was last updated
format: date-time
SurveyRespResponse:
title: SurveyRespResponse
type: object
description: container object for a Survey Response
properties:
data:
$ref: "#/components/schemas/SurveyResp"
required:
- data
SurveyRespsResponse:
title: SurveyRespsResponse
type: object
description: container object for multiple Survey Responses
properties:
data:
type: array
items:
$ref: "#/components/schemas/SurveyResp"
pagination:
$ref: "#/components/schemas/PaginationV2"
required:
- data
SurveyResp:
title: SurveyResponse
type: object
description: The Survey Response record
properties:
id:
type: string
description: the identifier used by Culture Amp to identify the Survey
employeeId:
type: string
description: The unique employee ID
answers:
type: array
items:
$ref: "#/components/schemas/SurveyRespAnswer"
rdeEnabled:
type: boolean
description: Identifies whether a survey was launched with `raw data extract` enabled (true/false).
captureLocale:
type: string
description: The the locale in which capture was completed
surveySubmittedBy:
type: string
description: The ID of the employee who submitted this response
startedAt:
type: string
description: The date the Survey response was started
format: date-time
nullable: true
submittedAt:
type: string
description: The date the Survey response was submitted
format: date-time
nullable: true
expiredAt:
type: string
description: The date the Survey response expires
format: date-time
nullable: true
createdAt:
type: string
description: The date the Survey response was created
format: date-time
updatedAt:
type: string
description: The date the Survey response was last updated
format: date-time
processedAt:
type: string
description: The date the survey response was last processed by the public API. This can be used by consumers to determine if the response has been updated since the last time it was retrieved.
format: date-time
required:
- id
- processedAt
- rdeEnabled
SurveyRespAnswer:
type: object
properties:
questionId:
type: string
description: the id of the question being answered
textValue:
type: string
description: The comment left for a free text style question, or the answer a user left when the "other" option is picked on a select question
ratingScore:
type: integer
description: The rating in the range 1..5 or -1 if it was not answered
selectOptions:
type: array
items:
$ref: "#/components/schemas/SurveyRespAnswerSelectOption"
answered:
type: boolean
description: Whether or not this answer was completed
additionalComment:
type: string
description: the comment text left against select questions as an additional input to the option chosen
mandatory:
type: boolean
description: Whether or not the question was made mandatory
createdAt:
type: string
description: The date the answer was created
format: date-time
updatedAt:
type: string
description: The date the answer was last updated
format: date-time
required:
- answered
- mandatory
SurveyRespAnswerSelectOption:
title: SurveyResponseAnswerSelectOption
type: object
description: A chosen select option in a survey response answer
properties:
id:
type: string
description: ID of a select option chosen as part of the response
label:
type: object
additionalProperties:
type: string
description: The localised label of a select option chosen as part of the response
example:
en: Hello!
fr: Bonjour!
SurveyFactor:
title: SurveyFactor
type: object
description: A Factor is an aspect that one seeks to measure in a Survey
properties:
id:
type: string
description: Unique identifier for this reporting factor
name:
type: object
additionalProperties:
type: string
description: Text name set by the survey admin for this reporting factor
example:
en: Hello!
fr: Bonjour!
type:
type: string
description: Defines the type of the reporting factor and how it will be used in survey reporting
code:
type: string
description: Auto-generated code for the reporting factor
indexFactor:
type: boolean
description: Whether the reporting factor is used as an index or not
customFactor:
type: boolean
description: Whether the reporting factor was created via the reporting factors page or not
shortDescription:
type: string
description: Short text label which describes the reporting factor
longDescription:
type: string
description: Long text label which describes the reporting factor
status:
type: string
description: Whether this reporting factor is active or deleted
order:
type: integer
description: Order of the factor as configured in the survey
format: int32
createdAt:
type: string
description: When this factor was created
format: date-time
updatedAt:
type: string
description: When the factor was last updated
format: date-time
SurveyFactorsResponse:
title: SurveyFactorsResponse
type: object
description: container object for multiple Factors
properties:
data:
type: array
items:
$ref: "#/components/schemas/SurveyFactor"
pagination:
$ref: "#/components/schemas/PaginationV2"
SurveyFactorResponse:
title: SurveyFactorResponse
type: object
description: container object for a single Factor
properties:
data:
$ref: "#/components/schemas/SurveyFactor"
required:
- data
SurveySection:
title: SurveySection
type: object
description: A section is a grouping of questions in a survey
properties:
id:
type: string
description: Unique identifier for this section.
name:
type: string
description: Name of this section
type:
type: string
description: Defines the type category of the section, including how it will display to respondents
code:
type: string
description: Auto-generated code for the section
shortDescription:
type: string
description: Short text label which describes the section
longDescription:
type: string
description: Long text label which describes the section
status:
type: string
description: Whether the section is active or deleted
order:
type: integer
description: Order of the section as configured in the survey
format: int32
createdAt:
type: string
description: When this section was created
format: date-time
updatedAt:
type: string
description: When this Section was last updated
format: date-time
SurveySectionsResponse:
title: SurveySectionsResponse
type: object
description: container object for multiple Sections
properties:
data:
type: array
items:
$ref: "#/components/schemas/SurveySection"
pagination:
$ref: "#/components/schemas/PaginationV2"
SurveySectionResponse:
title: SurveySectionResponse
type: object
description: container object for a single Section
properties:
data:
$ref: "#/components/schemas/SurveySection"
required:
- data
PerformanceCycleState:
type: string
enum:
- active
- closed
- ready
PerformanceReviewStatus:
type: string
description: |-
The status of the performance review.
\
**Note:** data from manager reviews with ‘dirty’ status is not served from this API.
enum:
- completed
- shared
- dirty
- incomplete
EmployeeByIDResponse:
title: EmployeeByIDResponse
type: object
properties:
data:
$ref: "#/components/schemas/Employee"
description: container object for a single employee response
required:
- data
EmployeesResponse:
title: EmployeesResponse
type: object
properties:
data:
type: array
items:
$ref: "#/components/schemas/Employee"
pagination:
$ref: "#/components/schemas/Pagination"
description: container object for multiple employees response
required:
- data
Error:
required:
- code
- message
type: object
properties:
code:
type: integer
description: the HTTP status code of the error
format: int32
message:
type: string
description: a description of the error
description: an object describing an API error
Link:
title: Link
type: object
properties:
rel:
type: string
description: "the type of related data e.g. demographics, goals, performance"
uri:
type: string
description: the relative url that points to the data
description: Link to related data
required:
- rel
- uri
Pagination:
title: Pagination
type: object
example:
afterKey: ewogICJQSyI6ICJzZGZzZGZzZGYtc2Rmc2Rmc2Qtc2Rmc2RmIiwKICAiU0siOiAic2Rmc2Rmc2RzZGYtc2RmYXNhc2ZzLS1zZGZzZGYiCn0J
nextPath: /<path>?cursor=ewogICJQSyI6ICJzZGZzZGZzZGYtc2Rmc2Rmc2Qtc2Rmc2RmIiwKICAiU0siOiAic2Rmc2Rmc2RzZGYtc2RmYXNhc2ZzLS1zZGZzZGYiCn0J
properties:
afterKey:
type: string
description: The pagination key to use for the next page of results
nextPath:
type: string
description: the relative url for the next page of data
required:
- nextPath
PaginationV2:
title: Pagination
type: object
example:
nextPath: /<path>?cursor=ewogICJQSyI6ICJzZGZzZGZzZGYtc2Rmc2Rmc2Qtc2Rmc2RmIiwKICAiU0siOiAic2Rmc2Rmc2RzZGYtc2RmYXNhc2ZzLS1zZGZzZGYiCn0J
properties:
nextPath:
type: string
description: the relative url for the next page of data
Demographic:
title: Demographic
type: object
example:
name: star sign
value: capricorn
properties:
name:
type: string
description: the name of the demographic
value:
type: string
description: the value of the demographic
required:
- name
- value
DemographicsResponse:
title: DemographicsResponse
type: object
description: container object for multiple demographics response
properties:
data:
type: array
items:
$ref: "#/components/schemas/Demographic"
required:
- data
Employee:
title: Employee
type: object
description: The employee data record
properties:
id:
type: string
description: the identifier used by Culture Amp to identify the employee
employeeIdentifier:
type: string
description: the identifier used by the employee's organization to identify the employee
email:
type: string
description: the employee's email address
name:
type: string
description: the name of the employee
preferredName:
type: string
description: the employee preferred name
birthDate:
type: string
description: the date of birth in YYYY-MM-DD format
format: date
startDate:
type: string
description: "the date the employee started in the company, in YYYY-MM-DD format"
format: date
endDate:
type: string
description: "the date the employee left the company, in YYYY-MM-DD format"
format: date
links:
type: array
description: links to data related to the employee
items:
$ref: "#/components/schemas/Link"
processedAt:
type: string
description: The date the employee was last processed by the public API. This can be used by consumers to determine if the employee has been updated since the last time they retrieved it.
format: date-time
required:
- id
- name
- processedAt
example:
id: 96b1cff7-3099-44a9-bd28-0292be8aff7f
name: Bertram Gilfoyle
preferredName: Gilfoyle
birthDate: "1980-08-24"
startDate: "2015-07-19"
endDate: "2019-08-01"
employeeIdentifier: "2"
email: gilfoyle@piedpiper.com
links:
- rel: demographics
uri: /v1/employees/96b1cff7-3099-44a9-bd28-0292be8aff7f/demographics
- rel: manager-reviews
uri: /v1/employees/96b1cff7-3099-44a9-bd28-0292be8aff7f/manager-reviews
processedAt: "2019-08-01T12:00:00Z"
PerformanceCycle:
title: PerformanceCycle
type: object
properties:
id:
type: string
name:
type: string
state:
$ref: "#/components/schemas/PerformanceCycleState"
createdAt:
type: string
description: The date the performance cycle was created in the source system
format: date-time
updatedAt:
type: string
description: The date the performance cycle was last updated in the source system
format: date-time
processedAt:
type: string
description: The date the performance cycle was last processed by the public API. This can be used by consumers to determine if the performance cycle has been updated since the last time they retrieved it.
format: date-time
required:
- id
- name
- state
- createdAt
- updatedAt
- processedAt
description: Describes a performance cycle
example:
id: b6505a73-d45f-4091-b3fb-74997de4cdc6
name: H1 2022 Pied Piper engineering performance cycle
state: active
createdAt: "2022-04-28T02:14:10+00:00"
updatedAt: "2022-08-02T02:14:10+00:00"
processedAt: "2022-08-02T02:15:10+00:00"
PerformanceRating:
title: PerformanceRating
type: object
description: Describes a performance rating for an employee
properties:
ratingQuestion:
$ref: "#/components/schemas/RatingQuestion"
ratingBuckets:
type: array
items:
$ref: "#/components/schemas/RatingBucket"
rating:
$ref: "#/components/schemas/Rating"
required:
- ratingBuckets
RatingQuestion:
type: object
properties:
title:
type: string
description:
type: string
required:
- title
RatingBucket:
title: RatingBucket
type: object
description: Describes a performance rating bucket that an employee may be assigned to
properties:
title:
type: string
description:
type: string
value:
type: integer
required:
- title
- value
Rating:
title: Rating
type: object
description: Describes a performance rating for an employee
properties:
id:
type: string
title:
type: string
description:
type: string
value:
type: integer
createdAt:
type: string
format: date-time
updatedAt:
type: string
format: date-time
required:
- id
- title
- value
- createdAt
- updatedAt
MultipleChoiceQuestion:
type: object
description: The multiple choice questions corresponding to a review
properties:
text:
type: string
options:
type: array
items:
type: string
answer:
type: string
required:
- text
- options
OpenTextQuestion:
type: object
description: The open text questions corresponding to a review
properties:
text:
type: string
answer:
type: string
required:
- text
ManagerReview:
title: ManagerReview
type: object
properties:
performanceCycleId:
type: string
managerReviewId:
type: string
employeeId:
description: The identifier used by Culture Amp to identify the employee
type: string
managerId:
description: The employee identifier used by Culture Amp to identify the manager performing the review
type: string
performanceRating:
$ref: "#/components/schemas/PerformanceRating"
openTextQuestions:
type: array
items:
$ref: "#/components/schemas/OpenTextQuestion"
multipleChoiceQuestions:
type: array
items:
$ref: "#/components/schemas/MultipleChoiceQuestion"
reviewAcknowledged:
type: boolean
description: Indicates whether the review has been shared with the employee and acknowledged by them
status:
type: string
$ref: "#/components/schemas/PerformanceReviewStatus"
links:
type: array
description: links to data related to the manager review
items:
$ref: "#/components/schemas/Link"
completedAt:
type: string
description: The date the manager review was completed in the source system
format: date-time
nullable: true
createdAt:
type: string
description: The date the manager review was created in the source system
format: date-time
updatedAt:
type: string
description: The date the manager review was last updated in the source system
format: date-time
processedAt:
type: string
description: The date the manager review was last processed by the public API. This may be used by consumers to determine if the manager review has been updated since the last time they retrieved it.
format: date-time
required:
- cycleId
- reviewId
- employeeId
- createdAt
- updatedAt
- processedAt
example:
performanceCycleId: b6505a73-d45f-4091-b3fb-74997de4cd01
managerReviewId: b6505a73-d45f-4091-b3fb-74997de4cd02
employeeId: b6505a73-d45f-4091-b3fb-74997de4cd03
managerId: b6505a73-d45f-4091-b3fb-74997de4cd04
performanceRating:
ratingQuestion:
title: "How would you rate the employee's performance?"
description: "Please rate the employee's overall performance, consider the impact they have had as well as how they live our values"
ratingBuckets:
- id: b6505a73-d45f-4091-b3fb-74997de4cd03
title: "Outstanding"
value: 2
description: "The employee has exceeded expectations and has had a significant impact on the team and the company"
createdAt: "2022-04-28T02:14:10+00:00"
updatedAt: "2022-08-02T02:14:10+00:00"
- id: b6505a73-d45f-4091-b3fb-74997de4cd04
title: "Good"
value: 1
description: "The employee has met expectations and has had a positive impact on the team and the company"
createdAt: "2022-04-28T02:14:10+00:00"
updatedAt: "2022-08-02T02:14:10+00:00"
- id: b6505a73-d45f-4091-b3fb-74997de4cd05
title: "Needs Improvement"
value: 0
description: "The employee has not met expectations and has had a negative impact on the team and the company"
createdAt: "2022-04-28T02:14:10+00:00"
updatedAt: "2022-08-02T02:14:10+00:00"
rating:
id: b6505a73-d45f-4091-b3fb-74997de4cd06
title: "Outstanding"
description: "The employee has exceeded expectations and has had a significant impact on the team and the company"
value: 5
createdAt: "2022-04-28T02:14:10+00:00"
updatedAt: "2022-08-02T02:14:10+00:00"
openTextQuestions:
- text: "What should this employee celebrate this year?"
answer: "Breaking a record for sales"
- text: "What should this employee focus on next year?"
answer: "Upskilling in Power BI"
multipleChoiceQuestions:
- text: "Does this employee embody company value #1?"
options:
- "yes"
- "no"
- "often"
- "sometimes"
answer: "yes"
- text: "Does this employee embody company value #2?"
options:
- "yes"
- "no"
- "often"
- "sometimes"
answer: "sometimes"
reviewAcknowledged: true
status: completed
links:
- rel: employee
uri: /v1/employees/b6505a73-d45f-4091-b3fb-74997de4cd03
- rel: performance-cycle
uri: /v1/performance-cycles/b6505a73-d45f-4091-b3fb-74997de4cd01
processedAt: "2022-08-02T02:15:10+00:00"
createdAt: "2022-04-28T02:14:10+00:00"
updatedAt: "2022-08-02T02:14:10+00:00"
completedAt: "2022-08-02T02:14:10+00:00"
PerformanceCyclesResponse:
title: PerformanceCycleResponse
type: object
properties:
data:
type: array
items:
$ref: "#/components/schemas/PerformanceCycle"
pagination:
$ref: "#/components/schemas/Pagination"
required:
- data
PerformanceCycleResponse:
title: PerformanceCycleResponse
type: object
properties:
data:
$ref: "#/components/schemas/PerformanceCycle"
required:
- data
ManagerReviewsResponse:
title: ManagerReviewsResponse
type: object
properties:
data:
type: array
items:
$ref: "#/components/schemas/ManagerReview"
pagination:
$ref: "#/components/schemas/Pagination"
required:
- data
ManagerReviewResponse:
title: ManagerReviewResponse
type: object
properties:
data:
$ref: "#/components/schemas/ManagerReview"
required:
- data
responses:
Forbidden:
description: Forbidden
content:
application/json:
schema:
$ref: "#/components/schemas/Error"
InternalServerError:
description: Internal Server Error
content:
application/json:
schema:
$ref: "#/components/schemas/Error"
NotFound:
description: The specified resource was not found
content:
application/json:
schema:
$ref: "#/components/schemas/Error"
Unauthorized:
description: Unauthorized
content:
application/json:
schema:
$ref: "#/components/schemas/Error"
BadRequest:
description: The request path parameters, query parameters or headers are not valid
content:
application/json:
schema:
$ref: "#/components/schemas/Error"
ServiceUnavailable:
description: Service Unavailable - endpoint rate limit exceeded
content:
application/json:
schema:
$ref: "#/components/schemas/Error"
TooManyRequests:
description: Too Many Requests - client rate limit exceeded
content:
application/json:
schema:
$ref: "#/components/schemas/Error"
securitySchemes:
Oauth2:
type: oauth2
flows:
clientCredentials:
tokenUrl: /oauth2/token
scopes:
employees-read: Grants read access to employees resources
employee-demographics-read: Grants access to employee demographics
performance-evaluations-read: Grants access to employee performance evaluations
examples: {}
# Turns off 'Try It' feature in the Developer Portal
"x-readme": { "explorer-enabled": false }