> ## Documentation Index
> Fetch the complete documentation index at: https://api-docs.tribalhabits.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Update an external knowledge

> This endpoint updates an existing external knowledge record. Only fields that are supplied will be updated. The user cannot be changed with this endpoint. Skills and categories are only changed when the request includes them. To clear an optional field, send an empty string, eg `"notes": ""`. Returns `404` if the record does not exist.

`id` is the unique identifier of an external knowledge record.

The country and region codes can be found in this site: [https://github.com/country-regions/country-region-data/blob/master/data.json](https://github.com/country-regions/country-region-data/blob/master/data.json)




## OpenAPI

````yaml /openapi.yaml put /external_knowledges/{id}
openapi: 3.1.0
info:
  title: Tribal Habits Public API
  version: '1'
  description: >
    The Tribal Habits Public API V1. Use it to manage your Tribal Habits user
    accounts (list, show, create and update) and other entities.


    Replace `myorg` in the server URL with your organisation's subdomain. See
    [Vanity URL](/vanity-url) if you use your own domain.
servers:
  - url: https://myorg.tribalhabits.com/papi
security:
  - ApiKeyHeader: []
tags:
  - name: Users
    description: Users
  - name: Topics
    description: Topics
  - name: Pathways
    description: Pathways
  - name: Enrolments
    description: Topic and Pathway Enrolments
  - name: Certificates
    description: >-
      Certificate generation and retrieval for completed topic and pathway
      enrolments.
  - name: External Knowledge
    description: Knowledge obtained from a source external of Tribal Habits.
  - name: Webhooks
    description: >-
      Webhooks triggered from certain actions in code that will call URLs
      assigned by you.
paths:
  /external_knowledges/{id}:
    parameters:
      - name: id
        in: path
        required: true
        schema:
          type: integer
        example: 12345
    put:
      tags:
        - External Knowledge
      summary: Update an external knowledge
      description: >
        This endpoint updates an existing external knowledge record. Only fields
        that are supplied will be updated. The user cannot be changed with this
        endpoint. Skills and categories are only changed when the request
        includes them. To clear an optional field, send an empty string, eg
        `"notes": ""`. Returns `404` if the record does not exist.


        `id` is the unique identifier of an external knowledge record.


        The country and region codes can be found in this site:
        [https://github.com/country-regions/country-region-data/blob/master/data.json](https://github.com/country-regions/country-region-data/blob/master/data.json)
      operationId: updateExternalKnowledge
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ExternalKnowledgeUpdate'
            example:
              title: title1
              provider: prov1
              knowledge_type: 1
              date_obtained: 1/6/2021
      responses:
        '200':
          description: The updated external knowledge record
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExternalKnowledge'
              examples:
                example:
                  $ref: '#/components/examples/ExternalKnowledge'
        '400':
          $ref: '#/components/responses/BadRequestGeneric'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '406':
          $ref: '#/components/responses/NotAcceptable'
        '429':
          $ref: '#/components/responses/TooManyRequests'
components:
  schemas:
    ExternalKnowledgeUpdate:
      type: object
      properties:
        user_name:
          type: string
          description: >-
            Identifies whose skills to update. Only needed with
            `skills_attained` when the record belongs to more than one user;
            otherwise `400` is returned
        knowledge_type:
          description: >-
            `1` = Training, `2` = Certificate, `3` = Qualification, `4` =
            License, `5` = Document, `6` = Development Plan. Can also be sent as
            a string, eg `"1"`
          type: integer
          enum:
            - 1
            - 2
            - 3
            - 4
            - 5
            - 6
        type:
          type: string
          description: >-
            Alternative to `knowledge_type`, as text: `Training`, `Certificate`,
            `Qualification`, `License`, `Document` or `Development Plan`
            (case-insensitive). Required to use `document_type` or the
            Development Plan fields
        document_type:
          type: string
          description: >-
            For `type` `Document` only. The type of Document, eg General,
            Employment, Financial, Medical, Performance, Policy, Travel,
            Registration, Membership. Stored in `code`
        title:
          type: string
          description: >-
            Title of external knowledge. Set automatically to `Development Plan`
            for Development Plans
        code:
          type: string
          description: Optional code for the external knowledge
        provider:
          type: string
          description: Provider
        date_obtained:
          type: string
          description: >-
            The date you obtained this knowledge. Formats: 'yyyy-mm-dd',
            'dd/mm/yyyy' or 'dd/mm/yy'. `date` is accepted as an alternative
            name
        certificate_number:
          type: string
          description: Certificate Number
        country_obtained:
          type: string
          description: Country in code form (eg 'AU' for Australia)
        state_obtained:
          type: string
          description: >-
            State or Region in code form (eg 'NSW'). `region_obtained` is
            accepted as an alternative name
        expires:
          type: string
          description: Date the knowledge expires. Same formats as `date_obtained`
        qualification_level:
          type: string
          description: >-
            Qualification level, eg `Certificate IV`, `Diploma`, `Bachelor
            Degree`
        assessment_score:
          type: number
          description: Assessment score as a decimal, eg 1.2
        total_time:
          type: integer
          description: Time in minutes, as a whole number
        notes:
          type: string
          description: Notes
        klass:
          type: string
          description: Class of knowledge. `class` is accepted as an alternative name
        reviewer:
          type: string
          description: For `type` `Development Plan` only. Stored in `provider`
        date_signed:
          type: string
          description: For `type` `Development Plan` only. Stored in `date_obtained`
        next_review_date:
          type: string
          description: For `type` `Development Plan` only. Stored in `expires`
        stage:
          type: string
          enum:
            - Initial
            - Mid Review
            - End Review
          description: >-
            For `type` `Development Plan` only. `Initial`, `Mid Review` or `End
            Review`. Stored in `code`
        development_focus:
          type: string
          enum:
            - At Level
            - Transition
            - Progression
          description: 'For Development Plans: `At Level`, `Transition` or `Progression`'
        skills_attained:
          type: string
          description: >-
            Skill names attained by this knowledge. Separate multiple skills
            with ;. Replaces the current skills; send an empty value to remove
            them. Unknown skills are ignored
        category_1:
          type: string
          description: >-
            Category name attained in the knowledge. The categories sent replace
            the current ones; if no category fields are sent, the categories are
            unchanged. Unknown categories return `400`
        category_1_points:
          type: number
          description: >-
            Points for category 1, eg `10` or `12.5`. Stored to 2 decimal
            places. Can also be sent as a numeric string, eg `"10"`
        category_1_time:
          type: number
          description: >-
            Time in minutes for category 1, eg `60` or `90.5`. Can also be sent
            as a numeric string, eg `"60"`
        category_2:
          type: string
          description: >-
            Category name attained in the knowledge. The categories sent replace
            the current ones; if no category fields are sent, the categories are
            unchanged. Unknown categories return `400`
        category_2_points:
          type: number
          description: >-
            Points for category 2, eg `10` or `12.5`. Stored to 2 decimal
            places. Can also be sent as a numeric string, eg `"10"`
        category_2_time:
          type: number
          description: >-
            Time in minutes for category 2, eg `60` or `90.5`. Can also be sent
            as a numeric string, eg `"60"`
        category_3:
          type: string
          description: >-
            Category name attained in the knowledge. The categories sent replace
            the current ones; if no category fields are sent, the categories are
            unchanged. Unknown categories return `400`
        category_3_points:
          type: number
          description: >-
            Points for category 3, eg `10` or `12.5`. Stored to 2 decimal
            places. Can also be sent as a numeric string, eg `"10"`
        category_3_time:
          type: number
          description: >-
            Time in minutes for category 3, eg `60` or `90.5`. Can also be sent
            as a numeric string, eg `"60"`
    ExternalKnowledge:
      type: object
      properties:
        id:
          type: integer
          description: >-
            Unique identifier of the external knowledge record, used with show
            and update
        knowledge_type:
          type: integer
          enum:
            - 1
            - 2
            - 3
            - 4
            - 5
            - 6
          description: >-
            `1` = Training, `2` = Certificate, `3` = Qualification, `4` =
            License, `5` = Document, `6` = Development Plan
        title:
          type: string
        code:
          type:
            - string
            - 'null'
          description: >-
            Code for the knowledge. For Documents this holds the document type,
            and for Development Plans the stage
        provider:
          type: string
        date_obtained:
          type: string
          description: Date in the form 'yyyy-mm-dd'
        certificate_number:
          type:
            - string
            - 'null'
        country_obtained:
          type:
            - string
            - 'null'
        state_obtained:
          type:
            - string
            - 'null'
          description: State or region code
        expires:
          type:
            - string
            - 'null'
          description: Date in the form 'yyyy-mm-dd'
        qualification_level:
          type:
            - string
            - 'null'
        assessment_score:
          type:
            - number
            - 'null'
        total_time:
          type:
            - integer
            - 'null'
        notes:
          type:
            - string
            - 'null'
        klass:
          type:
            - string
            - 'null'
          description: Class of knowledge
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
        development_focus:
          type:
            - string
            - 'null'
  examples:
    ExternalKnowledge:
      summary: An external knowledge record
      value:
        id: 12345
        knowledge_type: 1
        title: title1
        code: code1
        provider: prov1
        date_obtained: '2021-06-01'
        certificate_number: CI1
        country_obtained: AU
        state_obtained: NSW
        expires: null
        qualification_level: null
        assessment_score: 1
        total_time: 2
        notes: Notes
        klass: ClassA
        created_at: '2019-08-08T15:51:31.424+10:00'
        updated_at: '2020-01-22T14:38:39.099+11:00'
        development_focus: null
  responses:
    BadRequestGeneric:
      description: >-
        Bad Request - The request is missing a required parameter or has an
        invalid value. See the response body for more details
      content:
        application/json:
          schema:
            type: string
    Unauthorized:
      description: >-
        Unauthorized - The request does not include the API key, the API key is
        incorrect, or API access is not enabled on your plan.
    NotFound:
      description: Not Found - The specified resource or endpoint could not be found
      content:
        application/json:
          schema:
            type: string
          example: not found
    NotAcceptable:
      description: >-
        Not Acceptable - A `POST` or `PUT` request had a `Content-Type` header
        other than `application/json`
    TooManyRequests:
      description: >-
        Too Many Requests - You have exceeded the rate limit. See [Rate
        limits](/rate-limits)
      headers:
        Retry-After:
          description: Number of seconds until the rate limit window resets
          schema:
            type: integer
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: string
              retry_after_seconds:
                type: integer
          example:
            error: Rate limit exceeded. Please slow down.
            retry_after_seconds: 23
  securitySchemes:
    ApiKeyHeader:
      type: apiKey
      in: header
      name: Authorization
      description: >
        Your organisation's API key, sent as `Authorization: my_api_key`. The
        key can also be passed as an `api_key` query parameter. See
        [Authentication](/authentication).

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.