> ## 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.
# Batch create external knowledge
> This endpoint creates multiple external knowledge records in one call. Each record accepts the same fields as [Create a new external knowledge](/api-reference/external-knowledge/create-a-new-external-knowledge). Records are always created, not updated.
The batch is saved as a whole: if any record fails, nothing is saved and the error for that record is returned.
Maximum permitted batch size is 100.
## OpenAPI
````yaml /openapi.yaml post /external_knowledges/batch_save
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/batch_save:
post:
tags:
- External Knowledge
summary: Batch create external knowledge
description: >
This endpoint creates multiple external knowledge records in one call.
Each record accepts the same fields as [Create a new external
knowledge](/api-reference/external-knowledge/create-a-new-external-knowledge).
Records are always created, not updated.
The batch is saved as a whole: if any record fails, nothing is saved and
the error for that record is returned.
Maximum permitted batch size is 100.
operationId: batchSaveExternalKnowledges
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- external_knowledges
properties:
external_knowledges:
type: array
maxItems: 100
description: An array of external knowledge objects
items:
$ref: '#/components/schemas/ExternalKnowledgeCreate'
example:
external_knowledges:
- user_name: johnny
title: First Aid Certificate
provider: Red Cross
type: Certificate
date_obtained: 1/6/2021
expires: 1/6/2024
- user_name: mary
title: Forklift Licence
provider: WorkSafe
type: License
date_obtained: '2023-03-15'
responses:
'200':
description: Batch results
content:
application/json:
schema:
type: object
properties:
created:
type: integer
description: Number of records created
updated:
type: integer
description: Number of records updated
unchanged:
type: integer
description: Number of records unchanged
example:
created: 2
updated: 0
unchanged: 0
'401':
$ref: '#/components/responses/Unauthorized'
'406':
$ref: '#/components/responses/NotAcceptable'
'429':
$ref: '#/components/responses/TooManyRequests'
components:
schemas:
ExternalKnowledgeCreate:
type: object
required:
- user_name
- title
- provider
- date_obtained
properties:
user_name:
type: string
description: User name of the person this knowledge belongs to (case-insensitive)
knowledge_type:
description: >-
Required, unless `type` is given. `1` = Training, `2` = Certificate,
`3` = Qualification, `4` = License, `5` = Document, `6` =
Development Plan. Can also be sent as a string, eg `"1"`. Or use
`type`
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 ;. Unknown skills are ignored
category_1:
type: string
description: >-
Category name attained in the knowledge. 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. 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. 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"`
responses:
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.
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.