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

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

:warning: DEPRECATION: The base url for authentication will change! The authentication flow remains the same.

Base URL for authentications is

https://auth.1brd.com

POST https://auth.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 its 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"
        }
      ],
      "jobPostingUrl": "https://jobs.someurl.com/abc?source=Firstbird",
      "careerSiteUrl": "https://jobs.someurl.com/abc",
      "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"
    }
  ],
  "jobPostingUrl": "https://jobs.someurl.com/abc?source=Firstbird",
  "careerSiteUrl": "https://jobs.someurl.com/abc",
  "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)
jobPostingUrl	No	The target URL for ATS Forwarding, see also Candidate Experience Package
careerSiteUrl	No	The target URL for the custom public job page where the candidate will be redirected once they follow a job link
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"
      }],
      "jobPostingUrl": "https://jobs.someurl.com/abc?source=Firstbird",
      "careerSiteUrl": "https://jobs.someurl.com/abc"
}

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

Field name	Required	Description
location	Yes	The Location of your Company the Job is associated with.
department	Yes	The Id of the Department this Job is associated with.
title	Yes	The title of the Job. This field is limited to 255 characters.
description	Yes	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.
contactPerson	Yes	The Id of the Recruiter who is responsible for this Job.
reward	Yes	The Reward that will be payed as soon as an Applicant gets hired for that Job.
hot	Yes	Whether the job is a hot job or not.
endDate	No	The date when the job will be automatically closed once it is in status ACTIVE_PUBLISHED. Can be null to avoid autoclosing.
referenceNumber	No	This field allows to enter reference numbers of external systems.
responsiblePersons	No	An array of objects containing the User Ids of Recruiters being responsible for this Job as well
jobBranding	No	The Job Branding of your Company the Job is associated with
jobPostingUrl	No	The target URL for ATS Forwarding, see also Candidate Experience Package
careerSiteUrl	No	The target URL for the custom public job page where the candidate will be redirected once they follow a job link

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"
      }],
      "jobPostingUrl": "https://jobs.someurl.com/abc?source=Firstbird",
      "careerSiteUrl": "https://jobs.someurl.com/abc"
}

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}

Invitations

Invitations allow you to invite people to join your company

Create an Invitation

This endpoint lets you create a new invitation

HTTP Request

This is an example request body

{
    "email": "test.user@firstbird.com",
    "locale": "en_US",
    "message": "hey, would you like to join our company?",
    "role": "ROLE_TALENT_SCOUT"
}

This request returns JSON structured like this:

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

POST /v1/companies/{companyId}/invitations

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 can 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,
      "channel": "CHANNEL",
      "source": {
          "identifier": "00000000-0000-0000-0000-000000000009",
          "name": "source_name"
      }
    }
  ]
}

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

HTTP Request

GET /v1/companies/{companyId}/applications

Headers

If a media type header application/x.firstbird.application+json;version=2 is passed, the close reason in the response can be absent. Otherwise a default of CANDIDATE_ACCEPTED will be returned.

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,
  "channel": "CHANNEL",
  "source": {
      "identifier": "00000000-0000-0000-0000-000000000009",
      "name": "source_name"
  }
}

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

HTTP Request

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

Headers

If a media type header application/x.firstbird.application+json;version=2 is passed, the close reason in the response can be absent. Otherwise a default of CANDIDATE_ACCEPTED will be returned.

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.
closeReason	No	The close reason for a closed referral. Will only be returned if status is CLOSED and might be absent if media type header application/x.firstbird.application+json;version=2 is passed.

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	Optional field, 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 Application

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.

Edit a JobApplication

This endpoint is used to edit a job application’s information. It can also be used to edit or delete associated files and profile pictures from storage. To do this provide an empty array in the files field. When updating the job application any previously existing file that is left out in the update request, will be deleted. Also if you send a request without applicantImage, the associated Image will be deleted.

HTTP Request

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

this is an example request body

{
  "firstName": "Test",
  "lastName": "Applicant",
  "email": "test.applicant@firstbird.com",
  "phoneNumber": "123456789",
  "url": "https://somesocialmediaplattform.com/users/TestApplicant",
  "files": [
    {
      "id": "00000000-0000-0000-0000-000000000001"
    }
  ],
  "applicantImage": {
    "id": "00000000-0000-0000-0000-000000000002"
  }
}

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:

• 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"
}

reward.approved

{
    "reward": {
        "name": "250€ Amazon Gift Card",
        "value": "250",
        "currency": "EUR",
        "due_date": "2021-02-10",
        "company_id": "00000000-0000-0000-0000-000000000000",
        "id": "00000000-0000-0000-0000-000000000000"
    },
    "company_id": "00000000-0000-0000-0000-000000000000",
    "recipient": {
        "id": "00000000-0000-0000-0000-000000000000",
        "first_name": "Name",
        "last_name": "Last",
        "email": "email@email.com",
        "location": "Location",
        "department": "Department",
        "employee_id": "123"
    },
    "job": {
        "id": "00000000-0000-0000-0000-000000000000",
        "company_id": "00000000-0000-0000-0000-000000000000",
        "title": "Title"
    },
    "application": {
        "id": "00000000-0000-0000-0000-000000000000",
        "company_id": "00000000-0000-0000-0000-000000000000",
        "first_name": "Name",
        "last_name": "Last"
    },
    "approvedBy": {
        "id": "00000000-0000-0000-0000-000000000000",
        "company_id": "00000000-0000-0000-0000-000000000000",
        "first_name": "Name",
        "last_name": "Last"
    },
    "type": "reward.approved",
    "company": {
        "domain": "domain",
        "company_name": "ATS Forward",
        "street": "street",
        "postal_code": "1234",
        "city": "city"
    }
}

points.gained

{
    "user": {
        "id": "00000000-0000-0001-0000-000000000000",
        "first_name": "Mister",
        "last_name": "Finch",
        "email": "mister.finch@firstbird.com",
        "location": "Wien",
        "department": "IT",
        "employee_id": "1234"
    },
    "count": 1,
    "cause": "JOB_VIEWS",
    "company": {
        "id": "00000000-0000-0000-0000-000000000000",
        "domain": "test",
        "company_name": "test"
    },
    "type": "points.gained",
    "date_time": "0001-01-01T01:01:00.000+0139"
}

points.revoked

{
    "user": {
        "id": "00000000-0000-0001-0000-000000000000",
        "first_name": "Mister",
        "last_name": "Finch",
        "email": "mister.finch@firstbird.com",
        "location": "Wien",
        "department": "IT",
        "employee_id": "1234"
    },
    "count": 1,
    "cause": "JOB_APPLICATION_INVALID",
    "company": {
        "id": "00000000-0000-0000-0000-000000000000",
        "domain": "test",
        "company_name": "test"
    },
    "type": "points.revoked",
    "date_time": "0001-01-01T01:01:00.000+0139"
}

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.
reward.approved	The hiring reward that was approved by a recruiter which a talent scout should receive.
points.gained	A user gained points for actions within Firstbird.
points.revoked	A user got points revoked that were gained earlier within Firstbird.

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.

Note for reward.approved event:

• If the applicant of the job application got deleted the application / first_name and application / last_name keys are not present
• The recipient / employee_id key is optional as a user is not obliged to provide one.
• The reward / currency follows the ISO 4217 currency standard.
• The reward / currency has an exception to the above rule where the currency can be the value COINS. If this is the case the reward / name key is empty.
• The company / street, company / city and company / postal_code keys are optional as a company is not obliged to provide them.

Candidate Experience Package

Intro

With the introduction of our Candidate Experience Package we have revised our referral form for candidates. It is now split into two steps. On the first step the candidate accepts the referral which only needs basic information. On the second step the candidate can now be forwarded to an external URL to complete the job application directly in the ATS.

Requirement

The Candidate Experience Package has to be unlocked explicitly per Company Account on Firstbird side. The CEP is an add-on package.

Job-Import with external URL

The endpoint of creating a job has an additional field jobPostingUrl to add the target URL

POST /v1/companies/{companyId}/jobs

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"
      }],
      "jobPostingUrl": "https://jobs.someurl.com/abc?source=Firstbird"
}

Request basic referral information

Once a candidate has completed the first step the user is forwarded to the jobPostingUrl. A query parameter referralId is added to this URL which references the referral in Firstbird. Note that the referralId is different from the applicationId. This referralId can be used to request basic information the candidate has added to Firstbird.

GET /v1/companies/{companyId}/applications?sourceId={referralId}&expand=applicant

Move Accepted Referral to in Progress

In the background we besides a referral also create a job application. To update a status of a referral you actually need to accept the Terms and then update the status of the job application. That means to move a Job Application from “Accepted Referral” to “In Progress” you need to

• get the jobApplicationId
• accept the legal terms via API
• update the Status of the job application

Endpoint to get the Job Application Id

GET /v1/companies/{companyId}/applications?sourceId={referralId}&expand=applicant

Endpoint to accept the legal terms

PUT /v1/companies/{companyId}/applications/{applicationId}

This is an example request body

{
  "firstName": "Maria",
  "lastName": "Finch",
  "email": "maria.finch1983@gmail.com",
  "acceptTerms": true
}

Important to know

All fields are mandatory. Changing a field will update the Job Application information on Firstbird side!

Endpoint to move the job application to “In Progress”

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

This is an example request body

{
  "value": "FINISHED"
}

The value finished means that the job application has been finished and therefore is moved to “In Progress”.

Important to know

Customers may have set the attachments to mandatory, which block the job application to be finished as it will complain about missing files. First disable the mandatory files in the Company Account Preferences!

User Provisioning

Please note that the base URL for user provisioning is

https://profile.services.1brd.com

One caveat is that User-Pre-Provisioning just provides basic user profile information that is linked when a user registers, which means that the pre-provisioned profiles are only listed in the user list once they have registered themselves in Firstbird.

Ingest User Profiles

This is an example request body

{
  "users": [ 
    {
      "first_name":"Test",
      "last_name":"User",
      "personnel_number":"1234",
      "email_address":"test.user@firstbird.com",
      "location":"Vienna",
      "department":"IT"
    },
    {
      "first_name":"Test",
      "last_name":"User2",
      "personnel_number":"1235",
      "email_address":"test.user2@firstbird.com"
    }
  ]
}

You can use this endpoint to send multiple UserInformation objects as a list of users. This will stage all users for provisioning.

HTTP Request

POST /v1/companies/{companyId}/users/ingest

UserInformation Objects

All request parameters are in string format.

Field name	Required	Description
first_name	Yes	First name
last_name	Yes	Last name
personnel_number	Yes	The id of the employee in your system
email_address	Yes	Email address
location	No	The location of the user
department	No	The department of the user

Create a User Profile

This is an example request body

{
  "first_name":"Test",
  "last_name":"User",
  "email_address":"test.user@firstbird.com",
  "personnel_number":"1234",
  "active":true
}

To create a new user profile, use following request:

HTTP Request

POST /v1/companies/{companyId}/users/profile

Parameters

Field name	Required	Description
first_name	Yes	First name
last_name	Yes	Last name
personnel_number	Yes	The id of the employee in your system
email_address	Yes	Email address
location	No	The location of the user
department	No	The department of the user
active	No	A boolean value to activate or deactivate a user in firstbird. Default value is true.

Update a User Profile

This is an example request body

{
  "first_name":"Test",
  "last_name":"User",
  "email_address":"test.user@firstbird.com",
  "personnel_number":"1234",
  "active":true
}

To update a user profile, use following request:

HTTP Request

PUT /v1/companies/{companyId}/users/profile

Query Parameters

Query Parameter	Required	Description
identifier	Yes	You may use either of the personnel_number or the email address of the user.

Deactivate a User Profile

For deactivating a user profile, set the active field to false in the body and call the endpoint for updating a profile as follows.

This is an example request body

{
  "first_name":"Test",
  "last_name":"User",
  "email_address":"test.user@firstbird.com",
  "personnel_number":"1234",
  "active":false
}

HTTP Request

PUT /v1/companies/{companyId}/users/profile

Query Parameters

Query Parameter	Required	Description
identifier	Yes	You may use either of the personnel_number or the email address of the user.

Delete a User Profile

To delete a user profile, use following request:

HTTP Request

DELETE /v1/companies/{companyId}/users/profile

Query Parameters

Query Parameter	Required	Description
identifier	Yes	You may use either of the personnel_number or the email address of the user.

Get a User Profile

The request returns JSON structured like this:

{
  "first_name":"Test",
  "last_name":"User",
  "email_address":"test.user@firstbird.com",
  "personnel_number":"1234",
  "active":true
}

To get a user profile, use following request:

HTTP Request

GET /v1/companies/{companyId}/users/profile

Query Parameters

Query Parameter	Required	Description
identifier	Yes	You may use either of the personnel_number or the email address of the user.

Status Page

Our status page delivers the real time status of the functionality of our services.

Incidents or Maintenance updates will also be posted there with timely updates about the status and reason of the incident or maintenance.

Our status page can be found here:

Status Page