Push API and Webhooks

title push api and webhooks language tabs # must be one of https //git io/vqngj \ shell toc footers \ \<a href='mailto\ info\@jobylon com?subject=pushapi credentials'>email us to get your credentials\</a> \ \<a href='https //github com/lord/slate'>documentation powered by slate\</a> includes \ errors search true push api api for our integration partners, who want to push candidates and subscribers into jobylon model in jobylon every candidate can be represented by one or more applications, where every application relates to a job workflow the 3rd 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 3rd party if the 3rd 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" "kalle\@kula se", "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" "kello\@kalu se", "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", "answers" \[ { "question id" 1, "text" \[ "i am ready to start in the beggining of next month " ] }, { "question id" 2, "text" \[ "swedish", "english", "norwegian" ] }, ], "status id" 1 }' \# 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=kalle\@kula se" \\ 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 "cv=@cv pdf" \\ f "cover letter=@cover letter pdf" \\ f "other 1=@other 1 pdf" \\ f "other 2=@other 2 pdf" \\ f "other 3=@other 3 pdf" \\ f "other 4=@other 4 pdf" \\ f "other 5=@other 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) answers array array of answers to the job questions status id integer id of the application status answers object \[ { "question id" 1, "text" \[ "driver's license category b", "driver's license category d" ] } ] question id text id of the question list of answers to the question some questions support multiple choices 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 retrieve a push app can only retrieve applications that have been created by that push app applications created using another push app or who was created in jobylon using other means, will not be available get /applications/\<application id> query string parameters none response name type description status id integer status id exceptions status description 403 permission denied 404 application not found update a push app can only updated applications that have been created by that push app applications created using another push app or who was created in jobylon using other means, will not be possible to update put /applications/\<application id>/ patch /applications/\<application id>/ query string parameters none request payload status id is the only field that can be updated name type description status id integer status id response name type description status id integer status id exceptions status description 400 bad request the status id does not exist 403 permission denied 404 application not found 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' 'kalle\@kulla com', 'emails' \['kula\@kalle com', 'kalle\@kulla com'] }, { 'id' 2, 'role' 'owner', 'first name' 'kalle', 'last name' 'kula', 'email primary' 'kalle\@kulla com', 'emails' \['kula\@kalle com', 'kalle\@kulla com'] },{ 'id' 3, 'role' 'job owner', 'first name' 'kalle', 'last name' 'kula', 'email primary' 'kalle\@kulla com', 'emails' \['kula\@kalle com', 'kalle\@kulla com'] }, { 'id' 4, 'role' 'collaborator', 'first name' 'kalle', 'last name' 'kula', 'email primary' 'kalle\@kulla com', 'emails' \['kula\@kalle com', 'kalle\@kulla com'] }, { 'id' 5, 'role' 'viewer', 'first name' 'kalle', 'last name' 'kula', 'email primary' 'kalle\@kulla com', 'emails' \['kula\@kalle com', 'kalle\@kulla com'] }, { 'id' 6, 'role' 'application interviewer', 'first name' 'kalle', 'last name' 'kula', 'email primary' 'kalle\@kulla com', 'emails' \['kula\@kalle com', 'kalle\@kulla com'] } ] } 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' 'kalle\@kulla com', 'emails' \['kula\@kalle com', 'kalle\@kulla com'] }, { 'id' 2, 'role' 'owner', 'first name' 'kalle', 'last name' 'kula', 'email primary' 'kalle\@kulla com', 'emails' \['kula\@kalle com', 'kalle\@kulla com'] },{ 'id' 3, 'role' 'job owner', 'first name' 'kalle', 'last name' 'kula', 'email primary' 'kalle\@kulla com', 'emails' \['kula\@kalle com', 'kalle\@kulla com'] }, { 'id' 4, 'role' 'collaborator', 'first name' 'kalle', 'last name' 'kula', 'email primary' 'kalle\@kulla com', 'emails' \['kula\@kalle com', 'kalle\@kulla com'] }, { 'id' 5, 'role' 'viewer', 'first name' 'kalle', 'last name' 'kula', 'email primary' 'kalle\@kulla com', 'emails' \['kula\@kalle com', 'kalle\@kulla com'] }, { 'id' 6, 'role' 'job interviewer', 'first name' 'kalle', 'last name' 'kula', 'email primary' 'kalle\@kulla com', 'emails' \['kula\@kalle com', 'kalle\@kulla com'] } ] } 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' 'kalle\@kulla com', 'emails' \['kula\@kalle com', 'kalle\@kulla com'] }, { 'id' 2, 'role' 'owner', 'first name' 'kalle', 'last name' 'kula', 'email primary' 'kalle\@kulla com', 'emails' \['kula\@kalle com', 'kalle\@kulla com'] },{ 'id' 3, 'role' 'manager', 'first name' 'kalle', 'last name' 'kula', 'email primary' 'kalle\@kulla com', 'emails' \['kula\@kalle com', 'kalle\@kulla com'] }, { 'id' 4, 'role' 'member', 'first name' 'kalle', 'last name' 'kula', 'email primary' 'kalle\@kulla com', 'emails' \['kula\@kalle com', 'kalle\@kulla com'] }, ] } 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 integration 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 filtering you can control which webhooks you receive by applying filters that include or exclude events based on specific criteria for example, you might choose to receive webhooks only for jobs in a particular department, or exclude webhooks for applications belonging to a certain job the fields shown in the examples below can be used as filter parameters event types 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" "kalle\@kula se", "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" "application owner\@company com" }, "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" "manager\@company com", "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" "job owner\@company com" } "layers 1" \[ { "id" 1, "identifier" "first layer", "text" "first layer", } ], "layers 2" \[ { "id" 2, "identifier" "second layer", "text" "second layer", } ] } } } \# 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 push api and webhooks docid io2 sjeujv6vgtrtgyoz of the job location set array the push api and webhooks docid io2 sjeujv6vgtrtgyoz of the job categories array the push api and webhooks docid io2 sjeujv6vgtrtgyoz that this job belongs to departments array the push api and webhooks docid io2 sjeujv6vgtrtgyoz that this job belongs to layers x array the push api and webhooks docid io2 sjeujv6vgtrtgyoz that this job belongs to for each layer an layers x field is present see push api and webhooks docid io2 sjeujv6vgtrtgyoz (x is the dimension to which the layer options belong) status string the push api and webhooks docid io2 sjeujv6vgtrtgyoz value company object the push api and webhooks docid io2 sjeujv6vgtrtgyoz object owner object the push api and webhooks docid io2 sjeujv6vgtrtgyoz that owns the job employment type object the push api and webhooks docid io2 sjeujv6vgtrtgyoz object experience object the push api and webhooks docid io2 sjeujv6vgtrtgyoz object function object the push api and webhooks docid io2 sjeujv6vgtrtgyoz 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 layer name type description id integer layer id identifier string slug based on "text" text string layer name location name type description location string name of the location location json object object based on the data from google's map api recommended by 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 please ensure that the ab test parameter is less than 20 characters usecase example sequencediagram participant c as candidate participant w as web participant j as jobylon participant bi as bi c >>w follow link to site activate w note right of c session gets tagged\<br/> with a unique id \<br/> ex xyz123 w >>j follow link to jobylon deactivate w activate j note right of w link contains query\<br/> parameter ab test \<br/> ex ?ab test=xyz123 j >>j candiate applies to job alt bi db access note right of j nightly export to\<br/> dedicated database\<br/> hosted by jobylon\<br/> and accessed by\<br/> bi tool else csv export note right of j manual exported by\<br/> jobylon support\<br/> imported into bi\<br/> by client else webhooks j >>bi applicationevent\ created activate bi note right of j all application data\<br/> inc id, ab test bi >>bi process data and connect\<br/> to other data sources bi >>j deactivate bi deactivate j loop status changed activate j j >>bi applicationevent\ status changed activate bi note right of j all application data\<br/> inc id, ab test bi >>bi process data and add\<br/> status changes bi >>j deactivate bi deactivate j end end