NAV Navbar
shell

Push API

API for our integration partners, who want to push candidates into Jobylon.

Model

In Jobylon every candidate can be represented by one or more applications, where every application relates to a job.

Workflow

The 3:rd party app registers with Jobylon and gets one or more sets of credentials plus one or more feeds, that contains the promotions or jobs for one or more companies. The app uses the credentials and a job_id (found in the feed) to push new applications to Jobylon.

The type of feed (promotion or job) depends on the type of data required by the app and how our clients' contract work with the 3:rd party. If the 3:rd party do not require any extra information (such as purchase information) a simple job feed will be provided, otherwise a promotion feed will be provided. The promotion feed wraps a job and contains extra information.

Application

To run the examples:

export HOST='https://staging.jobylon.com'
export API_VERSION='p1'
export APP_ID='0123456789123456'
export APP_KEY='AbC123XyZ'

Basic example:

# Request
curl -i \
    -X POST "$HOST/$API_VERSION/applications/" \
    -H "X-App-Id: $APP_ID" \
    -H "X-App-Key: $APP_KEY" \
    -H "Content-Type: application/json" \
    -d '{
        "job_id": 123456789,
        "first_name": "Kalle",
        "last_name": "Kula",
        "email": "[email protected]",
        "phone": "+4670-123456789",
        "ln_url": "https://www.linkedin.com/in/kalle-kula-123a4567",
        "cv_url": "https://www.w3.org/WAI/ER/tests/xhtml/testfiles/resources/pdf/dummy.pdf",
        "message": "Message from the applicant...",
        "source_type": "applied",
        "source_json": {
            "partner_name": "best-source",
            "message": "Some other message...",
            "referrer": {
                "name": "Kella Kalu",
                "email": "[email protected]",
                "phone": "+46123456789",
                "avatar": "https://gravatar.com/avatar/ce757a5d51e6285434134e7b6c96ab86?s=200&d=robohash&r=g"
            }
            "questions": [
                {
                    "order": 1,
                    "question": "Why should we hire the person?",
                    "question_type": "text",
                    "answer": "Because she is great!"
                }, {
                    "order": 2,
                    "question": "Rank the skills",
                    "question_type": "range",
                    "question_args": {
                        "min": 1,
                        "max": 5,
                        "step": 1,
                        "unit": "star"
                    },
                    "answer": 4
                }, {
                    "order": 3,
                    "question": "Where can they be located?",
                    "question_type": "select-multiple",
                    "question_alternatives": [
                        "Avesta",
                        "London",
                        "Moskva",
                        "New York",
                        "Paris",
                        "Stockholm"
                    ],
                    "answer": [
                        "London",
                        "New York",
                        "Paris",
                        "Stockholm"
                    ]
                }, {
                  "order": 4,
                  "question": "Do they have a EU work permit?",
                  "question_type": "select-one",
                  "answer": "yes"
                }
            ]
        }
        "original_referrer": "https://bestreferrals.com/?utm_source=google&utm_medium=cpc&utm_term=earn_referrals",
        "ab_test": 'ABTestId'
    }'
# Response
Status Code: 201 Created
Content-Type: application/json

{'id': 123}

Example using a local JSON file


# Request
curl -i \
    -X POST "$HOST/$API_VERSION/applications/" \
    -H "X-App-Id: $APP_ID" \
    -H "X-App-Key: $APP_KEY" \
    -H "Content-Type: application/json"
    -d @<PATH-TO-FILE>

Example with files attached (multipart/form-data):


# Request
curl -i \
    -X POST "$HOST/$API_VERSION/applications/" \
    -H "X-App-Id: $APP_ID" \
    -H "X-App-Key: $APP_KEY" \
    -F "job_id=55" \
    -F "first_name=Kalle" \
    -F "last_name=Kula" \
    -F "[email protected]" \
    -F "phone=+4670-123456789" \
    -F "message=Message from the applicant..." \
    -F "source_type=applied" \
    -F "source_json={
        \"partner_name\": \"best-source\",
        \"message\": \"Some other message...\"
    }" \
    -F "[email protected]" \
    -F "[email protected]_letter.pdf" \
    -F "[email protected]_1.pdf" \
    -F "[email protected]_2.pdf" \
    -F "[email protected]_3.pdf" \
    -F "[email protected]_4.pdf" \
    -F "[email protected]_5.pdf"

Create

POST /applications/

Query String Parameters

None

Request Payload

Name Type Mandatory? Description
job_id integer yes Applicant first name
first_name string yes Applicant first name
last_name string yes Applicant last name
email string Applicant email
phone string Applicant phone
ln_url URL Applicant LinkedIn URL (will be validated)
message string Message from the applicant
source_type string yes Source type (applied/applied-silent/recommended/sourced). If set to applied, a thank-you email will be sent to the applicant.
source_json object yes Additional source data (partner dependent, but using the data from the example will be nicely styled in Jobylon.
cv file Application file (supported using multipart/form-data)
cv_url URL URL to the file to be downloaded and assigned to the field
cover_letter file Application file (supported using multipart/form-data)
cover_letter_url URL URL to the file to be downloaded and assigned to the field
other_1 file Application file (supported using multipart/form-data)
other_1_url URL URL to the file to be downloaded and assigned to the field
other_2 file Application file (supported using multipart/form-data)
other_2_url URL URL to the file to be downloaded and assigned to the field
other_3 file Application file (supported using multipart/form-data)
other_3_url URL URL to the file to be downloaded and assigned to the field
other_4 file Application file (supported using multipart/form-data)
other_4_url URL URL to the file to be downloaded and assigned to the field
other_5 file Application file (supported using multipart/form-data)
other_5_url URL URL to the file to be downloaded and assigned to the field
ab_test string A unique identifier used for A/B testing
original_referrer string Value used to keep track on the application origin (used in analytics)

Response

Name Type Description
id integer Application ID

Exceptions

Status Description
400 Bad request, job_id that app doesn't have access to.
403 Permission denied
405 Method not supported

ApplicationUser

Basic example:

# Request
curl -i \
    -X GET "$HOST/$API_VERSION/applications/1/users/XXX/" \
    -H "Content-Type: application/json"
# Response
Status Code: 200 Ok
Content-Type: application/json

{
  'count': 6,
  'next': '$HOST/$API_VERSION/applications/1/users/XXX/?page=4',
  'previous': '$HOST/$API_VERSION/applications/1/users/XXX/?page=2',
  'results': [
    {
      'id': 1,
      'role': 'admin',
      'first_name': 'Kalle',
      'last_name': 'Kula',
      'email_primary': '[email protected]',
      'emails': ['[email protected]', '[email protected]']
    },
    {
      'id': 2,
      'role': 'owner',
      'first_name': 'Kalle',
      'last_name': 'Kula',
      'email_primary': '[email protected]',
      'emails': ['[email protected]', '[email protected]']
    },{
      'id': 3,
      'role': 'job_owner',
      'first_name': 'Kalle',
      'last_name': 'Kula',
      'email_primary': '[email protected]',
      'emails': ['[email protected]', '[email protected]']
    },
    {
      'id': 4,
      'role': 'collaborator',
      'first_name': 'Kalle',
      'last_name': 'Kula',
      'email_primary': '[email protected]',
      'emails': ['[email protected]', '[email protected]']
    },
    {
      'id': 5,
      'role': 'viewer',
      'first_name': 'Kalle',
      'last_name': 'Kula',
      'email_primary': '[email protected]',
      'emails': ['[email protected]', '[email protected]']
    },
    {
      'id': 6,
      'role': 'application_interviewer',
      'first_name': 'Kalle',
      'last_name': 'Kula',
      'email_primary': '[email protected]',
      'emails': ['[email protected]', '[email protected]']
    }
  ]
}

List

GET /applications/<application_pk>/users/<sign_hash>

Query String Parameters

Name Type Mandatory? Description
roles string no Roles that can be use to filter users

Response

Name Type Description
count integer Total number of results
next string (URL) Link to the next page
previous string (URL) Link to the previous page
results array Collection of users that have access to the application

Exceptions

Status Description
403 Permission denied
405 Method not supported

JobUser

Basic example:

# Request
curl -i \
    -X GET "$HOST/$API_VERSION/jobs/1/users/XXX/" \
    -H "Content-Type: application/json"
# Response
Status Code: 200 Ok
Content-Type: application/json

{
  'count': 6,
  'next': '$HOST/$API_VERSION/jobs/1/users/XXX/?page=4',
  'previous': '$HOST/$API_VERSION/jobs/1/users/eXXX/?page=2',
  'results': [
    {
      'id': 1,
      'role': 'admin',
      'first_name': 'Kalle',
      'last_name': 'Kula',
      'email_primary': '[email protected]',
      'emails': ['[email protected]', '[email protected]']
    },
    {
      'id': 2,
      'role': 'owner',
      'first_name': 'Kalle',
      'last_name': 'Kula',
      'email_primary': '[email protected]',
      'emails': ['[email protected]', '[email protected]']
    },{
      'id': 3,
      'role': 'job_owner',
      'first_name': 'Kalle',
      'last_name': 'Kula',
      'email_primary': '[email protected]',
      'emails': ['[email protected]', '[email protected]']
    },
    {
      'id': 4,
      'role': 'collaborator',
      'first_name': 'Kalle',
      'last_name': 'Kula',
      'email_primary': '[email protected]',
      'emails': ['[email protected]', '[email protected]']
    },
    {
      'id': 5,
      'role': 'viewer',
      'first_name': 'Kalle',
      'last_name': 'Kula',
      'email_primary': '[email protected]',
      'emails': ['[email protected]', '[email protected]']
    },
    {
      'id': 6,
      'role': 'job_interviewer',
      'first_name': 'Kalle',
      'last_name': 'Kula',
      'email_primary': '[email protected]',
      'emails': ['[email protected]', '[email protected]']
    }
  ]
}

List

GET /jobs/<job_pk>/users/<sign_hash>

Query String Parameters

Name Type Mandatory? Description
roles string no Roles that can be use to filter the users

Response

Name Type Description
count integer Total number of results
next string (URL) Link to the next page
previous string (URL) Link to the previous page
results array Collection of users that have access to the job

Exceptions

Status Description
403 Permission denied
405 Method not supported

CompanyUser

Basic example:

# Request
curl -i \
    -X GET "$HOST/$API_VERSION/companies/1/users/XXX/" \
    -H "Content-Type: application/json"
# Response
Status Code: 200 Ok
Content-Type: application/json

{
  'count': 4,
  'next': '$HOST/$API_VERSION/companies/1/users/XXX/?page=4',
  'previous': '$HOST/$API_VERSION/companies/1/users/XXX/?page=2',
  'results': [
    {
      'id': 1,
      'role': 'admin',
      'first_name': 'Kalle',
      'last_name': 'Kula',
      'email_primary': '[email protected]',
      'emails': ['[email protected]', '[email protected]']
    },
    {
      'id': 2,
      'role': 'owner',
      'first_name': 'Kalle',
      'last_name': 'Kula',
      'email_primary': '[email protected]',
      'emails': ['[email protected]', '[email protected]']
    },{
      'id': 3,
      'role': 'manager',
      'first_name': 'Kalle',
      'last_name': 'Kula',
      'email_primary': '[email protected]',
      'emails': ['[email protected]', '[email protected]']
    },
    {
      'id': 4,
      'role': 'member',
      'first_name': 'Kalle',
      'last_name': 'Kula',
      'email_primary': '[email protected]',
      'emails': ['[email protected]', '[email protected]']
    },
  ]
}

List

GET /companies/<company_pk>/users/<sign_hash>

Query String Parameters

Name Type Mandatory? Description
roles string no Roles that can be use to filter the users

Response

Name Type Description
count integer Total number of results
next string (URL) Link to the next page
previous string (URL) Link to the previous page
results array Collection of company's users

Exceptions

Status Description
403 Permission denied
405 Method not supported

Webhooks

Callback API for our intergration partners who want to receive and act upon different Jobylon events.

Model

In Jobylon every webhook has a client url and an event type that it is subscribed to.

Workflow

After the third-party party app registers with Jobylon; they can request webhook intergration by providing a url and the type of events it should subscribe to. The webhook will use these details to send notifications when an event occurs.

When the event is sent to the url the webhook expects a successful response (HTTP 2XX). In the case it does not receive a valid response, it will retry again immediately and then after 30 seconds, 300 seconds (5 minutes), 3000 seconds (50 minutes), 30000 seconds (~8.3 hours) and 300000 seconds (~3 days and 12 hours).

Headers

You can request us to provide you with custom headers if you so choose.

Authentication

You can request us to provide basic authentication by providing a username and password of your choosing.

Limit IP

You can limit the IPs that the callback comes from by letting us know.

Event Types

i. Application Event ii. Job Event

ApplicationEvent

Example:

# Note this example is for an application event
# Request
Request Method: POST
Content-Type: application/json

{
  "event_type": "application",
  "action": "status_changed",
  "application": {
    "id": 1,
    "first_name": "Kalle",
    "last_name": "Kula",
    "email": "[email protected]",
    "phone_number": "+4670123456789",
    "url": "https://staging.jobylon.com/application/1/",
    "source_type": "applied",
    "status": {
      "id": 2,
      "name": "In Progress",
      "group": 1
    },
    "owner": {
      "id": 1,
      "name": "Application Owner",
      "email": "[email protected]"
    },
    "recommended_by": null,
    "rejection_sent": false,
    "ab_test": "ab-test-1",
    "users_url": "https://staging.jobylon.com/p1/applications/1/users/XXX/",
    "job": {
      "id": 1,
      "title": "Some title",
      "from_date": "2018-01-01T00:00:00.001Z",
      "to_date": null,
      "status": 1,
      "contact_name": "Manager's Name",
      "contact_email": "[email protected]",
      "users_url": "https://staging.jobylon.com/p1/jobs/1/users/XXX/",
      "employment_type": {
        "id": 1,
        "text": "Full-time"
      },
      "experience": {
        "id": 1,
        "text": "Entry level"
      },
      "function": {
        "id": 1,
        "text": "IT & Infrastructure"
      },
      "language": "sv",
      "location_set": [
        {
          "location": "Stockholm",
          "location_json": {
            "country_short": "SE",
            "city": "Stockholm",
            "url": "https://maps.google.com/?q=Stockholm,+Sweden&ftid=0x465f763119640bcb:0xa80d27d3679d7766",
            "country": "Sweden",
            "place_id": "ChIJywtkGTF2X0YRZnedZ9MnDag",
            "area_1_short": "Stockholm County",
            "area_1": "Stockholm County",
            "city_short": "Stockholm"
          }
        }
      ],
      "categories": [
        {
          "id": 1,
          "text": "Technology"
        }
      ],
      "departments": [
        {
          "id": 1,
          "text": "IT"
        }
      ],
      "company": {
        "id": 1,
        "name": "Some Company",
        "users_url": "https://staging.jobylon.com/p1/companies/1/users/XXX/"
      },
      "owner": {
        "id": 2,
        "name": "Job Owner",
        "email": "[email protected]"
      }
    }
  }
}
# Response
Status Code: 2XX

Actions

Name Description
created Application created
rejection_sent Rejection communicated/sent to applicant
status_changed Application status updated

Request Payload

Name Type Description
event_type string "application"
action string Action triggering the event (see above)
application object The application object

JobEvent

Actions

Name Description
created Job created
updated Job was updated
status_changed Job status was specifically updated

Request Payload

Name Type Description
event_type string "job"
action string Action triggering the event (see above)
job object The job object

Application

Name Type Description
id integer Application ID
first_name string First name
last_name string Last name
email string Email
phone_number string Phone number
url string (URL) Deep link to the application in Jobylon
recommended_by object The recommended_by object
rejection_sent boolean Info regarding if the rejection has been communicated to the applicant or not
status object The status object
source_type string The source where the application was received
job object The job object
owner object The user that owns the application
ab_test string A unique identifier used for A/B testing
users_url string (URL) Time-limited link to an list of users that have access to the application and their roles

Source Type

Value Description
'applied' Applied (thank-you email sent by Jobylon)
'applied-silent' Applied through partner (thank-you email possibly sent by partner)
'imported' Imported
'recommended' Recommended
'sourced' Sourced
'uploaded' Uploaded

Status

Name Type Description
id integer Status ID
name string Status name
group integer The status group value

Status Group

Value Description
0 New
1 In progress
19 Rejected
20 Hired
21 On hold

Job

Name Type Description
id integer Job ID
title string Title of the job
from_date string (date-time UTC) Datetime job first created
to_date string (date-time UTC) Deadline for the job
contact_name string Contact name
contact_email string Contact email
language string The language of the job
location_set array The location(s) of the job
categories array The categories that this job belongs to
departments array The departments that this job belongs to
status string The job status value
company object The company object
owner object The user that owns the job
employment_type object The employment type object
experience object The experience object
function object The function object
users_url string (URL) Time-limited link to an list of users that have access to the job and their roles

Job Status

Value Description
'draft' Draft
'published' Published
'closed' Closed
'archived' Archived

Category

Name Type Description
id integer Category ID
text string Category description

Company

Name Type Description
id integer Company ID
name string Name
users_url string (URL) Time-limited link to an list of users that have access to the job and their roles

Department

Name Type Description
id integer Department ID
name string Department name

Experience

Name Type Description
id integer Experience ID
text string Experience description

Employment Type

Name Type Description
id integer EmploymentType ID
text string EmploymentType description

Function

Name Type Description
id integer Function ID
text string Function description

Language

Value Description
'da' Dansk
'de' Deutsch
'en' English
'fi' Suomi
'fr' Fran├žais
'nb' Norsk
'nl' Nederlands
'sv' Svenska

Location

Name Type Description
location string name of the location
location_json object object based on the data from Google's map API
Name Type Description
name string Name
email string Email

User

Name Type Description
id integer User ID
name string Name
email string Email

UserRole

Name Type Description
id integer User ID
first_name string First name
last_name string Last name
role string User role
email_primary string Email
emails array Email

A/B Testing

A/B testing for customers who want to try different application flows

Roles

UserRole object can return one of this roles depending on what object/event (job/application) was called.

Name Description
owner Owner of the company
admin Administrator of the company
manager Manager of the company
member Member of the company
collaborator Collaborator on the job
viewer Viewer of the job
job_owner Owner of the job
job_interviewer Interviewer on the job
application_interviewer Interviewer of the application

Through Jobylon

You can pass the name of the A/B test as a query parameter on the Jobylon URL. The query parameter should be called jbl_ab_test. We will store it in the browser session storage for 30 minutes or until the session expires, whichever is shorter. In other words, it will be stored for a maximum of 30 minutes. If a new A/B testing query parameter is found on the URL, the existing one will be overridden and the timeout will be reset to 30 minutes. As long as the user ends up on the application form within 30 minutes, the A/B testing query parameter value will be stored with the application. A ab_test parameter is added to the application data sent to your webhook.

Through the Push API

Just add the ab_test parameter when pushing to Jobylon and the data will be stored in Jobylon.

Usecase example

Eyjjb2rlijoic2vxdwvuy2veawfncmftxg4gicagcgfydgljaxbhbnqgqybhcybdyw5kawrhdgvcbiagicbwyxj0awnpcgfudcbxigfzifdlylxuicagihbhcnrpy2lwyw50ieogyxmgsm9iewxvblxuicagihbhcnrpy2lwyw50iejjigfziejjxg4gicagqy0 plc6iezvbgxvdybsaw5rihrvihnpdgvcbiagicbhy3rpdmf0zsbxxg4gicagtm90zsbyawdodcbvzibdoibtzxnzaw9uigdldhmgdgfnz2vkpgjylz4gd2l0acbhihvuaxf1zsbpzc48ynivpibfedogwflamtizxg4gicagvy0 pko6iezvbgxvdybsaw5rihrviepvynlsb25cbiagicbkzwfjdgl2yxrlifdcbiagicbhy3rpdmf0zsbkxg4gicagtm90zsbyawdodcbvzibxoibmaw5rignvbnrhaw5zihf1zxj5pgjylz4gcgfyyw1ldgvyigfix3rlc3qupgjylz4grxg6id9hyl90zxn0pvhzwjeymyagxg4gicagsi0 pko6ienhbmrpyxrligfwcgxpzxmgdg8gam9ixg4gicagywx0iejjiercigfjy2vzc1xuicagicagicbob3rlihjpz2h0ig9mieo6ie5pz2h0bhkgzxhwb3j0ihrvpgjylz4gzgvkawnhdgvkigrhdgfiyxnlpgjylz4gag9zdgvkigj5iepvynlsb248ynivpibhbmqgywnjzxnzzwqgynk8ynivpibcssb0b29slibcbiagicblbhnlientviblehbvcnrcbiagicagicagtm90zsbyawdodcbvzibkoibnyw51ywwgzxhwb3j0zwqgynk8ynivpibkb2j5bg9uifn1chbvcnq8ynivpibpbxbvcnrlzcbpbnrviejjpgjylz4gynkgy2xpzw50llxuicagigvsc2ugv2viag9va3ncbiagicagicagsi0 pkjjoibbchbsawnhdglvbkv2zw50omnyzwf0zwrcbiagicagicagywn0axzhdgugqklcbiagicagicagtm90zsbyawdodcbvzibkoibbbgwgyxbwbgljyxrpb24gzgf0ytxici8 igluyy4gawqsigfix3rlc3quli5cbiagicagicagqkktpj5cstoguhjvy2vzcybkyxrhigfuzcbjb25uzwn0pgjylz4gdg8gb3rozxigzgf0ysbzb3vyy2vzxg4gicagicagiejjls0 pko6ifxuicagicagicbkzwfjdgl2yxrliejjxg4gicagicagigrlywn0axzhdgugslxuicagicagicbsb29wifn0yxr1cybjagfuz2vkxg4gicagicagicagicbhy3rpdmf0zsbkxg4gicagicagicagicbklt4 qkk6iefwcgxpy2f0aw9urxzlbnq6c3rhdhvzx2noyw5nzwrcbiagicagicagicagigfjdgl2yxrliejjxg4gicagicagicagicbob3rlihjpz2h0ig9mieo6iefsbcbhchbsawnhdglvbibkyxrhpgjylz4gaw5jlibpzcwgywjfdgvzdc4ullxuicagicagicagicagqkktpj5cstoguhjvy2vzcybkyxrhigfuzcbhzgq8ynivpibzdgf0dxmgy2hhbmdlc1xuicagicagicagicagqkktlt4 sjogxg4gicagicagicagicbkzwfjdgl2yxrliejjxg4gicagicagicagicbkzwfjdgl2yxrliepcbiagicagicagzw5kxg4gicagzw5kiiwibwvybwfpzci6eyj0agvtzsi6imrlzmf1bhqifx0

Errors

API uses the following error codes:

Error Code Meaning
400 Bad Request -- Your request is invalid.
401 Unauthorized -- Your API key is wrong.
403 Forbidden -- Permission denied
404 Not Found
405 Method Not Allowed -- You tried to access a endpoint with an invalid method.
406 Not Acceptable -- You requested a format that isn't json.
410 Gone
418 I'm a teapot.
429 Too Many Requests -- You've sent too many requests! Slow down!
500 Internal Server Error -- We had a problem with our server. Try again later.
503 Service Unavailable -- We're temporarily offline for maintenance. Please try again later.