New: Kith open-sources its ATS.Read why
Skip to Content

Introduce a candidate to a client

Attach Sam’s CV, record the introduction to Alex, and keep Alex’s reply with the job.

Sam is on the shortlist for Alex’s engineering director role. Sam sends you a CV and agrees to meet the hiring panel. Here’s how to give the team the file and keep a record of what Alex says. Start with the job, candidate and client contact IDs from the placement walkthrough.

1. Save Sam’s CV

Call createUploadUrl with Sam’s candidate ID as ownerId, the filename, its content type and purpose: CV. Here’s the first call for a PDF. Prepare an upload

mutation PrepareSamsCv($candidate: String!) {
  createUploadUrl(input: { ownerId: $candidate, purpose: CV, filename: "sam-cv.pdf", mimeType: "application/pdf" }) {
    uploadUrl
    key
  }
}

Send the PDF bytes to uploadUrl with an HTTP PUT and Content-Type: application/pdf. The signed URL authorizes that upload. Then send the returned key to attachCandidateDocument as uploadKey, with Sam’s candidate ID, filename and content type. If you lose the response, attaching the same key to Sam again returns the same document. Attach the file

To read it later, use Candidate.documents. Open the document’s downloadPath on the API host with your workspace key, then fetch the signed redirect without that key. Read a candidate document

2. Introduce Sam to Alex

Leave a note on Sam and this job with addCandidateNote, for example “Sam can meet the engineering panel on Tuesday.” Give the note a requestId so a retry records it once. Save a candidate note

Send Alex the introduction through your email provider. Record the sent email with recordTouch, using Alex’s client contact ID and the job ID. Keep the touch ID and Alex’s person ID from the response. Pass those to recordPresentation with Sam’s candidate ID and the job ID. Alex starts with NO_ANSWER. Record the email · Record the introduction

If you’re building a shortlist screen, the Present list block shows how your team can review the candidates it wants to introduce.

3. Keep Alex’s reply with the introduction

Alex emails back, “Yes, let’s meet.” Record that incoming email against the same contact and job. Then call recordPresentationResponse with the presentation ID, the new touch ID, response: WANTS_INTRO and the time Alex replied. Reading the presentation now brings back Sam, Alex, the job and both emails. The appointment can be scheduled when you have a time. Save Alex’s response · Read the introduction

Download the eight GraphQL calls to run this example with your own records.