Back to top

Beeple Sourcing

This document describes the Beeple API to interact with sourcing systems. The general flow is that Beeple sends a sourcing request. Once the sourcing systems has found a viable candidate they submit the info about the candidate back (a candidacy). It is assumed this candidate applied for the job. The candidates show up in Beeple, and the planner has a possibility to accept or reject the candidate for this job (which will be communicated back to the sourcing API).

Idempotency and authentication.

This is similar as to our other APIs; so we need to figure out a general location

Sourcing Requests

Sourcing Requests

Create a sourcing request
POST/sourcing

Example URI

POST /sourcing
Request
HideShow
Headers
Content-Type: application/json
Authentication-Reference: AAAA-BBBB-CCCC
Authentication-Epoch: 1493226007
Authentication-Signature: 051afb5d034f4a29db36d384ddc24f5a406dc0e787a761d6693b4c9348ed206071e18dc6c1854688cc7121152068f3787d6dffcda433dce312e8a5814c6b652f
Body
{
  "tenant_id": "example.beeple-client.com",
  "job_descriptions": [
    {
      "language": "nl",
      "job_description": {
        "team_name": "Project Name / Team Name",
        "short_description": "Bartender in some fancy bar",
        "long_description": "Bartender in some fancy bar, and more explanation",
        "function_name": "Bartender",
        "function_description": "Tending a bar"
      }
    }
  ],
  "request_id": "unique-string",
  "number_needed": 1,
  "work_address": {
    "street1": "Main Street 700",
    "street2": "Box 1",
    "zip": "10250",
    "city": "Newtown",
    "administrative_area_level_1": "Hello, world!",
    "administrative_area_level_2": "Hello, world!",
    "administrative_area_level_3": "Hello, world!",
    "administrative_area_level_4": "Hello, world!",
    "administrative_area_level_5": "Hello, world!",
    "country": "US",
    "geo": {
      "lat": "35.123",
      "lng": "15.12"
    }
  },
  "shifts": [
    {
      "start_datetime": "2017-07-05T15:30Z",
      "end_datetime": "2017-07-05T21:30Z",
      "break_duration": "00:30"
    }
  ],
  "profile_requests": [
    {
      "id": "785",
      "required_value_numeric_min": 5,
      "required_value_numeric_max": 15,
      "required_value_date_min": "2017-07-05",
      "required_value_date_max": "2017-07-12",
      "required_value_time_min": "00:30",
      "required_value_time_max": "02:00",
      "required_value_boolean": true,
      "required_value_list_option": [
        "Hello, world!",
        "English"
      ],
      "required_valie_list_option_all `true`": true,
      "mandatory": true
    }
  ],
  "contract_details": [
    {
      "contract_type": "volunteer",
      "total_compensation": 320.15,
      "total_compensation_in_text": "According to wage scale xyz"
    }
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "tenant_id": {
      "type": "string",
      "description": "A unique ID for the tenant i.e. his domain name"
    },
    "job_descriptions": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "language": {
            "type": "string",
            "description": "Language of the following job description according to ISO 639-1"
          },
          "job_description": {
            "type": "object",
            "properties": {
              "team_name": {
                "type": "string",
                "description": "The full team name"
              },
              "short_description": {
                "type": "string",
                "description": "A limited job description"
              },
              "long_description": {
                "type": "string",
                "description": "An extended job description"
              },
              "function_name": {
                "type": "string",
                "description": "A short function name"
              },
              "function_description": {
                "type": "string",
                "description": "A longer function description"
              }
            }
          }
        }
      }
    },
    "request_id": {
      "type": "string",
      "description": "A unique ID for the request, can be alphanumerical"
    },
    "number_needed": {
      "type": "number",
      "description": "The number of collaborators needed"
    },
    "work_address": {
      "type": "object",
      "properties": {
        "street1": {
          "type": "string",
          "description": "Street + house number"
        },
        "street2": {
          "type": "string",
          "description": "Extension of street1"
        },
        "zip": {
          "type": "string"
        },
        "city": {
          "type": "string"
        },
        "administrative_area_level_1": {
          "type": "string",
          "description": "An extra administrative level, depends per country / tenant what this means"
        },
        "administrative_area_level_2": {
          "type": "string",
          "description": "An extra administrative level, depends per country / tenant what this means"
        },
        "administrative_area_level_3": {
          "type": "string",
          "description": "An extra administrative level, depends per country / tenant what this means"
        },
        "administrative_area_level_4": {
          "type": "string",
          "description": "An extra administrative level, depends per country / tenant what this means"
        },
        "administrative_area_level_5": {
          "type": "string",
          "description": "An extra administrative level, depends per country / tenant what this means"
        },
        "country": {
          "type": "string",
          "description": "According to ISO 3166-1 alpha-2"
        },
        "geo": {
          "type": "object",
          "properties": {
            "lat": {
              "type": "string",
              "description": "Latitude of address"
            },
            "lng": {
              "type": "string",
              "description": "Longitude of address"
            }
          },
          "description": "Exact GPS location of address"
        }
      },
      "description": "The address the work takes place"
    },
    "shifts": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "start_datetime": {
            "type": "string",
            "description": "When the shift starts according RFC 3339."
          },
          "end_datetime": {
            "type": "string",
            "description": "When the shift stops according RFC 3339."
          },
          "break_duration": {
            "type": "string",
            "description": "Total planned break duration in HH:MM."
          }
        }
      },
      "description": "The shifts a collaborator has to work"
    },
    "profile_requests": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "The ID of the profile request"
          },
          "required_value_numeric_min": {
            "type": "number",
            "description": "The mimimum value required for numeric profile types"
          },
          "required_value_numeric_max": {
            "type": "number",
            "description": "The maximum value required for numeric profile types"
          },
          "required_value_date_min": {
            "type": "string",
            "description": "The mimimum value required for date/datetime profile types according RFC 3339."
          },
          "required_value_date_max": {
            "type": "string",
            "description": "The maximum value required for date/datetime profile types according RFC 3339."
          },
          "required_value_time_min": {
            "type": "string",
            "description": "The mimimum value required for time profile types in HH:MM format."
          },
          "required_value_time_max": {
            "type": "string",
            "description": "The maximum value required for time profile types in HH:MM format."
          },
          "required_value_boolean": {
            "type": "boolean",
            "description": "If a boolean value should match or not match"
          },
          "required_value_list_option": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "List of allowed options for single and multi choice profile types"
          },
          "required_valie_list_option_all `true`": {
            "type": "boolean",
            "description": "For multi choice profile types whether the list options are all required (true), or at least one (false)"
          },
          "mandatory": {
            "type": "boolean",
            "description": "If the profile request is required or rather a suggestion"
          }
        }
      },
      "description": "List of profile requests"
    },
    "contract_details": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "contract_type": {
            "type": "string",
            "description": "The type of contract"
          },
          "total_compensation": {
            "type": "number",
            "description": "The total compensation in the currency of the tenant"
          },
          "total_compensation_in_text": {
            "type": "string",
            "description": "Compensation in textual format"
          }
        }
      },
      "description": "List of potential contract details"
    }
  }
}
Response  200
HideShow
Headers
Content-Type: application/json

Candidacies

Candidacy

Create a candidacy
POST/candidacy

A candidacy is a candidate for a given job.

Example URI

POST /candidacy
Request
HideShow
Headers
Content-Type: application/json
Authentication-Reference: AAAA-BBBB-CCCC
Authentication-Epoch: 1493226007
Authentication-Signature: 051afb5d034f4a29db36d384ddc24f5a406dc0e787a761d6693b4c9348ed206071e18dc6c1854688cc7121152068f3787d6dffcda433dce312e8a5814c6b652f
Body
{
  "id": "something",
  "candidate_id": "something-unique",
  "sourcing_request_id": "something",
  "first_name": "John",
  "last_name": "Doe",
  "birth_date": "1970-01-01",
  "email": "example@example.org"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "ID of the candidacy. Should be a link between the candidate and the sourcing request"
    },
    "candidate_id": {
      "type": "string",
      "description": "ID of the candidate in the sourcing system"
    },
    "sourcing_request_id": {
      "type": "string",
      "description": "Unique Beeple request ID"
    },
    "first_name": {
      "type": "string",
      "description": "First name of the candidate"
    },
    "last_name": {
      "type": "string",
      "description": "Last name of the candidate"
    },
    "birth_date": {
      "type": "string",
      "description": "Birth date of the candidate according to RFC 3339"
    },
    "email": {
      "type": "string",
      "description": "Email address of the candidate"
    }
  }
}
Response  200
HideShow
Headers
Content-Type: application/json

Reply to candidacy
PATCH/candidacy

This is a message from Beeple to the sourcing system to let the sourcing system know whether the planners have accepted or rejected the candidate for this job.

Example URI

PATCH /candidacy
Request
HideShow
Headers
Content-Type: application/json
Authentication-Reference: AAAA-BBBB-CCCC
Authentication-Epoch: 1493226007
Authentication-Signature: 051afb5d034f4a29db36d384ddc24f5a406dc0e787a761d6693b4c9348ed206071e18dc6c1854688cc7121152068f3787d6dffcda433dce312e8a5814c6b652f
Body
{
  "id": "something",
  "accepted": true,
  "reason_denied": "Some reason"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "ID of the candidacy"
    },
    "accepted": {
      "type": "boolean",
      "description": "Whether the candidacy is accepted yes or no"
    },
    "reason_denied": {
      "type": "string",
      "description": "Only provided when the candidacy is not accepted"
    }
  }
}
Response  200
HideShow
Headers
Content-Type: application/json

Generated by aglio on 04 Dec 2021