How To

Get a User Access Token

Some API endpoints will require a User access token.

1. Go to Graph API Explorer tool.
2. Click the Application drop-down on the top right and select the Application that you will be using for the jobs integration. The default app is Graph API Explorer.
3. Click the Get Token drop-down and select Get User Access Token.
4. Copy the User access token from the input field. This token allows you to create the Recruiting Manager.

Note: The access token generated for this application is usually active for an hour. Verify your token using the Access Token Debugger.

Get Job Status

To retrieve the status of a job, send a GET request using the job_status and platform_review_status fields.

Sample Request

HttpRequest: GET
URL: https://graph.facebook.com/vX.X/${feed-id}/jobs?access_token=${app_id|secret}&fields=job_status,external_id,platform_review_status,id

Sample Response

{
  "data": [
    {
      "job_status": "DRAFT",
      "external_id": "111219491",
      "platform_review_status": "PENDING",
      "id": "2172866226275828"
    }
  ]
}    

Acceptance and review status does not refer to our Facebook page matching feature.

Get Company Insights

To retrieve the number of jobs from employers broken down their jobs_status and platform_review_status, send a GET request using the insights fields. You can filter by employers by setting the company_id filter as the company-id of that employer in your feed.

Sample Request

HttpRequest: GET
URL: https://graph.facebook.com/vX.X/${recruiting-manager-id}/employers?company_id={company-id}&access_token=${app_id|secret}&fields=insights

Sample Response

{
  "data": [
    {
      "external_company_id": "2432345",
      "insights":{
        "jobs_count":100,
        "jobs_status": {
          "open":90,
          "draft":10
        },
        "jobs_review_status":{
          "approved":70,
          "pending":10,
          "rejected":10
        }
      }
    }
  ]
}    

Acceptance and review status does not refer to our Facebook page matching feature.

Get Page Matching Status

To retrieve the page matching status for a company, send a GET request using the page_matching_info field.

Sample Request

HttpRequest: GET
URL: https://graph.facebook.com/vX.X/${recruiting-manager-id}/employers?company_id={company-id}&access_token=${app_id|secret}&fields=page_matching_info

Sample Response

{
  "data": [
    {
      "external_company_id": "2432345",
      "page_matching_info":{
        "page_matching_status":"CONNECTED",
        "page_url": "https://www.url-of-the-page-on-facebook"
      }
    }
  ]
}    

The page matching status is "CONNECTED", if the jobs for the employer have been successfully matched to a page on Facebook and the page admin has accepted the jobs. Otherwise, the page matching status is "DISCONNECTED".

View your published jobs

To view a published job go to www.facebook.com/{id}

GET XML Job Errors

If your Job status is DRAFT after the sync then it means there are issues with your XML file. To check the errors on a job you can use the following request

Sample Request

HttpRequest: GET
URL: https://graph.facebook.com/v3.0/${job_id}?access_token={app_id|secret}&fields=errors,external_id

Sample Response

{
    "errors": [
        "URL field company-url is invalid."
    ],
    "external_id": "31212",
    "id": "2172866226275828"
}

Application Callback Payload

When someone applies for a job on Facebook, Facebook Jobs Platform will immediately make an HTTP POST to the webhook configured in application-callback-url. The payload will be raw JSON data, not form-urlencoded.

Sample JSON payload

{
  "type": "new_application",
  "page_id": 789,
  "job_opening_id": 456,
  "job_application_id": 123,
  "job_external_id": 432
}

You can test your webhook by sending dummy data with a cURL command like the following:

curl --request POST --header 'Content-Type: application/json' --data \
    '{
        "type": "new_application",
        "page_id": 789,
        "job_opening_id": 456,
        "job_application_id": 123,
        "job_external_id": 432
    }' \
    "https://yourdomain.com/callback"    

Get Job Application details

To retrieve the job application details make a GET request with the job_application_id to fetch more information about the applicant.

Sample Request

An App access token is required.

GET /{job_application_id}?fields=name%2Cemail%2Ccity_name%2Ccreated_time%2Ccustom_responses%2Cresume_attachments%2Ceducation_experiences%7Bschool%2Carea_of_study%2Cstart%2Cend%2Cgraduated%7D%2Cwork_experiences%7Bcompany%2Cposition%2Ccurrent%2Cstart%2Cend%7D%2Cphone_number HTTP/1.1
Host: graph.facebook.com

/* PHP SDK v5.0.0 */
/* make the API call */
try {
  // Returns a `Facebook\FacebookResponse` object
  $response = $fb->get(
    '/{job_application_id}?fields=name%2Cemail%2Ccity_name%2Ccreated_time%2Ccustom_responses%2Cresume_attachments%2Ceducation_experiences%7Bschool%2Carea_of_study%2Cstart%2Cend%2Cgraduated%7D%2Cwork_experiences%7Bcompany%2Cposition%2Ccurrent%2Cstart%2Cend%7D%2Cphone_number',
    '{access-token}'
  );
} catch(Facebook\Exceptions\FacebookResponseException $e) {
  echo 'Graph returned an error: ' . $e->getMessage();
  exit;
} catch(Facebook\Exceptions\FacebookSDKException $e) {
  echo 'Facebook SDK returned an error: ' . $e->getMessage();
  exit;
}
$graphNode = $response->getGraphNode();
/* handle the result */

/* make the API call */
FB.api(
    "/{job_application_id}",
    {
        "fields": "name,email,city_name,created_time,custom_responses,resume_attachments,education_experiences{school,area_of_study,start,end,graduated},work_experiences{company,position,current,start,end},phone_number"
    },
    function (response) {
      if (response && !response.error) {
        /* handle the result */
      }
    }
);

curl -X GET -G \
  -d 'fields="name,email,city_name,created_time,custom_responses,resume_attachments,education_experiences{school,area_of_study,start,end,graduated},work_experiences{company,position,current,start,end},phone_number"' \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/{job_application_id}

Sample Response

{
  "name": "First Last",
  "email": "first_last@example.com",
  "city_name": "San Francisco, California",
  "custom_responses": [
    {
      "label": "Do you have experience within the sales area?",
      "response": "Yes",
      "external_id": "abcdef"
    },
    {
      "label": "Why are you qualified for this job?",
      "response": "No comment",
      "external_id": "12345"
    },
    {
      "label": "Which of the following skills do you have?",
      "response": "[\"Sales\", \"First Aid\"]",
      "external_id": "c0fa8584-1ac4-4d2d-a964-0f3f3f7ee333"
    }
  ],
  "education_experiences": {
    "data": [
      {
        "school": "University at Somewhere",
        "area_of_study": "Computer Science",
        "start": {
          "year": 2014
        },
        "end": {
          "year": 2016
        },
        "graduated": false
      },
      {
        "school": "University of Anotherwhere",
        "area_of_study": "Computer Science and Engineering",
        "start": {
          "year": 2010
        },
        "end": {
          "year": 2014
        },
        "graduated": false
      },
      {
        "school": "University of anywhere",
        "area_of_study": "General Coursework",
        "start": {
          "year": 2007
        },
        "end": {
          "year": 2010
        },
        "graduated": false
      }
    ]
  },
  "work_experiences": {
    "data": [
      {
        "company": "One company",
        "position": "Software Engineer",
        "current": true,
        "start": {
          "year": 2017,
          "month": 3
        }
      },
      {
        "company": "Another company",
        "position": "Internship",
        "current": false,
        "start": {
          "year": 2016
        },
        "end": {
          "year": 2016
        }
      }
    ]
  },
  "resume_attachments": [
    {
      "source": "https://lookaside.fbsbx.com/jobsearch/resume_attachment/?resume_id=91551262560935&user_id=100006621977374&app_id=306826663093202&ext=1587423303&hash=ATBq7Vn4dIIqaiUrfoNKzxEs0HWU6yB77D3i8v9oKNeQLs0S",
      "type": "PDF"
    },
    {
      "source": "https://lookaside.fbsbx.com/jobsearch/resume_attachment/?resume_id=91551262560935&user_id=100006621977374&app_id=306826663093202&ext=1587423303&hash=0F3F877836B90505EB008DA0841822C67762FB40",
      "type": "PNG"
    }    
  }
  "phone_number": "+15550152435",
  "id": "83944172955xxxx",
}

Job Application Fields

{
"source": "https://lookaside.fbsbx.com/jobsearch/resume_attachment/?resume_id=91551262560665&user_id=100006621977374&app_id=306824663093202&ext=1587423303&hash=ATBq7Vn4dIIqaiUrfoNKzxEs0HyU6yB77D3i8v9oKNeQLs0S",
"type": "PDF"
}

{
"label": "Foobar certified",
"response": "Yes",
"external_id": "12345"
}      

Add Custom/Screening Questions

You can set custom questions during job creation. There are four available questions types, FREE_TEXT, YES_NO, MULTIPLE_CHOICE, and MULTIPLE_SELECT. If the custom-questions-url attribute is set in the XML feed, we call this endpoint to fetch the questions you define in the JSON format mentioned below.

You can also include an optional external_id field which will be returned with answers. See Job Application Details for how user responses can be retrieved.

FREE_TEXT Custom Question Example

This field will return the user's input, up to a maximum of 500 characters.

[
  {
    "is_required": true,
    "question_type": "FREE_TEXT",
    "label": "Why are you qualified for this job?",
    "multiple_choice_options": [],
    "external_id": "12345"
  }
]

YES_NO Custom Question Example

The field will return a string containing either "Yes" or "No".

[
  {
    "is_required": false,
    "question_type": "YES_NO",
    "label": "Do you have experience within the sales area?",
    "multiple_choice_options": [],
    "external_id": "abcdef"
  }
]

MULTIPLE_CHOICE Custom Question Example

User may select a single choice from the options provided.

[
  {
    "is_required": true,
    "question_type": "MULTIPLE_CHOICE",
    "label": "What is the highest level of education you have completed?",
    "multiple_choice_options": [
       "Doctorate",
       "Masters or Professional Degree",
       "University",
       "High School",
       "Grade School",
       "Other"
    ],
    "external_id": "c0fa8584-1ac4-4d2d-a964-0f3f3f7ee334"
  }
]

MULTIPLE_SELECT Custom Question Example

User may select any combination of the options provided. Selected options will be returned as a single string containing a JSON-encoded array. Example "[\"Sales\", \"First Aid\"]".

[
  {
    "is_required": false,
    "question_type": "MULTIPLE_SELECT",
    "label": "Which of the following skills do you have?",
    "multiple_choice_options": [
       "Sales",
       "Excel",
       "Public Speaking",
       "First Aid"
    ],
    "external_id": "c0fa8584-1ac4-4d2d-a964-0f3f3f7ee333"
  }
]

Set of Custom Questions Example

[
  {
    "is_required": true,
    "question_type": "FREE_TEXT",
    "label": "Why are you qualified regarding to the job?",
    "multiple_choice_options": []
  },
  {
    "is_required": false,
    "question_type": "YES_NO",
    "label": "Do you have experience within the sales area?",
    "multiple_choice_options": []
  },
  {
    "is_required": true,
    "question_type": "MULTIPLE_CHOICE",
    "label": "What is the highest level of education you have completed?",
    "multiple_choice_options": [
       "Doctorate",
       "Masters or Professional Degree",
       "University",
       "High School",
       "Grade School",
       "Other"
    ],
  },       
  {
    "is_required": true,
    "question_type": "MULTIPLE_SELECT",
    "label": "Which of the following skills do you have?",
    "multiple_choice_options": [
       "Sales",
       "Excel",
       "Public Speaking",
       "Pipe fitting"
    ]
  } 
]

Delete Jobs

In order to remove an individual job, simply remove it from the XML representation of that job from your feed. Upon the next scrape, that job will be removed from the Facebook platform. Note that deleting a job will also delete all corresponding job applications—ensure that you have received the new applications first!

Delete a Feed

Deleting a job feed will delete all of the corresponding jobs. You can delete a job feed via the API. Find more details on the job feed API here. Note that deleting a job will also delete all corresponding job applications—ensure that you have received the new applications first!

Common Errors

A few of our most common errors preventing jobs from being successfully posted on our platform are listed below, with some recommendations for debugging.

At this current time, we will not provide you any errors when a job to Facebook page match - note this will not prevent the job from being posted or distributed, even if it is not matched successfully to a page.

Although page match can fail for variety of reasons, one frequent and easily solvable issue involves the field "company-id". Our system only allows one company-id per Facebook page. If you have multiple different company-ids that are intended to match to the same page, only jobs associated with the first company-id will match, and the others will fail (even if you provide the correct Facebook page URL). The best practice is to ensure that company-id has a 1:1 relationship with each Facebook page.

EEOC and Compliance Questions

In order to ask applicants diversity related questions in order to comply with the US Equal Employment Opportunity Commission, you must add additional content to your Custom/Screening Questions. You do not need to make any changes to the XML feed itself, assuming your custom questions are set up properly. This is how the flow looks:

For legal reasons, we require the extra compliance questions you ask to match our text directly (if you modify this text, it will throw an error). You can copy the following text and add it to your custom questions in order for your jobs to display this extra flow. Responses to these questions can be retrieved normally. The custom questions JSON text to add is as follows:

{
   "label":"Self-Identifying gender",
   "is_required":false,
   "multiple_choice_options":[

   ],
   "question_type":"MULTIPLE_CHOICE",
   "purpose":"USA_DIVERSITY",
   "structured_multiple_choice_options":[
      {
         "text":"Male",
         "info":""
      },
      {
         "text":"Female",
         "info":""
      },
      {
         "text":"I do not wish to disclose.",
         "info":""
      }
   ]
},
{
   "label":"Self-Identifying race\/ethnicity",
   "is_required":false,
   "multiple_choice_options":[

   ],
   "question_type":"MULTIPLE_CHOICE",
   "purpose":"USA_DIVERSITY",
   "structured_multiple_choice_options":[
      {
         "text":"Hispanic or Latino",
         "info":"A person of Cuban, Mexican, Puerto Rican, South or Central American, or other Spanish culture or origin regardless of race."
      },
      {
         "text":"White (Not Hispanic or Latino)",
         "info":"A person having origins in any of the original peoples of Europe, the Middle East, or North Africa."
      },
      {
         "text":"Black or African American (Not Hispanic or Latino)",
         "info":"A person having origins in any of the black racial groups of Africa."
      },
      {
         "text":"Native Hawaiian or Pacific Islander (Not Hispanic or Latino)",
         "info":"A person having origins in any of the peoples of Hawaii, Guam, Samoa, or other Pacific Islands."
      },
      {
         "text":"Asian (Not Hispanic or Latino)",
         "info":"A person having origins in any of the original peoples of the Far East, Southeast Asia, or the Indian Subcontinent, including, for example, Cambodia, China, India, Japan, Korea, Malaysia, Pakistan, the Philippine Islands, Thailand, and Vietnam."
      },
      {
         "text":"Native American or Alaska Native (Not Hispanic or Latino)",
         "info":"A person having origins in any of the original peoples of North and South America (including Central America), and who maintain tribal affiliation or community attachment."
      },
      {
         "text":"Two or More Races (Not Hispanic or Latino)",
         "info":"All persons who identify with more than one of the above five races."
      },
      {
         "text":"I do not wish to disclose.",
         "info":""
      }
   ]
}
    

Learn More

• What are the Frequently Asked Questions?
• Check out the reference docs to view fields and parameters.