Ethena

Ethena Learners API

Learner information and operations.

GitHub OpenAPI

Documentation

📖
APIReference
https://api.goethena.com/docs/
📖
Documentation
https://help.goethena.com/hc/en-us/articles/28796851013773-Ethena-s-API
📖
Authentication
https://raw.githubusercontent.com/api-evangelist/ethena/refs/heads/main/authentication/ethena-authentication.yml

Specifications

⚙
OpenAPI
https://raw.githubusercontent.com/api-evangelist/ethena/refs/heads/main/openapi/ethena-learners-api-openapi.yml
⚙
AsyncAPI
https://raw.githubusercontent.com/api-evangelist/ethena/refs/heads/main/asyncapi/ethena-asyncapi.yml

Other Resources

🔗
Conventions
https://raw.githubusercontent.com/api-evangelist/ethena/refs/heads/main/conventions/ethena-conventions.yml
🔗
ErrorCatalog
https://raw.githubusercontent.com/api-evangelist/ethena/refs/heads/main/errors/ethena-problem-types.yml
🔗
Lifecycle
https://raw.githubusercontent.com/api-evangelist/ethena/refs/heads/main/lifecycle/ethena-lifecycle.yml
🔗
ChangeLog
https://raw.githubusercontent.com/api-evangelist/ethena/refs/heads/main/changelog/ethena-changelog.yml
🔗
Conformance
https://raw.githubusercontent.com/api-evangelist/ethena/refs/heads/main/conformance/ethena-conformance.yml
🔗
DataModel
https://raw.githubusercontent.com/api-evangelist/ethena/refs/heads/main/data-model/ethena-data-model.yml
🔗
Webhooks
https://raw.githubusercontent.com/api-evangelist/ethena/refs/heads/main/asyncapi/ethena-webhooks.yml

OpenAPI Specification

ethena-learners-api-openapi.yml Raw ↑ 
openapi: 3.1.0
info:
  version: 1.3.0
  title: Ethena Learner Training Campaigns Learners API
  termsOfService: https://app.goethena.com/legal-and-privacy
  contact:
    name: Contact support
    email: support@goethena.com
  x-logo:
    url: ./ethena-logo.png
    altText: Ethena logo
  description: 'The Ethena API allows you to view and manage learners and training information.


    # Accessing the API

    In order to get access to our API please work with your sales representative to get an

    API key provisioned and shared with you.


    Webhooks are not enabled by default, please work with your sales representative to have them enabled if you need them.


    # Changelog

    - **v1.0.0** - Initial release of the API, including learners, training campaigns, learner training campaigns, and learner training modules.

    - **v1.1.0** - Added webhooks operations and support for learner training campaign completed webhook.

    - **v1.2.0** - Remove separate language region property on learner and support Unicode Common Locale Data Repository language formats.

    - **v1.3.0** - Added filter parameters for learners (email, name), learner training modules (learnerStatus, trainingCampaignStatus), and learner training campaigns (learnerStatus, trainingCampaignStatus). Added training campaign status field to training campaigns.'
servers:
- url: https://api.goethena.com
tags:
- name: Learners
  description: Learner information and operations.
paths:
  /v1/learners:
    get:
      tags:
      - Learners
      summary: Get learners
      description: "Get many learners.\n\nThe query parameter filters are applied as `AND` conditions across different filters. \nIf multiple filters are used, the response will include only the learners that satisfy all the filters.\n\nWithin a single filter, multiple values are applied as `OR` conditions."
      operationId: getLearners
      parameters:
      - name: id
        in: query
        description: Use this parameter to filter learners by id.
        schema:
          type: array
          maxItems: 25
          items:
            description: The unique identifier of a learner.
            type: string
            pattern: ^[a-zA-Z0-9]+$
            example: abc123def4
        example:
        - abc123def4
        - xyz123abc4
      - name: status
        in: query
        description: Use this parameter to filter learners by status. By default, all statuses are returned.
        schema:
          type: array
          items:
            description: Status of the learner account. Active learners can access training. Deactivated and terminated learners cannot access training.
            type: string
            enum: &id001
            - ACTIVE
            - DEACTIVATED
            - TERMINATED
            example: ACTIVE
        example:
        - ACTIVE
      - name: email
        in: query
        description: Use this parameter to filter learners by exact email match within the tenant.
        schema:
          type: array
          maxItems: 25
          items:
            type: string
            format: email
        example:
        - first.last@your-domain.com
      - name: name
        in: query
        description: Use this parameter to filter learners by exact name match.
        schema:
          type: array
          maxItems: 25
          items:
            type: string
            minLength: 2
            maxLength: 100
        example:
        - First Last
      - name: limit
        in: query
        description: Use this parameter to limit the number of entities returned.
        schema:
          type: integer
          minimum: 1
          default: 25
          maximum: 100
      - example: abc123def25
        name: cursor
        in: query
        description: "Use this parameter to paginate through entities. The cursor is the `id` of the last entity you want to start from.\n\nTo get the first page, omit this parameter. \n\nTo get the next page, use the `id` of the last entity from the previous response. Continue paginating while `hasMore` is `true` in the response.\n\nExample workflow:\n1. GET /v1/{endpoint} → returns data + hasMore: true, last entity id: \"xyz789end\"\n2. GET /v1/{endpoint}?cursor=xyz789end → returns next page"
        schema:
          type: string
      security:
      - basic_auth: []
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                allOf:
                - type: object
                  properties:
                    limit:
                      type: integer
                    hasMore:
                      type: boolean
                    data:
                      type: array
                - type: object
                  properties:
                    data:
                      type: array
                      items:
                        type: object
                        required:
                        - id
                        - name
                        - email
                        - status
                        - country
                        - isManager
                        - language
                        - trainingUrl
                        properties:
                          id:
                            allOf:
                            - description: The unique identifier of a learner.
                              type: string
                              pattern: ^[a-zA-Z0-9]+$
                              example: abc123def4
                          name:
                            allOf:
                            - description: The learner's full name.
                              type: string
                              minLength: 2
                              maxLength: 100
                              example: First Last
                          status:
                            allOf:
                            - description: Status of the learner account. Active learners can access training. Deactivated and terminated learners cannot access training.
                              type: string
                              enum: *id001
                              example: ACTIVE
                          email:
                            allOf:
                            - description: The learner's unique email address.
                              type: string
                              format: email
                              maxLength: 255
                              example: first.last@{your-domain}.com
                          country:
                            allOf:
                            - description: The learner's country of employment. Three letter country code.
                              type: string
                              minLength: 3
                              maxLength: 3
                              enum:
                              - AFG
                              - ALA
                              - ALB
                              - DZA
                              - ASM
                              - AND
                              - AGO
                              - AIA
                              - ATA
                              - ATG
                              - ARG
                              - ARM
                              - ABW
                              - AUS
                              - AUT
                              - AZE
                              - BHS
                              - BHR
                              - BGD
                              - BRB
                              - BLR
                              - BEL
                              - BLZ
                              - BEN
                              - BMU
                              - BTN
                              - BOL
                              - BES
                              - BIH
                              - BWA
                              - BVT
                              - BRA
                              - IOT
                              - VGB
                              - BRN
                              - BGR
                              - BFA
                              - BDI
                              - CPV
                              - KHM
                              - CMR
                              - CAN
                              - CYM
                              - CAF
                              - TCD
                              - CHL
                              - CHN
                              - CXR
                              - CCK
                              - COL
                              - COM
                              - COG
                              - COD
                              - COK
                              - CRI
                              - CIV
                              - HRV
                              - CUB
                              - CUW
                              - CYP
                              - CZE
                              - DNK
                              - DJI
                              - DMA
                              - DOM
                              - ECU
                              - EGY
                              - SLV
                              - GNQ
                              - ERI
                              - EST
                              - SWZ
                              - ETH
                              - FLK
                              - FRO
                              - FJI
                              - FIN
                              - FRA
                              - GUF
                              - PYF
                              - ATF
                              - GAB
                              - GMB
                              - GEO
                              - DEU
                              - GHA
                              - GIB
                              - GRC
                              - GRL
                              - GRD
                              - GLP
                              - GUM
                              - GTM
                              - GGY
                              - GIN
                              - GNB
                              - GUY
                              - HTI
                              - HMD
                              - HND
                              - HKG
                              - HUN
                              - ISL
                              - IND
                              - IDN
                              - IRN
                              - IRQ
                              - IRL
                              - IMN
                              - ISR
                              - ITA
                              - JAM
                              - JPN
                              - JEY
                              - JOR
                              - KAZ
                              - KEN
                              - KIR
                              - KWT
                              - KGZ
                              - LAO
                              - LVA
                              - LBN
                              - LSO
                              - LBR
                              - LBY
                              - LIE
                              - LTU
                              - LUX
                              - MAC
                              - MDG
                              - MWI
                              - MYS
                              - MDV
                              - MLI
                              - MLT
                              - MHL
                              - MTQ
                              - MRT
                              - MUS
                              - MYT
                              - MEX
                              - FSM
                              - MDA
                              - MCO
                              - MNG
                              - MNE
                              - MSR
                              - MAR
                              - MOZ
                              - MMR
                              - NAM
                              - NRU
                              - NPL
                              - NLD
                              - NCL
                              - NZL
                              - NIC
                              - NER
                              - NGA
                              - NIU
                              - NFK
                              - PRK
                              - MKD
                              - MNP
                              - NOR
                              - OMN
                              - PAK
                              - PLW
                              - PSE
                              - PAN
                              - PNG
                              - PRY
                              - PER
                              - PHL
                              - PCN
                              - POL
                              - PRT
                              - PRI
                              - QAT
                              - REU
                              - ROU
                              - RUS
                              - RWA
                              - BLM
                              - SHN
                              - KNA
                              - LCA
                              - MAF
                              - SPM
                              - VCT
                              - WSM
                              - SMR
                              - STP
                              - SAU
                              - SEN
                              - SRB
                              - SYC
                              - SLE
                              - SGP
                              - SXM
                              - SVK
                              - SVN
                              - SLB
                              - SOM
                              - ZAF
                              - SGS
                              - KOR
                              - SSD
                              - ESP
                              - LKA
                              - SDN
                              - SUR
                              - SJM
                              - SWE
                              - CHE
                              - SYR
                              - TWN
                              - TJK
                              - TZA
                              - THA
                              - TLS
                              - TGO
                              - TKL
                              - TON
                              - TTO
                              - TUN
                              - TUR
                              - TKM
                              - TCA
                              - TUV
                              - UGA
                              - UKR
                              - ARE
                              - GBR
                              - USA
                              - UMI
                              - URY
                              - UZB
                              - VUT
                              - VAT
                              - VEN
                              - VNM
                              - VIR
                              - WLF
                              - ESH
                              - YEM
                              - ZMB
                              - ZWE
                              example: USA
                          state:
                            allOf:
                            - description: 'The learner''s state of employment. Two letter state code.


                                Validation rules:

                                - Required when country is "USA"

                                - Must be null or omitted for all other countries

                                - Empty strings ("") are not allowed


                                Examples:

                                - "USA" + "NY" ✅

                                - "USA" + null ❌

                                - "CAN" + null ✅

                                - "CAN" + "ON" ❌ (Canadian provinces not supported)'
                              type: string
                              minLength: 2
                              maxLength: 2
                              enum:
                              - AL
                              - AK
                              - AZ
                              - AR
                              - CA
                              - CO
                              - CT
                              - DE
                              - FL
                              - GA
                              - HI
                              - ID
                              - IL
                              - IN
                              - IA
                              - KS
                              - KY
                              - LA
                              - ME
                              - MD
                              - MA
                              - MI
                              - MN
                              - MS
                              - MO
                              - MT
                              - NE
                              - NV
                              - NH
                              - NJ
                              - NM
                              - NY
                              - NC
                              - ND
                              - OH
                              - OK
                              - OR
                              - PA
                              - RI
                              - SC
                              - SD
                              - TN
                              - TX
                              - UT
                              - VT
                              - VA
                              - WA
                              - WV
                              - WI
                              - WY
                              - AS
                              - DC
                              - FM
                              - GU
                              - MH
                              - MP
                              - PW
                              - PR
                              - VI
                              example: NY
                          isManager:
                            allOf:
                            - description: Whether the learner is a manager.
                              type: boolean
                              example: true
                          managerLearnerId:
                            allOf:
                            - description: The unique identifier of the learner's manager.
                              allOf:
                              - description: The unique identifier of a learner.
                                type: string
                                pattern: ^[a-zA-Z0-9]+$
                                example: abc123def4
                              example: xyz123abc4
                          department:
                            allOf:
                            - description: The department the learner belongs to.
                              type: string
                              maxLength: 255
                              example: Engineering
                          workerType:
                            allOf:
                            - description: The learner's worker type.
                              type: string
                              maxLength: 255
                              example: Full Time
                          customCategory:
                            allOf:
                            - description: The learner's custom category. Can be populated with any value. For example, the office or city of a learner.
                              type: string
                              maxLength: 255
                              example: Brooklyn
                          language:
                            allOf:
                            - description: "The learner's language. Represented as any Unicode CLDR language documented here: https://cldr.unicode.org/\n\n⚠️ Important: Use language codes (e.g., \"en\"), not language names (e.g., \"English\").\n\n✅ Common valid examples:\n  - \"en\": English\n  - \"es\": Spanish  \n  - \"es-419\": Spanish (Latin America)\n  - \"es-MX\": Spanish (Mexico)\n  - \"zh\": Chinese\n  - \"zh-TW\": Chinese (Taiwan)\n  - \"zh-Hant-HK\": Chinese (traditional, Hong Kong)\n  - \"fr\": French\n  - \"de\": German\n  \n❌ Common invalid examples, which will cause validation errors:\n  - \"English\" (use \"en\" instead)\n  - \"Spanish\" (use \"es\" instead)  \n  - \"Chinese\" (use \"zh\" instead)"
                              type: string
                              minLength: 2
                              maxLength: 32
                              example: en
                          trainingUrl:
                            allOf:
                            - description: 'The learner-specific link to their Ethena training dashboard.


                                For SSO companies, the URL includes the SSO connection parameter.

                                For non-SSO companies, the URL includes the learning center login key.'
                              type: string
                              format: uri
                              example: https://{ethena-domain}/learning?key={uuid}
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
                minProperties: 1
                description: JSON description of the issues based on the The Problem Details JSON Object [[RFC7807](https://tools.ietf.org/html/rfc7807)].
                required: &id002
                - title
                properties: &id003
                  title:
                    description: A short, human-readable summary of the problem type.
                    type: string
                  detail:
                    description: A human-readable explanation specific to this occurrence of the problem.
                    type: string
                  invalid-params:
                    description: An array of objects, each representing a parameter that was invalid.
                    type: array
                    items:
                      type: object
                      properties:
                        name:
                          type: string
                          description: The name of the invalid parameter.
                        reason:
                          type: string
                          description: The reason why the parameter is invalid.
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
                minProperties: 1
                description: JSON description of the issues based on the The Problem Details JSON Object [[RFC7807](https://tools.ietf.org/html/rfc7807)].
                required: *id002
                properties: *id003
    post:
      tags:
      - Learners
      summary: Create a new learner
      description: Create a new learner.
      operationId: createLearner
      security:
      - basic_auth: []
      requestBody:
        description: Learner to be created.
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - name
              - email
              - country
              - isManager
              - language
              properties:
                name:
                  allOf:
                  - description: The learner's full name.
                    type: string
                    minLength: 2
                    maxLength: 100
                    example: First Last
                email:
                  allOf:
                  - description: The learner's unique email address.
                    type: string
                    format: email
                    maxLength: 255
                    example: first.last@{your-domain}.com
                country:
                  allOf:
                  - description: The learner's country of employment. Three letter country code.
                    type: string
                    minLength: 3
                    maxLength: 3
                    enum:
                    - AFG
                    - ALA
                    - ALB
                    - DZA
                    - ASM
                    - AND
                    - AGO
                    - AIA
                    - ATA
                    - ATG
                    - ARG
                    - ARM
                    - ABW
                    - AUS
                    - AUT
                    - AZE
                    - BHS
                    - BHR
                    - BGD
                    - BRB
                    - BLR
                    - BEL
                    - BLZ
                    - BEN
                    - BMU
                    - BTN
                    - BOL
                    - BES
                    - BIH
                    - BWA
                    - BVT
                    - BRA
                    - IOT
                    - VGB
                    - BRN
                    - BGR
                    - BFA
                    - BDI
                    - CPV
                    - KHM
                    - CMR
                    - CAN
                    - CYM
                    - CAF
                    - TCD
                    - CHL
                    - CHN
                    - CXR
                    - CCK
                    - COL
                    - COM
                    - COG
                    - COD
                    - COK
                    - CRI
                    - CIV
                    - HRV
                    - CUB
                    - CUW
                    - CYP
                    - CZE
                    - DNK
                    - DJI
                    - DMA
                    - DOM
                    - ECU
                    - EGY
                    - SLV
                    - GNQ
                    - ERI
                    - EST
                    - SWZ
                    - ETH
                    - FLK
                    - FRO
                    - FJI
                    - FIN
                    - FRA
                    - GUF
                    - PYF
                    - ATF
                    - GAB
                    - GMB
                    - GEO
                    - DEU
                    - GHA
                    - GIB
                    - GRC
                    - GRL
                    - GRD
                    - GLP
                    - GUM
                    - GTM
                    - GGY
                    - GIN
                    - GNB
                    - GUY
                    - HTI
                    - HMD
                    - HND
                    - HKG
                    - HUN
                    - ISL
                    - IND
                    - IDN
                    - IRN
                    - IRQ
                    - IRL
                    - IMN
                    - ISR
                    - ITA
                    - JAM
                    - JPN
                    - JEY
                    - JOR
                    - KAZ
                    - KEN
                    - KIR
                    - KWT
                    - KGZ
                    - LAO
                    - LVA
                    - LBN
                    - LSO
                    - LBR
                    - LBY
                    - LIE
                    - LTU
                    - LUX
                    - MAC
                    - MDG
                    - MWI
                    - MYS
                    - MDV
                    - MLI
                    - MLT
                    - MHL
                    - MTQ
                    - MRT
                    - MUS
                    - MYT
                    - MEX
                    - FSM
                    - MDA
                    - MCO
                    - MNG
                    - MNE
                    - MSR
                    - MAR
                    - MOZ
                    - MMR
                    - NAM
                    - NRU
                    - NPL
                    - NLD
                    - NCL
                    - NZL
                    - NIC
                    - NER
                    - NGA
                    - NIU
                    - NFK
                    - PRK
                    - MKD
                    - MNP
                    - NOR
                    - OMN
                    - PAK
                    - PLW
                    - PSE
                    - PAN
                    - PNG
                    - PRY
                    - PER
                    - PHL
                    - PCN
                    - POL
                    - PRT
                    - PRI
                    - QAT
                    - REU
                    - ROU
                    - RUS
                    - RWA
                    - BLM
                    - SHN
                    - KNA
                    - LCA
                    - MAF
                    - SPM
                    - VCT
                    - WSM
                    - SMR
                    - STP
                    - SAU
                    - SEN
                    - SRB
                    - SYC
                    - SLE
                    - SGP
                    - SXM
                    - SVK
                    - SVN
                    - SLB
                    - SOM
                    - ZAF
                    - SGS
                    - KOR
                    - SSD
                    - ESP
                    - LKA
                    - SDN
                    - SUR
                    - SJM
                    - SWE
                    - CHE
                    - SYR
                    - TWN
                    - TJK
                    - TZA
                    - THA
                    - TLS
                    - TGO
                    - TKL
                    - TON
                    - TTO
                    - TUN
                    - TUR
                    - TKM
                    - TCA
                    - TUV
                    - UGA
                    - UKR
                    - ARE
                    - GBR
                    - USA
                    - UMI
                    - URY
                    - UZB
                    - VUT
                    - VAT
                    - VEN
                    - VNM
                    - VIR
                    - WLF
                    - ESH
                    - YEM
                    - ZMB
                    - ZWE
                    example: USA
                state:
                  allOf:
                  - description: 'The learner''s state of employment. Two letter state code.


                      Validation rules:

                      - Required when country is "USA"

                      - Must be null or omitted for all other countries

                      - Empty strings ("") are not allowed


                      Examples:

                      - "USA" + "NY" ✅

                      - "USA" + null ❌

                      - "CAN" + null ✅

                      - "CAN" + "ON" ❌ (Canadian provinces not supported)'
                    type: string
                    minLength: 2
                    maxLength: 2
                    enum:
                    - AL
                    - AK
                    - AZ
                    - AR
                    - CA
                    - CO
                    - CT
                    - DE
                    - FL
                    - GA


# --- truncated at 32 KB (73 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/ethena/refs/heads/main/openapi/ethena-learners-api-openapi.yml