Select Page

Hiretual API


The Hiretual API will allow you to sync projects, candidates, and your hiring process. Using Hiretual API, customers can create a custom integration workflow for their ATS or CRM.


Table of Contents


Candidates

HiringProcesses

Projects


Authenticate

To access the API, you will need API Key and Client Id. Your API Key and Client Id can be found in the Settings -> API Credentials section of your Hiretual account. Every Hiretual account user will need their own API key to access Hireual API.


You authenticate to Hiretual API by providing X-API-KEY and X-CLIENT-ID headers to your API requests. You must authenticate for all the requests and all API requests must be made over HTTPS.

Partner With Hiretual

Please fill out this form and our partner team will get in touch with you to kick off the partnership.

Candidates

Create a new candidate

Request body

Body Parameter — Candidate JSON Body Parameters
Content-Type: application/json
{
  "fullname": "Brian Williams",
  "primary_email": "hello@sample.com",
  "extra_emails": ["hello@work.com","hello@example.com"],
  "work_authorization": null,
  "phone_number": 8888888888,
  "industry": "software",
  "image_url": "https://hiretual.s3.amazonaws.com/example",
  "indeed_url": "http://indeed.com/example",
  "candidate_summary": "CEO",
  "linkedin_url": "http://www.linkedin/in/sample",
  "linkedin_id": null,
  "location": "CA,USA",
  "address": "No.1 Sample Street",
  "current_company": "Hiretual",
  "current_title": "Engineer",
  "google_scholar_id": null,
  "facebook_url": "https://www.facebook.com/example",
  "twitter_url": "https://twitter.com/example",
  "angellist_url": "https://www.angel.co/example",
  "stackoverflow_url": "https://stackoverflow.com/example",
  "github_url": "https://www.github.com/example",
  "crunchbase_url": "https://crunchbase.com/example",
  "skype": "https://skype.com/example",
  "website": "https://example.com",
  "candidate_profile_url": "https://app.hiretual.com/example",
  "resume_url": "https://hiretual.s3.amazonaws.com/example(pdf,doc,docx)",
  "education": [
    {
      "education_school": "School Name",
      "education_major": "SC",
      "education_gpa": 4,
      "education_startyear": 2010,
      "education_endyear": 2014,
      "education_description": null,
      "education_activities": null
    }
  ],
  "position": [
    {
      "position_company": "Company Name",
      "position_title": "Engineer",
      "position_start_date": "2017-01-01T00:00:00.000Z",
      "position_end_date": "2019-01-01T00:00:00.000Z",
      "position_iscurrent": true
    }
  ]
}

Responses

201

Candidate information
{
  "id": "g636a294ea7865fd95.1343423420"
}

400

invalid input, object invalid

Get candidate information by candidate id

Path parameters

id (required)
Path Parameter — candidate id

Responses

200

Candidate information
{
    "award": [{
      "award_issuer" : "Award Issuer",
      "award_name" : "Award Name",
      "award_description" : "Award Description",
      "award_year" : 0
    }],
    "basic": {
        "angellist_url": "https://www.angel.co/example",
        "careerbuilder_url": "https://www.careerbuilder.com/example",
        "city": "San Francisco",
        "country": "United States",
        "current_company": "Apple",
        "crunchbase_url": "https://crunchbase.com/example",
        "current_title": "Software Engineer",
        "emails": ["hello@example.com"],
        "fullname": "Mark Anderson",
        "facebook_url": "https://www.facebook.com/example",
        "phone_numbers": ["8888888888"],
        "location": "San Francisco, California, United States",
        "gdpr_status": "Gdpr Status",
        "github_url": "https://github.com/example",
        "google_scholar_id": "Google Scholar Id",
        "healthgrades_url": "http://www.healthgrades.com/example",
        "highlight": " I am a software engineer & musician currently residing in California. I hold an M.M in Music Technology from New York University and a B.A. degree in Jazz Studies from the University of New Orleans. My passion lies in solving difficult problems in the mobile space and I am a proponent of simple and intuitive user experiences. I enjoy working in Agile work environments, where collaboration is strongly encouraged.\n I am proficient in Swift, Objective-C, C, JavaScript, Node.js, Python and Java. One of my hobbies is game development using Unity and Unreal game engines.\n Other specialties include organizing game hackathons, composing music and sound design for games, shredding my eight-string Novax guitar and cooking a mean Gumbo.",
        "indeed_url": "https://resumes.indeed.com/example",
        "kaggle_url": "https://www.kaggle.com/example",
        "linkedin_url": "https://www.linkedin.com/example",
        "stackoverflow_url": "https://stackoverflow.com/example",
        "state": "California",
        "twitter_url": "https://twitter.com/example",
        "user_create_date": "2016-04-21T15:41:25.000Z",
        "user_id": "fu5718f4a5ab88888.88888888",
        "user_update_date": "2020-03-05T16:35:07.000Z",
        "website": "https://example.com",
        "skill": ["composition", "music", "sound", "pro tools", "objective-c", "music education", "ableton live", "ios development", "javascript", "guitar", "final cut pro", "reason", "c", "html", "css", "logic pro", "swift", "music production", "unity", "finale", "music composition", "sound design", "event management", "fmod", "cruisecontrol", "unreal engine", "pure data", "word", "iwork"]
    },
    "certification": [{
      "certification_iscurrent" : true,
      "certification_country" : "Certification Country",
      "certification_name" : "Certification Name",
      "certification_start_date" : "Certification Start Date",
      "certification_license_number" : "Certification License Number",
      "certification_authority" : "Certification Authority",
      "certification_company" : "Certification Company",
      "certification_state" : "Certification State",
      "certification_end_date" : "Certification End Date",
      "certification_description" : "Certification Description"
    }],
    "education": [{
        "education_degree": "Master’s Degree",
        "education_description": "Education Description",
        "education_endyear": 2017,
        "education_major": "Entertainment Technology",
        "education_school": "Carnegie Mellon University",
        "education_startyear": 2015
    }, {
        "education_degree": "B.Tech",
        "education_description": "Education Description",
        "education_endyear": 2012,
        "education_major": "Computer Science and Engineering",
        "education_school": "Mahatma Gandhi University",
        "education_startyear": 2008
    }],
    "integrations": [{
        "company": "greenhouse",
        "profileId": 1488888888,
        "profileUrl": "https://app.greenhouse.io/people/1488888888"
    }],
    "language": [{
        "language_name": "English",
        "language_proficiency": "Native or bilingual proficiency"
    }],
    "organization": [{
          "organization_end_date" : "Organization End Date",
          "organization_description" : "Organization Description",
          "organization_iscurrent" : true,
          "organization_position" : "Organization Position",
          "organization_name" : "Organization Name",
          "organization_start_date" : "Organization Start Date"
    }],
    "patent": [{
        "patent_description": "Patent Description",
        "patent_issuer": "Patent Issuer",
        "patent_issuer_country": "Patent Issuer Country",
        "patent_url": "Patent URL",
        "patent_year": "Patent Year",
        "patent_title": "Patent Title",
        "patent_tracking_number": "Patent Tracking Number"
    }],
    "position": [{
        "position_company_name": "Apple",
        "position_title": "Software Engineer",
        "position_start_date": "2016-08-01T00:00:00.000Z",
        "position_end_date": "present",
        "position_iscurrent": true,
        "position_location": "San Francisco, CA",
        "position_summary": "Programmer and designer for visualization and data analysis software."
    }, {
        "position_company_name": "OpenGlobe Learning",
        "position_title": "Software Engineer, Designer (Contract)",
        "position_start_date": "2014-07-01T00:00:00.000Z",
        "position_end_date": "2014-10-01T00:00:00.000Z",
        "position_iscurrent": false,
        "position_location": "Santa Cruz, CA",
        "position_summary": "Worked on a cross-cultural learning tool to teach kids about different ways of thinking.\n\n* Designed web app interface for tablets\n* Implemented online activities in HTML/CSS/JS\n* Created intro video in After Effects"
    }, {
        "position_company_name": "Treofab, Inc.",
        "position_title": "Software Engineer (Contract)",
        "position_start_date": "2013-12-01T00:00:00.000Z",
        "position_end_date": "2014-01-01T00:00:00.000Z",
        "position_iscurrent": false,
        "position_location": "Santa Cruz, CA",
        "position_summary": "Worked on custom 3D product editing software.\n\nImplemented product editor interface:\n* Wrote WebGL code using the Three.js\nlibrary\n* Implemented mouse controls using\nraytracing\n* Implemented undo/redo stack, delete,\nchange variant, and other interface\nelements"
    }],
    "publication": [{
        "publication_year": 2014,
        "publication_description": "This paper presents MeanderMaps: a non-speech Augmented Reality Audio (ARA) application for Apple iPhone that aids in navigation purposes by sonifying geospatial data. Users request directions to a specified location on a Google Map overlay, and MeanderMaps uses spatial auditory cues such as distance and direction to guide him/her to the destination. As the user travels to consecutive waypoints known as path nodes, auditory cues indicate whether an incorrect turn has been made or if the user is traveling in the wrong direction. Preliminary findings are reported using qualitative and quantitative methods, evaluating the overall sonification model in addition to individual audio cues that (a) worked, (b) worked somewhat well, and (c) needed to be improved. Future improvements and modifications to MeanderMaps are presented.",
        "publication_organization": "International Conference on Auditory Display",
        "publication_title": "USE OF GEOSPATIAL DATA SONIFICATION FOR MOBILE AUGMENTED REALITY AUDIO NAVIGATION",
        "publication_citation": 0,
        "publication_url": "https://smartech.gatech.edu/bitstream/handle/1853/52057/Anderson%20-%20USE%20OF%20GEOSPATIAL%20DATA%20SONIFICATION%20FOR%20MOBILE%20AU.pdf?sequence=1"
    }],
    "recommendation": [{
        "recommendation": "Mark is a very interesting individual.  What is most notable to me is how all of a sudden, I kept hearing of this guy \"Mark Anderson\" and about how he is such a good guitar player, etc.  I would soon find out mark is a good guitar player, infact a GREAT guitar player.  Upon further investigation, I discovered that Mark had recently moved from to Providence from the south, I think Mississippi or Kentucky.  He quickly forged his reputation into the Providence music scene as a solid, versitile, and professional player.  I have learned how quickly he can learn music for projects and have come to appreciate his laid back, yet professional attitude.  It is a pleasure to have Mark as a part of our community in Providence.",
        "recommendation_type": "Recommendation Type"
    }, {
        "recommendation": "Mark is a wonderful musician and truly knows his stuff.  I began learning the Ableton Live production software by myself but realized that I needed more direction.  I met him in the Ableton Forums and found that he lived in the same area as me, so we scheduled some lessons.  \n\nMark has given me that direction and then some.  We've gone over many aspects of the production software, external hardware, composition and technical aspects of music itself.  I'm happy to have found Mark as a teacher and look forward to learning even more from his deep pool of knowledge.",
        "recommendation_type": "Recommendation Type"
    }],
    "volunteer": [{
      "volunteer_name" : "Volunteer Name",
      "volunteer_description" : "Volunteer Description"
    }]
}

400

bad input parameter

Search candidates
By passing in the appropriate options, you can search for available candidates in the system

Query parameters

keyword (optional)
Query Parameter — pass an optional keyword string for looking up candidates
project_id (optional)
Query Parameter — project id of candidates
page (optional)
Query Parameter — number of records to skip for pagination format: int
per_page (optional)
Query Parameter — maximum number of records to return format: int

Responses

200

Search results matching criteria
[
   {
      "id":"fu67c6fba4zab237.32939999",
      "link":"https://app.hiretual.com/talentprofile/fu67c6fba4zab237.32939999"
   },
   {
      "id":"9c783b6f-0938-4d8a-90e4-349aa253ff45",
      "link":"https://app.hiretual.com/talentprofile/9c783b6f-0938-4d8a-90e4-349aa253ff45"
   }
]

400

bad input parameter

Create candiate from resume

Path parameters

resume (required)
Path Parameter — resume file (pdf,doc,docx) format: binary

Request body

Body Parameter — Candidate Multipart Form Data Body Parameters
Content-Type: multipart/form-data

Responses

201

New candidate created
{
  "id": "8j36a294ea8965fd95.1367853420"
}

400

bad input parameter

HiringProcesses

Get all hiring processes

Responses

200

Search results matching criteria
[{
  "id" : 1,
  "hiringprocess_id" : "hp90ac786de08bdb7.33356876",
  "hiringprocess_name" : "Default Hiring Process",
  "hiringprocess_status" : 0,
  "hiringprocess_create_date" : "2018-04-01T00:00:00.000Z",
  "hiringprocess_user_id" : "78d76727-b476-4d09-bab9-4348f756e489",
  "hiringprocess_update_date" : "2018-04-01T00:00:00.000Z",
  "hiringprocess_team_id" : "team45ac678be90bdb7.33326876",
  "hiringprocess_detail" : [{
    "stages" : [
      {
        "stageStatus" : "active",
        "stageName" : "New",
        "isEditable" : false,
        "stageId" : 0
      }, {
        "stageStatus" : "active",
        "stageName" : "New",
        "isEditable" : false,
        "stageId" : 0
      }
    ],
    "categoryName" : "Sourcing",
    "categoryId" : 0
  }, {
    "stages" : [
      {
        "stageStatus" : "active",
        "stageName" : "New",
        "isEditable" : false,
        "stageId" : 0
      }, {
        "stageStatus" : "active",
        "stageName" : "New",
        "isEditable" : false,
        "stageId" : 0
      }
    ],
    "categoryName" : "Sourcing",
    "categoryId" : 0
  }]
}, {
  "id" : 2,
  "hiringprocess_id" : "hp34sd456de12byb7.33902276",
  "hiringprocess_name" : "Sample Hiring Process",
  "hiringprocess_status" : 0,
  "hiringprocess_create_date" : "2018-04-01T00:00:00.000Z",
  "hiringprocess_user_id" : "78d76727-b476-4d09-bab9-4348f756e489",
  "hiringprocess_update_date" : "2018-04-01T00:00:00.000Z",
  "hiringprocess_team_id" : "team45ac678be90bdb7.33326876",
  "hiringprocess_detail" : [{
    "stages" : [
      {
        "stageStatus" : "active",
        "stageName" : "New",
        "isEditable" : false,
        "stageId" : 0
      }, {
        "stageStatus" : "active",
        "stageName" : "New",
        "isEditable" : false,
        "stageId" : 0
      }
    ],
    "categoryName" : "Sourcing",
    "categoryId" : 0
  }, {
    "stages" : [
      {
        "stageStatus" : "active",
        "stageName" : "New",
        "isEditable" : false,
        "stageId" : 0
      }, {
        "stageStatus" : "active",
        "stageName" : "New",
        "isEditable" : false,
        "stageId" : 0
      }
    ],
    "categoryName" : "Sourcing",
    "categoryId" : 0
  }]
}]

400

bad input parameter

Get hiring processes by id

Path parameters

id (required)
Path Parameter — hiring processes id

Responses

200

Hiring process information
{
      "id" : 1,
      "hiringprocess_id" : "hp90ac786de08bdb7.33356876",
      "hiringprocess_name" : "Default Hiring Process",
      "hiringprocess_status" : 0,
      "hiringprocess_create_date" : "2018-04-01T00:00:00.000Z",
      "hiringprocess_user_id" : "78d76727-b476-4d09-bab9-4348f756e489",
      "hiringprocess_update_date" : "2018-04-01T00:00:00.000Z",
      "hiringprocess_team_id" : "team45ac678be90bdb7.33326876",
      "hiringprocess_detail" : [{
      "stages" : [
      {
      "stageStatus" : "active",
      "stageName" : "New",
      "isEditable" : false,
      "stageId" : 0
      }, {
      "stageStatus" : "active",
      "stageName" : "New",
      "isEditable" : false,
      "stageId" : 0
      }
      ],
      "categoryName" : "Sourcing",
      "categoryId" : 0
      }, {
      "stages" : [
      {
      "stageStatus" : "active",
      "stageName" : "New",
      "isEditable" : false,
      "stageId" : 0
      }, {
      "stageStatus" : "active",
      "stageName" : "New",
      "isEditable" : false,
      "stageId" : 0
      }
      ],
      "categoryName" : "Sourcing",
      "categoryId" : 0
      }]
      }

400

bad input parameter

Projects

Create a new project

Request body

Body Parameter — Project JSON Body Parameters
Content-Type: application/json
{
  "name": "Sample Project",
  "description": "This is a new sample project",
  "hiring_process_id": "hp5ac566d953ac4d1.15589506"
}

Responses

201

Project information
{
  "project_id": 871110,
  "project_name": "Sample Project",
  "project_description": "This is a new sample project",
  "project_hiring_process_id": "hp5ac566d953ac4d1.15589506",
  "project_status": "Active",
  "project_create_date": "2019-08-28T23:09:57.000Z",
  "project_update_date": "2019-08-28T23:09:57.000Z",
  "creator_id": "696576611c59eb77.99458934",
  "hiring_members": "Hiring members",
  "stage_details": "Stage details sample"
}

400

invalid input, object invalid

Delete project by project id

Path parameters

id (required)
Path Parameter — project id

Responses

200

Project deleted

400

bad input parameter

Get project by project id

Path parameters

id (required)
Path Parameter — project id

Responses

200

Project information
{
  "project_id": 871110,
  "project_team_id": "team45ac678be90bdb7.33326876",
  "project_user_id": "696576611c59eb77.99458934",
  "project_name": "Sample Project",
  "project_description": "This is a new sample project",
  "project_hiring_process_id": "hp90ac786de08bdb7.33356876",
  "project_status": "PROJECT_STATUS_NORMAL",
  "project_create_date": "2019-09-04T23:37:15.000Z",
  "project_update_date": "2019-10-09T00:31:31.000Z",
  "project_creator_id": "696576611c59eb77.99458934",
  "project_hiring_members": "Hiring members",
  "project_stage_details": "Stage details sample",
  "project_hiring_process":{
    "id": 1,
    "hiringprocess_id": "hp90ac786de08bdb7.33356876",
    "hiringprocess_team_id": "team45ac678be90bdb7.33326876",
    "hiringprocess_user_id": "78d76727-b476-4d09-bab9-4348f756e489",
    "hiringprocess_name": "Default Hiring Process",
    "hiringprocess_status": 0,
    "hiringprocess_create_date": "2018-04-02T02:26:38.000Z",
    "hiringprocess_update_date": "2018-04-02T02:26:38.000Z",
    "hiringprocess_detail":[{"stages":[{"stage_id": 0, "stage_name": "New", "stage_status": "active",…]
  }
}

400

bad input parameter

Search projects
By passing in the appropriate options, you can search for available projects in the system

Query parameters

project_name (optional)
Query Parameter — pass an optional project name string for looking up projects
page (optional)
Query Parameter — number of records to skip for pagination format: int
per_page (optional)
Query Parameter — maximum number of records to return format: int

Responses

200

Search results matching criteria
{
  "total": 127,
  "result": [
    {
      "project_id": 871110,
      "project_name": "Sample Project",
      "project_description": "This is a new sample project",
      "project_hiring_process_id": "hp90ac786de08bdb7.33356876",
      "project_status": "Active",
      "project_create_date": "2019-08-28T23:09:57.000Z",
      "project_update_date": "2019-08-28T23:09:57.000Z",
      "creator_id": "696576611c59eb77.99458934",
      "hiring_members": "Hiring members",
      "stage_details": "Stage details sample"
    }
  ]
}

400

bad input parameter

Update project information by project id

Path parameters

id (required)
Path Parameter — project id

Request body

Body Parameter — Project JSON Body Parameters
Content-Type: application/json
{
  "name": "Sample Project",
  "description": "This is a new sample project",
  "hiring_process_id": "hp90ac786de08bdb7.33356876"
}

Responses

200

Project information updated
{
  "project_id": 871110,
  "project_team_id": "team45ac678be90bdb7.33326876",
  "project_user_id": "696576611c59eb77.99458934",
  "project_name": "Sample Project",
  "project_description": "This is a new sample project",
  "project_hiring_process_id": "hp90ac786de08bdb7.33356876",
  "project_status": "PROJECT_STATUS_NORMAL",
  "project_create_date": "2019-09-04T23:37:15.000Z",
  "project_update_date": "2019-10-09T00:31:31.000Z",
  "project_creator_id": "696576611c59eb77.99458934",
  "project_hiring_members": "Hiring members",
  "project_stage_details": "Stage details sample",
  "project_hiring_process":{
    "id": 1,
    "hiringprocess_id": "hp90ac786de08bdb7.33356876",
    "hiringprocess_team_id": "team45ac678be90bdb7.33326876",
    "hiringprocess_user_id": "78d76727-b476-4d09-bab9-4348f756e489",
    "hiringprocess_name": "Default Hiring Process",
    "hiringprocess_status": 0,
    "hiringprocess_create_date": "2018-04-02T02:26:38.000Z",
    "hiringprocess_update_date": "2018-04-02T02:26:38.000Z",
    "hiringprocess_detail":[{"stages":[{"stage_id": 0, "stage_name": "New", "stage_status": "active",…]
  }
}

400

bad input parameter

Copyright © Hiretual 2020. All Rights Reserved