Compono Hire Employer GraphQL API

Welcome to the Compono Hire Employer GraphQL API! This reference includes the complete set of GraphQL types, queries, mutations, and their parameters for integrating the Compono Hire platform with your systems and data.

Getting started

To communicate with the GraphQL API, you will need a valid public/private key pair. Generate a key pair by logging in to Compono Hire with an administrator-level account. You will find the option to generate and manage your keys under the My Account > API management menu item.

https://app.compono.com/organisation/{yourOrganisationId}/employer-api

Endpoint

The GraphQL API has a single endpoint: https://employer-public-api.platform.compono.com/graphql The endpoint remains constant no matter what operation you perform.

Contact

Compono Hire Support

support@compono.com

https://www.compono.com/contact-us

API Endpoints
https://employer-public-api.platform.compono.com/graphql
Version

1.0.0

Authentication

An Authorization key is required to be sent as part of every request to the GraphQL API, in the form of an Authorization request header. The value is the Bearer type auth value against a Base64 encoded version of the API key pair in the format public key:private key. e.g.

  --header 'Authorization: Bearer NmQ0ZTRkMDM3MDdmMTg2NWIxZDNlxZWY6M2Q2ZTA5M2Q1ZjAzMjlhODc1N2NmZmEzYTA2MmIyNmY='

Error Handling

Error codes

Every response is a JSON map, and will include JSON keys for data and errors following the GraphQL specification. All error responses will contain an errors field. e.g.

{
   "errors": [
       {
           "message": "Context creation failed: Invalid API key provided publicKey:123456",
           "extensions": {
       "code": "UNAUTHENTICATED"
           }
       }
   ]
}

The errors field is a list where each entry has a message field that describes the error and a extensions field includes code that indicates a specific error.

Error codes

Code Description
BAD_USER_INPUT The GraphQL operation includes an invalid value for a field argument.
FORBIDDEN The server was unauthorised to access a required data source.
GRAPHQL_PARSE_FAILED The GraphQL operation string contains a syntax error.
GRAPHQL_VALIDATION_FAILED The GraphQL operation is not valid against the server's schema.
INTERNAL_SERVER_ERROR An unspecified error occurred.
NOT_FOUND Cannot find requested resource.
UNAUTHENTICATED The server failed to authenticate with a required data source.

Queries

applicants

Description

get applicants for a job

Response

Returns an ApplicantsResult

Arguments
Name Description
filters - ApplicantFilters Filter Applicant result
order - Order Order results return in
orderBy - ApplicantsOrderBy Field results are sorted by
pagination - Pagination pagination inputs these values are defaulted if not specified default page 1, pazeSize 20

Example

Query
query applicants(
  $filters: ApplicantFilters,
  $order: Order,
  $orderBy: ApplicantsOrderBy,
  $pagination: Pagination
) {
  applicants(
    filters: $filters,
    order: $order,
    orderBy: $orderBy,
    pagination: $pagination
  ) {
    items {
      ...ApplicantFragment
    }
    pageInfo {
      ...PageInfoFragment
    }
  }
}
Variables
{
  "filters": ApplicantFilters,
  "order": "asc",
  "orderBy": "appliedAt",
  "pagination": Pagination
}
Response
{
  "data": {
    "applicants": {
      "items": [Applicant],
      "pageInfo": PageInfo
    }
  }
}
Queries

jobs

Description

Returns an array of jobs

Response

Returns a JobsResult

Arguments
Name Description
filters - JobFilters Filter Job result
order - Order Order results return in
orderBy - JobsOrderBy Field results are sorted by
pagination - Pagination pagination inputs these values are defaulted if not specified default page 1, pazeSize 20

Example

Query
query jobs(
  $filters: JobFilters,
  $order: Order,
  $orderBy: JobsOrderBy,
  $pagination: Pagination
) {
  jobs(
    filters: $filters,
    order: $order,
    orderBy: $orderBy,
    pagination: $pagination
  ) {
    items {
      ...JobFragment
    }
    pageInfo {
      ...PageInfoFragment
    }
  }
}
Variables
{
  "filters": JobFilters,
  "order": "asc",
  "orderBy": "closedAt",
  "pagination": Pagination
}
Response
{
  "data": {
    "jobs": {
      "items": [Job],
      "pageInfo": PageInfo
    }
  }
}

Types

Applicant

Description

Job Applicant

Fields
Field Name Description
appliedAt - DateTime When the applicant applied to the job
candidate - Candidate Details about the applicant
hiredAt - DateTime When the applicant was hired
id - UUID! unique identifier for this applicant can be used in ApplicantFilters
jobId - UUID! Id of the job this application is for. Can be used in ApplicantFilters.
stage - String! 'Applied', 'Hired', 'Unsuccessful', 'Shortlist', 'Interview 1', 'Interview 2', 'Checks' or 'Offer'
updatedAt - DateTime When the application was last updated
Example
{
  "appliedAt": "2007-12-03T10:15:30Z",
  "candidate": Candidate,
  "hiredAt": "2007-12-03T10:15:30Z",
  "id": "b5299ce8-8d62-4130-bf03-9e66ceed5b4d",
  "jobId": "b5299ce8-8d62-4130-bf03-9e66ceed5b4d",
  "stage": "xyz789",
  "updatedAt": "2007-12-03T10:15:30Z"
}
Types

ApplicantFilters

Description

Input for filtering applicant results.

Fields
Input Field Description
hiredAt - DateRange Filter on the applicant hired at
id - UUID Filter applications by a specific applicant Id must be exact match
jobId - UUID Filter applications by job Id must be exact match
stage - String 'Applied', 'Hired', 'Unsuccessful', 'Shortlist', 'Interview 1', 'Interview 2', 'Checks' or 'Offer'
Example
{
  "hiredAt": DateRange,
  "id": "b5299ce8-8d62-4130-bf03-9e66ceed5b4d",
  "jobId": "b5299ce8-8d62-4130-bf03-9e66ceed5b4d",
  "stage": "xyz789"
}
Types

ApplicantsOrderBy

Description

Order results return in

Values
Enum Value Description

appliedAt

 Order by when the applicant applied

createdAt

 When the applicantion was created

updatedAt

 When the applicantion was last updated
Example
"appliedAt"
Types

ApplicantsResult

Description

Job Applicants query results with page info

Fields
Field Name Description
items - [Applicant!]! Job Applicant items
pageInfo - PageInfo Page info for a set of results. Used for pagination
Example
{
  "items": [Applicant],
  "pageInfo": PageInfo
}
Types

ApplicationSummary

Description

Summary of applications to a job

Fields
Field Name Description
applicantCount - Int! Number of applications for this job
lastApplicantId - UUID UUID of last applicant for this job
lastApplicantReceivedAt - DateTime Date of last applicant for this job
Example
{
  "applicantCount": 123,
  "lastApplicantId": "b5299ce8-8d62-4130-bf03-9e66ceed5b4d",
  "lastApplicantReceivedAt": "2007-12-03T10:15:30Z"
}
Types

Boolean

Description

The Boolean scalar type represents true or false.

Example
true
Types

Candidate

Description

Job Candidate

Fields
Field Name Description
contactDetails - ContactDetails Candidate contact details
education - [Education] The past or current education of this candidate
email - EmailAddress! Candidate's email address
employmentOptions - EmploymentOption Employment options candidate is looking for
firstName - String! Candidate's first name
lastName - String! Candidate's last name
professionalLinks - [ProfessionalLink] List of max 5 links to other professional websites
willRelocateTo - [Relocation] The locations this candidate is willing to relocate to.
Example
{
  "contactDetails": ContactDetails,
  "education": [Education],
  "email": "test@test.com",
  "employmentOptions": EmploymentOption,
  "firstName": "abc123",
  "lastName": "xyz789",
  "professionalLinks": [ProfessionalLink],
  "willRelocateTo": [Relocation]
}
Types

ContactDetails

Description

Job Applicant Contact Details

Fields
Field Name Description
address1 - String First line of the applicant's address
address2 - String Second line of the applicant's address
city - String City of the applicant's address
country - String Country of the applicant's address
phone - String! Contact number of the Applicant
postcode - String Postcode of the applicant's address
requiresVisa - Boolean Does the applicant require sponsorship to work in a location
state - String State of the applicant's address
Example
{
  "address1": "abc123",
  "address2": "abc123",
  "city": "xyz789",
  "country": "abc123",
  "phone": "abc123",
  "postcode": "xyz789",
  "requiresVisa": false,
  "state": "abc123"
}
Types

DateRange

Description

Filter on a date range from must be before to

Fields
Input Field Description
from - DateTime The from range if left blank all before the to value are returned
to - DateTime The to range if left blank all after the from value are returned
Example
{
  "from": "2007-12-03T10:15:30Z",
  "to": "2007-12-03T10:15:30Z"
}
Types

DateTime

Description

The DateTime scalar type represents a DateTime value as specified by iso8601.

Example
"2007-12-03T10:15:30Z"
Types

Education

Description

The certs, education, and qualifications of this candidate

Fields
Field Name Description
endDate - String The date in which study for this qualification was completed
institutionName - String Name of the institution
qualificationName - String Name of the qualification
startDate - String The date in which study for this qualification was started
Example
{
  "endDate": "abc123",
  "institutionName": "abc123",
  "qualificationName": "xyz789",
  "startDate": "abc123"
}
Types

EmailAddress

Description

A field whose value conforms to the standard internet email address format as specified in HTML Spec.

Example
"test@test.com"
Types

Employer

Description

Employer details

Fields
Field Name Description
email - EmailAddress!
firstName - String!
lastName - String!
Example
{
  "email": "test@test.com",
  "firstName": "xyz789",
  "lastName": "xyz789"
}
Types

EmploymentOption

Description

Job Applicant Employment Options

Fields
Field Name Description
preferredTypes - [String!] List of preferred employment types. full-time | part-time | contract | casual
workRemotely - Boolean Is the applicant willing to work remotely
Example
{
  "preferredTypes": ["xyz789"],
  "workRemotely": false
}
Types

Int

Description

The Int scalar type represents non-fractional signed whole numeric values. Int can represent values between -(2^31) and 2^31 - 1.

Example
987
Types

Job

Description

Detailed Job

Fields
Field Name Description
applicationSummary - ApplicationSummary
applyUrl - URL url provided for candidates to apply for the job
closedAt - DateTime Date job was closed for new applicant
company - String Company name displayed for candidates
createdAt - DateTime! Date job was created
description - String Job Description
id - UUID! UUID
location - Location Location of the listing location is deprecated. Use locations instead.
locations - [Location] Locations of the listing
openedAt - DateTime Date job was opened for applicants
owner - Employer! User that owns this job
status - JobStatus! The job's current status
team - Team! Team that owns this job
title - String! Job title
updatedAt - DateTime Date job was last updated
Example
{
  "applicationSummary": ApplicationSummary,
  "applyUrl": "http://www.test.com/",
  "closedAt": "2007-12-03T10:15:30Z",
  "company": "xyz789",
  "createdAt": "2007-12-03T10:15:30Z",
  "description": "xyz789",
  "id": "b5299ce8-8d62-4130-bf03-9e66ceed5b4d",
  "location": Location,
  "locations": [Location],
  "openedAt": "2007-12-03T10:15:30Z",
  "owner": Employer,
  "status": "archived",
  "team": Team,
  "title": "abc123",
  "updatedAt": "2007-12-03T10:15:30Z"
}
Types

JobFilters

Description

Input for filtering job results.

Fields
Input Field Description
closedAt - DateRange Filter on the date job was closed for new applicant
createdAt - DateRange Filter on the job createdAt
id - UUID Filter on the job UUID
location - LocationFilters Filter on location(Country State City)
owner - OwnerFilters Filter on the jobs by owner
status - JobStatus Filter on the job's current status
title - String Filter on the jobs that the title contains the filter. e.g. 'Keep' in 'Marsupial Keeper'
updatedAt - DateRange Filter on the date job was last updated
Example
{
  "closedAt": DateRange,
  "createdAt": DateRange,
  "id": "b5299ce8-8d62-4130-bf03-9e66ceed5b4d",
  "location": LocationFilters,
  "owner": OwnerFilters,
  "status": "archived",
  "title": "abc123",
  "updatedAt": DateRange
}
Types

JobStatus

Description

Current status of a Job

Values
Enum Value Description

archived

 Job is archived no new candidates can apply

closed

 Job is closed no new candidates can apply

draft

 Job is in a draft state candidates can not apply and will not be matched

open

 Job is live candidates can apply
Example
"archived"
Types

JobsOrderBy

Description

Sorting order of jobs

Values
Enum Value Description

closedAt

company

createdAt

description

openedAt

status

title

updatedAt
Example
"closedAt"
Types

JobsResult

Fields
Field Name Description
items - [Job!]!
pageInfo - PageInfo
Example
{
  "items": [Job],
  "pageInfo": PageInfo
}
Types

Location

Description

Location type used by applicants and jobs

Fields
Field Name Description
city - String City that has been nominated
country - String!
state - String
Example
{
  "city": "abc123",
  "country": "abc123",
  "state": "xyz789"
}
Types

LocationFilters

Description

Location Filter is used for search results based on location data, supporting case insensitive and fuzzy search, but abbreviation translating is not supported at the moment(e.g.NSW <==> New South Wales).

Fields
Input Field Description
city - String
country - String!
state - String
Example
{
  "city": "xyz789",
  "country": "xyz789",
  "state": "xyz789"
}
Types

Node

Fields
Field Name Description
id - UUID! UUID
Possible Types
Node Types

Applicant

Job
Example
{
  "id": "b5299ce8-8d62-4130-bf03-9e66ceed5b4d"
}
Types

Order

Description

Order results return in

Values
Enum Value Description

asc

desc
Example
"asc"
Types

OwnerFilters

Description

Input for filtering job results on owner.

Fields
Input Field Description
email - EmailAddress Must be exact match returns empty result if owner is not found
Example
{"email": "test@test.com"}
Types

PageInfo

Description

Page info for a set of results. Used for pagination

Fields
Field Name Description
pages - Int
total - Int
Example
{"pages": 987, "total": 987}
Types

PaginableResult

Description

query result that is paginated

Fields
Field Name Description
items - [Node!]! List of items
pageInfo - PageInfo Page information used for pagination
Possible Types
PaginableResult Types

ApplicantsResult

JobsResult
Example
{
  "items": [Node],
  "pageInfo": PageInfo
}
Types

Pagination

Description

Pagination query input

Fields
Input Field Description
page - PositiveInt if page is specified it must be > 0
pageSize - PositiveInt Number of results per page. Max 200. Default = 20
Example
{"page": 123, "pageSize": 123}
Types

PositiveInt

Description

Integers that will have a value greater than 0.

Example
123
Types

Relocation

Description

Location Job Applicant is willing to Relocate to

Fields
Field Name Description
city - String City of the applicant has nominated
country - String Country of the applicant has nominated
requiresVisa - Boolean Does the candidate require sponsorship to work in a location
state - String State of the applicant has nominated
Example
{
  "city": "abc123",
  "country": "xyz789",
  "requiresVisa": true,
  "state": "abc123"
}
Types

String

Description

The String scalar type represents textual data, represented as UTF-8 character sequences. The String type is most often used by GraphQL to represent free-form human-readable text.

Example
"abc123"
Types

Team

Description

Team

Fields
Field Name Description
name - String!
Example
{"name": "abc123"}
Types

URL

Description

A field whose value conforms to the standard URL format as specified in RFC3986

Example
"http://www.test.com/"
Types

UUID

Description

A field whose value is a generic Universally Unique Identifier.

Example
"b5299ce8-8d62-4130-bf03-9e66ceed5b4d"