> ## Documentation Index > Fetch the complete documentation index at: https://docs.join.tl/llms.txt > Use this file to discover all available pages before exploring further. # Execute an approved Zapier action > Execution available only to the installed Zapier app for approved, non-destructive, idempotent operations. ## OpenAPI ````yaml /specs/openapi/jointl-api-v1.openapi.yaml post /api/v1/actions/execute openapi: 3.1.2 info: title: Jointl REST API and OAuth version: 1.0.0 summary: Supported public HTTP contract for Jointl third-party connections. description: >- HTTP contract for Jointl REST operations, OAuth, and Zapier subscription and action endpoints. Jointl does not provide a public sandbox. termsOfService: https://join.tl/legal/terms-of-service contact: name: Jointl Support url: https://join.tl servers: - url: https://api.join.tl description: Jointl production API security: [] tags: - name: OAuth description: OAuth 2.0 and OpenID Connect endpoints. - name: Discovery description: OAuth resource and issuer discovery. - name: Operations description: Permission-filtered read operations. - name: Actions description: Prepare, human approval, and confirmation. - name: Zapier description: Endpoints restricted to the approved Jointl Zapier app. paths: /api/v1/actions/execute: post: tags: - Zapier summary: Execute an approved Zapier action description: >- Execution available only to the installed Zapier app for approved, non-destructive, idempotent operations. operationId: executeStandingZapierAction parameters: - name: Idempotency-Key in: header required: true schema: $ref: '#/components/schemas/IdempotencyKey' description: >- Derived by the Jointl Zapier app from Source Event ID and action identity. requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/StandingActionExecuteRequest' example: operationId: checks.verifications.runAll input: applicantId: applicantid_example_01 responses: '200': description: >- Zapier action completed or returned from a previous identical request. headers: X-Request-Id: $ref: '#/components/headers/RequestId' content: application/json: schema: type: object properties: data: {} requestId: type: string description: Request correlation identifier. required: - data - requestId additionalProperties: false '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '409': $ref: '#/components/responses/Conflict' '413': $ref: '#/components/responses/TooLarge' '429': $ref: '#/components/responses/RateLimited' '500': $ref: '#/components/responses/ServerError' '503': $ref: '#/components/responses/Unavailable' security: - JointlOAuth: - workspace.write components: schemas: IdempotencyKey: type: string minLength: 8 maxLength: 160 pattern: ^[A-Za-z0-9._:-]{8,160}$ description: Stable identity for one logical intent. Reuse only for identical input. StandingActionExecuteRequest: oneOf: - $ref: '#/components/schemas/ChecksVerificationsRunAllExecuteRequest' - $ref: '#/components/schemas/ChecksPublicProfilesFindExecuteRequest' - $ref: '#/components/schemas/ChecksStatusSetExecuteRequest' - $ref: '#/components/schemas/EmployeesStatusSetExecuteRequest' - $ref: '#/components/schemas/TalentsStatusSetExecuteRequest' - $ref: '#/components/schemas/ReferencesRequestExecuteRequest' - $ref: '#/components/schemas/ChecksBulkCreateExecuteRequest' - $ref: '#/components/schemas/EmployeesBulkImportExecuteRequest' - $ref: '#/components/schemas/ChecksAddNoteExecuteRequest' - $ref: '#/components/schemas/EmployeesAddNoteExecuteRequest' - $ref: '#/components/schemas/TalentsAddNoteExecuteRequest' discriminator: propertyName: operationId ChecksVerificationsRunAllExecuteRequest: type: object properties: operationId: type: string const: checks.verifications.runAll input: $ref: '#/components/schemas/ChecksVerificationsRunAllInput' required: - operationId - input additionalProperties: false x-jointl-logical-operation: checks.verifications.runAll x-jointl-scope: workspace.write x-jointl-audiences: - rest - zapier x-jointl-mcp-exposed: false x-jointl-confirmation-required: true x-jointl-destructive: false x-jointl-retry-safety: idempotent x-jointl-standing-automation: true x-jointl-prerequisites: >- Use when an external event should start the Run All Checks workflow; verification types that require unavailable applicant details are skipped x-jointl-side-effects: >- The exact effects are returned by the prepare preview and revalidated at confirmation. ChecksPublicProfilesFindExecuteRequest: type: object properties: operationId: type: string const: checks.publicProfiles.find input: $ref: '#/components/schemas/ChecksPublicProfilesFindInput' required: - operationId - input additionalProperties: false x-jointl-logical-operation: checks.publicProfiles.find x-jointl-scope: workspace.write x-jointl-audiences: - rest - zapier x-jointl-mcp-exposed: false x-jointl-confirmation-required: true x-jointl-destructive: false x-jointl-retry-safety: idempotent x-jointl-standing-automation: true x-jointl-prerequisites: >- Use when an external event should start the Find Profiles workflow; provide only known identity, location, or profile-URL hints and never speculative personal data x-jointl-side-effects: >- The exact effects are returned by the prepare preview and revalidated at confirmation. ChecksStatusSetExecuteRequest: type: object properties: operationId: type: string const: checks.status.set input: $ref: '#/components/schemas/ChecksStatusSetInput' required: - operationId - input additionalProperties: false x-jointl-logical-operation: checks.status.set x-jointl-scope: workspace.write x-jointl-audiences: - rest - mcp x-jointl-mcp-exposed: true x-jointl-confirmation-required: true x-jointl-destructive: false x-jointl-retry-safety: idempotent x-jointl-standing-automation: true x-jointl-prerequisites: >- Use only when the user explicitly asks to change one Check status; never shortlist or reject someone solely because an analysis, score, or ranking suggests it x-jointl-side-effects: >- The exact effects are returned by the prepare preview and revalidated at confirmation. EmployeesStatusSetExecuteRequest: type: object properties: operationId: type: string const: employees.status.set input: $ref: '#/components/schemas/EmployeesStatusSetInput' required: - operationId - input additionalProperties: false x-jointl-logical-operation: employees.status.set x-jointl-scope: workspace.write x-jointl-audiences: - rest - mcp x-jointl-mcp-exposed: true x-jointl-confirmation-required: true x-jointl-destructive: false x-jointl-retry-safety: idempotent x-jointl-standing-automation: true x-jointl-prerequisites: >- Use only when the user explicitly asks to mark a known Employee active or left and has supplied any required position end dates, or explicitly asks to send Exit Intelligence to an Employee already marked left; never infer this action from performance analytics x-jointl-side-effects: >- The exact effects are returned by the prepare preview and revalidated at confirmation. TalentsStatusSetExecuteRequest: type: object properties: operationId: type: string const: talents.status.set input: $ref: '#/components/schemas/TalentsStatusSetInput' required: - operationId - input additionalProperties: false x-jointl-logical-operation: talents.status.set x-jointl-scope: workspace.write x-jointl-audiences: - rest - mcp x-jointl-mcp-exposed: true x-jointl-confirmation-required: true x-jointl-destructive: false x-jointl-retry-safety: idempotent x-jointl-standing-automation: true x-jointl-prerequisites: >- Use only when the user explicitly asks to change one Talent Pool status; never infer shortlisting from an analysis or ranking x-jointl-side-effects: >- The exact effects are returned by the prepare preview and revalidated at confirmation. ReferencesRequestExecuteRequest: type: object properties: operationId: type: string const: references.request input: $ref: '#/components/schemas/ReferencesRequestInput' required: - operationId - input additionalProperties: false x-jointl-logical-operation: references.request x-jointl-scope: workspace.write x-jointl-audiences: - rest - mcp x-jointl-mcp-exposed: true x-jointl-confirmation-required: true x-jointl-destructive: false x-jointl-retry-safety: idempotent x-jointl-standing-automation: true x-jointl-prerequisites: >- Use after resolving the Check and selecting a template from flows.referenceTemplates.list x-jointl-side-effects: >- The exact effects are returned by the prepare preview and revalidated at confirmation. ChecksBulkCreateExecuteRequest: type: object properties: operationId: type: string const: checks.bulkCreate input: $ref: '#/components/schemas/ChecksBulkCreateInput' required: - operationId - input additionalProperties: false x-jointl-logical-operation: checks.bulkCreate x-jointl-scope: workspace.write x-jointl-audiences: - rest - mcp x-jointl-mcp-exposed: true x-jointl-confirmation-required: true x-jointl-destructive: false x-jointl-retry-safety: idempotent x-jointl-standing-automation: true x-jointl-prerequisites: >- Use after the client has parsed a file into validated fullName and email rows and resolved one authorized Flow ID; never pass a file or URL x-jointl-side-effects: >- The exact effects are returned by the prepare preview and revalidated at confirmation. EmployeesBulkImportExecuteRequest: type: object properties: operationId: type: string const: employees.bulkImport input: $ref: '#/components/schemas/EmployeesBulkImportInput' required: - operationId - input additionalProperties: false x-jointl-logical-operation: employees.bulkImport x-jointl-scope: workspace.write x-jointl-audiences: - rest - mcp x-jointl-mcp-exposed: true x-jointl-confirmation-required: true x-jointl-destructive: false x-jointl-retry-safety: idempotent x-jointl-standing-automation: true x-jointl-prerequisites: >- Use after the client has parsed and validated Employee rows and resolved exact authorized company IDs; use create for Search-or-Create, update for one exact existing work record, and upsert for bulk imports; never pass a file or URL x-jointl-side-effects: >- The exact effects are returned by the prepare preview and revalidated at confirmation. ChecksAddNoteExecuteRequest: type: object properties: operationId: type: string const: checks.addNote input: $ref: '#/components/schemas/ChecksAddNoteInput' required: - operationId - input additionalProperties: false x-jointl-logical-operation: checks.addNote x-jointl-scope: workspace.write x-jointl-audiences: - rest - mcp x-jointl-mcp-exposed: true x-jointl-confirmation-required: true x-jointl-destructive: false x-jointl-retry-safety: idempotent x-jointl-standing-automation: true x-jointl-prerequisites: >- Use only when the user explicitly asks to add text to one authorized Check, after resolving its applicant ID x-jointl-side-effects: >- The exact effects are returned by the prepare preview and revalidated at confirmation. EmployeesAddNoteExecuteRequest: type: object properties: operationId: type: string const: employees.addNote input: $ref: '#/components/schemas/EmployeesAddNoteInput' required: - operationId - input additionalProperties: false x-jointl-logical-operation: employees.addNote x-jointl-scope: workspace.write x-jointl-audiences: - rest - mcp x-jointl-mcp-exposed: true x-jointl-confirmation-required: true x-jointl-destructive: false x-jointl-retry-safety: idempotent x-jointl-standing-automation: true x-jointl-prerequisites: >- Use only when the user explicitly asks to add text to one authorized Employee, after resolving its Employee ID x-jointl-side-effects: >- The exact effects are returned by the prepare preview and revalidated at confirmation. TalentsAddNoteExecuteRequest: type: object properties: operationId: type: string const: talents.addNote input: $ref: '#/components/schemas/TalentsAddNoteInput' required: - operationId - input additionalProperties: false x-jointl-logical-operation: talents.addNote x-jointl-scope: workspace.write x-jointl-audiences: - rest - mcp x-jointl-mcp-exposed: true x-jointl-confirmation-required: true x-jointl-destructive: false x-jointl-retry-safety: idempotent x-jointl-standing-automation: true x-jointl-prerequisites: >- Use only when the user explicitly asks to add text to one authorized Talent Pool profile, after resolving its profile ID x-jointl-side-effects: >- The exact effects are returned by the prepare preview and revalidated at confirmation. ErrorEnvelope: type: object properties: error: type: object properties: code: type: string message: type: string required: - code - message additionalProperties: false requestId: type: string required: - error - requestId additionalProperties: false ChecksVerificationsRunAllInput: additionalProperties: false properties: applicantId: maxLength: 128 minLength: 1 pattern: ^[A-Za-z0-9_-]+$ type: string required: - applicantId type: object ChecksPublicProfilesFindInput: additionalProperties: false properties: applicantId: maxLength: 128 minLength: 1 pattern: ^[A-Za-z0-9_-]+$ type: string profileMatchingDetails: additionalProperties: false description: >- Optional corroborating identity and location hints. Jointl also reuses the Check name, email, stored verification location, and confirmed profile links. properties: aliases: items: maxLength: 256 minLength: 1 type: string maxItems: 8 type: array cities: items: maxLength: 128 minLength: 1 type: string maxItems: 8 type: array fullName: maxLength: 256 minLength: 1 type: string profileUrls: items: maxLength: 2048 minLength: 1 type: string maxItems: 16 type: array relevantCountries: items: pattern: ^[A-Za-z]{2}$ type: string maxItems: 12 type: array states: items: maxLength: 128 minLength: 1 type: string maxItems: 8 type: array type: object required: - applicantId type: object ChecksStatusSetInput: additionalProperties: false properties: applicantId: maxLength: 128 minLength: 1 pattern: ^[A-Za-z0-9_-]+$ type: string expectedStatus: description: >- Current status read from checks.get or checks.list; used for concurrency safety. enum: - new - archived - inProgress - shortlisted - rejected - selected type: string status: description: >- New Check status. selected is intentionally excluded because selection creates an Employee. enum: - new - archived - inProgress - shortlisted - rejected type: string required: - applicantId - expectedStatus - status type: object EmployeesStatusSetInput: additionalProperties: false properties: employeeId: maxLength: 128 minLength: 1 pattern: ^[A-Za-z0-9_-]+$ type: string exitIntelligenceFlowId: description: >- Optional active Exit Intelligence Flow to launch after marking the Employee left. maxLength: 128 minLength: 1 pattern: ^[A-Za-z0-9_-]+$ type: string expectedStatus: description: >- Current status read from employees.get or employees.list; used for concurrency safety. enum: - active - left type: string positionEndAt: description: >- One leaving date to apply to every active position. Do not combine with positionEndDates. pattern: ^\d{4}-\d{2}-\d{2}$ type: string positionEndDates: default: [] description: >- When marking left, provide an end date for every active position returned by employees.get. items: additionalProperties: false properties: endAt: pattern: ^\d{4}-\d{2}-\d{2}$ type: string positionId: maxLength: 128 minLength: 1 pattern: ^[A-Za-z0-9_-]+$ type: string required: - positionId - endAt type: object maxItems: 50 type: array status: enum: - active - left type: string required: - employeeId - expectedStatus - status type: object TalentsStatusSetInput: additionalProperties: false properties: expectedStatus: description: >- Current status read from talents.get or talents.list; used for concurrency safety. enum: - new - archived - shortlisted type: string status: enum: - new - archived - shortlisted type: string talentId: maxLength: 128 minLength: 1 pattern: ^[A-Za-z0-9_-]+$ type: string required: - talentId - expectedStatus - status type: object ReferencesRequestInput: additionalProperties: false properties: applicantId: maxLength: 128 minLength: 1 pattern: ^[A-Za-z0-9_-]+$ type: string referee: additionalProperties: false properties: email: format: email maxLength: 254 type: string name: maxLength: 180 minLength: 1 type: string phone: pattern: ^[1-9][0-9]{6,14}$ type: string phoneMessageConsent: default: false type: boolean required: - name - email type: object templateId: maxLength: 128 minLength: 1 pattern: ^[A-Za-z0-9_-]+$ type: string required: - applicantId - templateId - referee type: object ChecksBulkCreateInput: additionalProperties: false properties: applicants: items: additionalProperties: false properties: email: format: email maxLength: 254 type: string fullName: maxLength: 180 minLength: 1 type: string sourceRowNumber: description: >- Original one-based spreadsheet row number for preview and error reporting. maximum: 1000000 minimum: 1 type: integer required: - fullName - email type: object maxItems: 250 minItems: 1 type: array flowId: description: Exact authorized Hiring Review Flow ID. maxLength: 128 minLength: 1 pattern: ^[A-Za-z0-9_-]+$ type: string required: - flowId - applicants type: object EmployeesBulkImportInput: additionalProperties: false properties: employees: items: additionalProperties: false properties: companyId: maxLength: 128 minLength: 1 pattern: ^[A-Za-z0-9_-]+$ type: string companyName: maxLength: 180 minLength: 1 type: string compensation: additionalProperties: false properties: currency: maxLength: 3 minLength: 3 type: string effectiveAt: pattern: ^\d{4}-\d{2}-\d{2}$ type: string grossAmount: minimum: 0 type: number netAmount: minimum: 0 type: number payPeriod: enum: - annual - monthly - weekly - daily - hourly type: string type: object email: format: email maxLength: 254 type: string employeeId: description: Exact existing Employee ID. Required only in update mode. maxLength: 128 minLength: 1 pattern: ^[A-Za-z0-9_-]+$ type: string endAt: pattern: ^\d{4}-\d{2}-\d{2}$ type: string fullName: maxLength: 180 minLength: 1 type: string managerColumnMapped: description: >- True only when the uploaded file explicitly mapped a manager column; false preserves an existing matching position manager. type: boolean managerName: description: >- Manager full name from the mapped column. Jointl resolves only an unambiguous existing Employee. maxLength: 180 minLength: 1 type: string positionId: description: >- Exact work-record ID on employeeId. Required only in update mode. maxLength: 128 minLength: 1 pattern: ^[A-Za-z0-9_-]+$ type: string positionTitle: maxLength: 180 minLength: 1 type: string sourceRowNumber: description: >- Original one-based spreadsheet row number for preview and error reporting. maximum: 1000000 minimum: 1 type: integer startAt: pattern: ^\d{4}-\d{2}-\d{2}$ type: string tagNames: description: >- Tag names parsed from the mapped column. Missing names are created only on confirmation. items: maxLength: 100 minLength: 1 type: string maxItems: 50 type: array tagsColumnMapped: description: >- True only when the uploaded file explicitly mapped a tags column; false preserves existing tags on a matching position. type: boolean required: - fullName - companyId - positionTitle - startAt type: object maxItems: 500 minItems: 1 type: array mode: default: upsert description: >- upsert applies Jointl Employee matching; create rejects existing matches; update requires exact employeeId and positionId values. enum: - upsert - create - update type: string required: - employees type: object ChecksAddNoteInput: additionalProperties: false properties: applicantId: maxLength: 128 minLength: 1 pattern: ^[A-Za-z0-9_-]+$ type: string text: description: Exact note text the user asked to save. maxLength: 4000 minLength: 1 type: string visibleToTeam: default: false description: >- False keeps the note private to its author; true shares it with authorized workspace members. type: boolean required: - applicantId - text type: object EmployeesAddNoteInput: additionalProperties: false properties: employeeId: maxLength: 128 minLength: 1 pattern: ^[A-Za-z0-9_-]+$ type: string text: description: Exact note text the user asked to save. maxLength: 4000 minLength: 1 type: string visibleToTeam: default: false description: >- False keeps the note private to its author; true shares it with authorized workspace members. type: boolean required: - employeeId - text type: object TalentsAddNoteInput: additionalProperties: false properties: talentId: maxLength: 128 minLength: 1 pattern: ^[A-Za-z0-9_-]+$ type: string text: description: Exact note text the user asked to save. maxLength: 4000 minLength: 1 type: string visibleToTeam: default: false description: >- False keeps the note private to its author; true shares it with authorized workspace members. type: boolean required: - talentId - text type: object headers: RequestId: description: Request correlation identifier. schema: type: string RetryAfter: description: Seconds before retrying. schema: type: integer minimum: 1 responses: BadRequest: description: Invalid request. headers: X-Request-Id: $ref: '#/components/headers/RequestId' content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: code: invalid-external-operation-input message: The operation input is invalid. requestId: request_example_400 Unauthorized: description: Authentication required. headers: X-Request-Id: $ref: '#/components/headers/RequestId' content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: code: not-authenticated message: Authentication is required. requestId: request_example_401 Forbidden: description: Insufficient scope or permission. headers: X-Request-Id: $ref: '#/components/headers/RequestId' content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: code: not-authorized message: You are not allowed to perform this action. requestId: request_example_403 NotFound: description: The operation or visible record was not found. headers: X-Request-Id: $ref: '#/components/headers/RequestId' content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: code: not-found message: The requested record was not found. requestId: request_example_404 Conflict: description: State, replay, or idempotency conflict. headers: X-Request-Id: $ref: '#/components/headers/RequestId' content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: code: external-action-conflict message: The action conflicts with current state. requestId: request_example_409 TooLarge: description: Request exceeds one MiB. headers: X-Request-Id: $ref: '#/components/headers/RequestId' content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: code: request-too-large message: The request body is too large. requestId: request_example_413 RateLimited: description: Rate limit exceeded. headers: X-Request-Id: $ref: '#/components/headers/RequestId' Retry-After: $ref: '#/components/headers/RetryAfter' content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: code: too-many-requests message: Too many requests. requestId: request_example_429 ServerError: description: Server error. headers: X-Request-Id: $ref: '#/components/headers/RequestId' content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: code: internal-error message: The request could not be completed. requestId: request_example_500 Unavailable: description: Temporarily unavailable or action outcome unknown. headers: X-Request-Id: $ref: '#/components/headers/RequestId' content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: code: temporarily-unavailable message: The service is temporarily unavailable. requestId: request_example_503 securitySchemes: JointlOAuth: type: oauth2 description: OAuth access token issued for the REST resource. flows: authorizationCode: authorizationUrl: https://api.join.tl/oauth/authorize tokenUrl: https://api.join.tl/oauth/token refreshUrl: https://api.join.tl/oauth/token scopes: openid: Authenticate the Jointl member. email: Read the authorized member email claim. workspace.read: Read authorized Jointl workspace data. workspace.write: Prepare and confirm authorized Jointl changes. offline_access: Receive a rotating refresh token. x-jointl-resource: https://api.join.tl/api/v1 x-jointl-pkce-required: S256 ````