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:
- An HTTP Status Code indicating success or failure (possible codes can be found below)
- Any HTTP Headers
- A Response Body, which will contain the created entity resource (if the call succeeded), or a detailed error (if the call failed)
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:
- An HTTP Status Code indicating success or failure (possible codes can be found below)
- Any HTTP Headers
- A Response Body, which will contain the created entity resource (if the call succeeded), or a detailed error (if the call failed)
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
Links and Resource Expansion
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.
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. |
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:
- Services not directly responsible for making an API request may still need to know the response of that request
- Some events, like job application received and referral added events, are not the result of a direct API request
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:
- Send new e-mails to applicants on specific events
- Forward the job application to your ATS
- Integrate your whole hiring process with Firstbird
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 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:
- If the referrer/user of the job application got deleted, the
referrer
/user
key is not present. - If the applicant did not provide a picture, the
applicant_image
key is not present. - To get a file from the
attachments
array, follow this documentation.