{"openapi":"3.0.3","info":{"title":"Recruitment Marketing","version":"1.0.0","description":"Interactive documentation for the [PageUp Recruitment Marketing](https://www.pageuppeople.com/products/recruitment-marketing/) API.\n\nFor information on accquiring your API credentials and implementing your own API client please refer to our [PageUp Knowledge Portal](https://knowledgeportal.pageuppeople.com/hc/en-gb/articles/17127248228249-Clinch-API-Getting-Started).\n\nPlease ensure you are on the correct region for your account.\n\n* [US Region](https://api.clinchtalent.com/v1/openapi)\n* [EU Region](https://api.rec-marketing.dc3.pageuppeople.com/v1/openapi)\n* [AU Region](https://api.rec-marketing.dc2.pageuppeople.com/v1/openapi)\n\nPlease note the `x-hmac-date` header can be replaced with a regular `date` header.\n\nWhen authorizing please use your API key & secret in place of username & password.\n"},"servers":[{"url":"https://api.clinchtalent.com/v1"}],"paths":{"/candidates":{"get":{"summary":"List candidates","description":"List known candidates with options to paginate, filter and return related resources(e.g. social_profile).","operationId":"listCandidates","tags":["Candidate"],"parameters":[{"$ref":"#/components/parameters/page"},{"$ref":"#/components/parameters/perPage"},{"$ref":"#/components/parameters/candidateInclude"},{"$ref":"#/components/parameters/candidateFilter"}],"responses":{"200":{"description":"Success"},"401":{"description":"Invalid API credentials"}}},"post":{"summary":"Add a new candidate","description":"Returns a new candidate object","operationId":"createCandidate","tags":["Candidate"],"requestBody":{"required":true,"content":{"application/vnd.api+json":{"schema":{"required":["data"],"properties":{"data":{"type":"object","required":["type","attributes"],"properties":{"type":{"type":"string","example":"candidate"},"attributes":{"type":"object","required":["email"],"properties":{"first_name":{"type":"string","example":"Jane"},"last_name":{"type":"string","example":"Smith"},"email":{"type":"string","format":"email","example":"jane.smith@example.com"},"phone_number":{"type":"string","example":"+1-202-555-0169"},"tag_values":{"type":"array","items":{"type":"string"},"example":["foo","bar"]}}}}}}}}}},"responses":{"201":{"description":"Created"},"401":{"description":"Invalid API credentials"},"422":{"description":"Unprocessable entity"}}}},"/candidates/{candidateId}":{"get":{"summary":"Find candidate by ID","description":"Returns a candidate and optionally includes related resources(e.g. social_profile).","operationId":"getCandidate","tags":["Candidate"],"parameters":[{"$ref":"#/components/parameters/candidateId"},{"$ref":"#/components/parameters/candidateInclude"}],"responses":{"200":{"description":"Success"},"401":{"description":"Invalid API credentials"},"404":{"description":"Not found"}}},"patch":{"summary":"Update candidate by ID","operationId":"updateCandidate","tags":["Candidate"],"parameters":[{"$ref":"#/components/parameters/candidateId"}],"requestBody":{"required":true,"content":{"application/vnd.api+json":{"schema":{"required":["data"],"properties":{"data":{"type":"object","required":["type","attributes"],"properties":{"type":{"type":"string","example":"candidate"},"attributes":{"type":"object","properties":{"first_name":{"type":"string","example":"New first name"},"last_name":{"type":"string","example":"New last name"}}}}}}}}}},"responses":{"200":{"description":"Success"},"401":{"description":"Invalid API credentials"},"404":{"description":"Not found"},"422":{"description":"Unprocessable entity"}}}},"/candidates/{candidateId}/tags":{"get":{"summary":"List candidate tags","description":"List the tags for a candidate","operationId":"getCandidateTag","tags":["Candidate"],"parameters":[{"$ref":"#/components/parameters/candidateId"}],"responses":{"200":{"description":"Success"},"401":{"description":"Invalid API credentials"},"404":{"description":"Not found"}}},"post":{"summary":"Create candidate tag","description":"Creates a tag for a candidate","operationId":"createCandidateTag","tags":["Candidate"],"requestBody":{"required":true,"content":{"application/vnd.api+json":{"schema":{"required":["data"],"properties":{"data":{"type":"object","required":["type","attributes"],"properties":{"type":{"type":"string","example":"tag"},"attributes":{"type":"object","required":["email"],"properties":{"name":{"type":"string","example":"Tag Name"}}}}}}}}}},"parameters":[{"$ref":"#/components/parameters/candidateId"}],"responses":{"200":{"description":"Success"},"401":{"description":"Invalid API credentials"},"404":{"description":"Not found"}}}},"/candidates/{candidateId}/tags/{tagId}":{"delete":{"summary":"Delete candidate tag","description":"Deletes a candidate tag","operationId":"deleteCandidateTag","tags":["Candidate"],"parameters":[{"$ref":"#/components/parameters/candidateId"},{"in":"path","name":"tagId","description":"UUID of the tag to delete","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"401":{"description":"Invalid API credentials"},"404":{"description":"Not found"}}}},"/candidates/{candidateId}/candidate_files":{"post":{"summary":"Upload a candidates resume","description":"Upload a candidates resume. Both filename and content are mandatory. Content should be a base64 encoded string.","operationId":"createCandidateFile","tags":["Candidate"],"requestBody":{"required":true,"content":{"application/vnd.api+json":{"schema":{"required":["data"],"properties":{"data":{"type":"object","required":["type","attributes"],"properties":{"type":{"type":"string","example":"candidate_files"},"attributes":{"type":"object","required":["filename","content"],"properties":{"filename":{"type":"string","description":"resume.pdf"},"content":{"type":"string","format":"byte","description":"base64 encoded string"}}}}}}}}}},"parameters":[{"$ref":"#/components/parameters/candidateId"}],"responses":{"201":{"description":"Created - File was added to the Candidate."},"401":{"description":"Invalid API credentials"},"404":{"description":"Not found"},"422":{"description":"Unprocessable entity - File was not added to the Candidate."}}}},"tags":[{"name":"Candidate","description":"Candidate operations"},{"name":"Job","description":"Job operations"},{"name":"List","description":"List operations"}]},"components":{"securitySchemes":{"HMAC":{"type":"http","scheme":"basic"}},"parameters":{"page":{"in":"query","name":"page","required":false,"schema":{"type":"integer"}},"perPage":{"in":"query","name":"per_page","required":false,"schema":{"type":"integer","example":5}},"candidateId":{"in":"path","name":"candidateId","description":"Candidate ID","required":true,"schema":{"type":"string"}},"candidateInclude":{"in":"query","name":"include","description":"Specify candidate relationships to include in the response","required":false,"type":"array","explode":false,"schema":{"type":"array","items":{"type":"string","enum":["events.call_to_action","events.form_submission.fields","social_profile","page_sessions","timeline_entries","timeline_entries.lifecycle","form_submissions","web_sessions.events.user_agent","web_sessions.events.call_to_action","web_sessions.events.form_submission.fields","web_sessions.events.city","messages.from","list_memberships","locations","static_lists","project_template_stages","cities","recent_location","resumes","newest_event","jobs","job_applications","notes"]}}},"candidateFilter":{"in":"query","name":"filter","description":"To filter candidates by `updated_at`, add the query parameters `filter[updated_at][(operator)]` e.g. `/candidates?filter[updated_at][lt]=2021-01-01T13:00:17`. Two operators are supported. `lt` meaning \"less than\", and `gte` meaning \"greater than or equal to\". They can be combined e.g. `/candidates?filter[updated_at][gte]=2020-01-01T00:00:00&filter[updated_at][lt]=2021-01-01T00:00:00`\n\nTo filter candidates by `email`, add the query parameters `filter[email][eq]` e.g. `/candidates?filter[email][eq]=name%40example.com`\n","required":false,"schema":{"type":"object","properties":{"updated_at":{"type":"object","properties":{"gte":{"type":"string","format":"date-time","example":"2021-01-01T13:00:17"}}}}},"style":"deepObject","explode":true},"jobInclude":{"in":"query","name":"include","description":"Specify whether to include categories in the response","required":false,"type":"array","explode":false,"schema":{"type":"array","items":{"type":"string","enum":["categories"]}}},"listId":{"in":"path","name":"listId","description":"List ID","schema":{"type":"string"}}},"schemas":{"Candidate":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string","example":"candidates"},"attributes":{"type":"object","properties":{"uid":{"type":"string","description":"Randomly generated unique identifier consisting of alphanumeric characters"},"created_at":{"$ref":"#/components/schemas/DateTime"},"updated_at":{"$ref":"#/components/schemas/DateTime"},"links":{"type":"object","properties":{"edit":{"properties":{"url":{"type":"string"}}},"self":{"properties":{"url":{"type":"string"}}},"modal":{"properties":{"url":{"type":"string"}}},"archive":{"properties":{"url":{"type":"string"}}},"linkedin_search":{"properties":{"url":{"type":"string"}}},"mail_to":{"properties":{"url":{"type":"string"}}},"tel":{"properties":{"url":{"type":"string"}}},"linkedin":{"properties":{"url":{"type":"string"}}}}},"name":{"type":"string"},"first_name":{"type":"string"},"last_name":{"type":"string"},"kind":{"type":"string"},"email":{"type":"string"},"phone_number":{"type":"string"},"tags":{"type":"array","items":{"type":"string","example":["Seed Data"]}},"skills":{"type":"array","items":{"type":"string","example":["business analysis","management","project delivery","requirements specifications"]}},"interaction_score":{"type":"number","minimum":0,"maximum":1,"description":"Metric for evaluating the engagement of a candidate"},"industry":{"type":"string"},"subscription_status":{"type":"string","enum":["unsubscribed","subscribed"]},"internal_candidate":{"type":"boolean"},"has_linkedin":{"type":"boolean"},"linkedin_connected":{"type":"boolean"},"last_seen_at":{"$ref":"#/components/schemas/DateTime"},"last_location":{"type":"string"},"last_employer_name":{"type":"string"},"last_employment_title":{"type":"string"},"in_eu":{"type":"boolean"},"manually_added":{"type":"boolean"},"visit_count":{"type":"integer"},"custom_data":{"type":"object","description":"This attribute is used to store company specific data against a candidate"},"job_departments_viewed":{"type":"array","items":{"type":"string","example":["Systems Integration"]}},"job_categories_viewed":{"type":"array","items":{"type":"string","example":["Information Technology","Engineering"]}},"job_cities":{"type":"array","items":{"type":"string","example":["Austin"]}},"first_seen_at":{"$ref":"#/components/schemas/DateTime"},"educated_at":{"type":"array","items":{"type":"string","example":["Harvard University"]}},"studied":{"type":"array","items":{"type":"string","example":["Business","Marketing"]}},"first_traffic_source_name":{"type":"string","description":"The traffic source name of the \"first touch event\" associated with a candidate.","example":"LinkedIn"},"last_traffic_source_name":{"type":"string"},"applications_started_date":{"$ref":"#/components/schemas/DateTime"},"ats_statuses":{"type":"array","description":"All of the ATS statuses associated with a candidate e.g. Review, Interview, Offer, etc.","items":{"type":"object","example":["CandidateEvent"]}},"latest_ats_status":{"type":"object","description":"The most recent ATS status associated with a candidate e.g. Review, Interview, Offer, etc."},"utm_parameters":{"type":"object","description":"URL parameters used for tracking the effectiveness of an online marketing campaign Extracted from links that the candidate clicked on e.g. https://acme.career-pages.com?utm_source=linked_in","properties":{"source":{"type":"string"},"medium":{"type":"string"},"campaign":{"type":"string"},"term":{"type":"string"},"content":{"type":"string"}}}}},"relationships":{"type":"object","description":"The id and event type of the association record","properties":{"social_profile":{"description":"This is the candidate's social profile (to be deprecated)","example":{"id":"680e8c9dff1f3946fb4ef612caefc6d2","type":"social_profiles"},"allOf":[{"$ref":"#/components/schemas/DataType"}]},"page_sessions":{"description":"The pages which the candidate viewed during a web session","example":{"id":"35b24aace05952641a90752f26638691","type":"page_sessions"},"allOf":[{"$ref":"#/components/schemas/DataType"}]},"resumes":{"description":"The resume documents uploaded by the candidate","example":{"id":"dbba840f1a68c9d2c96ed15f47cc4c5c","type":"candidate_files"},"allOf":[{"$ref":"#/components/schemas/DataType"}]},"web_sessions":{"example":{"id":"975e35450d408211df636b29a0ae83f7","type":"candidate_web_sessions"},"allOf":[{"$ref":"#/components/schemas/DataType"}]},"form_submissions":{"description":"The call to action form submissions","example":{"id":"30b25014753b4977b139855f9a32a846","type":"form_submissions"},"allOf":[{"$ref":"#/components/schemas/DataType"}]},"form_submission_fields":{"description":"The fields completed on a call to action form","example":{"id":"0aea4a5d0878998cd89026dd4dc9501e","type":"form_submission_fields"},"allOf":[{"$ref":"#/components/schemas/DataType"}]},"job_alert_subscriptions":{"allOf":[{"$ref":"#/components/schemas/DataType"}]},"events":{"example":{"id":"e3c4276c9d7311f5021083e9888b6df7","type":"candidate_events"},"allOf":[{"$ref":"#/components/schemas/DataType"}]},"project_template_stages":{"description":"A list of projects template stages belonging to a candidate. It consists of a uid, and a stage name, and a project name","allOf":[{"$ref":"#/components/schemas/DataType"}]},"static_lists":{"description":"The static lists to which the candidate belongs","example":{"id":"4320a760576121f4e870b79fbd3e1904","type":"company_lists"},"allOf":[{"$ref":"#/components/schemas/DataType"}]},"locations":{"description":"The recorded locations of the candidate","example":{"id":"ed63f07fa6015fbe4f9a643e149c132a","type":"candidate_locations"},"allOf":[{"$ref":"#/components/schemas/DataType"}]},"recent_location":{"description":"The most recently recorded location of the candidate","allOf":[{"$ref":"#/components/schemas/DataType"}]},"jobs":{"description":"All of the jobs associated with a candidate's activities e.g. the jobs that a candidate has viewed, applied for, received ATS statuses about etc.","example":{"id":"4aa454fa42106969bc4a6ea2366262e5","type":"jobs"},"allOf":[{"$ref":"#/components/schemas/DataType"}]},"job_applications":{"description":"The job applications that the candidate has submitted","allOf":[{"$ref":"#/components/schemas/DataType"}]},"notes":{"description":"The notes recorded of the candidate by an agent/recruiter","example":{"id":"5a403ce1f54c195712cf8f390554cdee","type":"candidate_notes"},"allOf":[{"$ref":"#/components/schemas/DataType"}]},"project_entry":{"allOf":[{"$ref":"#/components/schemas/DataType"}]},"call_to_actions":{"example":{"id":"9e4f3ad3c87ec69f14f826e1f7b7074b","type":"call_to_actions"},"allOf":[{"$ref":"#/components/schemas/DataType"}]},"jobs_application_dropped_off":{"example":{"id":"7c6ac6d1159bbbf36543eeb7b07256cc","type":"jobs"},"allOf":[{"$ref":"#/components/schemas/DataType"}]},"jobs_applied":{"allOf":[{"$ref":"#/components/schemas/DataType"}]},"jobs_favourited":{"allOf":[{"$ref":"#/components/schemas/DataType"}]},"jobs_viewed":{"allOf":[{"$ref":"#/components/schemas/DataType"}]},"pages_performed_cta":{"example":{"id":"f842577ea7fa637cb189bfe21b84dc8b","type":"pages"},"allOf":[{"$ref":"#/components/schemas/DataType"}]},"pages_viewed":{"allOf":[{"$ref":"#/components/schemas/DataType"}]},"recruitment_events":{"allOf":[{"$ref":"#/components/schemas/DataType"}]},"web_campaigns":{"example":{"id":"28a34a729c942d49a9e0f001e5efc6e6","type":"web_campaigns"},"allOf":[{"$ref":"#/components/schemas/DataType"}]}}}}},"DateTime":{"type":"object","properties":{"utc":{"type":"string","format":"date-time"},"epoch":{"type":"integer","format":"int64"},"ago":{"type":"string"},"local":{"type":"string","format":"date-time"},"local_epoch":{"type":"integer","format":"int64"}}},"DataType":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string"}}}}},"security":[{"HMAC":[]}]}