NAV
shell

Introduction

Welcome to the WedgeHR Connect API!

This API allows you to do things like fetch a list of interviews, create an invite for a candidate, and view your existing invites. For assistance, feel free to reach out to success@wedgehr.com.

Looking for the legacy API v1? See the API v1 Reference.

Environments

Use the following hostnames and base paths based on your environment:

Hostname Base Path Port TLS ENV / Usage
api.wedgebeta.com /connect/v2 443 true Staging / Dev
api.wedgehr.com /connect/v2 443 true Production

API Key

Start by logging in at WedgeHR Hire App

Click Settings at the top and then Integrations on the left menu

settings

Now click Connect Integration

integration

Copy your Integration Token and use it to interact with the WedgeHR Connect API

Authentication

Example request with authentation header:

# With shell, you can just pass the correct header with each request
curl "<connect-api>"
  -H "Authorization: Bearer $API_KEY"

Make sure to replace $API_KEY!.

WedgeHR uses an API key to allow access to the API. This API key is company specific.

WedgeHR expects for the API key to be included in all API requests to the server in a header which looks like the following:

Authorization: Bearer $API_KEY

Invites

Properties of an Invite

An invite contains the following properties:

Property Type Description
id int unique identifier of this invite
interviewId int ID of the interview this invite belongs to
email string Email of the candidate this invite belongs to
inviteSent bool Indicates if an invite has been sent to the Candidate
status string The status of the invite, one of unknown, invited, complete, send_failure, canceled
resultUrl string The public URL to the result
inviteUrl string the public URL to the invite
createdAt string Timestamp of when invite was created
expiresAt string Timestamp of when invite expires - null if invite has does not expire or is complete
completedAt string Timestamp of when invite was completed

Create an Invite

Parameter Type Description Required
interviewId int ID of the interview this invitation belongs to Yes
email string Email of the candidate Yes
firstName string The first name of the candidate No
lastName string The last name of the candidate No
shouldSendInvite bool Should an invitation be sent to the candidate No
uniqueId string Add your own ID No

Possible Response Codes

Code Description
201 Successfully created invite
422 Validation error - one or more required fields are missing
500 Something unexpected happened ( Contact Us ) 
curl "<connect-api>/invites"
  -H "Content-Type: application/json"
  -H "Authorization: Bearer ACCESS_TOKEN"
  -X POST
  --data '{"interviewId": 2, "email": "fred@example.io", "firstName": "Fred", "lastName": "Smith", "shouldSentInvite": true, "uniqueId": "abc123"}'

The above command returns JSON structured like this:

{
  "data": {
    "id": 4017600317622981,
    "interviewId": 7749825975819241,
    "email": "job_invite@wedge.test",
    "uniqueId": "32092387-2b2c-48f0-b864-2019c48fd4ce",
    "inviteUrl": "https://record.wedge.video/4017600317622981.CfWf85vQJNsqmbtMgRsjwX",
    "resultUrl": null,
    "inviteSent": true,
    "status": "invited",
    "createdAt": "2023-09-01T00:00:00Z",
    "expiresAt": null,
    "completedAt": null
  }
}

This endpoint creates a specific invite.

HTTP Request

POST <connect-api>/invites

List Invites

curl "<connect-api>/invites?filter[id]=1234"
  -H "Authorization: Bearer ACCESS_TOKEN"

The above command returns JSON structured like this:

{
  "data": [
    {
      "id": 7952721015002024,
      "interviewId": 5911293050157308,
      "email": "job_invite@wedge.test",
      "uniqueId": "32092387-2b2c-48f0-b864-2019c48fd4ce",
      "inviteUrl": "https://record.wedge.video/7952721015002024.sew9R6MWqgrTAqukzJogxT",
      "resultUrl": null,
      "inviteSent": true,
      "status": "invited",
      "createdAt": "2023-09-01T00:00:00Z",
      "expiresAt": null,
      "completedAt": null
    }
  ],
  "meta": {
    "path": "<connect-api>invites",
    "per_page": 30
  },
  "pagination": {
    "prev": null,
    "next": null
  }
}

This endpoint retrieves a specific invitation.

HTTP Request

Get by All

GET <connect-api>/invites

Get by Interview ID

GET <connect-api>/invites?filter[interviewId]=2482948239842

Get by Invite ID

GET <connect-api>/invites?filter[id]=9588249528452

Get by Unique ID

GET <connect-api>/invites?filter[uniqueId]=abc123

Get by Email

GET <connect-api>/invites?filter[email]=test@wedge.test

Get by Status

GET <connect-api>/invites?filter[status]=invited

Status accepts either the string label (unknown, invited, complete, send_failure, canceled) or its numeric equivalent (0–4).

Possible Response Codes

Code Description
200 Success
400 Bad filter ID given
403 System could not fetch session data ( Contact Us )
404 No invites found for given filter query
500 Something unexpected happen ( Contact Us )

Get an Invite

curl "<connect-api>/invites/7952721015002024"
  -H "Authorization: Bearer ACCESS_TOKEN"

The above command returns JSON structured like this:

{
  "data": {
    "id": 7952721015002024,
    "interviewId": 5911293050157308,
    "email": "job_invite@wedge.test",
    "uniqueId": "32092387-2b2c-48f0-b864-2019c48fd4ce",
    "inviteUrl": "https://record.wedge.video/7952721015002024.sew9R6MWqgrTAqukzJogxT",
    "resultUrl": null,
    "inviteSent": true,
    "status": "invited",
    "createdAt": "2023-09-01T00:00:00Z",
    "expiresAt": null,
    "completedAt": null
  }
}

This endpoint retrieves a single invite by its ID.

HTTP Request

GET <connect-api>/invites/:id

Possible Response Codes

Code Description
200 Success
403 System could not fetch session data ( Contact Us )
404 Invite not found
500 Something unexpected happen ( Contact Us )

Wedges

Properties of a Wedge

A fetched wedge contains these properties

Property Type Description
id int unique identifier of this wedge
candidateEmail string Email of the candidate
candidateFirstName string? First name of the candidate
candidateLastName string? Last name of the candidate
interviewId int ID of the interview
interviewName string Name of the interview
interviewNameContextualized string Contextualized name of the interview
expiresAt string? Timestamp of when the wedge expires, null if wedge does not expire or is complete
completedAt string? Timestamp of when the wedge was completed
createdAt string Timestamp of when the wedge was created
resultUrl string? The public URL to the result
invites list<Invite> List of invites associated with this wedge

List Wedges

curl "<connect-api>/wedges"
  -H "Authorization: Bearer ACCESS_TOKEN"

The above command returns JSON structured like this:

{
  "data": [
    {
      "id": 4017600317622981,
      "candidateFirstName": "Fred",
      "candidateLastName": "Smith",
      "candidateEmail": "job_invite@wedge.test",
      "interviewId": 5911293050157308,
      "interviewName": "General Practitioner",
      "interviewNameContextualized": "General Practitioner",
      "expiresAt": null,
      "completedAt": null,
      "createdAt": "2023-09-01T00:00:00Z",
      "resultUrl": null,
      "invites": [
        {
          "id": 7952721015002024,
          "interviewId": 5911293050157308,
          "email": "job_invite@wedge.test",
          "uniqueId": "32092387-2b2c-48f0-b864-2019c48fd4ce",
          "inviteUrl": "https://record.wedge.video/7952721015002024.sew9R6MWqgrTAqukzJogxT",
          "resultUrl": null,
          "inviteSent": true,
          "status": "invited"
        }
      ]
    }
  ],
  "meta": {
    "path": "<connect-api>/wedges",
    "per_page": 30
  },
  "pagination": {
    "prev": null,
    "next": null
  }
}

This endpoint retrieves wedges.

HTTP Request

Get All

GET <connect-api>/wedges

Get by Wedge ID

GET <connect-api>/wedges?filter[id]=4017600317622981

Get by Interview ID

GET <connect-api>/wedges?filter[interviewId]=5911293050157308

Get by Email

GET <connect-api>/wedges?filter[email]=test@wedge.test

Possible Response Codes

Code Description
200 Success
400 Bad filter given
404 No wedges found for given filter query
500 Something unexpected happen ( Contact Us )

Get a Wedge

curl "<connect-api>/wedges/4017600317622981"
  -H "Authorization: Bearer ACCESS_TOKEN"

The above command returns JSON structured like this:

{
  "data": {
    "id": 4017600317622981,
    "candidateFirstName": "Fred",
    "candidateLastName": "Smith",
    "candidateEmail": "job_invite@wedge.test",
    "interviewId": 5911293050157308,
    "interviewName": "General Practitioner",
    "interviewNameContextualized": "General Practitioner",
    "completedAt": null,
    "createdAt": "2023-09-01T00:00:00Z",
    "resultUrl": null,
    "invites": [
      {
        "id": 7952721015002024,
        "interviewId": 5911293050157308,
        "email": "job_invite@wedge.test",
        "uniqueId": "32092387-2b2c-48f0-b864-2019c48fd4ce",
        "inviteUrl": "https://record.wedge.video/7952721015002024.sew9R6MWqgrTAqukzJogxT",
        "resultUrl": null,
        "inviteSent": true,
        "status": "invited"
      }
    ]
  }
}

This endpoint retrieves a single wedge by its ID.

HTTP Request

GET <connect-api>/wedges/:id

Possible Response Codes

Code Description
200 Success
403 System could not fetch session data ( Contact Us )
404 Wedge not found
500 Something unexpected happen ( Contact Us )

Resend Invite

curl "<connect-api>/wedges/4017600317622981/resend-invite"
  -H "Authorization: Bearer ACCESS_TOKEN"
  -X POST

The above command returns JSON structured like this:

{
  "data": {
    "id": 4017600317622981,
    "candidateFirstName": "Fred",
    "candidateLastName": "Smith",
    "candidateEmail": "job_invite@wedge.test",
    "interviewId": 5911293050157308,
    "interviewName": "General Practitioner",
    "interviewNameContextualized": "General Practitioner",
    "expiresAt": null,
    "completedAt": null,
    "createdAt": "2023-09-01T00:00:00Z",
    "resultUrl": null,
    "invites": [
      {
        "id": 7952721015002024,
        "interviewId": 5911293050157308,
        "email": "job_invite@wedge.test",
        "uniqueId": "32092387-2b2c-48f0-b864-2019c48fd4ce",
        "inviteUrl": "https://record.wedge.video/7952721015002024.sew9R6MWqgrTAqukzJogxT",
        "resultUrl": null,
        "inviteSent": true,
        "status": "invited"
      }
    ]
  }
}

This endpoint resends the invite for a wedge.

HTTP Request

POST <connect-api>/wedges/:id/resend-invite

Possible Response Codes

Code Description
200 Successfully resent invite
403 System could not fetch session data ( Contact Us )
404 Wedge not found
500 Something unexpected happen ( Contact Us )

Interviews

Properties of an Interview

A fetched interview contains these properties

Property Type Description
id int unique identifier of this interview
companyId int ID of the company this interview belongs to
name string Name of the interview
nameContextualized string Contextualized name of the interview
properties list List of custom properties, each with name (string) and value (string)

List Interviews

HTTP Request

Get all your WedgeHR interviews. The results are paginated with cursors.

GET <connect-api>/interviews

GET <connect-api>/interviews?page[cursor]=cursorKey&page[size]=10

Search by Name

GET <connect-api>/interviews?filter[search]=Acme

Possible Response Codes

Code Description
201 Successfully fetched interviews
500 Something unexpected happened ( Contact Us ) 
curl "<connect-api>/interviews?page[size]=2"
  -H "Authorization: Bearer ACCESS_TOKEN"

The above command returns JSON structured like this:

{
  "data": [
    {
      "_type": "interview",
      "id": 1382244997593464,
      "companyId": 7182893298555114,
      "name": "Movers",
      "nameContextualized": "Movers",
      "properties": [{ "name": "Location", "value": "Chicago" }],
      "createdAt": "2023-09-01T00:00:00Z"
    },
    {
      "_type": "interview",
      "id": 5972691925058329,
      "companyId": 7182893298555114,
      "name": "General Practitioner",
      "nameContextualized": "General Practitioner",
      "properties": [],
      "createdAt": "2023-09-01T00:00:00Z"
    }
  ],
  "meta": {
    "path": "<connect-api>/interviews",
    "per_page": 2
  },
  "pagination": {
    "prev": null,
    "next": "eyJqb2IuaWQiOjU5NzI2OTE5MjUwNTgzMjksIl9wb2ludHNUb05leHRJdGVtcyI6dHJ1ZX0"
  }
}

Pagination

Pagination

Pagination can be used when fetching interviews and invites.

Append page[size]=30 to set the page size for the data returned. Maximum size is 100.

At the bottom of the JSON returned on the right you will notice the pagination object.

"pagination": {
    "prev": null,
    "next": "eyJqb2IuaWQiOjU5NzI2OTE5MjUwNTgzMjksIl9wb2ludHNUb05leHRJdGVtcyI6dHJ1ZX0"
  }

This object contains cursors to go forward and backward in the page list.

If you would like to go forward a page append &page[cursor]= with the next cursor value.

When either cursor has the value of null then no other results exist in that direction.

curl "<connect-api>/interviews?page[size]=2
      &page[cursor]=eyJqb2IuaWQiOjU5NzI2OTE5MjUwNTgzMjksIl9wb2ludHNUb05leHRJdGVtcyI6dHJ1ZX0"
  -H "Authorization: Bearer ACCESS_TOKEN"
shell