Mutations

Mutations allow for modifying data within the Worksome API.

acceptBid

Type: Hire!

Hire a worker for a job by accepting their bid.

Only companies can make hires. The worker must have submitted a bid on the job before this mutation can be used.

Once a hire is created, a draft contract is automatically generated (Hire.latestContract) and is pending acceptance from the other party (usually the worker).

Arguments
inputAcceptBidInput!
The input required for hiring a worker by accepting their bid.

actionApprovalApprovable

Type: ApprovalApprovable

Take action on a pending approval request — approve, reject, or request changes.

The authenticated user must be a member of the approver’s user group and the approval request must be awaiting their action (viewerCanAction must be true).

Arguments
inputActionApprovalApprovableInput!
The action to take on the approval request.

approveEmploymentChanges

Type: Employment!

Mark an employment as updated.

Arguments
inputApproveEmploymentChangesInput!
The input for approving employment changes.

approveTrustedContact

Type: TrustedContact!

Approve a trusted contact.

Only companies can approve trusted contacts.

Arguments
inputApproveTrustedContactInput!
The details of the trusted contact to be approved.

attachJobsToProject

Type: Project!

Attach one or more jobs to a project.

Only companies can attach jobs to projects.

Arguments
inputAttachJobsToProjectInput!
The details for attaching a job to a project.

attachUsersToUserGroup

Type: UserGroup!

Attach one or more users to a group.

Only companies can attach users to groups.

Arguments
inputAttachUsersToUserGroupInput!
The details for attaching users to a group.

attributeRecruiterToHire

Type: Hire!

Attribute a recruiter to a hire.

Only companies can attribute recruiters to their hires.

Arguments
inputAttributeRecruiterToHireInput!
The input required for attributing a recruiter to a hire.

blockTrustedContact

Type: TrustedContact!

Block an applied trusted contact.

Only companies can block trusted contacts.

Arguments
inputBlockTrustedContactInput!
The details of the trusted contact to be blocked.

cancelHire

Type: Hire!

Cancel a hire.

Only companies can cancel their hires.

Arguments
inputCancelHireInput!
The input required for canceling a hire.

changeEmail

Type: User!

Change the email of the currently authenticated user.

Arguments
inputChangeEmailInput!
The input for changing the email.

createApproval

Type: Approval!

Create an approval flow.

Only companies can create approvals. An approval defines a review process that is automatically triggered when certain events occur (e.g. a hire is created or a contract changes). Once created, add approval rules to define the conditions and approvers for the flow.

Arguments
inputCreateApprovalInput!
The details for the new approval flow.

createApprovalRule

Type: ApprovalRule!

Add a rule to an approval flow.

A rule defines the conditions under which an approval is required. Each rule contains one or more variable conditions (e.g. “hourly rate > 100”) that are evaluated when the trigger event fires. After creating the rule, use createApprover to assign user groups who will review matching items.

Arguments
inputCreateApprovalRuleInput!
The details for the new approval rule.

createApprover

Type: Approver!

Assign a user group as an approver on an approval rule.

Approvers are processed in position order — position 1 is asked to approve first, then position 2, and so on. Each approver is a user group whose members can act on the approval request.

Arguments
inputCreateApproverInput!
The details for the new approver assignment.

createBatch

Type: Batch

Create a new batch of items for processing.

Arguments
inputCreateBatchInput!
The details for the new batch.

createCompanyRecruiter

Type: CompanyRecruiter

Add and invite a new recruiter.

Only companies can add and invite recruiters.

Arguments
inputCreateCompanyRecruiterInput!
The details for adding & inviting the recruiter.

createCustomField

Type: CustomField!

Create a custom field.

Arguments
inputCreateCustomFieldInput!
The input for creating a custom field.

createCustomTimesheet

Type: CreateCustomTimeSheetResponse!

Create a custom timesheet.

Use this endpoint to create timesheets in Worksome from a custom data format. The endpoint requires data in a custom format, as defined by the input schema.

Arguments
inputCreateCustomTimesheetInput!
The details for creating a custom timesheet.

createDraftHire

Type: Hire!

Create a draft hire for a trusted contact.

Only companies can make hires. The worker must already be a trusted contact of the hiring company. A job is optional — if omitted, one will be created automatically from the provided details.

Draft hires must be completed in the Worksome UI before they become active, such as applicable compliance checks. The hire will start in DRAFT status and progress through the lifecycle once all required steps are finished.

Arguments
inputHireInput!
The input required for creating a draft hire.

createExport

Type: CreateExportResponse

Create an export.

The export URL and the number of rows will be returned (excluding headings).

Arguments
inputCreateExportInput!
The input for creating an export.

createJob

Type: Job!

Create a job with minimal required fields.

Only companies can create jobs. The job is created in DRAFT status with just a title, skills, and owner. Use updateJob to set the full details (description, rates, dates, location, etc.) and to publish the job.

Arguments
inputCreateJobInput!
The minimal details for the new job.

createJobCandidate

Type: [JobCandidate!]!

Create a job candidate.

This will make the workers eligible and proposed for a job.

Arguments
inputCreateJobCandidateInput!
Input data to create the job candidate.

createJobShare

Type: [JobShare!]!

Create a job share.

Arguments
inputCreateJobShareInput!
The details for the job share.

createMilestones

Type: [Milestone!]!

Create one or more milestones.

Arguments
inputCreateMilestonesInput!
The details for the new milestones.

createNote

Type: Note!

Create a note.

Arguments
inputCreateNoteInput!
The details for creating a note.

createPassword

Type: User!

Create a password for the authenticated user.

This operation is only allowed if the user currently does not have a password for changing the password see updatePassword operation instead.

Arguments
inputCreatePasswordInput!
The input for creating a password.

createPaymentRequest

Type: PaymentRequest!

Create a payment request.

Arguments
inputCreatePaymentRequestInput!
The details for creating a payment request.

createProject

Type: Project!

Create a project.

Only companies can create projects.

Arguments
inputCreateProjectInput!
The details for creating a project.

createRecruiterCandidate

Type: RecruiterCandidate

Add and invite a new candidate.

Only recruiters can add and invite candidates.

Arguments
inputCreateRecruiterCandidateInput!
The details for adding & inviting the candidate.

createSmsMultiFactor

Type: SmsCreateMultiFactorPayload!

Create a new multi-factor authentication implementation.

Arguments
inputCreateSmsMultiFactorInput!
The details for the new SMS multi-factor authentication implementation.

createTimesheet

Type: Timesheet

Create a timesheet.

Only workers can create timesheets.

Arguments
inputCreateTimesheetInput!
The details for the new timesheet.

createTotpMultiFactor

Type: TotpCreateMultiFactorPayload!

Create a new multi-factor authentication implementation.

Arguments
inputCreateTotpMultiFactorInput!
The details for the new TOTP multi-factor authentication implementation.

createTrustedContact

Type: TrustedContact!

Add and invite a new trusted contact.

Only companies can add & invite trusted contacts.

Arguments
inputCreateTrustedContactInput!
The details for adding & inviting the trusted contact.

createUserGroup

Type: UserGroup!

Create a user group.

Only companies can create user groups.

Arguments
inputCreateUserGroupInput!
The details for creating a group.

createWebhook

Type: Webhook!

Create a webhook.

Only companies can create webhooks.

Arguments
inputCreateWebhookInput!
The input required for creating a webhook.

createWorkflow

Type: Workflow!

Create an approval workflow as a complete tree in a single operation.

Only companies can create workflows. This is the recommended way to set up an approval flow — it creates the approval (root), its rules (conditions), and approvers (user groups) all at once, rather than calling createApproval, createApprovalRule, and createApprover separately.

The input is structured as a tree: a root node (the approval definition), rule nodes (conditions), and approver nodes (user groups). Nodes reference each other via temporary id and parent/children fields.

Arguments
inputCreateWorkflowInput!
The complete workflow tree: root approval, rules, and approvers.

deleteCompanyRecruiter

Type: CompanyRecruiter

Delete a recruiter relationship.

Both the company and the recruiter can delete the relationship.

Arguments
inputDeleteCompanyRecruiterInput!
The details of the recruiter relationship to be deleted.

deleteCustomField

Type: CustomField!

Delete a custom field.

All fields details must be provided.

Arguments
inputDeleteCustomFieldInput!
“ The input for deleting a custom field.

deleteMilestones

Type: [Milestone!]!

Delete one or more milestones.

Arguments
inputDeleteMilestonesInput!
The details for the milestone to delete.

deleteNote

Type: Note!

Delete a note.

Arguments
inputDeleteNoteInput!
The details for deleting a note.

deletePaymentRequest

Type: PaymentRequest!

Delete a payment request.

Arguments
inputDeletePaymentRequestInput!
The details for deleting a payment request.

deleteProject

Type: Project!

Soft delete a project.

Only companies can delete projects.

Arguments
inputDeleteProjectInput!
The details for deleting a project.

deleteRecruiterCandidate

Type: RecruiterCandidate

Delete a recruiter candidate relationship.

Both the recruiter and the candidate can delete the relationship.

Arguments
inputDeleteRecruiterCandidateInput!
The details of the recruiter candidate relationship to be deleted.

deleteTimesheet

Type: Timesheet!

Delete a timesheet.

Only workers can delete timesheets.

Arguments
inputDeleteTimesheetInput!
The details for the timesheet.

deleteTimesheetRegistration

Type: TimesheetRegistration!

Delete a timesheet registration.

Only workers can delete timesheet registrations.

Arguments
inputDeleteTimesheetRegistrationInput!
The details for the timesheet registration.

deleteTrustedContact

Type: TrustedContact

Delete a trusted contact.

Only companies can delete trusted contacts.

Arguments
inputDeleteTrustedContactInput!
The details of the trusted contact to be soft deleted.

deleteUserGroup

Type: UserGroup!

Soft delete a user group.

Only companies can delete user groups.

Arguments
inputDeleteUserGroupInput!
The details for deleting a user group.

deleteWebhook

Type: Webhook!

Delete a webhook.

Arguments
inputDeleteWebhookInput!
The input required for deleting a webhook.

deleteWorkflow

Type: Workflow!

Delete an approval workflow.

Only companies can delete workflows. If the workflow has no existing approval requests, it is permanently removed along with its rules and approvers. If it has existing approval requests, the workflow is archived instead — its rules and approvers are preserved, but it will no longer evaluate new events.

Arguments
inputDeleteWorkflowInput!
The ID of the workflow to delete.

detachJobFromProject

Type: Project!

Detach a job from a project

Only companies can detach a job from a project.

Arguments
inputDetachJobFromProjectInput!
The details for attaching a job to a project.

detachUsersFromUserGroup

Type: UserGroup!

Detach one or more user from a group.

Only companies can detach users from a group.

Arguments
inputDetachUsersFromUserGroupInput!
The details for detaching users from a group.

duplicateJob

Type: Job!

Duplicate a job.

Creates a copy of the job with all its details (description, skills, location, budget, etc.) Only companies can duplicate jobs.

Arguments
inputDuplicateJobInput!
The details for duplicating the job.

endJob

Type: Job!

End a job.

Only companies can end jobs.

Arguments
inputEndJobInput!
The details to end the job.

endProject

Type: Project!

End a project.

This is used to set an end date on the project to consider it no longer active.

Arguments
inputEndProjectInput!
The details for ending a project.

forwardCandidate

Type: JobCandidate!

Present a candidate to a linked job with a specified rate.

Arguments
inputForwardCandidateInput!
Input data to forward a candidate.

generateInviteLink

Type: Company!

Generate the company invite link token.

Arguments
inputGenerateInviteLinkInput!
The input required to generate the company invite link token.

generatePersonalInviteLink

Type: String!

Generate or regenerate a personal invite link for the authenticated user.

This URL allows workers to join as trusted contacts with auto-approval. Only company members can generate personal invite links.

Arguments
inputGeneratePersonalInviteLinkInput!
The company for which to generate the personal invite link.

hire

Type: Hire!

Deprecated

Directly hire a trusted contact without requiring a bid.

Deprecated: use createDraftHire to create draft hires via the public API.

Only companies can make hires. The worker must already be a trusted contact of the hiring company. A job is optional — if omitted, one will be created automatically from the provided details.

Arguments
inputHireInput!
The input required for directly hiring a trusted contact.

inviteCompanyRecruiter

Type: CompanyRecruiter!

Invite an existing recruiter.

Only companies can invite the recruiter.

Arguments
inputInviteCompanyRecruiterInput!
The details of the recruiter to be invited.

manageOnboardingDocuments

Type: Company

Manage Onboarding documents.

Arguments
inputManageOnboardingDocumentsInput!
The input required to manage onboarding documents.

markFilesAsUploaded

Type: [File!]!

Mark one or more files as uploaded to the temporary URL.

Arguments
inputMarkFilesAsUploadedInput!
The input required for marking files as uploaded.

onboardEmployment

Type: Employment!

Onboard an employment with optional employment costs.

Arguments
inputOnboardEmploymentInput!
The input for onboarding an employment.

openProject

Type: Project!

Open a project.

This is used to set the end date on the project to null to make it open again.

Arguments
inputOpenProjectInput!
The details for opening a project.

reinviteTrustedContact

Type: TrustedContact!

Resend an invitation to a Trusted Contact that already exists in the Talent Pool.

This can be used for workers that has not responded to the initial invitation or for workers that was previously managed by a Staffing Agency.

Arguments
inputReinviteTrustedContactInput!
The input for resending an invitation to a Trusted Contact.

rejectHire

Type: Hire!

Reject a hire.

Arguments
inputRejectHireInput!
The input required to reject a hire.

removeJobShare

Type: [JobShare!]!

Remove a job share.

Arguments
inputRemoveJobShareInput!
The details for removing the job share.

removeMultiFactor

Type: MultiFactor

Remove a multi-factor authentication implementation.

Arguments
inputRemoveMultiFactorInput!
The details for removing the multi-factor authentication implementation instance.

removeOnboardingDocuments

Type: Company

Remove Onboarding documents.

Arguments
inputRemoveOnboardingDocumentsInput!
The input required to remove onboarding documents.

removeRecruiterFromHire

Type: Hire!

Remove a recruiter from a hire.

Only companies can remove recruiters from their hires.

Arguments
inputRemoveRecruiterFromHireInput!
The input required for removing a recruiter from a hire.

retryWebhookEvent

Type: WebhookEvent!

Retry a webhook event.

Only companies can retry webhook events.

Arguments
inputRetryWebhookEventInput!
The input required for retrying a webhook event.

runBatchAction

Type: RunBatchActionResponse!

Run an action on a batch.

Arguments
inputRunBatchActionInput!
The details for the batch action.

sendVerificationEmail

Type: User!

Sends a new verification email.

This operation is only allowed if the user has not verified their email.

setInternalBudgetOnJob

Type: Job!

Set the internal budget of a job.

Only companies can set the internal budget on the job.

Arguments
inputSetInternalBudgetOnJobInput!
The details of internal budget for the job.

shareCandidatesWithPartner

Type: [JobCandidate!]!

[Experimental] Share candidates with the linked partner account.

Arguments
inputShareCandidatesWithPartnerInput!
Input data to share candidates.

shareHire

Type: Hire!

Share a hire offer with a worker.

Only companies can share hires with workers.

Arguments
inputShareHireInput!
The input required for sharing a hire.

storeBankDetails

Type: BankDetail!

Update the bank account details.

Arguments
inputStoreBankDetailsInput!
The details for updating the bank account record.

terminateHire

Type: Hire!

Terminate a hire.

Arguments
inputTerminateHireInput!
The input required for terminating a hire.

updateApproval

Type: Approval!

Update an approval flow.

Updating an approval creates a new version. Only companies that own the approval can update it.

Arguments
inputUpdateApprovalInput!
The fields to update on the approval.

updateApprover

Type: Approver!

Update an approver’s user group or position in the approval sequence.

Arguments
inputUpdateApproverInput!
The fields to update on the approver.

updateCompanyRecruiter

Type: CompanyRecruiter

Update a recruiter relationship.

Only companies can edit recruiter relationships.

Arguments
inputUpdateCompanyRecruiterInput!
The details of the recruiter relationship to be updated.

updateCustomField

Type: CustomField!

Update a custom field.

All fields must be provided.

Arguments
inputUpdateCustomFieldInput!
The input for updating a custom field.

updateJob

Type: Job!

Update a job’s details.

Only companies can update jobs. This is the follow-up to createJob — use it to set the full role details (description, rates, dates, location, visibility) and to publish the job when ready.

All fields are optional; only the fields you provide will be updated.

Arguments
inputUpdateJobInput!
The fields to update on the job.

updateJobCandidatePreferred

Type: JobCandidate!

Update job candidates “preferred” status.

Arguments
inputUpdateJobCandidatePreferredInput!
Input data to update a job candidate preferred status.

updateJobCandidateStatus

Type: JobCandidate!

Update a job candidate status.

A reason and comment can be provided.

Arguments
inputUpdateJobCandidateStatusInput!
Input data to update a job candidates status.

updateMilestones

Type: [Milestone!]!

Update one or more milestones.

Arguments
inputUpdateMilestonesInput!
The details for the milestones to update.

updateNote

Type: Note!

Update a note.

Arguments
inputUpdateNoteInput!
The details for updating a note.

updatePassword

Type: User!

Update a user’s password.

Arguments
inputUpdatePasswordInput!
The input for the user update mutation.

updatePaymentRequest

Type: PaymentRequest!

Update a payment request.

Arguments
inputUpdatePaymentRequestInput!
The details for updating a payment request.

updateProject

Type: Project!

Update a project.

Only companies can update projects.

Arguments
inputUpdateProjectInput!
The details for updating a project.

updateRecruiterCandidate

Type: RecruiterCandidate

Update a recruiter candidate information.

Only recruiters can edit the relationship.

Arguments
inputUpdateRecruiterCandidateInput!
The details of the recruiter candidate relationship to be updated.

updateTimesheet

Type: Timesheet!

Update a timesheet.

Only workers can update timesheets.

Arguments
inputUpdateTimesheetInput!
The details for the timesheet.

updateTimesheetRegistration

Type: TimesheetRegistration!

Update a timesheet registration.

Only workers can update timesheet registrations.

Arguments
inputUpdateTimesheetRegistrationInput!
The details for the timesheet registration.

updateTrustedContact

Type: TrustedContact!

Update a trusted contact.

Only companies can edit trusted contacts.

Arguments
inputUpdateTrustedContactInput!
The details of the trusted contact to be edited.

updateUserGroup

Type: UserGroup!

Update a user group.

Only companies can update user groups.

Arguments
inputUpdateUserGroupInput!
The details for updating a group.

updateWebhook

Type: Webhook!

Update a webhook.

Arguments
inputUpdateWebhookInput!
The input required for updating a webhook.

updateWorker

Type: Worker!

Update a worker.

Arguments
inputUpdateWorkerInput!
The details for updating a worker.

updateWorkerCustomFieldValues

Type: UpdateWorkerCustomFieldValuesPayload!

Update custom field values for a fieldable entity as a worker.

Accepts a collection of field values in a single payload. Only fields with workerInputAllowed: true can be updated. Partial updates are supported - fields not included are ignored.

Arguments
inputUpdateWorkerCustomFieldValuesInput!
The input for updating custom field values as a worker.

updateWorkflow

Type: Workflow!

Update an existing approval workflow as a complete tree.

Only companies can update workflows. Replaces the entire workflow structure (root, rules, and approvers) with the provided tree. Creates a new version of the underlying approval.

Arguments
inputUpdateWorkflowInput!
The updated workflow tree.

updateWorksomeIntelligenceConsent

Type: Boolean!

Update consent to use Worksome Intelligence for the current user.

Arguments
inputUpdateWorksomeIntelligenceConsentInput!
The input required for consent.

uploadFiles

Type: [TemporaryFileUploadResponse!]!

Generate temporary upload URLs for files for the given account.

The temporary URL will expire after 1 week.

Arguments
input[UploadFileInput!]!
The input required for upload a file.

verifySmsMultiFactor

Type: SmsMultiFactor

Verify a multi-factor authentication implementation.

Arguments
inputVerifySmsMultiFactorInput!
The details for the verification of the SMS multi-factor authentication implementation.

verifyTotpMultiFactor

Type: TotpMultiFactor

Verify a TOTP multi-factor authentication implementation.

Arguments
inputVerifyTotpMultiFactorInput!
The details for the verification of the TOTP multi-factor authentication implementation.