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"
    }
  ]
}    
jobs_statusplatform_review_statusCommentsJob visible?

DRAFT

PENDING

Not all input required to create a full-fledged job opening has been provided, and/or there were errors during creation.

No

OPEN

PENDING

Waiting in the Jobs Review Queue. All jobs go through an automated integrity review and many also go through human review. Pending jobs have not yet been reviewed, but all jobs are reviewed within 24-48 hours.

No

OPEN

REJECTED

The job has been rejected rejected due to not following our Jobs Policy: See Facebook Platform Policy, Jobs terms (section 23) and Facebook Pages Guidelines, Jobs on Pages (section F). The job will not be posted anywhere on the Facebook platform.

No

OPEN

APPROVED

Job is live and available at https://www.facebook.com/{job-id}

Yes

Note:

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
        }
      }
    }
  ]
}    
Note:

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"
      }
    }
  ]
}    
Note:

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.

Graph API Explorer
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

NameDescription

name

Type: string

The full name of the applicant.

Example: First Last

email

Type: string

The email address of the applicant.

Example: first_last@example.com

phone_number

Type: string

The phone number of the applicant.

Example: +15550152435

city_name

Type: string

The city of the applicant.

Example: San Francisco, California

created_time

Type: string

ISO 8601 timestamp when application was submitted.

Example: 2020-10-26T15:43:22+0000

resume_attachments

Type: object

Object containing resume information that was attached to the application via the resume-attachment-field, or automatically generated. This will be an array of objects containing these keys:
  • type : File type of the attachment. Will be one of: PDF, JPG, PNG, GIF, WEBP, PDF_AUTOGENERATED.
  • source : URL for the attachment.

PDF_AUTOGENERATED will be included only if an attached resume was not provided by the job applicant. This is a PDF file created by Facebook containing the applicant's information in a standard template.

Example:

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

custom_responses

Type: object

Object containing applicant's answers to custom questions.

Example:

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

education_experiences

Type: object

Object containing applicant's education experiences.

work_experiences

Type: object

Object containing applicant's work experiences.

id

Type: integer

The id of this job application.

Example: 678019899492984

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

MULTIPLE_SELECT is a new feature. These questions may not appear for the fraction of users who have not yet updated their app. We recommend not requiring questions of this type.

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.

Error MessageExplanationSuggested Actions

Your job's location is invalid.

Our geolocation service did not manage to determine the location of the job based on the data you provided us.

First of all, ensure that the data provided is consistent. If we receive a posting indicating "Toronto, United States" (note: Toronto is a city in Canada, not in the United States), this error will be thrown. Secondly, provide as much location information as possible, and ensure there are no errors in formatting. Providing more detailed, accurate location information generally prevents this error from being thrown.

Your job's custom questions were unable to be added. OR The custom questions download failed because the request timed out.

Most of the time this is not a formatting issue—it is caused by our inability to hit your server to collect the custom questions.

Refer to the custom questions section of this page for more details. If we are hitting your sever and failing, it is possible that your server cannot handle the load of requests and either throttling or timeout-ing the requests, resulting in us not being able to receive the custom questions. Either set up more servers or set your throttle limit higher in order to handle the load.

URL field {uri} is invalid.

One of the URLs provided to us (note: there are a variety of different fields that can contain URLS) was invalid.

The vast majority of the time this is because full URLs are not provided. We require a full address, including "https://", in order to consider a URL valid. For example, "https://www.facebook.com" would be a valid url, while "www.facebook.com" or "facebook.com" would not be.

Job to Page Matching Failures

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