Interview API User Guide


By using this API, this API documentation, and/or building the integration, you agree to the Additional API Terms and Guidelines.


Use the Interview API to schedule and conduct virtual interviews with job candidates. Create, update, and delete virtual interview events.

  1. Before you start
  2. Create an interview
  3. Update an interview
  4. Delete an interview

References:

Before you start

Use of this API is gated by a developer agreement. Contact marketplacesupport@indeed.com to request access before attempting to develop against this API.
  1. Read the additional terms and guidelines to understand Indeed’s requirements to use the Interview API.

    Guidelines:

    • You agree to place a button in your user interface that will allow your clients (Employers) to create an interview with Indeed Platform. The button will meet the specifications provided by Indeed.

    • You agree to accurately describe to a Jobseeker:

      • What information and data you collect from and about that Jobseeker and how that data is shared with Indeed when such Jobseeker are scheduled for an interview, including how you handle and share such information and data.

    • You also agree to honor a Jobseeker request for their information and data that you collect in connection with any API.

    • You agree to provide ATS Name, Employer Name, Job Identifiers, and Interviewee email address, via this API, when that data is available to you.

  2. Follow these steps to get a client ID for your application and authenticate using an OAuth token generated by an Indeed account.

    • Request the interviews scope when creating the token.

    • Select an Indeed employer if one is associated with the account. This is passed to the caller as an advertiser ID in an ID token; it represents that employer.

    • Indeed will create a new Interview OAuth scope to grant to the API caller.

    • You will receive an access token (lasts 1h), a refresh token (lasts 30d), and an ID token (contains user information).

Create an interview

To create an interview, you need to:

  1. Call our API and provide a list of email strings:

    • Email addresses of known interviewers.

    • Email address of the interviewee. (optional)

  2. Provide back the advertiser ID if one is present in the ID token.

  3. Provide a start date and end date with a timezone for the interview.

    • Note: the timezone will be used to display time for both the interviewee and interviewers in the event.

  1. Provide a string for the title of the interview (likely the same as the calendar event.)

  2. Provide strings for:

    • atsName: The partner application (usually ATS) that the request is from (if you have it and are not an ATS.)

    • employerName: The employer name (if you have it.)


Note:
  • The API does not require an interviewee object to be sent with interview creation. However, if one is not provided, the API will not return the interviewee URL.
  • If you don’t have an interviewee name but need an interviewee URL, we recommend you create an interviewee object with the name Candidate. You can always change the interviewee object later by updating the interview event.

Example request:

createVirtualInterviewEvent(input: {
   interviewers: [{email: "test@example.com"}]
   startTime: "2022-06-01 09:30:00.00Z"
   endTime: "2022-06-01 10:30:00.00Z"
   timezone: America/New_York
   name: "Interview with Candidate Name"
   createRequestMetadata: {}
}) {
   virtualInterviewEvent {
       id
       interviewerLobbyUrl
       intervieweesConnection {
            ...on interviewees {
                intervieweeLobbyUrl
           }
       }
   }
}
Note: You must get the URL for the interviewee from the intervieweeConnection.interviewee list.

What happens after creating an interview?

Indeed returns:

  • Confirmation that the interview was scheduled or an error code.
  • A unique interview ID that can then be used to read and delete an interview.
  • A text blob to be sent to interviewers and the interviewee, containing a join link for interviewers and a separate join link for the interviewee.

Indeed also sends these communications:

  • Indeed emails each interviewer on the event immediately to let them know they’ve been added to the interview.
  • A few minutes before the interview begins, Indeed emails the interviewee (if an interviewee email address was provided) to remind them that they have an interview coming up and to provide the link again.

The scheduler:

  • Notifies all attendees that the event has been created, and puts calendar items on the calendar of each interviewer.
  • Sends the interviewer link to the interviewers, and the interviewee link to the interviewee.

Interviewers:

  • When it’s time to start the interview, interviewers must log in with Indeed accounts matching the email address that was scheduled.
  • Any interviewer without an Indeed account will need to create one.
  • Interviewees do not need to create accounts.

Update an interview

To update an interview, you need to:

  • Authenticate using an OAuth token with an account that represents one of the interviewers on the event, or the scheduler.

  • Call our API to update the interview:

    • Provide the unique interview ID.

    • Provide any fields you need to update per the list above.

Example request:

rescheduleVirtualInterviewEvent(input: {
   eventId: "1facd23b-4333-46c3-a356-627798f72619",
   startTime: "2022-06-04 09:30:00.00Z",
   endTime: "2022-06-04 10:30:00.00Z"
}) {
   result {
       startTime
       endTime
   }
}

Delete an interview

To delete an interview, you need to:

  • Authenticate using the same account that was used to create the interview.

  • Call our API to delete the interview:

    • Provide the unique interview ID.

Example request:

deleteVirtualInterviewEvent(input: {
   id: "1facd23b-4333-46c3-a356-627798f72619"
}) {
   result {
       id
  }
}




GraphQL schema

type Mutation {
    """
    Create a Virtual Interview Event with one interviewee. This adds the scheduler to the interviewer list for the event 
   
    Get the URL for the interviewee from the VirtualInterviewInterviewee object in the intervieweeConnection list.
    """
    createVirtualInterviewEvent(
        input: CreateVirtualInterviewEventInput!
    ): CreateVirtualInterviewEventPayload

    """ 
    Update the details of a VirtualInterviewEvent
    """
    updateVirtualInterviewEvent(
        input: UpdateVirtualInterviewEventInput!
    ): UpdateVirtualInterviewEventPayload

    """ 
    Update the details of a VirtualInterviewEvent Interviewee
    """
    updateVirtualInterviewInterviewee(
        input: UpdateVirtualInterviewIntervieweeInput!
    ): UpdateVirtualInterviewIntervieweePayload

    """ 
    Delete a VirtualInterviewEvent
    """
    deleteVirtualInterviewEvent(
        input: DeleteVirtualInterviewEventInput!
    ): DeleteVirtualInterviewEventPayload
}

""" 
Input for the Virtual Interview Event.
VirtualInterviewIntervieweeInput is not required. 
Hold on to the VirtualInterviewInterviewee ID to make updates to the VirtualInterviewInterviewee.
"""
input CreateVirtualInterviewEventInput {
    """
    The list of interviewers allowed in the VirtualInterviewEvent
    """
    interviewers: [VirtualInterviewInterviewerInput!]!
    """
    Scheduled start time for the event. RFC3339 string value with timezone offset
    """
    startTime: DateTime!
    """
    Scheduled end time for the event. RFC3339 string value with timezone offset
    """
    endTime: DateTime!
    """
    Timezone of event used to display local time on event pages. Timezone input should follow IANA time zone database name format 
    """
    timezone: TimeZone!
    """
    The scheduler’s specified title of the event
    """
    title: String!
    """
    Optional interviewee information
    """
    interviewee: VirtualInterviewIntervieweeInput
    """
    Information about the request
    """
    requestMetadata: VirtualInterviewRequestMetadataInput
}

"""
Partner metadata related to the request
"""
input VirtualInterviewRequestMetadataInput {
    atsName: String
    employerName: String
}

"""
Input for a VirtualInterview Interviewee
"""
input VirtualInterviewIntervieweeInput {
    name: String
    email: EmailAddress!
}

"""
Input for a Virtual Interview Interviewer
"""
input VirtualInterviewInterviewerInput {
    name: String
    email: EmailAddress!
}

type CreateVirtualInterviewEventPayload {
    virtualInterviewEvent: VirtualInterviewEvent!
}

type VirtualInterviewEvent {
    """
    The event's UUID identifier
    """
    id: ID!
    """
    The scheduler’s specified title of the event
    """
    title: String!
    """
    Scheduled start time for the event. RFC3339 string value with timezone offset
    """
    startTime: DateTime!
    """
    Scheduled end time for the event. RFC3339 string value with timezone offset
    """
    endTime: DateTime!
    """
    Timezone of event used to display time on event pages
    """
    timezone: TimeZone!
    """
    List of interviewers allowed in the Virtual Interview Event
    """
    interviewersConnection(first: Int = 10, after: String, before: String, last: Int) : VirtualInterviewInterviewersConnection!
    """    
    Interviewer’s URL to the event lobby for this Virtual Interview Event
    """
    interviewerLobbyUrl: WebUrl!
    """
    The language code of the event. An ISO 639-1 - alpha 2 language code string
    """
    languageCode: LanguageCode!
    """
    The country code of the event. An ISO 3166-1 - alpha 2 country code string
    """
    countryCode: CountryCode!
    """
    The list of interviewees for a Virtual Interview Event
    """
    intervieweesConnection(first: Int = 10, after: String, before: String, last: Int) : VirtualInterviewIntervieweeConnection!
    """
    The VirtualInterviewEvent’s current status
    """
    status: VirtualInterviewEventStatus!
    """
    The media type of the VirtualInterviewEvent
    """
    mediaType: VirtualInterviewMediaType!
}

type VirtualInterviewInterviewersConnection {
    """
    Edges for pagination
    """
    edges: [VirtualInterviewInterviewerEdge!]!
    """
    Page info for pagination. Defined in com.indeed.graphql.relay.PageInfo
    """
    pageInfo: PageInfo!
    """
    The list of allowed interviewers for this page
    """
    interviewers: [VirtualInterviewInterviewer!]!
    """
    The total result count ignoring pagination
    """
    totalCount: Int!
}

type VirtualInterviewIntervieweeConnection {
    """
    Edges for pagination
    """
    edges: [VirtualInterviewIntervieweeEdge!]!
    """
    Page info for pagination. Defined in com.indeed.graphql.relay.PageInfo
    """
    pageInfo: PageInfo!
    """
    The list of interviewees for this page
    """
    interviewees: [VirtualInterviewInterviewee!]!
    """
    The total result count ignoring pagination
    """
    totalCount: Int!
    """
    The list of jobs for this event
    """
    jobsSummary: [VirtualInterviewJob]!
}

type VirtualInterviewInterviewee {
    """
    The UUID unique identifier of the interviewee for the VirtualInterviewEvent
    """
    id: ID!
    """
    The interviewee's name
    """
    name: String!
    """
    The interviewee's email address
    """  
    email: EmailAddress
    """
    The URL for the Interviewee to join the lobby for the VirtualInterviewEvent
    """
    intervieweeLobbyUrl: WebUrl!
    """
    Information about the job the Interviewee is interviewing for
    """
    job: VirtualInterviewJob
}

"""
Union type describing the output options for job information
"""
union VirtualInterviewJob = VirtualInterviewJobInfo | EmployerJob


type VirtualInterviewJobData {
    """
    The job title
    """
    title: String
    """
    The job location
    """
    location: String
}

type VirtualInterviewInterviewer {
    """
    The interviewer's global UUID unique identifier
    """
    id: ID!
    """
    The interviewee's email address
    """
    email: EmailAddress!
    """
    The interviewee's name
    """
    name: String
}

"""
The media format on which the interviews will take place
"""
enum VirtualInterviewMediaType {
    """
    Type describing Indeed Interview video interviews
    """
    VIDEO
    """
    Type describing Indeed Interview phone interviews
    """
    PHONE
}

"""
Current status of the Event
"""
enum VirtualInterviewEventStatus {
    SCHEDULED
    STARTED
    ENDED
    ARCHIVED
    CANCELLED
}

"""
Only one of the following fields can be sent in one update request. Updates are made to one use case per mutation. 
Interviewee info can be updated via the updateVirtualInterviewEventInterviewee mutation.
"""
input UpdateVirtualInterviewEventInput {
    interviewersToAdd: UpdateVirtualInterviewEventInterviewersInput
    interviewersToRemove: UpdateVirtualInterviewEventInterviewersInput
    reschedule: RescheduleVirtualInterviewEventInput
    title: UpdateVirtualInterviewEventTitleInput
    timezone: UpdateVirtualInterviewEventTimezoneInput
}

input UpdateVirtualInterviewEventInterviewersInput {
    """
    ID of the VirtualInterviewEvent
    """
    id: ID!
    """
    The list of interviewers to update
    """
    interviewers: [VirtualInterviewInterviewerInput!]!
}

input RescheduleVirtualInterviewEventInput {
    """
    ID of the VirtualInterviewEvent
    """
    id: ID!
    """
    Updated scheduled start time for the event. RFC3339 string value with timezone offset
    """
    startTime: DateTime!
    """
    Updated scheduled end time for the event. RFC3339 string value with timezone offset
    """
    endTime: DateTime!
}

input UpdateVirtualInterviewEventTitleInput {
    """
    ID of the VirtualInterviewEvent
    """
    id: ID!
    """
    Updated title of the event
    """
    title: String!
}

input UpdateVirtualInterviewEventTimezoneInput {
    """
    ID of the VirtualInterviewEvent
    """
    id: ID!
    """
    Updated timezone of the event used to display time on event pages
    """
    timezone: TimeZone!
}


type UpdateVirtualInterviewEventPayload {
    virtualInterviewEvent: VirtualInterviewEvent!
}


input UpdateVirtualInterviewIntervieweeInput {
    """
    ID of the VirtualInterviewInterviewee for the VirtualInterviewEvent
    """
    id: ID!
    input: VirtualInterviewIntervieweeInput!
}


type UpdateVirtualInterviewIntervieweePayload {
    interviewee: VirtualInterviewInterviewee!
}


input DeleteVirtualInterviewEventInput {
    """
    ID of the VirtualInterviewEvent
    """
    id: ID!
}

type DeleteVirtualInterviewEventPayload {
    result: DeleteVirtualInterviewEventResult!
}

type DeleteVirtualInterviewEventResult {
    """
    ID of the VirtualInterviewEvent
    """
    id: ID! 
}

type VirtualInterviewInterviewerEdge {
    """
    The interviewer item
    """
    node: VirtualInterviewInterviewer!
    """
    The cursor position of the node
    """
    cursor: String!
}

type VirtualInterviewIntervieweeEdge {
    """
    The interviewee item
    """
    node: VirtualInterviewInterviewee!
    """
    The cursor position of the node
    """
    cursor: String!
}