OData documentation

OData Requests

There are many ways to request data via the OData APIs ranging from simple requests to complex requests containing queries with multiple conditions and actions, such as filter, orderby, and expand. There are often several ways to request the same data.

A few example requests (based upon the above service and metadata documents) are outlined below. For a detailed treatment of the different request and query options, please refer to the OData documentation.

For each example, the raw request, response, and a sample cURL command are presented.

The following parameters are used throughout:

TENANT_CODE is the tenant code that was provided by MHR.
ENVIRONMENT_CODE is the environment code that was provided by MHR. When accessing your default environment (typically your production environment) the -ENVIRONMENT_CODE hostname segment, and EnvironmentCode HTTP header field can be omitted.
ACCESS_TOKEN is the access token supplied by your System Administrator, or ID token obtained separately (see:OIDC ID Tokens).

Request a list of all applicants

GET /api/v1/recruitment/odata/applicants HTTP/1.1
Host: TENANT_CODE-ENVIRONMENT_CODE.people-first.com
Accept-Language: en-GB
Content-Type: application/json; charset=utf-8
TenantCode: TENANT_CODE
EnvironmentCode: ENVIRONMENT_CODE
Authorization: Bearer ACCESS_TOKEN

{
  "@odata.context": "https://TENANT_CODE-ENVIRONMENT_CODE.people-first.com/api/v1/recruitment/odata/$metadata#applicants",
  "value": [
    {
      "Forename": "Jimmy",
      "Surname": "Jobseeker",
      "Id": "aa96f4fd-9df3-4ef1-8fac-17ae30f07e60",
    },
    {
      "Forename": "Dotty",
      "Surname": "Net",
      "Id": "c33b1258-fe25-4a03-8ada-17bf3cb15dd1",
    }
  ]
}

curl --location --request GET "https://tpruk-dev.people-first.com/api/v1/recruitment/odata/applicants" \
    --header "TenantCode: tpruk" \
    --header "EnvironmentCode: dev" \
    --header "Accept-Language: en-GB" \
    --header "Content-Type: application/json; charset=utf-8" \
    --header "Authorization: Bearer eyJ0eXAiOiJKVMsntWbLxWnNnRNZva2iueYc7KTFKP1Kz6Paog

Request an applicant by their primary key (ID)

GET /api/v1/recruitment/odata/applicants(aa96f4fd-9df3-4ef1-8fac-17ae30f07e60) HTTP/1.1
Host: TENANT_CODE-ENVIRONMENT_CODE.people-first.com
Accept-Language: en-GB
Content-Type: application/json; charset=utf-8
TenantCode: TENANT_CODE
EnvironmentCode: ENVIRONMENT_CODE
Authorization: Bearer ACCESS_TOKEN

{
  "@odata.context": "https://TENANT_CODE-ENVIRONMENT_CODE.people-first.com/api/v1/recruitment/odata/$metadata#applicants/$entity",
  "Forename": "Jimmy",
  "Surname": "Jobseeker",
  "Id": "aa96f4fd-9df3-4ef1-8fac-17ae30f07e60"
}

curl --location --request GET "https://tpruk-dev.people-first.com/api/v1/recruitment/odata/applicants(aa96f4fd-9df3-4ef1-8fac-17ae30f07e60)" \
    --header "TenantCode: tpruk" \
    --header "EnvironmentCode: dev" \
    --header "Accept-Language: en-GB" \
    --header "Content-Type: application/json; charset=utf-8" \
    --header "Authorization: Bearer eyJ0eXAiOiJKVMsntWbLxWnNnRNZva2iueYc7KTFKP1Kz6Paog

Request an applicant by their name

GET /api/v1/recruitment/odata/applicants?$filter=(Forename eq 'Jimmy') and (Surname eq 'Jobseeker') HTTP/1.1
Host: TENANT_CODE-ENVIRONMENT_CODE.people-first.com
Accept-Language: en-GB
Content-Type: application/json; charset=utf-8
TenantCode: TENANT_CODE
EnvironmentCode: ENVIRONMENT_CODE
Authorization: Bearer ACCESS_TOKEN

{
  "@odata.context": "https://TENANT_CODE-ENVIRONMENT_CODE.people-first.com/api/v1/recruitment/odata/$metadata#applicants",
  "value": [
    {
      "Forename": "Jimmy",
      "Surname": "Jobseeker",
      "Id": "aa96f4fd-9df3-4ef1-8fac-17ae30f07e60",
    }
  ]
}

curl --location --request GET "https://tpruk-dev.people-first.com/api/v1/recruitment/odata/applicants?$filter=(Forename eq 'Jimmy') and (Surname eq 'Jobseeker')" \
    --header "TenantCode: tpruk" \
    --header "EnvironmentCode: dev" \
    --header "Accept-Language: en-GB" \
    --header "Content-Type: application/json; charset=utf-8" \
    --header "Authorization: Bearer eyJ0eXAiOiJKVMsntWbLxWnNnRNZva2iueYc7KTFKP1Kz6Paog

Count the number of applicants

GET /api/v1/recruitment/odata/applicants?$count=true HTTP/1.1
Host: TENANT_CODE-ENVIRONMENT_CODE.people-first.com
Accept-Language: en-GB
Content-Type: application/json; charset=utf-8
TenantCode: TENANT_CODE
EnvironmentCode: ENVIRONMENT_CODE
Authorization: Bearer ACCESS_TOKEN

{
  "@odata.context": "https://TENANT_CODE-ENVIRONMENT_CODE.people-first.com/api/v1/recruitment/odata/$metadata#applicants",
  "@odata.count": 2,
  "value": [
    {
      "Forename": "Jimmy",
      "Surname": "Jobseeker",
      "Id": "aa96f4fd-9df3-4ef1-8fac-17ae30f07e60",
    },
    {
      "Forename": "Dotty",
      "Surname": "Net",
      "Id": "c33b1258-fe25-4a03-8ada-17bf3cb15dd1",
    }
  ]
}

curl --location --request GET "https://tpruk-dev.people-first.com/api/v1/recruitment/odata/applicants?$count=true" \
    --header "TenantCode: tpruk" \
    --header "EnvironmentCode: dev" \
    --header "Accept-Language: en-GB" \
    --header "Content-Type: application/json; charset=utf-8" \
    --header "Authorization: Bearer eyJ0eXAiOiJKVMsntWbLxWnNnRNZva2iueYc7KTFKP1Kz6Paog

Request an ordered list of applicants

GET /api/v1/recruitment/odata/applicants?$orderby=Forename HTTP/1.1
Host: TENANT_CODE-ENVIRONMENT_CODE.people-first.com
Accept-Language: en-GB
Content-Type: application/json; charset=utf-8
TenantCode: TENANT_CODE
EnvironmentCode: ENVIRONMENT_CODE
Authorization: Bearer ACCESS_TOKEN

{
  "@odata.context": "https://TENANT_CODE-ENVIRONMENT_CODE.people-first.com/api/v1/recruitment/odata/$metadata#applicants",
  "value": [
    {
      "Forename": "Dotty",
      "Surname": "Net",
      "Id": "c33b1258-fe25-4a03-8ada-17bf3cb15dd1",
    },
    {
      "Forename": "Jimmy",
      "Surname": "Jobseeker",
      "Id": "aa96f4fd-9df3-4ef1-8fac-17ae30f07e60",
    }
  ]
}

curl --location --request GET "https://tpruk-dev.people-first.com/api/v1/recruitment/odata/applicants?$orderby=Forename" \
    --header "TenantCode: tpruk" \
    --header "EnvironmentCode: dev" \
    --header "Accept-Language: en-GB" \
    --header "Content-Type: application/json; charset=utf-8" \
    --header "Authorization: Bearer eyJ0eXAiOiJKVMsntWbLxWnNnRNZva2iueYc7KTFKP1Kz6Paog

Request an applicant by their primary key (ID) and include all of their applications

GET /api/v1/recruitment/odata/applicants(aa96f4fd-9df3-4ef1-8fac-17ae30f07e60)?$expand=Applications HTTP/1.1
Host: TENANT_CODE-ENVIRONMENT_CODE.people-first.com
Accept-Language: en-GB
Content-Type: application/json; charset=utf-8
TenantCode: TENANT_CODE
EnvironmentCode: ENVIRONMENT_CODE
Authorization: Bearer ACCESS_TOKEN

{
  "@odata.context": "https://TENANT_CODE-ENVIRONMENT_CODE.people-first.com/api/v1/recruitment/odata/$metadata#applicants/$entity",
  "Forename": "Jimmy",
  "Surname": "Jobseeker",
  "Id": "aa96f4fd-9df3-4ef1-8fac-17ae30f07e60",
  "Applications": [
    {
      "Id": "47aedb1b-a2e2-4c6d-9065-17ae722ae740",
      "CurrentStateId": "f75c757c-8112-4847-9b0b-17ba06e338b0",
      "Applicantid": "aa96f4fd-9df3-4ef1-8fac-17ae30f07e60",
    },
    {
      "Id": "bbb0b87a-9401-4528-815f-17b9c2403e00",
      "CurrentStateId": "5a1f8e17-c8a3-4a97-93d3-17b9d01d0ef0",
      "Applicantid": "aa96f4fd-9df3-4ef1-8fac-17ae30f07e60",
    }
  ]
}

curl --location --request GET "https://tpruk-dev.people-first.com/api/v1/recruitment/odata/applicants(aa96f4fd-9df3-4ef1-8fac-17ae30f07e60)?$expand=Applications" \
    --header "TenantCode: tpruk" \
    --header "EnvironmentCode: dev" \
    --header "Accept-Language: en-GB" \
    --header "Content-Type: application/json; charset=utf-8" \
    --header "Authorization: Bearer eyJ0eXAiOiJKVMsntWbLxWnNnRNZva2iueYc7KTFKP1Kz6Paog