> ## Documentation Index > Fetch the complete documentation index at: https://docs-v2.sortx.co.uk/llms.txt > Use this file to discover all available pages before exploring further. # Instruct event > Instruct an eligible contractor for the visit (or change the instructed contractor before it is booked) ## OpenAPI ````yaml /openapi.json post /planned-maintenance/events/{id}/instruct openapi: 3.1.0 info: title: SortX API version: 1.0.0 description: >- Reactive repairs, planned maintenance, compliance and the repairs desk for UK letting agents and property managers. servers: - url: https://api.sortx.co.uk description: Production security: [] tags: - name: tenants - name: entitlements - name: events - name: workspace-settings - name: operational-catalogues - name: money - name: contacts - name: properties - name: address-lookup - name: tenancies - name: contractor-invoices - name: keys - name: inspections - name: handovers - name: planned-maintenance - name: contractors - name: documents - name: compliance - name: activity - name: tasks - name: today - name: reports - name: workspace-search - name: calendar - name: telephony - name: maintenance-pro - name: front-desk - name: maintenance-pro-public - name: maintenance-pro-contractor paths: /planned-maintenance/events/{id}/instruct: post: tags: - planned-maintenance summary: Instruct event description: >- Instruct an eligible contractor for the visit (or change the instructed contractor before it is booked) operationId: planned-maintenance.instructEvent parameters: - name: id in: path schema: type: string required: true requestBody: content: application/json: schema: type: object properties: requestId: type: string expectedRevision: anyOf: - type: number - type: string enum: - Infinity - '-Infinity' - NaN contractorContactId: type: string notes: anyOf: - anyOf: - type: string - type: 'null' - type: 'null' override: anyOf: - anyOf: - type: object properties: reason: type: string required: - reason additionalProperties: false - type: 'null' - type: 'null' required: - requestId - expectedRevision - contractorContactId additionalProperties: false required: true responses: '200': description: Success content: application/json: schema: $ref: '#/components/schemas/ServiceEventDetailRow' '400': description: >- TenantCreateRejected | ConfigMissing | IntegrationRejected | AuthRejected | RegistrationRejected | UnknownIntegration | WebhookUnroutable | RateUnavailable content: application/json: schema: anyOf: - $ref: '#/components/schemas/TenantCreateRejectedEncoded' - $ref: '#/components/schemas/ConfigMissingEncoded' - $ref: '#/components/schemas/IntegrationRejectedEncoded' - $ref: '#/components/schemas/AuthRejectedEncoded' - $ref: '#/components/schemas/RegistrationRejectedEncoded' - $ref: '#/components/schemas/UnknownIntegrationEncoded' - $ref: '#/components/schemas/WebhookUnroutableEncoded' - $ref: '#/components/schemas/RateUnavailableEncoded' - $ref: '#/components/schemas/PlannedInputInvalid' '401': description: Unauthenticated | WebhookRejected | ApiKeyRejected content: application/json: schema: anyOf: - $ref: '#/components/schemas/UnauthenticatedEncoded' - $ref: '#/components/schemas/WebhookRejectedEncoded' - $ref: '#/components/schemas/ApiKeyRejectedEncoded' '402': description: TenantSuspended content: application/json: schema: $ref: '#/components/schemas/TenantSuspendedEncoded' '403': description: >- EntitlementMissing | NotAMember | ScopeUnknown | ScopeMissing | TenantMismatch | WorkspaceOwnerRequired | WorkspaceRoleRequired content: application/json: schema: anyOf: - $ref: '#/components/schemas/EntitlementMissingEncoded' - $ref: '#/components/schemas/NotAMemberEncoded' - $ref: '#/components/schemas/ScopeUnknownEncoded' - $ref: '#/components/schemas/ScopeMissingEncoded' - $ref: '#/components/schemas/TenantMismatchEncoded' - $ref: '#/components/schemas/ContractorForbidden' - $ref: '#/components/schemas/WorkspaceOwnerRequiredEncoded' - $ref: '#/components/schemas/WorkspaceRoleRequiredEncoded' '404': description: TenantNotFound | ModuleRequestNotFound content: application/json: schema: anyOf: - $ref: '#/components/schemas/TenantNotFoundEncoded' - $ref: '#/components/schemas/ModuleRequestNotFoundEncoded' - $ref: '#/components/schemas/PlannedNotFound' '409': description: WebhookDuplicate | RegistrationConflict | MoneyBusy content: application/json: schema: anyOf: - $ref: '#/components/schemas/WebhookDuplicateEncoded' - $ref: '#/components/schemas/RegistrationConflictEncoded' - $ref: '#/components/schemas/PlannedStale' - $ref: '#/components/schemas/PlannedRequestConflict' - $ref: '#/components/schemas/PlannedTransitionInvalid' - $ref: '#/components/schemas/ContractorIneligible' - $ref: '#/components/schemas/MoneyBusyEncoded' '429': description: RateLimited content: application/json: schema: $ref: '#/components/schemas/RateLimitedEncoded' '503': description: IntegrationUnavailable content: application/json: schema: $ref: '#/components/schemas/IntegrationUnavailableEncoded' security: - apiKey: [] components: schemas: ServiceEventDetailRow: type: object properties: id: type: string programmeId: type: string programmeReference: type: string programmeName: type: string occurrence: anyOf: - type: number - type: string enum: - Infinity - '-Infinity' - NaN reference: type: string status: type: string enum: - due - instructed - booked - completed - cancelled reviewState: anyOf: - type: string enum: - pending - accepted - rejected - type: 'null' dueOn: type: string instructBy: type: string overdue: type: boolean revisit: type: boolean statutory: type: boolean propertyId: anyOf: - type: string - type: 'null' propertyLabel: anyOf: - type: string - type: 'null' blockId: anyOf: - type: string - type: 'null' blockLabel: anyOf: - type: string - type: 'null' assetId: anyOf: - type: string - type: 'null' assetLabel: anyOf: - type: string - type: 'null' complianceKind: anyOf: - type: string enum: - gas_safety - eicr - epc - smoke_co - type: 'null' contractorContactId: anyOf: - type: string - type: 'null' contractorName: anyOf: - type: string - type: 'null' instructedAt: anyOf: - type: string - type: 'null' instructionNotes: anyOf: - type: string - type: 'null' instructedAutomatically: type: boolean autoInstructSkippedReason: anyOf: - type: string - type: 'null' booking: anyOf: - type: object properties: appointmentId: type: string status: type: string enum: - held - confirmed - cancelled - done startsAt: type: string endsAt: type: string staffId: anyOf: - type: string - type: 'null' staffName: anyOf: - type: string - type: 'null' revision: anyOf: - type: number - type: string enum: - Infinity - '-Infinity' - NaN required: - appointmentId - status - startsAt - endsAt - staffId - staffName - revision additionalProperties: false - type: 'null' completedOn: anyOf: - type: string - type: 'null' completedAt: anyOf: - type: string - type: 'null' completedByUserId: anyOf: - type: string - type: 'null' completionNotes: anyOf: - type: string - type: 'null' reviewedAt: anyOf: - type: string - type: 'null' reviewedByUserId: anyOf: - type: string - type: 'null' reviewNotes: anyOf: - type: string - type: 'null' rejectionReason: anyOf: - type: string - type: 'null' remedialRepair: anyOf: - type: object properties: id: type: string reference: anyOf: - type: string - type: 'null' required: - id - reference additionalProperties: false - type: 'null' nextEventId: anyOf: - type: string - type: 'null' certificateDocumentId: anyOf: - type: string - type: 'null' costCodeId: anyOf: - type: string - type: 'null' cancelledAt: anyOf: - type: string - type: 'null' cancelReason: anyOf: - type: string - type: 'null' evidenceCount: anyOf: - type: number - type: string enum: - Infinity - '-Infinity' - NaN revision: anyOf: - type: number - type: string enum: - Infinity - '-Infinity' - NaN createdAt: type: string updatedAt: type: string evidence: anyOf: - type: array items: type: object properties: documentId: type: string name: type: string contentType: anyOf: - type: string - type: 'null' kind: type: string createdAt: type: string archivedAt: anyOf: - type: string - type: 'null' purged: type: boolean required: - documentId - name - contentType - kind - createdAt - archivedAt - purged additionalProperties: false - type: 'null' certificate: anyOf: - type: object properties: documentId: type: string name: type: string kind: type: string reference: anyOf: - type: string - type: 'null' issuedOn: anyOf: - type: string - type: 'null' expiresOn: anyOf: - type: string - type: 'null' archivedAt: anyOf: - type: string - type: 'null' replaced: type: boolean required: - documentId - name - kind - reference - issuedOn - expiresOn - archivedAt - replaced additionalProperties: false - type: 'null' visits: type: array items: type: object properties: appointmentId: type: string status: type: string enum: - held - confirmed - cancelled - done startsAt: type: string endsAt: type: string staffName: anyOf: - type: string - type: 'null' outcome: anyOf: - type: string enum: - attended - no_show - type: 'null' cancelReason: anyOf: - type: string - type: 'null' required: - appointmentId - status - startsAt - endsAt - staffName - outcome - cancelReason additionalProperties: false invoices: anyOf: - type: array items: type: object properties: id: type: string subjectKind: type: string subjectId: type: string subjectLabel: anyOf: - type: string - type: 'null' propertyId: type: string propertyLabel: anyOf: - type: string - type: 'null' tenancyId: anyOf: - type: string - type: 'null' contractorContactId: anyOf: - type: string - type: 'null' contractorName: anyOf: - type: string - type: 'null' number: type: string issuedOn: type: string dueOn: anyOf: - type: string - type: 'null' currency: type: string netMinor: anyOf: - type: number - type: string enum: - Infinity - '-Infinity' - NaN vatMinor: anyOf: - type: number - type: string enum: - Infinity - '-Infinity' - NaN grossMinor: anyOf: - type: number - type: string enum: - Infinity - '-Infinity' - NaN borneBy: type: string enum: - landlord - tenant - agency documentId: anyOf: - type: string - type: 'null' status: type: string enum: - received - approved - part_paid - paid - disputed - credited - void approvedAt: anyOf: - type: string - type: 'null' creditedMinor: anyOf: - type: number - type: string enum: - Infinity - '-Infinity' - NaN paidMinor: anyOf: - type: number - type: string enum: - Infinity - '-Infinity' - NaN outstandingMinor: anyOf: - type: number - type: string enum: - Infinity - '-Infinity' - NaN disputedMinor: anyOf: - type: number - type: string enum: - Infinity - '-Infinity' - NaN payableMinor: anyOf: - type: number - type: string enum: - Infinity - '-Infinity' - NaN recoveredMinor: anyOf: - type: number - type: string enum: - Infinity - '-Infinity' - NaN recoverableMinor: anyOf: - type: number - type: string enum: - Infinity - '-Infinity' - NaN disputeReason: anyOf: - type: string - type: 'null' disputedAt: anyOf: - type: string - type: 'null' voidedAt: anyOf: - type: string - type: 'null' voidReason: anyOf: - type: string - type: 'null' legacy: type: boolean legacyStatus: anyOf: - type: string - type: 'null' legacySettled: type: boolean revision: anyOf: - type: number - type: string enum: - Infinity - '-Infinity' - NaN createdAt: type: string lines: type: array items: type: object properties: id: type: string ordinal: anyOf: - type: number - type: string enum: - Infinity - '-Infinity' - NaN kind: type: string enum: - labour - materials - other description: type: string netMinor: anyOf: - type: number - type: string enum: - Infinity - '-Infinity' - NaN vatMinor: anyOf: - type: number - type: string enum: - Infinity - '-Infinity' - NaN grossMinor: anyOf: - type: number - type: string enum: - Infinity - '-Infinity' - NaN required: - id - ordinal - kind - description - netMinor - vatMinor - grossMinor additionalProperties: false payments: type: array items: type: object properties: id: type: string amountMinor: anyOf: - type: number - type: string enum: - Infinity - '-Infinity' - NaN paidOn: type: string reference: type: string legacy: type: boolean createdAt: type: string correctedAt: anyOf: - type: string - type: 'null' correctionReason: anyOf: - type: string - type: 'null' required: - id - amountMinor - paidOn - reference - legacy - createdAt - correctedAt - correctionReason additionalProperties: false creditNotes: type: array items: type: object properties: id: type: string number: type: string issuedOn: type: string netMinor: anyOf: - type: number - type: string enum: - Infinity - '-Infinity' - NaN vatMinor: anyOf: - type: number - type: string enum: - Infinity - '-Infinity' - NaN grossMinor: anyOf: - type: number - type: string enum: - Infinity - '-Infinity' - NaN reason: type: string documentId: anyOf: - type: string - type: 'null' createdAt: type: string correctedAt: anyOf: - type: string - type: 'null' correctionReason: anyOf: - type: string - type: 'null' required: - id - number - issuedOn - netMinor - vatMinor - grossMinor - reason - documentId - createdAt - correctedAt - correctionReason additionalProperties: false recoveries: type: array items: type: object properties: id: type: string amountMinor: anyOf: - type: number - type: string enum: - Infinity - '-Infinity' - NaN receivedOn: type: string reference: type: string createdAt: type: string correctedAt: anyOf: - type: string - type: 'null' correctionReason: anyOf: - type: string - type: 'null' required: - id - amountMinor - receivedOn - reference - createdAt - correctedAt - correctionReason additionalProperties: false authorisation: type: object properties: state: type: string enum: - within - over - no_limit - currency_mismatch - not_checked basis: anyOf: - type: string enum: - approved_quote - spend_limit - selected_quote - type: 'null' authorisedMinor: anyOf: - anyOf: - type: number - type: string enum: - Infinity - '-Infinity' - NaN - type: 'null' authorisedCurrency: anyOf: - type: string - type: 'null' earlierMinor: anyOf: - type: number - type: string enum: - Infinity - '-Infinity' - NaN chargedMinor: anyOf: - type: number - type: string enum: - Infinity - '-Infinity' - NaN remainingMinor: anyOf: - anyOf: - type: number - type: string enum: - Infinity - '-Infinity' - NaN - type: 'null' excessMinor: anyOf: - type: number - type: string enum: - Infinity - '-Infinity' - NaN required: - state - basis - authorisedMinor - authorisedCurrency - earlierMinor - chargedMinor - remainingMinor - excessMinor additionalProperties: false limitOverride: anyOf: - type: object properties: id: type: string state: type: string basis: type: string authorisedMinor: anyOf: - type: number - type: string enum: - Infinity - '-Infinity' - NaN authorisedCurrency: type: string earlierMinor: anyOf: - type: number - type: string enum: - Infinity - '-Infinity' - NaN chargedMinor: anyOf: - type: number - type: string enum: - Infinity - '-Infinity' - NaN excessMinor: anyOf: - type: number - type: string enum: - Infinity - '-Infinity' - NaN reason: type: string userId: anyOf: - type: string - type: 'null' createdAt: type: string required: - id - state - basis - authorisedMinor - authorisedCurrency - earlierMinor - chargedMinor - excessMinor - reason - userId - createdAt additionalProperties: false - type: 'null' required: - id - subjectKind - subjectId - subjectLabel - propertyId - propertyLabel - tenancyId - contractorContactId - contractorName - number - issuedOn - dueOn - currency - netMinor - vatMinor - grossMinor - borneBy - documentId - status - approvedAt - creditedMinor - paidMinor - outstandingMinor - disputedMinor - payableMinor - recoveredMinor - recoverableMinor - disputeReason - disputedAt - voidedAt - voidReason - legacy - legacyStatus - legacySettled - revision - createdAt - lines - payments - creditNotes - recoveries - authorisation - limitOverride additionalProperties: false - type: 'null' required: - id - programmeId - programmeReference - programmeName - occurrence - reference - status - reviewState - dueOn - instructBy - overdue - revisit - statutory - propertyId - propertyLabel - blockId - blockLabel - assetId - assetLabel - complianceKind - contractorContactId - contractorName - instructedAt - instructionNotes - instructedAutomatically - autoInstructSkippedReason - booking - completedOn - completedAt - completedByUserId - completionNotes - reviewedAt - reviewedByUserId - reviewNotes - rejectionReason - remedialRepair - nextEventId - certificateDocumentId - costCodeId - cancelledAt - cancelReason - evidenceCount - revision - createdAt - updatedAt - evidence - certificate - visits - invoices additionalProperties: false TenantCreateRejectedEncoded: type: object properties: _tag: type: string enum: - TenantCreateRejected reason: type: string field: anyOf: - type: string - type: 'null' required: - _tag - reason additionalProperties: false ConfigMissingEncoded: type: object properties: _tag: type: string enum: - ConfigMissing key: type: string required: - _tag - key additionalProperties: false IntegrationRejectedEncoded: type: object properties: _tag: type: string enum: - IntegrationRejected integration: type: string reason: type: string required: - _tag - integration - reason additionalProperties: false AuthRejectedEncoded: type: object properties: _tag: type: string enum: - AuthRejected code: type: string message: type: string required: - _tag - code - message additionalProperties: false RegistrationRejectedEncoded: type: object properties: _tag: type: string enum: - RegistrationRejected message: type: string field: anyOf: - type: string - type: 'null' required: - _tag - message additionalProperties: false UnknownIntegrationEncoded: type: object properties: _tag: type: string enum: - UnknownIntegration integration: type: string required: - _tag - integration additionalProperties: false WebhookUnroutableEncoded: type: object properties: _tag: type: string enum: - WebhookUnroutable integration: type: string reason: type: string required: - _tag - integration - reason additionalProperties: false RateUnavailableEncoded: type: object properties: _tag: type: string enum: - RateUnavailable base: type: string quote: type: string 'on': type: string required: - _tag - base - quote - 'on' additionalProperties: false PlannedInputInvalid: type: object properties: _tag: type: string enum: - PlannedInputInvalid field: type: string message: type: string required: - _tag - field - message additionalProperties: false UnauthenticatedEncoded: type: object properties: _tag: type: string enum: - Unauthenticated required: - _tag additionalProperties: false WebhookRejectedEncoded: type: object properties: _tag: type: string enum: - WebhookRejected integration: type: string reason: type: string required: - _tag - integration - reason additionalProperties: false ApiKeyRejectedEncoded: type: object properties: _tag: type: string enum: - ApiKeyRejected required: - _tag additionalProperties: false TenantSuspendedEncoded: type: object properties: _tag: type: string enum: - TenantSuspended tenantId: type: string reason: type: string required: - _tag - tenantId - reason additionalProperties: false EntitlementMissingEncoded: type: object properties: _tag: type: string enum: - EntitlementMissing tenantId: type: string moduleId: type: string required: - _tag - tenantId - moduleId additionalProperties: false NotAMemberEncoded: type: object properties: _tag: type: string enum: - NotAMember userId: type: string slug: type: string required: - _tag - userId - slug additionalProperties: false ScopeUnknownEncoded: type: object properties: _tag: type: string enum: - ScopeUnknown scope: type: string required: - _tag - scope additionalProperties: false ScopeMissingEncoded: type: object properties: _tag: type: string enum: - ScopeMissing scope: type: string required: - _tag - scope additionalProperties: false TenantMismatchEncoded: type: object properties: _tag: type: string enum: - TenantMismatch header: type: string organizationId: type: string required: - _tag - header - organizationId additionalProperties: false ContractorForbidden: type: object properties: _tag: type: string enum: - ContractorForbidden message: type: string required: - _tag - message additionalProperties: false WorkspaceOwnerRequiredEncoded: type: object properties: _tag: type: string enum: - WorkspaceOwnerRequired required: - _tag additionalProperties: false WorkspaceRoleRequiredEncoded: type: object properties: _tag: type: string enum: - WorkspaceRoleRequired role: anyOf: - type: string - type: 'null' required: type: array items: type: string message: type: string required: - _tag - role - required - message additionalProperties: false TenantNotFoundEncoded: type: object properties: _tag: type: string enum: - TenantNotFound slug: type: string required: - _tag - slug additionalProperties: false ModuleRequestNotFoundEncoded: type: object properties: _tag: type: string enum: - ModuleRequestNotFound id: type: string required: - _tag - id additionalProperties: false PlannedNotFound: type: object properties: _tag: type: string enum: - PlannedNotFound kind: type: string id: type: string required: - _tag - kind - id additionalProperties: false WebhookDuplicateEncoded: type: object properties: _tag: type: string enum: - WebhookDuplicate integration: type: string externalId: type: string required: - _tag - integration - externalId additionalProperties: false RegistrationConflictEncoded: type: object properties: _tag: type: string enum: - RegistrationConflict message: type: string field: anyOf: - type: string - type: 'null' required: - _tag - message additionalProperties: false PlannedStale: type: object properties: _tag: type: string enum: - PlannedStale revision: anyOf: - type: number - type: string enum: - Infinity - '-Infinity' - NaN expectedRevision: anyOf: - type: number - type: string enum: - Infinity - '-Infinity' - NaN message: type: string required: - _tag - revision - expectedRevision - message additionalProperties: false PlannedRequestConflict: type: object properties: _tag: type: string enum: - PlannedRequestConflict message: type: string required: - _tag - message additionalProperties: false PlannedTransitionInvalid: type: object properties: _tag: type: string enum: - PlannedTransitionInvalid code: type: string message: type: string required: - _tag - code - message additionalProperties: false ContractorIneligible: type: object properties: _tag: type: string enum: - ContractorIneligible contactId: type: string contractor: type: string refusals: type: array items: type: object properties: code: type: string message: type: string overridable: type: boolean required: - code - message - overridable additionalProperties: false overridable: type: boolean warnings: type: array items: type: object properties: code: type: string message: type: string important: type: boolean required: - code - message - important additionalProperties: false message: type: string required: - _tag - contactId - contractor - refusals - overridable - warnings - message additionalProperties: false MoneyBusyEncoded: type: object properties: _tag: type: string enum: - MoneyBusy message: type: string required: - _tag - message additionalProperties: false RateLimitedEncoded: type: object properties: _tag: type: string enum: - RateLimited key: type: string retryAfterSeconds: anyOf: - type: number - type: string enum: - Infinity - '-Infinity' - NaN message: type: string required: - _tag - key - retryAfterSeconds - message additionalProperties: false IntegrationUnavailableEncoded: type: object properties: _tag: type: string enum: - IntegrationUnavailable integration: type: string detail: anyOf: - type: string - type: 'null' required: - _tag - integration additionalProperties: false securitySchemes: apiKey: type: apiKey in: header name: x-api-key description: >- A workspace API key (Settings → API keys), scoped to `:read` / `:write`. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.