{"_id":"58da6127982c64230088c0c4","initVersion":{"_id":"587395fe11b3ec1900d3b6db","version":"3"},"user":{"_id":"55111100318f8c170023787a","username":"","name":"Nikos Moraitakis"},"__v":0,"project":"551111444878730d00220ecb","hidden":false,"createdAt":"2017-03-28T13:12:07.934Z","fullscreen":false,"htmlmode":false,"html":"","body":"## How it works\n\nThe first step is for Workable and the Video Interview Providers to be authenticated. Then the user can select one from the available/configured interviews from the Provider and push a candidate's information over, to create a new interview. When the candidate completes the interview, the Provider should inform Workable about the results.\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/613064f-video_interviews_push.png\",\n        \"video_interviews_push.png\",\n        925,\n        625,\n        \"#0b0808\"\n      ],\n      \"caption\": \"\"\n    }\n  ]\n}\n[/block]\nThere are 2 endpoints that should be provided, with `${BASE_URL}` being the root path for both of them:\n\n1. `https://${BASE_URL}/interview-templates` which allows the `GET` method and lists the available interview templates\n2. `https://${BASE_URL}/interviews` which allows the `POST` method and creates an invitation for a candidate\n\n> Workable provides an endpoint for receiving the results, see creating an interview for more info.\n\n### Authentication\n\n#### 1. Workable to Video Interview Provider\nEvery call from Workable towards the Video Interview Provider is authenticated using an access token contained in the Authentication HTTP Header. e.g. `Authorization: Bearer 78e3be68d98268509ea304a506ed6362d`. This token should be provided to the user from the Video Interview Provider and configured in the respective Workable account.\n\n#### 2. Video Interview Provider to Workable\nRegarding the requests originating from the Video Interview Provider, an access token will be generated and communicated upon the integration creation. This token should be included in the Authorization Header as well.\n\n> The Bearer token is the standard authorization scheme used in [OAuth 2](https://tools.ietf.org/html/rfc6750)\n\n\n[block:api-header]\n{\n  \"title\": \"Listing available interview templates\"\n}\n[/block]\nWorkable needs access in the available/configured interview templates; an authenticated `GET` is triggered towards the Video Interview Provider to fetch them. The endpoint should be formatted as `https://${BASE_URL}/interview-templates` and the response should be a JSON document with an array of interview templates. Each interview template is described through identification and name.\n\n## Response\n```json\n{\n  \"interview_templates\": [\n    {\n      \"id\": \"1\",\n      \"name\": \"Aptitude Interview\"\n    },\n    {\n      \"id\": \"2\",\n      \"name\": \"Java Interview\"\n    }\n  ]\n}\n```\n\n> One interview template per job can be selected. See below where the identification becomes handy.\n\n\n[block:api-header]\n{\n  \"title\": \"Listing available jobs (optional)\"\n}\n[/block]\nIf a job categorization of interviews is supported by the Video Interview Provider, then Workable can issue an authenticated `GET` to fetch them. The endpoint should be formatted as `https://${BASE_URL}/jobs` and the response should be a JSON document with an array of jobs. Each job is described through identification and name.\n\n## Response\n```json\n{\n  \"jobs\": [\n    {\n      \"id\": \"qa2e\",\n      \"name\": \"Accountant\"\n    },\n    {\n      \"id\": \"yec3\",\n      \"name\": \"Treasury Manager\"\n    }\n  ]\n}\n```\n\n> If this endpoint is provided, Workable will include a `job_id` in the interview creation step.\n\n\n[block:api-header]\n{\n  \"title\": \"Creating an interview\"\n}\n[/block]\nWorkable provides users with the ability to create an interview for a candidate on demand. If the action is called, Workable will `POST` the Video Interview Provider on `https://${BASE_URL}/interviews` with a payload that looks as follows:\n\n```json\n{\n  \"interview_template_id\": \"12345\",\n  \"job_id\": \"6789\",\n  \"job_title\": \"Operations Manager\",\n  \"callback_url\": \"https://groove-tech.workable.com/interviews/8823119\",\n  \"candidate\": {\n    \"first_name\": \"Lakita\",\n    \"last_name\": \"Marrero\",\n    \"phone\": \"(785)991-6256\",\n    \"email\": \"lakita_marrero@gmail.com\",\n  },\n  \"preferences\": {\n    \"key\": \"value\"\n  }\n}\n```\n\n* `interview_template_id`: The identification provided in the previous step\n* `job_id`: (Optional) The job identified in the list jobs step\n* `job_title`: The job that the candidate applied to. Can be contained in the invitation email.\n* `callback_url`: The URL in which the Video Interview Provider should publish the results (see below)\n* `candidate`: Candidate info. Can be used in the invitation email.\n* `preferences`: This field can be used to pass custom values to the Video Interview Provider\n\n> The Video Interview Provider should respond with a `201` status and an identifier for the created interview.\n> ```json\n> { \"interview_id\": \"2044922\" }\n> ```\n\n\n[block:api-header]\n{\n  \"title\": \"Results collection\"\n}\n[/block]\n### 1. Publishing the Results to Workable\n\nThere are 4 statuses for an interview. The initial status is `pending` and then the interview can be `completed`, `rejected` or `expired`. The status depends on the actions of the candidate regarding the interview. Whenever the status changes, the Video Interview Provider should publish the new status to Workable using `PUT` on the `callback_url` provided in the interview creation step.\n\n> When the status is completed, the request should include the interview results.\n\n### 2. Publishing the Results on an API\n\nAnother alternative is for Workable to poll the endpoint `https://${BASE_URL}/interviews/:id` with the interview identifier returned in the interview creation step. This method however is suboptimal since it requires more than one requests until the results are finally fetched. Moreover, a failsafe mechanism should be created in case the invitation was rejected by the candidate.\n\nIn both cases the payload provided by the Video Interview Provider should be as follows:\n\n```json\n{\n  \"results_url\": \"https://acme.com/interviews/2044922\",\n  \"status\": \"completed\",\n  \"interview\": {\n    \"score\": \"78\",\n    \"grade\": \"excelled\",\n    \"summary\": \"This candidate is an excellent prospect.\",\n    \"details\": {\n        \"behavior\": {\n          \"Influence\": 97,\n          \"conscientiousness\": 76\n        },\n        \"mental_skills\":  {\n          \"Problem Solving\": 82,\n          \"Aptitude\": 91\n        }\n    },\n    \"duration\": \"01:01:17\"\n  },\n  \"attachments\": [\n    {\n      \"description\": \"Interview Report\",\n      \"url\": \"https://acme.com/interviews/2044922/report.pdf\"\n    }\n  ]\n}\n```\n\n* `results_url`: A link to the fully fledged report on the Provider's site\n* `status`: This can take any of the values `completed`, `declined` or `expired`\n* `grade`: This is the final conclusion of the interview, it can take any of the values `failed`, `passed` or `excelled`. This is respectively mapped to `no`, `yes` and `definitely yes` in Workable evaluation system.\n* `interview`:\n  * `score`: An overall score, preferably a percentage\n  * `summary`: Small description/evaluation of the interview\n  * `details`: This can be used to provide a deeper analysis on the candidate's results. It's a JSON with a maximum of two levels nested objects and is presented to the user with minimum formatting, so keys should be descriptive and readable. The structure should follow the `key: value` format, no arrays should be included and a first level value may be consisted of more objects itself. Any values holding dates should conform to ISO 8601.\n  * `duration`: How long did it take the candidate to complete the interview, if available\n* `attachments`: Currently only supporting PDF. A results report of the interview along with a description, if available. The URL should be publicly accessible.\n\n## Errors\n\nThe endpoints of the Video Interview Provider should handle request errors with a status code followed by a readable message. The description message should be short yet verbose enough to facilitate ease of troubleshooting.\n\n\n| Type            | Status        | Example messages                         |\n|:---------------:|:-------------:| ---------------------------------------- |\n| Authentication  | `401`         | *Missing Token*                          |\n| Authentication  | `401`         | *Invalid Token*                          |\n| Invalid Request | `400`         | *Invalid JSON*                           |\n| Invalid Request | `400`         | *Invalid field: name should be a string* |\n| Invalid Request | `422`         | *Missing field: name should be provided* |\n\n> A valid response on an Error would be\n> ```json\n> { \"status\": 401, \"message\": \"Invalid Token\" }\n> ```\n\n### 3. Retrieving a shared link\n\nThis is an optional `GET` endpoint to be implemented by the Video Interview Provider. This endpoint serves interview links, in case when the system supports sharing public links. The URL should look like `https://${BASE_URL}/interviews/:id/shared-link` and the `interview-id` should be the one returned from the interview creation call.\n\n## Response\n```json\n{\n  \"url\": \"https://acme.com/interviews/2044922/link\",\n  \"ttl\": \"120\",\n  \"ttl_units\": \"minutes\"\n}\n```\n\n* `url`: A link to the public shared report on the Provider's site\n* `ttl`: (Optional) The time this link will be available. If this is not set, the link is assumed to be permanent.\n* `ttl_units`: The units used for measuring the TTL. Currently supported values: `minutes`, `days` and `views`.","slug":"video-interview-providers","title":"Video Interview Providers"}

Video Interview Providers


## How it works The first step is for Workable and the Video Interview Providers to be authenticated. Then the user can select one from the available/configured interviews from the Provider and push a candidate's information over, to create a new interview. When the candidate completes the interview, the Provider should inform Workable about the results. [block:image] { "images": [ { "image": [ "https://files.readme.io/613064f-video_interviews_push.png", "video_interviews_push.png", 925, 625, "#0b0808" ], "caption": "" } ] } [/block] There are 2 endpoints that should be provided, with `${BASE_URL}` being the root path for both of them: 1. `https://${BASE_URL}/interview-templates` which allows the `GET` method and lists the available interview templates 2. `https://${BASE_URL}/interviews` which allows the `POST` method and creates an invitation for a candidate > Workable provides an endpoint for receiving the results, see creating an interview for more info. ### Authentication #### 1. Workable to Video Interview Provider Every call from Workable towards the Video Interview Provider is authenticated using an access token contained in the Authentication HTTP Header. e.g. `Authorization: Bearer 78e3be68d98268509ea304a506ed6362d`. This token should be provided to the user from the Video Interview Provider and configured in the respective Workable account. #### 2. Video Interview Provider to Workable Regarding the requests originating from the Video Interview Provider, an access token will be generated and communicated upon the integration creation. This token should be included in the Authorization Header as well. > The Bearer token is the standard authorization scheme used in [OAuth 2](https://tools.ietf.org/html/rfc6750) [block:api-header] { "title": "Listing available interview templates" } [/block] Workable needs access in the available/configured interview templates; an authenticated `GET` is triggered towards the Video Interview Provider to fetch them. The endpoint should be formatted as `https://${BASE_URL}/interview-templates` and the response should be a JSON document with an array of interview templates. Each interview template is described through identification and name. ## Response ```json { "interview_templates": [ { "id": "1", "name": "Aptitude Interview" }, { "id": "2", "name": "Java Interview" } ] } ``` > One interview template per job can be selected. See below where the identification becomes handy. [block:api-header] { "title": "Listing available jobs (optional)" } [/block] If a job categorization of interviews is supported by the Video Interview Provider, then Workable can issue an authenticated `GET` to fetch them. The endpoint should be formatted as `https://${BASE_URL}/jobs` and the response should be a JSON document with an array of jobs. Each job is described through identification and name. ## Response ```json { "jobs": [ { "id": "qa2e", "name": "Accountant" }, { "id": "yec3", "name": "Treasury Manager" } ] } ``` > If this endpoint is provided, Workable will include a `job_id` in the interview creation step. [block:api-header] { "title": "Creating an interview" } [/block] Workable provides users with the ability to create an interview for a candidate on demand. If the action is called, Workable will `POST` the Video Interview Provider on `https://${BASE_URL}/interviews` with a payload that looks as follows: ```json { "interview_template_id": "12345", "job_id": "6789", "job_title": "Operations Manager", "callback_url": "https://groove-tech.workable.com/interviews/8823119", "candidate": { "first_name": "Lakita", "last_name": "Marrero", "phone": "(785)991-6256", "email": "lakita_marrero@gmail.com", }, "preferences": { "key": "value" } } ``` * `interview_template_id`: The identification provided in the previous step * `job_id`: (Optional) The job identified in the list jobs step * `job_title`: The job that the candidate applied to. Can be contained in the invitation email. * `callback_url`: The URL in which the Video Interview Provider should publish the results (see below) * `candidate`: Candidate info. Can be used in the invitation email. * `preferences`: This field can be used to pass custom values to the Video Interview Provider > The Video Interview Provider should respond with a `201` status and an identifier for the created interview. > ```json > { "interview_id": "2044922" } > ``` [block:api-header] { "title": "Results collection" } [/block] ### 1. Publishing the Results to Workable There are 4 statuses for an interview. The initial status is `pending` and then the interview can be `completed`, `rejected` or `expired`. The status depends on the actions of the candidate regarding the interview. Whenever the status changes, the Video Interview Provider should publish the new status to Workable using `PUT` on the `callback_url` provided in the interview creation step. > When the status is completed, the request should include the interview results. ### 2. Publishing the Results on an API Another alternative is for Workable to poll the endpoint `https://${BASE_URL}/interviews/:id` with the interview identifier returned in the interview creation step. This method however is suboptimal since it requires more than one requests until the results are finally fetched. Moreover, a failsafe mechanism should be created in case the invitation was rejected by the candidate. In both cases the payload provided by the Video Interview Provider should be as follows: ```json { "results_url": "https://acme.com/interviews/2044922", "status": "completed", "interview": { "score": "78", "grade": "excelled", "summary": "This candidate is an excellent prospect.", "details": { "behavior": { "Influence": 97, "conscientiousness": 76 }, "mental_skills": { "Problem Solving": 82, "Aptitude": 91 } }, "duration": "01:01:17" }, "attachments": [ { "description": "Interview Report", "url": "https://acme.com/interviews/2044922/report.pdf" } ] } ``` * `results_url`: A link to the fully fledged report on the Provider's site * `status`: This can take any of the values `completed`, `declined` or `expired` * `grade`: This is the final conclusion of the interview, it can take any of the values `failed`, `passed` or `excelled`. This is respectively mapped to `no`, `yes` and `definitely yes` in Workable evaluation system. * `interview`: * `score`: An overall score, preferably a percentage * `summary`: Small description/evaluation of the interview * `details`: This can be used to provide a deeper analysis on the candidate's results. It's a JSON with a maximum of two levels nested objects and is presented to the user with minimum formatting, so keys should be descriptive and readable. The structure should follow the `key: value` format, no arrays should be included and a first level value may be consisted of more objects itself. Any values holding dates should conform to ISO 8601. * `duration`: How long did it take the candidate to complete the interview, if available * `attachments`: Currently only supporting PDF. A results report of the interview along with a description, if available. The URL should be publicly accessible. ## Errors The endpoints of the Video Interview Provider should handle request errors with a status code followed by a readable message. The description message should be short yet verbose enough to facilitate ease of troubleshooting. | Type | Status | Example messages | |:---------------:|:-------------:| ---------------------------------------- | | Authentication | `401` | *Missing Token* | | Authentication | `401` | *Invalid Token* | | Invalid Request | `400` | *Invalid JSON* | | Invalid Request | `400` | *Invalid field: name should be a string* | | Invalid Request | `422` | *Missing field: name should be provided* | > A valid response on an Error would be > ```json > { "status": 401, "message": "Invalid Token" } > ``` ### 3. Retrieving a shared link This is an optional `GET` endpoint to be implemented by the Video Interview Provider. This endpoint serves interview links, in case when the system supports sharing public links. The URL should look like `https://${BASE_URL}/interviews/:id/shared-link` and the `interview-id` should be the one returned from the interview creation call. ## Response ```json { "url": "https://acme.com/interviews/2044922/link", "ttl": "120", "ttl_units": "minutes" } ``` * `url`: A link to the public shared report on the Provider's site * `ttl`: (Optional) The time this link will be available. If this is not set, the link is assumed to be permanent. * `ttl_units`: The units used for measuring the TTL. Currently supported values: `minutes`, `days` and `views`.