Recruitee Careers Site API

API Endpoint
https://company.recruitee.com
A new documentation with more examples and possibility to test the endpoints, is available at https://docs.recruitee.com

The Recruitee Careers Site API allows to show company’s jobs and add new candidates to jobs.

API does not require authorization and is available under your Careers Site address (for example https://yourcompany.recruitee.com).

Candidates

Candidate

POST https://company.recruitee.com/api/offers/operations-manager/candidates
Requestsjsonform-data
Headers
Content-Type: application/json
Body
{
  "candidate": {
    "name": "John Smith",
    "email": "john.smith@example.com",
    "phone": "987654321",
    "cover_letter": "Example cover letter",
    "remote_photo_url": "https://site.example.com/images/myimage.jpeg",
    "remote_cv_url": "https://site.example.com/resumes/myresume.pdf",
    "open_question_answers_attributes": [
      {
        "open_question_id": 5,
        "content": "Yes"
      },
      {
        "open_question_id": 8,
        "content": "Responsibility"
      },
      {
        "open_question_id": 9,
        "content": "Blue"
      },
      {
        "open_question_id": 10,
        "multi_content": ["Pizza", "Hamburger"]
      }
      {
        "open_question_id": 11,
        "remote_file_url": "https://site.example.com/files/additional_file.jpg"
      }
    ]
  }
}
Responses201422
Body
{
  "candidate": {
    "id": 53,
    "name": "John Smith",
    "phones": [
      "987654321"
    ],
    "emails": [
      "john.smith@example.com"
    ],
    "photo_url": "https://storage.example.com/53/normal_photo_1453899932.jpg",
    "photo_thumb_url": "https://storage.example.com/53/thumb_photo_1453899932.jpg",
    "updated_at": "2016-01-27T13:05:32.368Z",
    "created_at": "2016-01-27T13:05:32.368Z",
    "open_question_answers": [
      {
        "id": 100,
        "question": "Do you like pizza?",
        "content": "Yes",
        "file_url": "null"
      },
      {
        "id": 101,
        "question": "What are your strengths?",
        "content": "Responsibility",
        "file_url": "null"
      },
      {
        "id": 102,
        "question": "Your favorite color?",
        "content": "Blue",
        "file_url": "null"
      },
      {
        "id": 103,
        "question": "What kind of food do you like?",
        "content": "Pizza, Hamburger",
        "file_url": "null"
      },
      {
        "id": 104,
        "question": "Additional file",
        "content": "null",
        "file_url": "https://storage.example.com/attachments/200/additional_file_1453899932.jpg"
      }
    ]
  }
}
Schema
{
  "type": "object",
  "properties": {
    "candidate": {
      "type": "object",
      "properties": {
        "id": {
          "type": "number"
        },
        "name": {
          "type": "string"
        },
        "phones": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "emails": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "photo_url": {
          "type": "string"
        },
        "photo_thumb_url": {
          "type": "string"
        },
        "updated_at": {
          "type": "string"
        },
        "created_at": {
          "type": "string"
        },
        "open_question_answers": {
          "type": "array",
          "items": {
            "anyOf": [
              {
                "type": "object",
                "properties": {
                  "id": {
                    "type": "number"
                  },
                  "question": {
                    "type": "string"
                  },
                  "content": {
                    "type": "string"
                  },
                  "file_url": {
                    "type": "string"
                  }
                }
              },
              {
                "type": "object",
                "properties": {
                  "id": {
                    "type": "number"
                  },
                  "question": {
                    "type": "string"
                  },
                  "content": {
                    "type": "string"
                  },
                  "file_url": {
                    "type": "string"
                  }
                }
              },
              {
                "type": "object",
                "properties": {
                  "id": {
                    "type": "number"
                  },
                  "question": {
                    "type": "string"
                  },
                  "content": {
                    "type": "string"
                  },
                  "file_url": {
                    "type": "string"
                  }
                }
              },
              {
                "type": "object",
                "properties": {
                  "id": {
                    "type": "number"
                  },
                  "question": {
                    "type": "string"
                  },
                  "content": {
                    "type": "string"
                  },
                  "file_url": {
                    "type": "string"
                  }
                }
              },
              {
                "type": "object",
                "properties": {
                  "id": {
                    "type": "number"
                  },
                  "question": {
                    "type": "string"
                  },
                  "content": {
                    "type": "string"
                  },
                  "file_url": {
                    "type": "string"
                  }
                }
              }
            ]
          }
        }
      }
    }
  },
  "$schema": "http://json-schema.org/draft-04/schema#"
}
Body
{
  "error": [
    "Name can't be blank",
    "Email can't be blank",
    "Email is invalid",
    "Cv can't be blank",
    "Phone can't be blank"
  ]
}
Headers
Content-Type: application/x-www-form-urlencoded
Body
candidate[name]=John Smith&
candidate[email]=john.smith@example.com&
candidate[phone]=987654321&
candidate[cover_letter]=Example cover_letter&
candidate[cv]=#<ActionDispatch::Http::UploadedFile>&
candidate[photo]=#<ActionDispatch::Http::UploadedFile>&
candidate[open_question_answers_attributes][0][open_question_id]=5&
candidate[open_question_answers_attributes][0][content]=Yes&
candidate[open_question_answers_attributes][1][open_question_id]=8&
candidate[open_question_answers_attributes][1][content]=Responsibility&
candidate[open_question_answers_attributes][2][open_question_id]=9&
candidate[open_question_answers_attributes][2][content]=Blue&
candidate[open_question_answers_attributes][3][open_question_id]=10&
candidate[open_question_answers_attributes][3][multi_content][]=Pizza&
candidate[open_question_answers_attributes][3][multi_content][]=Hamburger&
candidate[open_question_answers_attributes][3][open_question_id]=11&
candidate[open_question_answers_attributes][3][file]=#<ActionDispatch::Http::UploadedFile>
Responses201422
Body
{
  "candidate": {
    "id": 53,
    "name": "John Smith",
    "phones": [
      "987654321"
    ],
    "emails": [
      "john.smith@example.com"
    ],
    "photo_url": "https://storage.example.com/53/normal_photo_1453899932.jpg",
    "photo_thumb_url": "https://storage.example.com/53/thumb_photo_1453899932.jpg",
    "updated_at": "2016-01-27T13:05:32.368Z",
    "created_at": "2016-01-27T13:05:32.368Z",
    "open_question_answers": [
      {
        "id": 100,
        "question": "Do you like pizza?",
        "content": "Yes",
        "file_url": "null"
      },
      {
        "id": 101,
        "question": "What are your strengths?",
        "content": "Responsibility",
        "file_url": "null"
      },
      {
        "id": 102,
        "question": "Your favorite color?",
        "content": "Blue",
        "file_url": "null"
      },
      {
        "id": 103,
        "question": "What kind of food do you like?",
        "content": "Pizza, Hamburger",
        "file_url": "null"
      },
      {
        "id": 104,
        "question": "Additional file",
        "content": "null",
        "file_url": "https://storage.example.com/attachments/200/additional_file_1453899932.jpg"
      }
    ]
  }
}
Schema
{
  "type": "object",
  "properties": {
    "candidate": {
      "type": "object",
      "properties": {
        "id": {
          "type": "number"
        },
        "name": {
          "type": "string"
        },
        "phones": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "emails": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "photo_url": {
          "type": "string"
        },
        "photo_thumb_url": {
          "type": "string"
        },
        "updated_at": {
          "type": "string"
        },
        "created_at": {
          "type": "string"
        },
        "open_question_answers": {
          "type": "array",
          "items": {
            "anyOf": [
              {
                "type": "object",
                "properties": {
                  "id": {
                    "type": "number"
                  },
                  "question": {
                    "type": "string"
                  },
                  "content": {
                    "type": "string"
                  },
                  "file_url": {
                    "type": "string"
                  }
                }
              },
              {
                "type": "object",
                "properties": {
                  "id": {
                    "type": "number"
                  },
                  "question": {
                    "type": "string"
                  },
                  "content": {
                    "type": "string"
                  },
                  "file_url": {
                    "type": "string"
                  }
                }
              },
              {
                "type": "object",
                "properties": {
                  "id": {
                    "type": "number"
                  },
                  "question": {
                    "type": "string"
                  },
                  "content": {
                    "type": "string"
                  },
                  "file_url": {
                    "type": "string"
                  }
                }
              },
              {
                "type": "object",
                "properties": {
                  "id": {
                    "type": "number"
                  },
                  "question": {
                    "type": "string"
                  },
                  "content": {
                    "type": "string"
                  },
                  "file_url": {
                    "type": "string"
                  }
                }
              },
              {
                "type": "object",
                "properties": {
                  "id": {
                    "type": "number"
                  },
                  "question": {
                    "type": "string"
                  },
                  "content": {
                    "type": "string"
                  },
                  "file_url": {
                    "type": "string"
                  }
                }
              }
            ]
          }
        }
      }
    }
  },
  "$schema": "http://json-schema.org/draft-04/schema#"
}
Body
{
  "error": [
    "Name can't be blank",
    "Email can't be blank",
    "Email is invalid",
    "Cv can't be blank",
    "Phone can't be blank"
  ]
}

Create a Candidate
POST/api/offers/{offer_id}/candidates

Apply for the job offer (create candidate).

Required candidate parameters:

  • name

  • email

  • phone

  • cv

API also allows to answer for the job’s questions. You just need to attach list of answers to the request. Answer consists of question ID and content (always is string, regardless of questions type).

If you use form-data request, do not forget to escape [ with %5B and ] with %5D.

If you create candidates with heavy media files e.g. PDFs, add async=true parameter in the request URL to ensure that file upload finishes before candidate is created.

URI Parameters
HideShow
offer_id
string (required) Example: operations-manager

Offer slug

Offers

Offers List

GET https://company.recruitee.com/api/offers/?department=ExampleDepartment
Responses200
Headers
Content-Type: application/json
Body
[
  {
    "id": 1,
    "title": "Operations Manager",
    "slug": "operations-manager",
    "position": 8,
    "status": "published",
    "department": "ExampleDepartment",
    "description": "<p>Example job description</p>",
    "requirements": "<p>Example job requirements</p>",
    "options_phone": "required",
    "options_photo": "optional",
    "options_cover_letter": "optional",
    "options_cv": "required",
    "open_questions": [
      {
        "id": 5,
        "kind": "boolean",
        "body": "Do you like pizza?",
        "required": true,
        "open_question_options": []
      },
      {
        "id": 8,
        "kind": "string",
        "body": "What are your strengths?",
        "required": true,
        "open_question_options": []
      },
      {
        "id": 9,
        "kind": "single_choice",
        "body": "Your favorite color?",
        "required": true,
        "open_question_options": [
          {
            "id": 15,
            "body": "Green"
          },
          {
            "id": 16,
            "body": "Blue"
          },
          {
            "id": 17,
            "body": "Yellow"
          }
        ]
      },
      {
        "id": 10,
        "kind": "multi_choice",
        "body": "What kind of food do you like?",
        "required": true,
        "open_question_options": [
          {
            "id": 21,
            "body": "Pizza"
          },
          {
            "id": 23,
            "body": "Hamburger"
          },
          {
            "id": 24,
            "body": "Hot-dog"
          }
        ]
      },
      {
        "id": 11,
        "kind": "file",
        "body": "Additional file",
        "required": true,
        "open_question_options": []
      }
    ],
    "location": "London, United Kingdom",
    "country": "United Kingdom",
    "city": "London",
    "country_code": "GB",
    "state_code": "EN",
    "careers_url": "https://examplecompany.recruitee.com/o/operations-manager",
    "mailbox_email": "job.sxdcr@/examplecompany.recruitee.com",
    "created_at": "2016-01-05T15:20:34.961Z"
  }
]
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "array"
}

Get Offers
GET/api/offers/{?department}

Returns a collection of company jobs.

You can filter a collection by department.

URI Parameters
HideShow
department
string (optional) Example: ExampleDepartment

Filter job offers by department name

Generated by aglio on 22 Nov 2016