NAV
code

Firstbird API Documentation

This section covers the Core Concepts of the Firstbird REST API, as well as serving as a complete reference for all of the Firstbird resources as well as the operations that it is possible to perform with them. The documentation also includes information about the Firstbird Webhooks integration which you can use to be informed of the latest actions in your Firstbird account.

Concepts

The following information is essential to understanding how the Firstbird API functions. You should familiarize yourself with it before moving on to the rest of this guide.

Base URL

All URLs referenced in the API documentation begin with the following base URL, unless specified differently:

https://api.1brd.com/v1/

This is the base URL for Firstbird’s public API. Please note that we only support HTTPS

Resource Format

The Firstbird REST API currently only supports JSON resource representations.

Authentication

POST https://api.1brd.com/oauth/token
Content-Type: application/x-www-form-urlencoded
Accept: application/json
Authorization: Basic {apikey:apisecret base64 encoded}

grant_type=client_credentials&scope=read%20write

This returns following response

{
  "access_token": "youraccesstoken",
  "token_type": "bearer",
  "expires_in": 2147483646,
  "scope": "read write",
  "jti": "ede67ad4-60ac-4526-8c54-083d6e83ae46"
}

As Firstbird uses OAuth2 authentication mechanism, you can authenticate your services using OAuth2 Client Credentials authentication method. To authenticate a Company Administrator needs to generate an API key and API secret within the account settings. With the key and the secret you can request a so called Bearer token from our API with the request to the right.

Authenticating Requests

The access token can be used to authenticate for any further request.

GET /v1/{anyrequest}
Authorization: Bearer youraccesstoken

To authenticate any request from now on you have to add the access token your received in access_token field to the Authorization header of the request, prefixed with “Bearer”.

Creating Resources

You create a resource by submitting an HTTP POST to a resource URL. Any POST body must be represented as JSON. Requests that contain body content must specify the HTTP Content-Type header with a value of application/json.

Responses to your create POST calls will contain:

Status Codes

Response Code Description
201 CREATED The request was successful, we created a new resource, and the response body contains the representation.
400 BAD REQUEST The data given in the POST failed validation. Inspect the response body for details.
401 UNAUTHORIZED Authentication credentials are required to access the resource. All requests must be authenticated.
403 FORBIDDEN The supplied authentication credentials are not sufficient to access the resource.
404 NOT FOUND We could not locate the resource based on the specified URL.
405 METHOD NOT ALLOWED POST is not supported for the resource.
409 CONFLICT You cannot create or update a resource because another resource already exists or conflicts with one you are submitting.
415 UNSUPPORTED MEDIA TYPE You did not specify the request Content-Type header to have a value of application/json.
500 SERVER ERROR We could not create or update the resource. Please try again.
503 SERVICE UNAVAILABLE We are temporarily unable to service the request. Please wait for a bit and try again.

Updating Resources

If you want to update a resource, submit an HTTP PUT request to the resource’s URL. Any request body must be represented as JSON. You must submit all attributes. As with the creation POST calls, requests that contain body content must specify the HTTP Content-Type header with a value of application/json.

Responses to your update requests will contain:

Status Codes

Response Code Description
200 OK The request was successful and the response body contains the resource requested.
400 BAD REQUEST The data given in the POST failed validation. Inspect the response body for details.
401 UNAUTHORIZED Authentication credentials are required to access the resource. All requests must be authenticated.
403 FORBIDDEN The supplied authentication credentials are not sufficient to access the resource.
404 NOT FOUND We could not locate the resource based on the specified URL.
405 METHOD NOT ALLOWED POST is not supported for the resource.
409 CONFLICT You cannot create or update a resource because another resource already exists or conflicts with one you are submitting.
415 UNSUPPORTED MEDIA TYPE You did not specify the request Content-Type header to have a value of application/json.
500 SERVER ERROR We could not create or update the resource. Please try again.
503 SERVICE UNAVAILABLE We are temporarily unable to service the request. Please wait for a bit and try again.

Deleting Resources

To delete a resource, make an HTTP DELETE request to the resource URL. Note that not all Firstbird API resources support DELETE.

Status Codes

Response Code Description
200 OK The request was successful and the response body contains the resource requested.
401 UNAUTHORIZED Authentication credentials are required to access the resource. All requests must be authenticated.
403 FORBIDDEN The supplied authentication credentials are not sufficient to access the resource.
404 NOT FOUND We could not locate the resource based on the specified URL.
405 METHOD NOT ALLOWED POST is not supported for the resource.
500 SERVER ERROR We could not create or update the resource. Please try again.
503 SERVICE UNAVAILABLE We are temporarily unable to service the request. Please wait for a bit and try again.

Error Responses

{
  "status" : 404,
  "code" : "4040",
  "message": "Oops!",
  "message" : "The resource you have called couldn't be found"
}

REST API responses indicating an error or warning are represented by a proper response HTTP status code (403, 404, etc) along with a response body containing the following information:

Attributes Type Description
status Number The corresponding HTTP status code.
code Number A Firstbird specific error code that can be used to obtain more information.
message String A simple, easy to understand message that you can show directly to your application’s end-user.
developerMessage String A clear explanation with technical details that might assist a developer calling our API.

Collection Resource

A Collection Resource is a resource containing other resources. It is known as a Collection Resource because it is itself a first class resource - it has its own attributes in addition to the resources it contains.

If you want to interact with multiple resources, you must do so with a Collection Resource. Collection Resources also support additional behavior specific to collections, such as pagination, sorting, and searching.

The Collection response will contain the elements of the collection in the array-field items.

Pagination

The following example shows a paginated response

{
  "href": "https://api.1brd.com/v1/companies/00000000-0000-0000-0000-000000000000/jobs?status=active_closed,active_published,archived,deleted,draft&offset=0&limit=25",
  "total": 100,
  "offset": 25,
  "limit": 25,
  "first": {
    "href": "https://api.1brd.com/v1/companies/00000000-0000-0000-0000-000000000000/jobs?status=active_closed,active_published,archived,deleted,draft&offset=0&limit=25"
  },
  "last": {
    "href": "https://api.1brd.com/v1/companies/00000000-0000-0000-0000-000000000000/jobs?status=active_closed,active_published,archived,deleted,draft&offset=0&limit=25"
  },
  "next": {
    "href": "http://localhost:8081/api/v1/companies/00000000-0000-0000-0000-000000000000/jobs?status=active_closed,active_published,archived,deleted,draft&offset=25&limit=25"
  },
  "last": {
    "href": "http://localhost:8081/api/v1/companies/00000000-0000-0000-0000-000000000000/jobs?status=active_closed,active_published,archived,deleted,draft&offset=75&limit=25"
  },
  "items": [
    {
      "href": "https://api.1brd.com/v1/companies/00000000-0000-0000-0000-000000000000/jobs/0a3f98fa-ef4f-457f-abb9-0a052d6ced5a",
      "id": "0a3f98fa-ef4f-457f-abb9-0a052d6ced5a",
      "...":"..."
    },
    {
      "href": "https://api.1brd.com/v1/companies/00000000-0000-0000-0000-000000000000/jobs/14e35b9e-669e-4e9a-bb23-2f2ea550318f",
      "id": "14e35b9e-669e-4e9a-bb23-2f2ea550318f",
      "...": "..."
    },
    "..."
  ]
}

If a Collection Resource represents a large enough number of resource instances, it will not include them all in a single response. Instead a technique known as pagination is used to break up the results into one or more pages of data. You can request additional pages as separate requests.

There are two optional query parameters that may be specified to control pagination:

Query Parameter Description
offset The zero-based starting index in the entire collection of the first item to return. Default is 0.
limit The maximum number of collection items to return for a single request. Minimum value is 1. Maximum value is 100. Default is 25.
Field Description
href The request line that has been used to get the current response
total Total number of all elements for the request (e.g., All Jobs the request matches)
offset The offset used in the current request
limit The limit used in the current request
first The URL to get the first limit items of the collection
next The URL to the next limit items of the collection
last The URL to the last limit or less items of the collection

Sorting

To sort collection resources there is the sort query parameter which allows you to specify the field and the sorting direction.

GET /v1/companies/{companyId}/jobs?sort=title,asc

GET /v1/companies/{companyId}/jobs?sort=title,desc

Please keep in mind that sorting does not work for all collection resources. If it is possible to sort the response, it will be explicitly mentioned. You are not able to sort nested properties as well as you are not able to sort for non-primitive object properties.

Customizing Response Fields

{
  "href": "https://api.1brd.com/v1/companies/00000000-0000-0000-0000-000000000000/jobs/0a3f98fa-ef4f-457f-abb9-0a052d6ced5a",
  "id": "0a3f98fa-ef4f-457f-abb9-0a052d6ced5a",
  "location": {
    "id": "50c7be5d-3e2d-4e57-9394-87d5ffc7f50f",
    "href": "https://api.1brd.com/v1/companies/00000000-0000-0000-0000-000000000000/location/50c7be5d-3e2d-4e57-9394-87d5ffc7f50f"
  }
}

To fit your needs we allow to customize which fields are included in our responses. By default all available fields are included in a response. To select fields to be included use the fields query parameter which takes a comma separated list of fields. Take a look at the following Job request for an example:

GET /v1/companies/00000000-0000-0000-0000-000000000000/jobs/0a3f98fa-ef4f-457f-abb9-0a052d6ced5a?fields=id,location

The following example shows collapsed fields:

{
  "company": {
    "id": "00000000-0000-0000-0000-000000000000",
    "href": "https://api.1brd.com/v1/companies/00000000-0000-0000-0000-000000000000"
  },
  "location": {
    "id": "00000000-0000-0000-0000-000000000001",
    "href": "https://api.1brd.com/v1/companies/00000000-0000-0000-0000-000000000000/locations/00000000-0000-0000-0000-000000000001"
  },
  "department": {
    "id": "00000000-0000-0000-0000-000000000002",
    "href": "https://api.1brd.com/v1/companies/00000000-0000-0000-0000-000000000000/departments/00000000-0000-0000-0000-000000000002"
  },
  "reward": {
    "id": "00000000-0000-0000-0000-000000000003",
    "href": "https://api.1brd.com/v1/companies/00000000-0000-0000-0000-000000000000/rewards/00000000-0000-0000-0000-000000000003"
  },
  "applicant": {
    "id": "00000000-0000-0000-0000-000000000004",
    "href": "https://api.1brd.com/v1/companies/00000000-0000-0000-0000-000000000000/applicants/00000000-0000-0000-0000-000000000004"
  },
  "referrer": {
    "id": "00000000-0000-0000-0000-000000000005",
    "href": "https://api.1brd.com/v1/companies/00000000-0000-0000-0000-000000000000/users/00000000-0000-0000-0000-000000000005"
  },
  "job": {
    "id": "00000000-0000-0000-0000-000000000007",
    "href": "https://api.1brd.com/v1/companies/00000000-0000-0000-0000-000000000000/jobs/00000000-0000-0000-0000-000000000007"
  },
  "referrals": {
    "href": "https://api.1brd.com/v1/companies/00000000-0000-0000-0000-000000000000/applications/00000000-0000-0000-0000-000000000008/referrals"
  },
  "contactPerson": {
    "id": "00000000-0000-0000-0000-000000000009",
    "href": "https://api.1brd.com/v1/companies/00000000-0000-0000-0000-000000000000/users/00000000-0000-0000-0000-000000000009"
  }
}

At Firstbird we want to provide a powerful REST API which allows easy navigation through our services. Therefore we do not simply add the IDs of referenced resources to our responses but also provide links where you can find more detailed information about the referenced resource. If you take a look at the example response fields, you can see that fields do not provide detailed information but only the reference to it. All objects contain their ID in id property and a link to the REST API Resource in property href.

The following example shows expanded fields:

{
  "company": {
    "id": "00000000-0000-0000-0000-000000000000",
    "name": "Firstbird",
    "domainName": "1bird",
    "website": "www.firstbird.eu"
  },
  "location": {
    "name": "Paris",
    "id": "00000000-0000-0000-0000-000000000001"
  },
  "department": {
    "name": "Finance",
    "id": "00000000-0000-0000-0000-000000000002"
  },
  "reward": {
    "name": "250€ Amazon Gift Card",
    "id": "00000000-0000-0000-0000-000000000003"
  },
  "applicant": {
    "id": "00000000-0000-0000-0000-000000000004",
    "firstName": "Max",
    "lastName": "Mustermann",
    "email": "max.mustermann@gamil.com"
  },
  "referrer": {
    "companyId": "00000000-0000-0000-0000-000000000000",
    "firstName": "Birdy",
    "lastName": "Pigeon",
    "email": "birdy.pigeon@firstbird.com",
    "locale": "en_US",
    "roles": [
      "ROLE_TALENT_SCOUT"
    ],
    "location": {
      "id": "00000000-0000-0000-0000-0000000000001",
      "href": "https://api.1brd.com/v1/companies/00000000-0000-0000-0000-000000000000/locations/00000000-0000-0000-0000-000000000001"
    },
    "department": {
      "id": "00000000-0000-0000-0000-000000000002",
      "href": "https://api.1brd.com/v1/companies/00000000-0000-0000-0000-000000000000/departments/00000000-0000-0000-0000-0000000000002"
    },
    "mainRole": "ROLE_TALENT_SCOUT",
    "status": "ACTIVE",
    "incognito": false,
    "timeZone": "Europe/Vienna",
    "id": "00000000-0000-0000-0000-000000000005",
    "profile_picture": {
      "id": "00000000-0000-0000-0000-000000000006",
       "href": "https://aws.com/eu-central-1/profimg/150x150/00000000-0000-0000-0000-000000000006.jpeg"
    }
  },
  "job": {
    "id": "00000000-0000-0000-0000-000000000007",
    "title": "Nr. 1 System Engineer/Administrator (m/w)"
  },
  "referrals": {
    "negativeCount": 0,
    "neutralCount": 0,
    "referralCount": 1
  },
  "contactPerson": {
    "companyId": "00000000-0000-0000-0000-000000000000",
    "firstName": "Birdy",
    "lastName": "Pigeon",
    "email": "birdy.pigeon@firstbird.com",
    "locale": "en_US",
    "roles": [
      "ROLE_TALENT_SCOUT"
    ],
    "location": {
      "id": "00000000-0000-0000-0000-0000000000001",
      "href": "https://api.1brd.com/v1/companies/00000000-0000-0000-0000-000000000000/locations/00000000-0000-0000-0000-000000000001"
    },
    "department": {
      "id": "00000000-0000-0000-0000-000000000002",
      "href": "https://api.1brd.com/v1/companies/00000000-0000-0000-0000-000000000000/departments/00000000-0000-0000-0000-0000000000002"
    },
    "mainRole": "ROLE_TALENT_SCOUT",
    "status": "ACTIVE",
    "incognito": false,
    "timeZone": "Europe/Vienna",
    "id": "00000000-0000-0000-0000-000000000009",
    "profile_picture": {
      "id": "00000000-0000-0000-0000-000000000006",
       "href": "https://aws.com/eu-central-1/profimg/150x150/00000000-0000-0000-0000-000000000006.jpeg"
    }
  }
}

To make it even easier for you to use our API, it is possible to expand (include) often used referenced resources within the responses to avoid additional requests to those referenced resources. If you take a look on the following example response, you can see that we expanded all resources, and now the values you are allowed to see are included in the response. To specify which resources should get expanded you have to specify a comma separated list of fields for the expand query parameter. For example:

GET /v1/companies/00000000-0000-0000-0000-000000000000/jobs/00000000-0000-0000-0000-000000000005?expand=company,location,department,reward

Deprecation

Every endpoint which is marked as deprecated will soon be unsupported. That means that it will be disabled and removed without a compatible replacement. It is recommended to not rely on deprecated endpoints to avoid compatibility issues. We try to keep the API as stable as possible, but on rare occasions we have to make changes and want to notify you ahead of time so you can prepare upfront. Deprecated endpoints add the Warning HTTP header with the following structure.

Example: HTTP/1.1 200 Ok Warning 299 api-gateway Endpoint deprecated

Errors

The firstbird API uses the following error codes:

Error Code Meaning
0000 Unhandled error
0999 This functionality is not implemented right now
4000 A query parameter is invalid
4001 One of the fields requested in fields query parameter is not allowed for that request
4002 The validation of your request failed
4003 One of the path variables is invalid
4004 Inviting a User failed
4005 The company domain name is not allowed
4006 The requested email address is already in use for your company
4007 The social network token for a user is invalid
4010 The request was unauthorized
4020 The provided file was empty
4030 The used access token in Authorization HTTP header has been blacklisted.
4031 The request contained illegal arguments
4032 The invitation limit for one request exceeded
4033 A plan limitation has been exceeded
4041 The requested company does not exist
4042 The requested applicant does not exist
4043 The requested job application does not exist
40431 The requested job application file does not exist
4044 The requested file does not exist
4045 A password reset request does not exist for the current user
4046 The requested invitation does not exist
4047 The requested social network is not connected for the current user
4048 The requested activity feed does not exist
4049 The requested user does not exist
40410 The provided password for checking your current password is invalid
4290 Too many requests to social networks
5001 We were not able to create the provided resource
5002 We failed connecting you to the requested social network

Locations

Locations represent the geographical entities of your company. We here at Firstbird have only one Location which is Vienna

Get All Locations

This endpoint retrieves all locations that are configured for you company.

This request returns JSON structured like this:

HTTP Request

[
  {
    "id": "50c7be5d-3e2d-4e57-9394-87d5ffc7f50f",
    "name": "Paris"
  },
  {
    "id": "9aac4ea9-09c3-41f0-868f-e1183dca3542",
    "name": "Munich"
  },
  {
    "id": "bfb10c01-fa32-499a-bbdd-34b5f166c272",
    "name": "Vienna"
  }
]

GET /v1/companies/{companyId}/locations

Query Parameters

Parameter Description
query A comma seperated list of fields that should be contained in the response. See Fields documentation.

Get a Single Location

To get a single Location by it’s Id you have to use following request:

HTTP Request

This request returns JSON structured like this:

{
  "id": "50c7be5d-3e2d-4e57-9394-87d5ffc7f50f",
  "name": "Paris"
}

GET /v1/companies/{companyId}/locations/{locationId}

Create a Location

To create a new Location for your Company use following request

HTTP Request

This is an example request body

{
  "name":"Chicago"
}

This request returns JSON structured like this:

{
  "id": "54d49fa7-97cb-4502-bb55-4217cb281b3f"
}

POST /v1/companies/{companyId}/locations

Updating a Locations Status

To allow correct displaying of your Jobs and other entities using Locations on the one side and the need to remove outdated Locations we allow to set Locations inactive which is done with the following request:

HTTP Request

This is an example request body

{
  "status":"INACTIVE"
}

PUT /v1/companies/{companyId}/locations/{locationId}/status

Parameters

Property Description
status New status of a the Location. Possible values are: INACTIVE, ACTIVE

Departments

Departments represent any unit of organization within your company, as an example, we here at Firstbird have the departments Sales, IT and Marketing & PR

Get All Departments

This endpoint retrieves all departments that are configured for you company.

HTTP Request

This request returns JSON structured like this:

[
  {
    "id": "50018463-d804-46ae-90a7-8187a12e6540",
    "name": "Sales"
  },
  {
    "id": "02a11025-4397-40b8-aa24-e09af0d784b0",
    "name": "Marketing & PR"
  },
  {
    "id": "5a768e73-3344-4a03-80cf-48f0c717f8f8",
    "name": "Product Development"
  }
]

GET /v1/companies/{companyId}/departments

Get a Single Department

To get a single Department by it’s Id you have to use following request:

HTTP Request

This request returns JSON structured like this:

{
  "id": "02a11025-4397-40b8-aa24-e09af0d784b0",
  "name": "Marketing & PR"
}

GET /v1/companies/{companyId}/departments/{departmentId}

Create a Department

To create a new Department for your Company use following request

HTTP Request

This is an example request body

{
  "name":"Business Development"
}

This request returns JSON structured like this:

{
  "id": "54d49fa7-97cb-4502-bb55-4217cb281b3f"
}

POST /v1/companies/{companyId}/departments

Parameters

Property Description
name The name of your new Department. We recommend to keep the names unique for all your Departments

Updating a Departments Status

To allow correct displaying of your Jobs and other entities using Departments on the one side and the need to remove outdated Departments we allow to set Departments inactive which is done with the following request:

HTTP Request

This is an example request body

{
  "status":"INACTIVE"
}

PUT /v1/companies/{companyId}/departments/{departmentId}/status

Parameters

Property Description
status New status of a the Department. Possible values are: INACTIVE, ACTIVE

Job Brandings

Job Brandings allow you to customize your jobs to make them stand out on social networks.

Get All Job Brandings

This endpoint retrieves all Job Brandings that are configured for your company.

HTTP Request

This request returns JSON structured like this:

[
  {
    "href": "https://api.1brd.com/v1/companies/00000000-0000-0000-0000-000000000000/job_brandings/00000000-0000-0000-0000-000000000001",
    "id": "00000000-0000-0000-0000-000000000001",
    "company": {
      "id": "00000000-0000-0000-0000-000000000000",
      "href": "https://api.1brd.com/v1/companies/00000000-0000-0000-0000-000000000000"
    },
    "name": "Branding One",
    "isDefault": false,
    "shareLogo": {
      "id": "00000000-0000-0000-0000-0000000000002",
      "href": "https://localhost/share-logo-image.jpeg"
    },
    "linkedInShareLogo": {
      "id": "00000000-0000-0000-0000-000000000002",
      "href": "https://localhost/linkedin-share-logo-image.jpeg"
    },
    "jobHeader": {
      "id": "00000000-0000-0000-0000-000000000003",
      "href": "https://localhost/job-header-image.jpeg"
    },
    "shareDescription": "This is my share description.",
    "createdAt": "2018-10-09T10:03:39Z",
    "updatedAt": "2018-10-09T10:04:38Z"
  }
]

GET /v1/companies/{companyId}/job_brandings

Response Fields

Property Required Description
href Yes The link to this job branding.
id Yes The id of this job branding.
company Yes The company this job branding is associated with.
name No The name of this job branding. Absent, if this is the default branding.
isDefault Yes Whether this job branding is the default one or not.
shareLogo Yes The share logo that will be used for this job branding.
linkedInShareLogo Yes The share logo that will be used for this job branding on LinkedIn.
jobHeader Yes The job header image that will be used for this job branding.
shareDescription Yes The share description that will be used for this job branding.
createdAt No The date time when this job branding got created. Absent, if this is the default branding.
updatedAt No The date time when this job branding got updated. Absent, if this job branding has never been updated.

Note: There will always be a default branding, if no job branding has been created.

Get a Single Job Branding

To get a single Job Branding by it’s Id you have to use following request:

HTTP Request

This request returns JSON structured like this:

{
  "href": "https://api.1brd.com/v1/companies/00000000-0000-0000-0000-000000000000/job_brandings/00000000-0000-0000-0000-000000000001",
  "id": "00000000-0000-0000-0000-000000000001",
  "company": {
    "id": "00000000-0000-0000-0000-000000000000",
    "href": "https://api.1brd.com/v1/companies/00000000-0000-0000-0000-000000000000"
  },
  "name": "Branding One",
  "isDefault": false,
  "shareLogo": {
    "id": "00000000-0000-0000-0000-0000000000002",
    "href": "https://localhost/share-logo-image.jpeg"
  },
  "linkedInShareLogo": {
    "id": "00000000-0000-0000-0000-000000000002",
    "href": "https://localhost/linkedin-share-logo-image.jpeg"
  },
  "jobHeader": {
    "id": "00000000-0000-0000-0000-000000000003",
    "href": "https://localhost/job-header-image.jpeg"
  },
  "shareDescription": "This is my share description.",
  "createdAt": "2018-10-09T10:03:39Z",
  "updatedAt": "2018-10-09T10:04:38Z"
}

GET /v1/companies/{companyId}/job_brandings/{jobBrandingId}

Response Fields

Property Required Description
href Yes The link to this job branding.
id Yes The id of this job branding.
company Yes The company this job branding is associated with.
name No The name of this job branding. Absent, if this is the default branding.
isDefault Yes Whether this job branding is the default one or not.
shareLogo Yes The share logo that will be used for this job branding.
linkedInShareLogo Yes The share logo that will be used for this job branding on LinkedIn.
jobHeader Yes The job header image that will be used for this job branding.
shareDescription Yes The share description that will be used for this job branding.
createdAt No The date time when this job branding got created. Absent, if this is the default branding.
updatedAt No The date time when this job branding got updated. Absent, if this job branding has never been updated.

Create a Job Branding

To create a new Job Branding for your company use following request:

HTTP Request

This is an example request body

{
  "name": "Branding One",
  "jobHeader": {
    "id": "00000000-0000-0000-0000-000000000003"
  },
  "shareLogo": {
    "id": "00000000-0000-0000-0000-000000000002"
  },
  "shareDescription": "This is my share description."
}

This request returns JSON structured like this:

{
  "id": "00000000-0000-0000-0000-000000000000"
}

POST /v1/companies/{companyId}/job_brandings

Parameters

Property Required Description
name Yes The name of the new job branding.
jobHeader Yes The job header image that will be used for the new job branding. See here
shareLogo Yes The share logo that will be used for the new job branding. See here
shareDescription Yes The share description that will be used for the new job branding.

Updating a Job Branding

To update an existing Job Branding for your company use following request:

HTTP Request

This is an example request body

{
  "name": "Test",
  "jobHeader": {
    "id": "00000000-0000-0000-0000-000000000003"
  },
  "shareLogo": {
    "id": "00000000-0000-0000-0000-000000000002"
  },
  "shareDescription": "This is my share logo description."
}

PUT /v1/companies/{companyId}/job_brandings/{jobBrandingId}

Parameters

Property Required Description
name Yes The name of the new job branding.
jobHeader Yes The job header image that will be used for the new job branding. See here
shareLogo Yes The share logo that will be used for the new job branding. See here
shareDescription Yes The share description that will be used for the new job branding.

Jobs

Jobs are one of the main pillars of Firstbird

Jobs can have different statuses:

Status Description
DRAFT Those Jobs are only visible to Company Administrators and Recruiters before they get published to all Talent Scouts
ACTIVE_PUBLISHED Those Jobs are visible to all Talent Scouts and can be shared and candidates can be referred for those Jobs
ACTIVE_CLOSED Those Jobs are only visible to Recruiters and Company Administrators, candidates who got a shared link to that job before can’t apply anymore.
ARCHIVED Candidates can’t apply to those Jobs anymore
DELETED Those jobs aren’t visible anymore

Jobs can also be flagged as Hot which means they are hard to achieve. Most of the time this flag is used for visual indication on the UI.

Get All Jobs

To get a list of all your Jobs you have to issue following request:

HTTP Request

This request returns JSON structured like this:

{
  "href": "https://api.1brd.com/v1/companies/00000000-0000-0000-0000-000000000000/jobs?status=active_closed,active_published,archived,deleted,draft&offset=0&limit=25",
  "total": 1,
  "offset": 0,
  "limit": 25,
  "first": {
    "href": "https://api.1brd.com/v1/companies/00000000-0000-0000-0000-000000000000/jobs?status=active_closed,active_published,archived,deleted,draft&offset=0&limit=25"
  },
  "last": {
    "href": "https://api.1brd.com/v1/companies/00000000-0000-0000-0000-000000000000/jobs?status=active_closed,active_published,archived,deleted,draft&offset=0&limit=25"
  },
  "items": [
    {
      "href": "https://api.1brd.com/v1/companies/00000000-0000-0000-0000-000000000000/jobs/00000000-0000-0000-0000-000000000005",
      "id": "00000000-0000-0000-0000-000000000005",
      "company": {
        "id": "00000000-0000-0000-0000-000000000000",
        "href": "https://api.1brd.com/v1/companies/00000000-0000-0000-0000-000000000000"
      },
      "location": {
        "id": "00000000-0000-0000-0000-000000000001",
        "href": "https://api.1brd.com/v1/companies/00000000-0000-0000-0000-000000000000/location/00000000-0000-0000-0000-000000000001"
      },
      "creationDate": "2016-03-22T09:57:21Z",
      "title": "Nr. 1 System Engineer/Administrator (m/w)",
      "referenceNumber": "123456",
      "department": {
        "id": "00000000-0000-0000-0000-000000000002",
        "href": "https://api.1brd.com/v1/companies/00000000-0000-0000-0000-000000000000/departments/00000000-0000-0000-0000-000000000002"
      },
      "contactPerson": {
        "id": "00000000-0000-0000-0000-000000000003",
        "href": "https://api.1brd.com/v1/companies/00000000-0000-0000-0000-000000000000/users/00000000-0000-0000-0000-000000000003"
      },
      "reward": {
        "id": "00000000-0000-0000-0000-000000000004",
        "href": "https://api.1brd.com/v1/companies/00000000-0000-0000-0000-000000000000/rewards/00000000-0000-0000-0000-000000000004"
      },
      "responsiblePersons": [
        {
          "id": "00000000-0000-0000-0000-000000000005",
          "href": "https://api.1brd.com/v1/companies/00000000-0000-0000-0000-000000000000/users/00000000-0000-0000-0000-000000000006"
        }
      ],
      "description": "<h1>This is a description</h1>",
      "status": "ACTIVE_PUBLISHED",
      "hot": false,
      "image": {
        "href": "https://aws.com/eu-central-1/job-headers/2160x705/00000000-0000-0000-0000-000000000007.jpeg"
      },
      "statistics": {
        "href": "https://api.1brd.com/v1/companies/00000000-0000-0000-0000-000000000000/jobs/00000000-0000-0000-0000-000000000005/statistics"
      },
      "shareLink": {
        "href": "https://api.1brd.com/job/00000000-0000-0000-0000-000000000005?referrer=dddddddd-dddd-dddd-dddd-dddddddddddd"
      },
      "jobBranding": {
          "id": "00000000-0000-0000-0000-000000000007",
          "href": "https://api.1brd.com/v1/companies/00000000-0000-0000-0000-000000000000/job_brandings/00000000-0000-0000-0000-000000000008"
      }
    }
  ]
}

GET /v1/companies/{companyId}/jobs

Query Parameters

Query Parameter Description
status Comma separated list of statuses which should be included in the response.
endDateBefore Jobs where the endDate is before the given date. (e.g. 2017-01-05)
department Comma separated list of Department Ids to filter after
location Comma separated list of Location Ids to filter after
contact Comma separated list of User Ids to filter the Job’s Contact Person after
hot Show Hot Jobs only
referenceNumber Filter by reference number
query Filter by job title
fields See Fields documentation
limit See Pagination documentation
offset See Pagination documentation
sort See Sorting documentation

Get a Single Job

To get a single Job by Id you have to use following request:

HTTP Request

This request returns JSON structured like this:

{
  "href": "https://api.1brd.com/v1/companies/00000000-0000-0000-0000-000000000000/jobs/00000000-0000-0000-0000-000000000005",
  "id": "00000000-0000-0000-0000-000000000005",
  "company": {
    "id": "00000000-0000-0000-0000-000000000000",
    "href": "https://api.1brd.com/v1/companies/00000000-0000-0000-0000-000000000000"
  },
  "location": {
    "id": "00000000-0000-0000-0000-000000000001",
    "href": "https://api.1brd.com/v1/companies/00000000-0000-0000-0000-000000000000/location/00000000-0000-0000-0000-000000000001"
  },
  "creationDate": "2016-03-22T09:57:21Z",
  "title": "Nr. 1 System Engineer/Administrator (m/w)",
  "referenceNumber": "123456",
  "department": {
    "id": "00000000-0000-0000-0000-000000000002",
    "href": "https://api.1brd.com/v1/companies/00000000-0000-0000-0000-000000000000/departments/00000000-0000-0000-0000-000000000002"
  },
  "contactPerson": {
    "id": "00000000-0000-0000-0000-000000000003",
    "href": "https://api.1brd.com/v1/companies/00000000-0000-0000-0000-000000000000/users/00000000-0000-0000-0000-000000000003"
  },
  "reward": {
    "id": "00000000-0000-0000-0000-000000000004",
    "href": "https://api.1brd.com/v1/companies/00000000-0000-0000-0000-000000000000/rewards/00000000-0000-0000-0000-000000000004"
  },
  "responsiblePersons": [
    {
      "id": "00000000-0000-0000-0000-000000000005",
      "href": "https://api.1brd.com/v1/companies/00000000-0000-0000-0000-000000000000/users/00000000-0000-0000-0000-000000000006"
    }
  ],
  "description": "<h1>This is a description</h1>",
  "status": "ACTIVE_PUBLISHED",
  "hot": false,
  "image": {
    "href": "https://aws.com/eu-central-1/job-headers/2160x705/00000000-0000-0000-0000-000000000007.jpeg"
  },
  "statistics": {
    "href": "https://api.1brd.com/v1/companies/00000000-0000-0000-0000-000000000000/jobs/00000000-0000-0000-0000-000000000005/statistics"
  },
  "shareLink": {
    "href": "https://api.1brd.com/job/00000000-0000-0000-0000-000000000005?referrer=dddddddd-dddd-dddd-dddd-dddddddddddd"
  },
  "jobBranding": {
      "id": "00000000-0000-0000-0000-000000000007",
      "href": "https://api.1brd.com/v1/companies/00000000-0000-0000-0000-000000000000/job_brandings/00000000-0000-0000-0000-000000000008"
  }
}

GET /v1/companies/{companyId}/jobs/{jobId}

Query Parameters

Query Parameter Description
fields See Fields documentation.
expand See Resource Expansion documentation. Available are: company, location, department, reward and contactPerson

Response Fields

Field name Required Description
href Yes The link to this job.
id Yes The id of this job.
company Yes The company this job belongs to.
location Yes The location that has been assigned.
creationDate Yes The creation date.
title Yes The job title.
referenceNumber No The reference number. (Not present, if no reference number entered)
department Yes The department that has been assigned.
contactPerson Yes The contact person.
reward Yes The reward that has been assigned.
responsiblePersons No The responsible persons that have been assigned. (Not present, if no responsible persons assigned)
description Yes The job description.
status Yes The status of the job.
hot Yes Whether the job is a hot job or not.
image Yes The job header image.
statistics Yes The statistics of this job.
shareLink Yes The sharing link of this job.
jobBranding No The branding that has been assigned. (Not present, if no branding assigned)

Create a Job

This is an example request body

{
      "department": {
              "id": "50018463-d804-46ae-90a7-8187a12e6540"
      },
      "contactPerson": {
              "id": "a9709b55-69b9-4400-a5a9-6101790ea6d6"
      },
      "description": "<h1>This is HTML Description of a Job</h1><p></p>",
      "endDate": "2016-03-23",
      "hot": true,
      "location": {
              "id": "50c7be5d-3e2d-4e57-9394-87d5ffc7f50f"
      },
      "referenceNumber": "123456",
      "reward": {
              "id": "00000000-0000-0000-0000-000000000000"
      },
      "jobBranding": {
               "id": "00000000-0000-0000-0000-000000000001"
      },
      "title": "Developer",
      "responsiblePersons": [{
              "id": "a9709b55-69b9-4400-a5a9-6101790ea6d6"
      }]
}

This request returns JSON structured like this:

{
  "id": "54d49fa7-97cb-4502-bb55-4217cb281b3f"
}

To create a new Job for your Company use following request

HTTP Request

POST /v1/companies/{companyId}/jobs

Parameters

Property Description
department The Id of the Department this Job is associated with
contactPerson The Id of the Recruiter who is responsible for this Job
description HTMl describing the Job. Allowed HTML tags: a, b, br, div, em, h1, h2, h3, i, iframe, img, li, ol, p, span, strike, strong, u, ul
endDate The date when the job will be automatically closed once it is in status ACTIVE_PUBLISHED. Can be null to avoid autoclosing.
hot The Hot flag
location The Location of your Company the Job is associated with
referenceNumber This field allows to enter reference numbers of external systems
reward The Reward that will be payed as soon as an Applicant gets hired for that Job
jobBranding The Job Branding of your Company the Job is associated with
title The title of the Job. This field is limited to 255 characters
responsiblePersons An array of objects containing the User Ids of Recruiters being responsible for this Job as well

Update a Job

This is an example request body

{
      "department": {
              "id": "50018463-d804-46ae-90a7-8187a12e6540"
      },
      "contactPerson": {
              "id": "a9709b55-69b9-4400-a5a9-6101790ea6d6"
      },
      "description": "<h1>This is HTML Description of a Job</h1><p></p>",
      "endDate": "2016-03-23",
      "hot": true,
      "location": {
              "id": "50c7be5d-3e2d-4e57-9394-87d5ffc7f50f"
      },
      "referenceNumber": "123456",
      "reward": {
              "id": "00000000-0000-0000-0000-000000000000"
      },
      "title": "Developer",
      "responsiblePersons": [{
              "id": "a9709b55-69b9-4400-a5a9-6101790ea6d6"
      }]
}

After creating a Job you maybe want to change some fields. All fields used during Job creation can be updated with following request

HTTP Request

PUT /v1/companies/{companyId}/jobs/{jobId}

Update a Jobs Status

This is an example request body

{
  "value":"ACTIVE_PUBLISHED"
}

To change the status of a Job you need following request. Please keep in mind that not all status transitions are allowed.

status transitions

HTTP Request

PUT /v1/companies/{companyId}/jobs/{jobId}/status

Parameters

Property Description
status New status of a the Job. Possible values are: ACTIVE_PUBLISHED, ACTIVE_CLOSED, ARCHIVED (you can’t set DRAFT and DELETED directly)

Delete a Job

After a while you may want to delete a Job because it is outdated to do so use following request:

HTTP Request

DELETE /v1/companies/{companyId}/jobs/{jobId}

Job Applications

Job Applications are the other main pillar of your Account at Firstbird.

Job Applications can have following statuses:

Status Description
IN_PROGRESS This Job Application is currently in progress and waits for your Recruiters decisions
HIRED The candidate of this Job Application got hired
CLOSED The Job Application has been withdrawn by your Recruiters

Your Recruiters can give a Job Application different ratings:

Rating Description
A The A rating corresponds to the 3-star rating from the web applications
B The B rating corresponds to the 2-star rating from the web applications
C The C rating corresponds to the 1-star rating from the web applications

In case of a closed Job Application, one of the following reasons must be provided:

Reason Description
CANDIDATE_KNOWN This Applicant was already being considered by the company prior to this referral
CANDIDATE_REJECTED This Applicant was reject for this position
CANDIDATE_WITHDRAWN This Applicant withdrew is application
CANDIDATE_EVIDENCE This Applicant was not selected, but might be a good in the future
APPLICATION_INVALID The application is not valid

Get All Job Applications

This request returns JSON structured like this:

{
  "href": "https://api.1brd.com/v1/companies/00000000-0000-0000-0000-000000000000/applications?offset=0&limit=25",
  "total": 2,
  "offset": 0,
  "limit": 25,
  "first": {
    "href": "https://api.1brd.com/v1/companies/00000000-0000-0000-0000-000000000000/applications?offset=0&limit=25"
  },
  "last": {
    "href": "https://api.1brd.com/v1/companies/00000000-0000-0000-0000-000000000000/applications?offset=1&limit=25"
  },
  "items": [
    {
      "href": "https://api.1brd.com/v1/companies/00000000-0000-0000-0000-000000000000/applications/00000000-0000-0000-0000-000000000001",
      "id": "00000000-0000-0000-0000-000000000001",
      "status": "IN_PROGRESS",
      "applicationDate": "2016-03-23T08:37:15Z",
      "company": {
        "id": "00000000-0000-0000-0000-000000000000",
        "href": "https://api.1brd.com/v1/companies/00000000-0000-0000-0000-000000000000"
      },
      "applicant": {
        "id": "1d029da5-0a39-45d2-a26a-eb14a5d05d36",
        "href": "https://api.1brd.com/v1/companies/00000000-0000-0000-0000-000000000000/applicants/00000000-0000-0000-0000-000000000002"
      },
      "referrer": {
        "id": "dddddddd-dddd-dddd-dddd-dddddddddddd",
        "href": "https://api.1brd.com/v1/companies/00000000-0000-0000-0000-000000000000/users/dddddddd-dddd-dddd-dddd-dddddddddddd"
      },
      "share": {
        "id": "00000000-0000-0000-0000-000000000004",
        "href": "https://api.1brd.com/v1/companies/00000000-0000-0000-0000-000000000000/jobs/00000000-0000-0000-0000-000000000003/shares/00000000-0000-0000-0000-000000000004"
      },
      "job": {
        "id": "00000000-0000-0000-0000-000000000003",
        "href": "https://api.1brd.com/v1/companies/00000000-0000-0000-0000-000000000000/jobs/00000000-0000-0000-0000-000000000003"
      },
      "referrals": {
        "href": "https://api.1brd.com/v1/companies/00000000-0000-0000-0000-000000000000/applications/00000000-0000-0000-0000-000000000001/referrals"
      },
      "files": [
        {
          "id": "00000000-0000-0000-0000-000000000006",
          "href": "https://api.1brd.com/v1/companies/00000000-0000-0000-0000-000000000000/applications/00000000-0000-0000-0000-000000000005/files/00000000-0000-0000-0000-000000000006"
        }
      ],
      "applicantImage": {
        "href": "https://s3.eu-central-1.amazonaws.com/hummingbird-development/applicantimg/150x150/b642441c-2dc4-4cd1-8873-c5d7e2e725f2.jpeg?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Date=20160323T083722Z&X-Amz-SignedHeaders=host&X-Amz-Expires=1800&X-Amz-Credential=AKIAJX7FDXXZDKC4NZVA%2F20160323%2Feu-central-1%2Fs3%2Faws4_request&X-Amz-Signature=06981e7b0b46d4d43cd407bd2848391a01195714f6ce0df2a8cb67358efaa598"
      },
      "rewardPaid": false
    }
  ]
}

To get a list of all your Job Applications user following request:

HTTP Request

GET /v1/companies/{companyId}/applications

Query Parameters

Query Parameter Description
status A comma separated list of statuses. Possible values are IN_PROGRESS, HIRED and CLOSED
rating A comma separated list of ratings. Possible values are A, B and C
rated A boolean value filtering for Job Applications that are whether rated or not. Possible values are true and false
fields See Fields documentation
expand See Resource Expansion documentation. Expandable fields are: applicant, referrer, job, referrals
offset See Pagination documentation
limit See Pagination documentation
sort See Sorting documentation

Get a Single Job Application

This request returns JSON structured like this:

{
  "href": "https://api.1brd.com/v1/companies/00000000-0000-0000-0000-000000000000/applications/00000000-0000-0000-0000-000000000001",
  "id": "00000000-0000-0000-0000-000000000001",
  "status": "IN_PROGRESS",
  "applicationDate": "2016-03-23T08:37:15Z",
  "company": {
    "id": "00000000-0000-0000-0000-000000000000",
    "href": "https://api.1brd.com/v1/companies/00000000-0000-0000-0000-000000000000"
  },
  "applicant": {
    "id": "1d029da5-0a39-45d2-a26a-eb14a5d05d36",
    "href": "https://api.1brd.com/v1/companies/00000000-0000-0000-0000-000000000000/applicants/00000000-0000-0000-0000-000000000002"
  },
  "referrer": {
    "id": "dddddddd-dddd-dddd-dddd-dddddddddddd",
    "href": "https://api.1brd.com/v1/companies/00000000-0000-0000-0000-000000000000/users/dddddddd-dddd-dddd-dddd-dddddddddddd"
  },
  "share": {
    "id": "00000000-0000-0000-0000-000000000004",
    "href": "https://api.1brd.com/v1/companies/00000000-0000-0000-0000-000000000000/jobs/00000000-0000-0000-0000-000000000003/shares/00000000-0000-0000-0000-000000000004"
  },
  "job": {
    "id": "00000000-0000-0000-0000-000000000003",
    "href": "https://api.1brd.com/v1/companies/00000000-0000-0000-0000-000000000000/jobs/00000000-0000-0000-0000-000000000003"
  },
  "referrals": {
    "href": "https://api.1brd.com/v1/companies/00000000-0000-0000-0000-000000000000/applications/00000000-0000-0000-0000-000000000001/referrals"
  },
  "files": [
    {
      "id": "00000000-0000-0000-0000-000000000006",
      "href": "https://api.1brd.com/v1/companies/00000000-0000-0000-0000-000000000000/applications/00000000-0000-0000-0000-000000000005/files/00000000-0000-0000-0000-000000000006"
    }
  ],
  "applicantImage": {
    "href": "https://s3.eu-central-1.amazonaws.com/hummingbird-development/applicantimg/150x150/b642441c-2dc4-4cd1-8873-c5d7e2e725f2.jpeg?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Date=20160323T083722Z&X-Amz-SignedHeaders=host&X-Amz-Expires=1800&X-Amz-Credential=AKIAJX7FDXXZDKC4NZVA%2F20160323%2Feu-central-1%2Fs3%2Faws4_request&X-Amz-Signature=06981e7b0b46d4d43cd407bd2848391a01195714f6ce0df2a8cb67358efaa598"
  },
  "rewardPaid": false
}

To get a single Job Application you have to use following request:

HTTP Request

GET /v1/companies/{companyId}/applications/{jobApplicationId}

Query Parameters

Query Parameter Description
fields See Fields documentation.
expand See Resource Expansion documentation. Expandable fields are: applicant, referrer, job, referrals

Response Fields

Field name Required Description
href Yes The link to this job application.
id Yes The id to this job application.
status Yes The status.
applicationDate Yes The date of the application.
company Yes The company this job application belongs to.
applicant Yes The applicant.
referrer Yes The referrer.
share No The related share of this job application. (Not present, if the application didn’t come through a share)
job Yes The job this job application belongs to.
referrals Yes The referrals of this job application.
files No The attached files. (Not present, if no files provided by the applicant).
applicantImage No The applicant’s image. (Not present, if no applicant image provided by the applicant).
rewardPaid Yes Whether a reward has been paid or not.

Get Attachment file of a Job Application

The file information request returns JSON structured like this:

{
  "id": "a3beb15a-84ac-4646-a20b-7aa5faf982a7",
  "name": "my_application.pdf",
  "contentType": "application/pdf",
  "size": "100000",
  "url": "https://api.1brd.com/v1/companies/00000000-0000-0000-0000-000000000000/applications/d648096f-c3f4-4121-af9a-5377753e467e/files/a3beb15a-84ac-4646-a20b-7aa5faf982a7/url"
}

The file URL request returns JSON structured like this:

{
  "url": "https://s3-eu-central-1.amazonaws.com/hummingbird-development/files/775845ca-5837-4f65-9a4f-658d22f12622?response-content-disposition=inline%3B%20filename%3Dtest.pdf&response-content-type=application%2Fpdf&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Date=20170327T124130Z&X-Amz-SignedHeaders=host&X-Amz-Expires=15&X-Amz-Credential=AKIAJRDHPR2ZNVGR6XRQ%2F20170327%2Feu-central-1%2Fs3%2Faws4_request&X-Amz-Signature=6e3bdd82aa17d13af791c73314ab1accba5dc00644bbdd5670aacc66bbc88309"
}

First, you have to get basic information of job application file by issuing a File Information request.

The response contains a url property where you can request the actual file URL. You can do this by issuing a File URL request. This will return the URL to the actual file. Be aware, that the URL is valid for 15 seconds only.

HTTP Requests

File Information

GET /v1/companies/{companyId}/applications/{jobApplicationId}/files/{fileId}

File URL

GET /v1/companies/{companyId}/applications/{jobApplicationId}/files/{fileId}/url

Get Feedback of a Job Application

This request returns JSON structured like this:

{
  "href": "https://api.1brd.com/v1/companies/00000000-0000-0000-0000-000000000000/applications/d648096f-c3f4-4121-af9a-5377753e467e/referrals",
  "items": [
    {
      "id": "b93bb536-c964-4e11-9d30-11da0c362e09",
      "user": {
        "id": "dddddddd-dddd-dddd-dddd-dddddddddddd",
        "href": "https://api.1brd.com/v1/companies/00000000-0000-0000-0000-000000000000/users/dddddddd-dddd-dddd-dddd-dddddddddddd"
      },
      "referralType": "REFERRAL",
      "connection": "John Does is a former coworker",
      "reason": "I highly recommend this candidate"
    }
  ]
}

This is the feedback of the Talent Scout who shared/referred this candidate. Feedback can have different types whether the Talent Scout wants to support the applicant or not:

Type Description
REFERRAL The Talent Scout supports the Applicant and refers him for the position he applied on
NEUTRAL The Talent Scout doesn’t want to give either negative or positive feedback
NEGATIVE The Talent Scout doesn’t think that the candidate is a good fit for the postition

HTTP Request

GET /v1/companies/{companyId}/applications/{jobApplicationId}/referrals

Rate a Job Application

This is an example request body

{
  "value": "A",
  "message": "Test"
}

In order to rate a Job Application you have to use the following request

HTTP Request

PUT /v1/companies/{companyId}/applications/{jobApplicationId}/rating

Parameters

Property Description
value Rating value as described in the Job Application’s rating table
message Optional field, containing a message that the Recruiter may wish to send to the Referrer regarding this Applicant

Hire a Job Application

This is an example request body

{
  "firstDayOfWork": "2017-01-01",
  "message": "This was a very good referral. The candidate is a great fit.",
  "payReward": true,
  "value": "HIRED"
}

In order to hire a Job Application you must change its status to HIRED using the following request

HTTP Request

PUT /v1/companies/{companyId}/applications/{jobApplicationId}/status

Parameters

Property Description
firstDayOfWork First day of work for the Applicant. Date format: “yyyy-MM-dd”
message Optional field, containing a message that the Recruiter may wish to send to the Referrer regarding this Applicant
payReward Whether or not the reward should be given to the Referrer
value New Job Application status. In this case, ‘HIRED’. Check Job Application’s Status table

Close a Job Application

This is an example request body

{
  "closeReason": "CANDIDATE_WITHDRAWN",
  "message": "test",
  "value": "CLOSED"
}

In order to close a Job Application you must change its status to CLOSED using the following request

HTTP Request

PUT /v1/companies/{companyId}/applications/{jobApplicationId}/status

Parameters

Property Description
closeReason Reason why this Job Application is being rejected. Check Job Application’s close reasons
message Optional field, containing a message that the Recruiter may wish to send to the Referrer regarding this Applicant
value New Job Application status. In this case, 'CLOSED’. Check Job Application’s Status table

Re-open a Job Application

This is an example request body

{
  "value": "IN_PROGRESS"
}

In order to re-open a closed Job Application you must change its status to IN_PROGRESS using the following request

HTTP Request

PUT /v1/companies/{companyId}/applications/{jobApplicationId}/status

Parameters

Property Description
value New Job Application status. In this case, 'IN_PROGRESS’. Check Job Application’s Status table

Delete a closed Job Applcation

In order to delete a closed or hired Job Application you must use the following request

HTTP Request

DELETE /v1/companies/{companyId}/applications/{jobApplicationId}

If the request succeeds, the api will return a 200 response with no body.

Users

Users are one of the main pillars of Firstbird.

Get All Users

This endpoint retrieves all Users for your company.

HTTP Request

This request returns JSON structured like this:

{
  "href": "https://api.1brd.com/v1/companies/00000000-0000-0000-0000-000000000000/users?offset=0&limit=25",
  "total": 1,
  "offset": 0,
  "limit": 25,
  "first": {
    "href": "https://api.1brd.com/v1/companies/00000000-0000-0000-0000-000000000000/users?offset=0&limit=25"
  },
  "last": {
    "href": "https://api.1brd.com/v1/companies/00000000-0000-0000-0000-000000000000/users?offset=0&limit=25"
  },
  "items": [
    {
      "href": "https://api.1brd.com/v1/companies/00000000-0000-0000-0000-000000000000/users/00000000-0000-0000-0000-000000000001",
      "id": "00000000-0000-0000-0000-000000000001",
      "companyId": "00000000-0000-0000-0000-000000000000",
      "firstName": "Test",
      "lastName": "User",
      "email": "test.user@firstbird.com",
      "department": {
        "id": "00000000-0000-0000-0000-000000000002",
        "href": "https://api.1brd.com/v1/companies/00000000-0000-0000-0000-000000000000/departments/00000000-0000-0000-0000-000000000002"
      },
      "location": {
        "id": "00000000-0000-0000-0000-000000000003",
        "href": "https://api.1brd.com/v1/companies/00000000-0000-0000-0000-000000000000/locations/00000000-0000-0000-0000-000000000003"
      },
      "locale": "en_US",
      "status": "ACTIVE",
      "incognito": false,
      "mainRole": "ROLE_COMPANY_ADMIN",
      "timeZone": "Europe/Vienna",
      "roles": [
        "ROLE_COMPANY_ADMIN",
        "ROLE_RECRUITER",
        "ROLE_TALENT_SCOUT"
      ],
      "profile_picture": {
        "id": "00000000-0000-0000-0000-000000000003",
        "href": "https://api.1brd.com/v1/companies/00000000-0000-0000-0000-000000000000/users/00000000-0000-0000-0000-000000000001/profile_picture"
      },
      "employeeId": "123456"
    }
  ]
}

GET /v1/companies/{companyId}/users

Query Parameters

Query Parameter Required Description
mainRoles No Comma separated list of main roles which should be included in the response. Allowed: ROLE_COMPANY_ADMIN, ROLE_RECRUITER or ROLE_TALENT_SCOUT
roles No Comma separated list of roles which should be included in the response. Allowed: ROLE_COMPANY_ADMIN, ROLE_RECRUITER or ROLE_TALENT_SCOUT
locations No Comma separated list of location ids which should be included in the response.
departments No Comma separated list of department ids which should be included in the response.
inactives No Whether inactive users should be included in the response or not. Allowed: true or false
incognitos No Whether incognito users should be included in the response or not. Allowed: true or false
exclude No Comma separated list of user ids which should not be included in the response.
query No Filter by user name or email.
status No Comma separated list of statuses which should be included in the response. Allowed: ACTIVE or INACTIVE
fields No See Fields documentation.
limit No See Pagination documentation.
offset No See Pagination documentation.
sort No See Sorting documentation.

Response Fields

Property Required Description
href Yes The link to this user.
id Yes The id of this user.
companyId Yes The company this user belongs to.
firstName Yes The first name of this user.
lastName Yes The last name of this user.
email Yes The email of this user.
department Yes The department this user belongs to.
location Yes The location this user belongs to.
locale Yes The locale of this user.
status Yes The status of this user.
incognito Yes Whether this user is in incognito mode or not.
mainRole Yes The main role of this user.
roles Yes All roles of this user.
timeZone Yes The time zone of this user.
profile_picture No The profile picture of this user.
employeeId No The external employee id of this user.

Files

Files are managed via the endpoints described below and are used in various places in Firstbird (e.g. Job Brandings). Wherever you need to specify a file, you always reference them by their Id.

Upload a File: Binary

To upload a file using in binary use the following request:

HTTP Request

This request returns JSON structured like this:

{
  "id": "00000000-0000-0000-0000-000000000000",
  "name": "my_filename.jpeg",
  "contentType": "image/jpeg",
  "size": 100000,
  "createdAt": "2018-10-09T10:04:38Z"
}

POST https://services.1brd.com/files/v1/binary

Headers

Property Required Description
X-Filename Yes The name of the file.
Content-Type Yes The content type of the file. Must be one of: application/msword, application/vnd.openxmlformats-officedocument.wordprocessingml.document, application/pdf, application/zip, image/jpeg, image/png or image/bmp.

Request Body

The binary file that you want to upload.

Upload a File: Multipart

To upload a file using multipart use the following request:

HTTP Request

This request returns JSON structured like this:

{
  "id": "00000000-0000-0000-0000-000000000000",
  "name": "my_filename.jpeg",
  "contentType": "image/jpeg",
  "size": 100000,
  "createdAt": "2018-10-09T10:04:38Z"
}

POST https://services.1brd.com/files/v1/multipart

Request Body

In your multipart form, set a key called file where you put in the binary file.

Upload a File: Base64

To upload a file using Base64 use the following request:

HTTP Request

This is an example request body

{
  "name": "my_filename.jpeg",
  "contentType": "image/jpeg",
  "contentBase64": "base64-image"
}

This request returns JSON structured like this:

{
  "id": "00000000-0000-0000-0000-000000000000",
  "name": "my_filename.jpeg",
  "contentType": "image/jpeg",
  "size": 100000,
  "createdAt": "2018-10-09T10:04:38Z"
}

POST https://services.1brd.com/files/v1/base64

Parameters

Property Required Description
name Yes The name of the file.
contentType Yes The content type of the file. Must be one of: application/msword, application/vnd.openxmlformats-officedocument.wordprocessingml.document, application/pdf, application/zip, image/jpeg, image/png or image/bmp.
contentBase64 Yes The binary file base64 encoded.

Reward Plans

Reward Plans allow you to customize rewards defined by your company. Currently, there can be rewards for job application hires only.

Get All Reward Plans

This endpoint retrieves all Reward Plans that are configured for your company.

HTTP Request

This request returns JSON structured like this:

{
  "href": "https://api.1brd.com/v1/companies/00000000-0000-0000-0000-000000000000/rewarding/plans?offset=0&limit=25",
  "total": 1,
  "offset": 0,
  "limit": 25,
  "first": {
    "href": "https://api.1brd.com/v1/companies/00000000-0000-0000-0000-000000000000/rewarding/plans?offset=0&limit=25"
  },
  "last": {
    "href": "https://api.1brd.com/v1/companies/00000000-0000-0000-0000-000000000000/rewarding/plans?offset=0&limit=25"
  },
  "items": [
    {
      "href": "https://api.1brd.com/v1/companies/00000000-0000-0000-0000-000000000000/rewarding/plans/00000000-0000-0000-0000-000000000005",
      "id": "00000000-0000-0000-0000-000000000005",
      "type": "hire",
      "name": "Just a Plan",
      "currency": "EUR",
      "external": false,
      "details": {
        "items": [
           {
              "description":"250€ Amazon Gift Card",
              "value":250,
              "paymentDate":"CANDIDATE_IS_HIRED"
           },
           {
              "description":"400€ Amazon Gift Card",
              "value":400,
              "paymentDate":"4_MONTHS_AFTER_EMPLOYMENT"
           }
        ]
      }
    }
  ]
}

GET /v1/companies/{companyId}/rewarding/plans

Query Parameters

Query Parameter Required Description
status No Comma separated list of statuses which should be included in the response. Allowed: ACTIVE or INACTIVE
limit No See Pagination documentation.
offset No See Pagination documentation.

Response Fields

Property Required Description
href Yes The link to this reward plan.
id Yes The id of this reward plan.
type Yes The type of reward plan. Supported types: hire
name Yes The name of this reward plan.
currency Yes The currency for this reward plan.
external Yes Whether this is an external reward or not.
details.items Yes The rewards for this reward plan.
details.items[i].description Yes The description of this reward.
details.items[i].value Yes The value of this reward.
details.items[i].paymentDate Yes The payment date of this reward.

Webhooks

Use webhooks to be notified about events that happen in a Firstbird account.

Webhook terminology

An event is an account occurrence, such as a new job application being received, a referral added, or an applicant being hired. Each occurrence has a corresponding event object. Webhook endpoints are URLs defined by users to which Firstbird sends events. A single event may be sent to many webhook endpoints. Webhooks refers to the overall concept of sending notifications to webhook endpoints.

–

Why using webhooks

Interacting with a third-party API like Firstbird’s can introduce two problems:

Webhooks solve these problems by letting you register a URL that we will notify anytime an event happens in your account. When the event occurs—for example, when a job application was received, Firstbird creates an event object. This object contains all the relevant information about what just happened, including the type of event and the data associated with that event. Firstbird then sends the event object to any URLs in your account’s webhooks settings via an HTTP(s) POST request.

You might use webhooks as the basis to:

Configuring Webhooks

Webhooks can be configured as a Company Administrator within the Integration tab of the Account Preferences. For a single webhook destination you have to configure your callback URL, which can be either HTTP or HTTPS. You can decide yourself which of the available events should be sent to which webhook destination.

webhooks settings

Webhooks Structure

[
  {
    "event_name": "entity.event_name",
    "event": {

    }
  }
]

Our webhooks are sent as JSON data with POST requests to your configured URL. To allow batching of webhooks we send them as arrays which can contain multiple event envelopes, containing the type of the event and the payload.

Acknowledge webhooks

Following HTTP response status values are considered as success: 2XX, 3XX. If your configured URL returns any of this status values, Firstbird considers this webhook as successfully delivered.

If the request to your configured URL returns with a status of 4XX or 5XX we will consider that as a failure (e.g. your receiving server has been unavailable) and are going to retry the delivery for 24 hours which exponential increasing intervals between the retries.

Security Considerations

As our webhooks don’t provide authentication mechanisms, you shouldn’t take the values contained in the requests as granted. It is considered a good practice to request the contained values by their reference id (e.g. job_application.received contains the job application id which allows you to request the referenced job application via our REST API)

You can restrict the webhooks to only accept them from our IPs: 52.57.76.133, 52.57.83.207.

Available Events

job_application.received by link or referral

{
  "job_application": {
      "id": "00000000-0000-0000-0000-000000000000",
      "job_id": "00000000-0000-0000-0000-000000000000",
      "rating": "A, B or C",
      "created_by_user_id": "00000000-0000-0000-0000-000000000000",
      "status": "IN_PROGRESS, HIRED or CLOSED",
      "applicant_image": "http://example.com/applicant_image.png",
      "attachments": [
          "https://api.1brd.com/v1/companies/00000000-0000-0000-0000-000000000000/applications/d648096f-c3f4-4121-af9a-5377753e467e/files/a3beb15a-84ac-4646-a20b-7aa5faf982a7"
      ]
  },
  "company_id": "00000000-0000-0000-0000-000000000000",
  "applicant": {
      "id": "00000000-0000-0000-0000-000000000000",
      "first_name": "Mister",
      "last_name": "Finch",
      "email": "mister.finch@firstbird.com",
      "phone_number": "123456789"
  },
  "referrer": {
      "id": "00000000-0000-0000-0000-000000000000",
      "company_id": "00000000-0000-0000-0000-000000000000",
      "first_name": "Mister",
      "last_name": "Finch",
      "email": "mister.finch@firstbird.com",
      "locale": "en_US",
      "main_role": "ROLE_TALENT_SCOUT",
      "location_id": "00000000-0000-0000-0000-000000000000",
      "department_id": "00000000-0000-0000-0000-000000000000",
      "status": "ACTIVE or INACTIVE",
      "incognito": false,
      "time_zone": "Europe/Vienna"
  },
  "job": {
      "id": "00000000-0000-0000-0000-000000000000",
      "company_id": "00000000-0000-0000-0000-000000000000",
      "location_id": "00000000-0000-0000-0000-000000000000",
      "contact_person_id": "00000000-0000-0000-0000-000000000000",
      "reward_id": "00000000-0000-0000-0000-000000000000",
      "department_id": "00000000-0000-0000-0000-000000000000",
      "reference_number": "ref-no",
      "title": "Developer",
      "description": "Java Backend Dev",
      "end_date": "1970-01-01 12:00:00.000Z",
      "status": "DRAFT, ACTIVE_PUBLISHED, ACTIVE_CLOSED, ARCHIVED or DELETED",
      "hot": true,
      "responsible_persons": [
          "00000000-0000-0000-0000-000000000000",
          "00000000-0000-0000-0000-000000000000"
      ],
      "creation_date": "1970-01-01 12:00:00.000Z"
  },
  "date_time": "1970-01-01 12:00:00.000Z",
  "type": "link or referral"
}

job_application.received by share

{
  "job_application": {
      "id": "00000000-0000-0000-0000-000000000000",
      "job_id": "00000000-0000-0000-0000-000000000000",
      "rating": "A, B or C",
      "created_by_user_id": "00000000-0000-0000-0000-000000000000",
      "status": "IN_PROGRESS, HIRED or CLOSED",
      "applicant_image": "http://example.com/applicant_image.png",
      "attachments": [
          "https://api.1brd.com/v1/companies/00000000-0000-0000-0000-000000000000/applications/d648096f-c3f4-4121-af9a-5377753e467e/files/a3beb15a-84ac-4646-a20b-7aa5faf982a7"
      ]
  },
  "company_id": "00000000-0000-0000-0000-000000000000",
  "applicant" : {
      "id": "00000000-0000-0000-0000-000000000000",
      "first_name": "Mister",
      "last_name": "Finch",
      "email": "mister.finch@firstbird.com",
      "phone_number": "123456789"
  },
  "referrer": {
      "id": "00000000-0000-0000-0000-000000000000",
      "company_id": "00000000-0000-0000-0000-000000000000",
      "first_name": "Mister",
      "last_name": "Finch",
      "email": "mister.finch@firstbird.com",
      "locale": "en_US",
      "main_role": "ROLE_TALENT_SCOUT",
      "location_id": "00000000-0000-0000-0000-000000000000",
      "department_id": "00000000-0000-0000-0000-000000000000",
      "status": "ACTIVE or INACTIVE",
      "incognito": false,
      "time_zone": "Europe/Vienna"
  },
  "share_id": "00000000-0000-0000-0000-000000000000",
  "job": {
      "id": "00000000-0000-0000-0000-000000000000",
      "company_id": "00000000-0000-0000-0000-000000000000",
      "location_id": "00000000-0000-0000-0000-000000000000",
      "contact_person_id": "00000000-0000-0000-0000-000000000000",
      "reward_id": "00000000-0000-0000-0000-000000000000",
      "department_id": "00000000-0000-0000-0000-000000000000",
      "reference_number": "ref-no",
      "title": "Developer",
      "description": "Java Backend Dev",
      "end_date": "1970-01-01 12:00:00.000Z",
      "status": "DRAFT, ACTIVE_PUBLISHED, ACTIVE_CLOSED, ARCHIVED or DELETED",
      "hot": true,
      "responsible_persons": [
          "00000000-0000-0000-0000-000000000000",
          "00000000-0000-0000-0000-000000000000"
      ],
      "creation_date": "1970-01-01 12:00:00.000Z"
  },
  "date_time" : "1970-01-01 12:00:00.000Z",
  "type" : "share"
}

job_application.received from user

{
  "job_application": {
      "id": "00000000-0000-0000-0000-000000000000",
      "job_id": "00000000-0000-0000-0000-000000000000",
      "rating": "A, B or C",
      "created_by_user_id": "00000000-0000-0000-0000-000000000000",
      "status": "IN_PROGRESS, HIRED or CLOSED",
      "applicant_image": "http://example.com/applicant_image.png",
      "attachments": [
          "https://api.1brd.com/v1/companies/00000000-0000-0000-0000-000000000000/applications/d648096f-c3f4-4121-af9a-5377753e467e/files/a3beb15a-84ac-4646-a20b-7aa5faf982a7"
      ]
  },
  "company_id": "00000000-0000-0000-0000-000000000000",
  "applicant": {
      "id": "00000000-0000-0000-0000-000000000000",
      "first_name": "Mister",
      "last_name": "Finch",
      "email": "mister.finch@firstbird.com",
      "phone_number": "123456789"
  },
  "user": {
      "id": "00000000-0000-0000-0000-000000000000",
      "company_id": "00000000-0000-0000-0000-000000000000",
      "first_name": "Mister",
      "last_name": "Finch",
      "email": "mister.finch@firstbird.com",
      "locale": "en_US",
      "main_role": "ROLE_TALENT_SCOUT",
      "location_id": "00000000-0000-0000-0000-000000000000",
      "department_id": "00000000-0000-0000-0000-000000000000",
      "status": "ACTIVE or INACTIVE",
      "incognito": false,
      "time_zone": "Europe/Vienna"
  },
  "share_id": "00000000-0000-0000-0000-000000000000",
  "job": {
      "id": "00000000-0000-0000-0000-000000000000",
      "company_id": "00000000-0000-0000-0000-000000000000",
      "location_id": "00000000-0000-0000-0000-000000000000",
      "contact_person_id": "00000000-0000-0000-0000-000000000000",
      "reward_id": "00000000-0000-0000-0000-000000000000",
      "department_id": "00000000-0000-0000-0000-000000000000",
      "reference_number": "ref-no",
      "title": "Developer",
      "description": "Java Backend Dev",
      "end_date": "1970-01-01 12:00:00.000Z",
      "status": "DRAFT, ACTIVE_PUBLISHED, ACTIVE_CLOSED, ARCHIVED or DELETED",
      "hot": true,
      "responsible_persons": [
          "00000000-0000-0000-0000-000000000000",
          "00000000-0000-0000-0000-000000000000"
      ],
      "creation_date": "1970-01-01 12:00:00.000Z"
  },
  "date_time": "1970-01-01 12:00:00.000Z",
  "type": "application"
}

job_application.deleted from user

{
  "job_application": {
      "id": "00000000-0000-0000-0000-000000000000",
      "job_id": "00000000-0000-0000-0000-000000000000",
      "rating": "A,B or C",
      "created_by_user_id": "00000000-0000-0000-0000-000000000000",
      "status": "IN_PROGRESS, HIRED or CLOSED"
  },
  "company_id": "00000000-0000-0000-0000-000000000000",
  "user_id": "00000000-0000-0000-0000-000000000000",
  "date_time" : "1970-01-01 12:00:00.000Z"
}

job_application.rated from user

{
  "job_application": {
      "id": "00000000-0000-0000-0000-000000000000",
      "job_id": "00000000-0000-0000-0000-000000000000",
      "rating": "A, B or C",
      "created_by_user_id": "00000000-0000-0000-0000-000000000000",
      "status": "IN_PROGRESS, HIRED or CLOSED"
  },
  "company_id": "00000000-0000-0000-0000-000000000000",
  "user_id": "00000000-0000-0000-0000-000000000000",
  "date_time": "1970-01-01 12:00:00.000Z",
  "initial": true,
  "rating": "A, B or C"
}

job_application.closed from user

{
  "job_application": {
      "id": "00000000-0000-0000-0000-000000000000",
      "job_id": "00000000-0000-0000-0000-000000000000",
      "rating": "A, B or C",
      "created_by_user_id": "00000000-0000-0000-0000-000000000000",
      "status": "IN_PROGRESS, HIRED or CLOSED"
  },
  "company_id": "00000000-0000-0000-0000-000000000000",
  "user_id": "00000000-0000-0000-0000-000000000000",
  "date_time": "1970-01-01 12:00:00.000Z",
  "close_reason": "CANDIDATE_KNOWN"
}

job_application.hired from user

{
  "job_application": {
      "id": "00000000-0000-0000-0000-000000000000",
      "job_id": "00000000-0000-0000-0000-000000000000",
      "rating": "A, B or C",
      "created_by_user_id": "00000000-0000-0000-0000-000000000000",
      "status": "IN_PROGRESS, HIRED or CLOSED"
  },
  "company_id": "00000000-0000-0000-0000-000000000000",
  "user_id" : "00000000-0000-0000-0000-000000000000",
  "date_time" : "1970-01-01 12:00:00.000Z",
  "pay_reward" : true,
  "first_day_of_work" : "2020-01-01"
}

job_application.referral_added from user

{
  "job_application": {
      "id": "00000000-0000-0000-0000-000000000000",
      "job_id": "00000000-0000-0000-0000-000000000000",
      "rating": "A, B or C",
      "created_by_user_id": "00000000-0000-0000-0000-000000000000",
      "status": "IN_PROGRESS, HIRED or CLOSED"
  },
  "company_id": "00000000-0000-0000-0000-000000000000",
  "user_id" : "00000000-0000-0000-0000-000000000000",
  "date_time" : "1970-01-01 12:00:00.000Z",
  "referral_id" : "00000000-0000-0000-0000-000000000000",
  "connection" : "Former coworker!",
  "reason" : "Great employee!",
  "referral_type" : "NEUTRAL, POSITIVE or NEGATIVE"
}
type Description
job_application.received A job application has been created inside Firstbird. The type fields indicates how it has been created.
job_application.edited One of your recruiters edited a job application
job_application.deleted One of your recruiters deleted a job application
job_application.rated One of your recruiters rated a job application
job_application.closed One of your recruiters closed a job application
job_application.hired One of your recruiters hired the applicant
job_application.referral_added The talent scout via whom the job application has been received provided feedback.

Note for job_application.received events:

code