360Learning External IDs API
The External IDs API from 360Learning — 2 operation(s) for external ids.
OpenAPI Specification
openapi: 3.1.0
info:
title: Bulk Authentication External IDs API
description: ''
version: 1.0.0
contact: {}
servers:
- url: https://app.360learning.com
description: Production EU
- url: https://app.us.360learning.com
description: Production US
tags:
- name: External IDs
paths:
/api/v2/external-ids:
post:
description: '> 🔑
>
> Required OAuth scope: `externalIds:write`.
Creates an external ID mapping.'
operationId: v2.externalIds.CreateExternalIdController_createExternalId
parameters:
- name: 360-api-version
in: header
description: The version of the API.
required: true
schema:
type: string
enum:
- v2.0
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/InputExternalIdDTO'
responses:
'201':
description: Returns the created external ID mapping.
content:
application/json:
schema:
$ref: '#/components/schemas/ExternalIdDTO'
'400':
description: The server cannot or will not process the request due to something that is perceived to be a client error.
content:
application/json:
schema:
oneOf:
- description: A mapping already exists for the given resource on this platform.
title: Mapping Already Exists
type: object
properties:
error:
type: object
properties:
code:
type: string
enum:
- mappingAlreadyExists
message:
type: string
example: A human-readable message to help with debugging.
required:
- code
- message
required:
- error
- description: The platform is one of the reserved ones.
title: Reserved Platform Name
type: object
properties:
error:
type: object
properties:
code:
type: string
enum:
- reservedPlatformName
message:
type: string
example: A human-readable message to help with debugging.
required:
- code
- message
required:
- error
- description: The value is already used with another resource.
title: Value Already Used
type: object
properties:
error:
type: object
properties:
code:
type: string
enum:
- valueAlreadyUsed
message:
type: string
example: A human-readable message to help with debugging.
required:
- code
- message
required:
- error
'401':
description: The given access token is either missing, invalid, has expired, or has been revoked.
content:
application/json:
schema:
type: object
properties:
error:
type: string
enum:
- invalid_token
required:
- error
'403':
description: The given access token does not have the required OAuth scope to execute the request.
content:
application/json:
schema:
title: Invalid Scope
type: object
properties:
error:
type: object
properties:
code:
type: string
enum:
- invalid_scope
message:
type: string
example: A human-readable message to help with debugging.
required:
- code
- message
required:
- error
'404':
description: The targeted resource does not exist.
content:
application/json:
schema:
title: Resource Not Found
type: object
properties:
error:
type: object
properties:
code:
type: string
enum:
- resourceNotFound
message:
type: string
example: A human-readable message to help with debugging.
required:
- code
- message
required:
- error
'429':
description: 'The client has sent too many requests in a short amount of time. '
content:
application/json:
schema:
type: object
properties:
error:
type: string
enum:
- tooManyRequests
required:
- error
security:
- oauth2: []
summary: Create an ID mapping
tags:
- External IDs
get:
description: '> 🔑
>
> Required OAuth scope: `externalIds:read`.
> 📖
>
> This endpoint is paginated with a page size of 5,000 external IDs. For more information, see the [Pagination guide](doc:pagination).
Lists all external ID mappings that link resources together.'
operationId: v2.externalIds.GetExternalIdsController_getExternalIds
parameters:
- name: 360-api-version
in: header
description: The version of the API.
required: true
schema:
type: string
enum:
- v2.0
- name: platform
required: false
in: query
style: deepObject
explode: true
description: 'Filter on **platform** property with LHS bracket notation.
Expected value format is a string.'
schema:
properties:
eq:
type: string
description: Filter on values equal to the given one
example: loremIpsum
ne:
type: string
description: Filter on values not equal to the given one
example: loremIpsum
in:
type: array
description: Filter on values including the given ones
items:
type: string
example: loremIpsum
nin:
type: array
description: Filter on values excluding the given ones
items:
type: string
example: loremIpsum
- name: type
required: false
in: query
style: deepObject
explode: true
description: 'Filter on **type** property with LHS bracket notation.
Expected value format is a string (`attempt`, `classroom`, `classroomAttendance`, `classroomAttendanceSheet`, `classroomSlot`, `classroomSlotRegistration`, `course`, `group`, `learningNeed`, `path`, `pathEnrollment`, `pathSession`, `pathTracking`, `registrationRequest`, `user`).'
schema:
properties:
eq:
type: string
description: Filter on values equal to the given one
example: attempt
enum:
- attempt
- classroom
- classroomAttendance
- classroomAttendanceSheet
- classroomSlot
- classroomSlotRegistration
- course
- group
- learningNeed
- path
- pathEnrollment
- pathSession
- pathTracking
- registrationRequest
- user
ne:
type: string
description: Filter on values not equal to the given one
example: attempt
enum:
- attempt
- classroom
- classroomAttendance
- classroomAttendanceSheet
- classroomSlot
- classroomSlotRegistration
- course
- group
- learningNeed
- path
- pathEnrollment
- pathSession
- pathTracking
- registrationRequest
- user
in:
type: array
description: Filter on values including the given ones
items:
type: string
example: attempt
enum:
- attempt
- classroom
- classroomAttendance
- classroomAttendanceSheet
- classroomSlot
- classroomSlotRegistration
- course
- group
- learningNeed
- path
- pathEnrollment
- pathSession
- pathTracking
- registrationRequest
- user
nin:
type: array
description: Filter on values excluding the given ones
items:
type: string
example: attempt
enum:
- attempt
- classroom
- classroomAttendance
- classroomAttendanceSheet
- classroomSlot
- classroomSlotRegistration
- course
- group
- learningNeed
- path
- pathEnrollment
- pathSession
- pathTracking
- registrationRequest
- user
- name: value
required: false
in: query
style: deepObject
explode: true
description: 'Filter on **value** property with LHS bracket notation.
Expected value format is a string.'
schema:
properties:
eq:
type: string
description: Filter on values equal to the given one
example: loremIpsum
ne:
type: string
description: Filter on values not equal to the given one
example: loremIpsum
in:
type: array
description: Filter on values including the given ones
items:
type: string
example: loremIpsum
nin:
type: array
description: Filter on values excluding the given ones
items:
type: string
example: loremIpsum
- name: targetId
required: false
in: query
style: deepObject
explode: true
description: 'Filter on **targetId** property with LHS bracket notation.
Expected value format is a valid ID (24 digits or letters).'
schema:
properties:
eq:
type: string
format: ObjectId
pattern: ^[a-fA-F0-9]{24}$
description: Filter on values equal to the given one
example: 507f1f77bcf86cd799439011
ne:
type: string
format: ObjectId
pattern: ^[a-fA-F0-9]{24}$
description: Filter on values not equal to the given one
example: 507f1f77bcf86cd799439011
in:
type: array
description: Filter on values including the given ones
items:
type: string
format: ObjectId
pattern: ^[a-fA-F0-9]{24}$
example: 507f1f77bcf86cd799439011
nin:
type: array
description: Filter on values excluding the given ones
items:
type: string
format: ObjectId
pattern: ^[a-fA-F0-9]{24}$
example: 507f1f77bcf86cd799439011
responses:
'200':
description: Returns one page of 5000 external IDs.
headers:
Link:
schema:
type: string
description: 'URL (between `<` `>`) to fetch the immediate next page of results. For more information, see our [Pagination guide](doc:pagination).
⚠️ Only included if there is another page of results.'
example: <my/resource/url>; rel="next"
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/ExternalIdDTO'
'401':
description: The given access token is either missing, invalid, has expired, or has been revoked.
content:
application/json:
schema:
type: object
properties:
error:
type: string
enum:
- invalid_token
required:
- error
'403':
description: The given access token does not have the required OAuth scope to execute the request.
content:
application/json:
schema:
title: Invalid Scope
type: object
properties:
error:
type: object
properties:
code:
type: string
enum:
- invalid_scope
message:
type: string
example: A human-readable message to help with debugging.
required:
- code
- message
required:
- error
'429':
description: 'The client has sent too many requests in a short amount of time. '
content:
application/json:
schema:
type: object
properties:
error:
type: string
enum:
- tooManyRequests
required:
- error
security:
- oauth2: []
summary: List all ID mappings
tags:
- External IDs
/api/v2/external-ids/{mappingId}:
delete:
description: '> 🔑
>
> Required OAuth scope: `externalIds:write`.
Deletes a specific external ID mapping given its unique ID.'
operationId: v2.externalIds.DeleteExternalIdController_deleteExternalId
parameters:
- name: 360-api-version
in: header
description: The version of the API.
required: true
schema:
type: string
enum:
- v2.0
- name: mappingId
required: true
in: path
description: The unique ID that identifies the resources mapping.
schema:
format: ObjectId
pattern: ^[a-fA-F0-9]{24}$
example: 507f1f77bcf86cd799439011
type: string
responses:
'204':
description: Deletes a specific external ID mapping.
'400':
description: The platform is one of the reserved ones.
content:
application/json:
schema:
title: Reserved Platform Name
type: object
properties:
error:
type: object
properties:
code:
type: string
enum:
- reservedPlatformName
message:
type: string
example: A human-readable message to help with debugging.
required:
- code
- message
required:
- error
'401':
description: The given access token is either missing, invalid, has expired, or has been revoked.
content:
application/json:
schema:
type: object
properties:
error:
type: string
enum:
- invalid_token
required:
- error
'403':
description: The given access token does not have the required OAuth scope to execute the request.
content:
application/json:
schema:
title: Invalid Scope
type: object
properties:
error:
type: object
properties:
code:
type: string
enum:
- invalid_scope
message:
type: string
example: A human-readable message to help with debugging.
required:
- code
- message
required:
- error
'404':
description: The given `mappingId` does not correspond to any existing mapping.
content:
application/json:
schema:
title: Mapping Id Not Found
type: object
properties:
error:
type: object
properties:
code:
type: string
enum:
- mappingIdNotFound
message:
type: string
example: A human-readable message to help with debugging.
required:
- code
- message
required:
- error
'429':
description: 'The client has sent too many requests in a short amount of time. '
content:
application/json:
schema:
type: object
properties:
error:
type: string
enum:
- tooManyRequests
required:
- error
security:
- oauth2: []
summary: Delete an ID mapping
tags:
- External IDs
put:
description: '> 🔑
>
> Required OAuth scope: `externalIds:write`.
Replaces an existing external ID mapping with the provided data.'
operationId: v2.externalIds.UpdateExternalIdController_updateExternalId
parameters:
- name: 360-api-version
in: header
description: The version of the API.
required: true
schema:
type: string
enum:
- v2.0
- name: mappingId
required: true
in: path
description: The unique ID that identifies the resources mapping.
schema:
format: ObjectId
pattern: ^[a-fA-F0-9]{24}$
example: 507f1f77bcf86cd799439011
type: string
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/InputExternalIdDTO'
responses:
'200':
description: Returns the updated external ID mapping.
content:
application/json:
schema:
$ref: '#/components/schemas/ExternalIdDTO'
'400':
description: The server cannot or will not process the request due to something that is perceived to be a client error.
content:
application/json:
schema:
oneOf:
- description: The platform is one of the reserved ones.
title: Reserved Platform Name
type: object
properties:
error:
type: object
properties:
code:
type: string
enum:
- reservedPlatformName
message:
type: string
example: A human-readable message to help with debugging.
required:
- code
- message
required:
- error
- description: The target already has an external ID on this platform.
title: Target Already Mapped
type: object
properties:
error:
type: object
properties:
code:
type: string
enum:
- targetAlreadyMapped
message:
type: string
example: A human-readable message to help with debugging.
required:
- code
- message
required:
- error
- description: The value is already used with another resource.
title: Value Already Used
type: object
properties:
error:
type: object
properties:
code:
type: string
enum:
- valueAlreadyUsed
message:
type: string
example: A human-readable message to help with debugging.
required:
- code
- message
required:
- error
'401':
description: The given access token is either missing, invalid, has expired, or has been revoked.
content:
application/json:
schema:
type: object
properties:
error:
type: string
enum:
- invalid_token
required:
- error
'403':
description: The given access token does not have the required OAuth scope to execute the request.
content:
application/json:
schema:
title: Invalid Scope
type: object
properties:
error:
type: object
properties:
code:
type: string
enum:
- invalid_scope
message:
type: string
example: A human-readable message to help with debugging.
required:
- code
- message
required:
- error
'404':
description: The server cannot find the requested resource.
content:
application/json:
schema:
oneOf:
- description: The given `mappingId` does not correspond to any existing mapping.
title: Mapping Id Not Found
type: object
properties:
error:
type: object
properties:
code:
type: string
enum:
- mappingIdNotFound
message:
type: string
example: A human-readable message to help with debugging.
required:
- code
- message
required:
- error
- description: The targeted resource does not exist.
title: Resource Not Found
type: object
properties:
error:
type: object
properties:
code:
type: string
enum:
- resourceNotFound
message:
type: string
example: A human-readable message to help with debugging.
required:
- code
- message
required:
- error
'429':
description: 'The client has sent too many requests in a short amount of time. '
content:
application/json:
schema:
type: object
properties:
error:
type: string
enum:
- tooManyRequests
required:
- error
security:
- oauth2: []
summary: Replace an ID mapping
tags:
- External IDs
components:
schemas:
InputExternalIdDTO:
title: Input External Id
type: object
properties:
platform:
type: string
description: The name of the platform where the external ID comes from.
example: external catalog
minLength: 1
targetId:
type: string
description: The resource ID to which the external ID is linked.
format: ObjectId
example: 507f1f77bcf86cd799439011
pattern: ^[a-fA-F0-9]{24}$
targetType:
type: string
enum:
- attempt
- classroom
- classroomAttendance
- classroomAttendanceSheet
- classroomSlot
- classroomSlotRegistration
- course
- group
- learningNeed
- path
- pathEnrollment
- pathSession
- pathTracking
- registrationRequest
- user
description: The resource type to which the external ID is linked.
example: course
value:
type: string
description: The value of the external ID.
example: 945628-01
minLength: 1
required:
- platform
- targetId
- targetType
- value
ExternalIdDTO:
title: External Id
type: object
properties:
platform:
type: string
description: The name of the platform where the external ID comes from.
example: external catalog
minLength: 1
targetId:
type: string
description: The resource ID to which the external ID is linked.
format: ObjectId
example: 507f1f77bcf86cd799439011
pattern: ^[a-fA-F0-9]{24}$
targetType:
type: string
enum:
- attempt
- classroom
- classroomAttendance
- classroomAttendanceSheet
- classroomSlot
- classroomSlotRegistration
- course
- group
- learningNeed
- path
- pathEnrollment
- pathSession
- pathTracking
- registrationRequest
- user
description: The resource type to which the external ID is linked.
example: course
value:
type: string
description: The value of the external ID.
example: 945628-01
minLength: 1
_id:
type: string
description: The unique ID that identifies the resources mapping.
format: ObjectId
example: 507f1f77bcf86cd799439011
pattern: ^[a-fA-F0-9]{24}$
required:
- platform
- targetId
- targetType
- value
- _id
securitySchemes:
oauth2:
type: oauth2
flows: {}
description: 'Use the token from the authentication endpoint in the Authorization header.
Example: `Authorization: Bearer <token>`'