> For the complete documentation index, see [llms.txt](https://guide.fariaedu.com/integrations-portal/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://guide.fariaedu.com/integrations-portal/schoolsbuddy/public-rest-apis/external.md).

# External

## POST /api/v1/External/events

> Post events from external sources (e.g., Vectare).

```json
{"openapi":"3.0.1","info":{"title":"SchoolsBuddy Public API","version":"1.0"},"servers":[{"url":"https://publicapi-eu.schoolsbuddy.net","description":"EMEA Public Api server"},{"url":"https://publicapi-asia.schoolsbuddy.net","description":"Asia Public Api server"},{"url":"https://publicapi-us.schoolsbuddy.net","description":"US Public Api server"},{"url":"https://publicapi.schoolsbuddy.cn","description":"China Public Api server"},{"url":"https://identity-eu.schoolsbuddy.net","description":"EMEA Identity server"},{"url":"https://identity-asia.schoolsbuddy.net","description":"Asia Identity server"},{"url":"https://identity-us.schoolsbuddy.net","description":"US Identity server"},{"url":"https://accounts.schoolsbuddy.cn","description":"China Identity server"}],"security":[{"Bearer":[]}],"components":{"securitySchemes":{"Bearer":{"type":"apiKey","description":"Type \"Bearer\" followed by a space and a token.","name":"Authorization","in":"header"}},"schemas":{"EventRequestDto":{"required":["endDateTime","id","name","organisationId","source","startDateTime"],"type":"object","properties":{"organisationId":{"type":"integer","format":"int32"},"id":{"minLength":1,"type":"string"},"source":{"$ref":"#/components/schemas/ExternalSource"},"name":{"minLength":1,"type":"string"},"startDateTime":{"type":"string","format":"date-time"},"endDateTime":{"type":"string","format":"date-time"},"participants":{"type":"array","items":{"$ref":"#/components/schemas/EventParticipantDto"},"nullable":true}},"additionalProperties":false},"ExternalSource":{"enum":["Vectare"],"type":"string"},"EventParticipantDto":{"required":["attendeeStatus","misId","registerStatus"],"type":"object","properties":{"misId":{"minLength":1,"type":"string"},"attendanceNote":{"type":"string","nullable":true},"attendeeStatus":{"$ref":"#/components/schemas/ExternalAttendeeStatus"},"registerStatus":{"$ref":"#/components/schemas/ExternalRegisterStatus"}},"additionalProperties":false},"ExternalAttendeeStatus":{"enum":["NotExpected","Expected"],"type":"string"},"ExternalRegisterStatus":{"enum":["Unset","Present","Absent"],"type":"string"},"ProblemDetails":{"type":"object","properties":{"type":{"type":"string","nullable":true},"title":{"type":"string","nullable":true},"status":{"type":"integer","format":"int32","nullable":true},"detail":{"type":"string","nullable":true},"instance":{"type":"string","nullable":true}},"additionalProperties":{}},"ErrorResponse":{"type":"object","properties":{"code":{"type":"string","description":"Gets or sets the machine-readable error code (e.g.\r\n`VALIDATION_FAILED`, `RESOURCE_NOT_FOUND`,\r\n`INTERNAL_ERROR`) per cross-cutting-design.md §5.1.","nullable":true},"error":{"type":"string","description":"Gets or sets the human-readable error message.","nullable":true}},"additionalProperties":false,"description":"Structured body for 4xx / 5xx responses on the new Public API surface:\r\na machine-readable SchoolsBuddy.PublicAPI.Models.ErrorResponse.Code plus a human-readable\r\nSchoolsBuddy.PublicAPI.Models.ErrorResponse.Error. See cross-cutting-design.md §5.3. This is additive —\r\nexisting endpoints continue returning their legacy plain-string /\r\nModelState shapes until migrated by their per-controller ticket."}}},"paths":{"/api/v1/External/events":{"post":{"tags":["External"],"summary":"Post events from external sources (e.g., Vectare).","requestBody":{"description":"List of events","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/EventRequestDto"}}}}},"responses":{"200":{"description":"Success"},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}}
```

## PUT /api/v1/External/events

> Update or create events from external sources (e.g., Vectare).
> \
> This endpoint performs an upsert operation - updates existing events or creates new ones if they don't exist.

```json
{"openapi":"3.0.1","info":{"title":"SchoolsBuddy Public API","version":"1.0"},"servers":[{"url":"https://publicapi-eu.schoolsbuddy.net","description":"EMEA Public Api server"},{"url":"https://publicapi-asia.schoolsbuddy.net","description":"Asia Public Api server"},{"url":"https://publicapi-us.schoolsbuddy.net","description":"US Public Api server"},{"url":"https://publicapi.schoolsbuddy.cn","description":"China Public Api server"},{"url":"https://identity-eu.schoolsbuddy.net","description":"EMEA Identity server"},{"url":"https://identity-asia.schoolsbuddy.net","description":"Asia Identity server"},{"url":"https://identity-us.schoolsbuddy.net","description":"US Identity server"},{"url":"https://accounts.schoolsbuddy.cn","description":"China Identity server"}],"security":[{"Bearer":[]}],"components":{"securitySchemes":{"Bearer":{"type":"apiKey","description":"Type \"Bearer\" followed by a space and a token.","name":"Authorization","in":"header"}},"schemas":{"EventRequestDto":{"required":["endDateTime","id","name","organisationId","source","startDateTime"],"type":"object","properties":{"organisationId":{"type":"integer","format":"int32"},"id":{"minLength":1,"type":"string"},"source":{"$ref":"#/components/schemas/ExternalSource"},"name":{"minLength":1,"type":"string"},"startDateTime":{"type":"string","format":"date-time"},"endDateTime":{"type":"string","format":"date-time"},"participants":{"type":"array","items":{"$ref":"#/components/schemas/EventParticipantDto"},"nullable":true}},"additionalProperties":false},"ExternalSource":{"enum":["Vectare"],"type":"string"},"EventParticipantDto":{"required":["attendeeStatus","misId","registerStatus"],"type":"object","properties":{"misId":{"minLength":1,"type":"string"},"attendanceNote":{"type":"string","nullable":true},"attendeeStatus":{"$ref":"#/components/schemas/ExternalAttendeeStatus"},"registerStatus":{"$ref":"#/components/schemas/ExternalRegisterStatus"}},"additionalProperties":false},"ExternalAttendeeStatus":{"enum":["NotExpected","Expected"],"type":"string"},"ExternalRegisterStatus":{"enum":["Unset","Present","Absent"],"type":"string"},"ProblemDetails":{"type":"object","properties":{"type":{"type":"string","nullable":true},"title":{"type":"string","nullable":true},"status":{"type":"integer","format":"int32","nullable":true},"detail":{"type":"string","nullable":true},"instance":{"type":"string","nullable":true}},"additionalProperties":{}},"ErrorResponse":{"type":"object","properties":{"code":{"type":"string","description":"Gets or sets the machine-readable error code (e.g.\r\n`VALIDATION_FAILED`, `RESOURCE_NOT_FOUND`,\r\n`INTERNAL_ERROR`) per cross-cutting-design.md §5.1.","nullable":true},"error":{"type":"string","description":"Gets or sets the human-readable error message.","nullable":true}},"additionalProperties":false,"description":"Structured body for 4xx / 5xx responses on the new Public API surface:\r\na machine-readable SchoolsBuddy.PublicAPI.Models.ErrorResponse.Code plus a human-readable\r\nSchoolsBuddy.PublicAPI.Models.ErrorResponse.Error. See cross-cutting-design.md §5.3. This is additive —\r\nexisting endpoints continue returning their legacy plain-string /\r\nModelState shapes until migrated by their per-controller ticket."}}},"paths":{"/api/v1/External/events":{"put":{"tags":["External"],"summary":"Update or create events from external sources (e.g., Vectare).\r\nThis endpoint performs an upsert operation - updates existing events or creates new ones if they don't exist.","requestBody":{"description":"List of events","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/EventRequestDto"}}}}},"responses":{"200":{"description":"Success"},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}}
```