Skip to main content
All CollectionsSAP SuccessFactors ResourcesIntegration Resources
SAP SuccessFactors Integration Instructions – Recruiting Module
SAP SuccessFactors Integration Instructions – Recruiting Module
Sam Abello avatar
Written by Sam Abello
Updated this week

Scope of Work

Grayscale’s High Volume Hiring Platform is designed to help recruiters streamline and automate a high-touch candidate experience at scale. Grayscale’s conversational recruiting platform makes it easy to text with candidates from within SAP SuccessFactors, while automating repetitive tasks in the hiring process. This document outlines the scope of work for implementing our solution within your ATS.


Integration Steps

    1. Enable Transcript Syncing

    2. Add SMS Consent Question

    1. API Server URL

    2. SAP SuccessFactors Username

    3. Company ID

    4. Client ID

    5. Client Secret

    6. SMS Consent question

      1. Field ID

      2. "Yes" Option ID

      3. "No" Option ID


We are currently partnering with the company Merge, and before integrating, there are a few permissions we’ll need to set up to enable all the functionality we need. Please see the steps outlined below.


Candidate Profile Configuration


Note: A SuccessFactors implementation user with administrative access will need to complete these tasks.

The Grayscale integration will need access to two fields on the Candidate Profile for transcript syncing and SMS consent management:

  1. Transcript syncing utilizes a Standard Field labeled "Comments"

  2. SMS consent management utilizes a Custom Field

To enable both fields on the Candidate Profile Template:

  1. Search for and select Manage Templates

  2. From the Recruiting Management tab, select Candidate Profile

  3. Click on the name of the profile template you want to edit


  4. On the main Template Settings page, scroll to the bottom of the screen. Select the button {N} Fields defined. Click to modify

  5. To enable Transcript Syncing

    1. Select Add > Add standard field from the dropdown at the top of the modal

    2. In the new field form, enter:

      1. Field id: “comments”

      2. Field type: “text”

      3. Field Label: “Comments”

  6. For SMS Consent Management

    1. Add a new Custom Field – collect values for Field ID & Picklist ID (make note of case structure)

      1. Field id: Grayscale_sms_consent

      2. Field Type: picklist

      3. Field Label: [Enter SMS Consent Question Verbiage]

        1. Example:
          “Would you like to opt-in to receiving text messages from the recruiter for this role in relation to the hiring process – such as interview requests, reminders, etc.?
          Note: Selecting “no” will not eliminate you from consideration for this role. Message and data rates may apply, depending on your mobile phone service plan. At any time you can get more help by replying HELP to these texts, or you can opt out completely by replying STOP.)

        2. For more examples, see SMS Consent Question Examples

      4. Field Description: (optional) smsConsentPicklist

      5. Required: True*

        1. *Our recommendations on configuring this field is to mark this field required – but can be left optional if it would otherwise disrupt your existing workflow.

      6. Anonymize: False

      7. Is Sensitive: False

      8. Picklist id: Select an appropriate Yes/No picklist option for your organization

  7. Click Done

  8. From the top menu bar, click Publish

  9. Confirm the changes by clicking Yes

Note: Some warnings may be displayed relating to the existing profile configuration, but the changes will have been applied.

Verify Transcript Syncing Permissions

Grayscale conversation transcripts will be published to the candidate profile via the API. Here are the necessary field permissions needed to allow the conversation transcripts to be visible on the candidate profile internally:

  • Description: [Enter a description for the field permission]

  • Type *: Read Permission

  • Group Name: [Select a dynamic group for which this permission is applicable. These are the dynamic groups defined in the instance. If no group name is selected, the permission will apply for the Candidate by default]

  • Countries/Regions *: [Select the countries/regions of candidates for which this permission is applicable]

  • Sources *: ANY

  • Fields *: • Selected comments

  • Background Elements: None

Candidate comments should now be visible on the candidate profile!


Verify OData Permissions


By default, users can only view or edit relevant fields based on field-level permissions that are defined in entity templates. These field-level permissions allow Recruiting operators to perform the same actions using ODATA APIs as they perform on entities in SAP SuccessFactors Recruiting.

The following permissions will allow the Grayscale API user to view and edit all fields required by the Grayscale integration, regardless of the integrating user’s relation to those entities:

  1. Candidate Tagging Permission

  2. Employee Central Foundation OData API (read only)

  3. OData API Application Export

  4. OData API Candidate Create

  5. OData API Candidate Export

  6. OData API Interview Central Create/Update

  7. OData API Requisition Export

  8. OData Application Create

  9. OData Application Create and Bypass Required Fields

  10. OData Application Update

  11. Picklist Management and Picklist Mapping Set Up

Troubleshooting Odata Permissions

Sometimes, in order to get the above permissions and authentication adjustments to take effect, there’s a need for an “OData Metadata Refresh”.

  1. Log into SuccessFactors

    1. Search for refresh and select Refresh under OData API Metadata Refresh and Export?

  2. If your organization's API has IP access restrictions in place, then an admin will need to allow our servers to speak to the SAP API. Do so by adding the values outlined in this SAP documentation.

  3. To add the Grayscale IP Addresses:

    1. In SuccessFactors, search and select Password & Login Policy

    2. Click Set API Login Exceptions and expand it to find the Grayscale Admin User

    3. Click on the Pencil Icon to Edit

    4. Paste in these Comma-delimited IP Addresses:

      1. 44.194.126.11

      2. 44.194.4.0

      3. 3.232.227.174

      4. 3.214.125.237

      5. 54.158.121.71

      6. 44.193.163.62

  4. Click Save and Close


Gather Integration Values


1 – API Server URL

Using your login URL, you can find the corresponding API Server URL by visiting this link.

  1. Your SAP SuccessFactors API Server URL is a URL that is closely related to the login URL where you sign into your company's SAP SuccessFactors instance.

  2. For example, if you log in at "https://acme.successfactors.com/login", your login URL is acme.successfactors.com (the value after "https://" and before "/login").

  3. Typically, appending "api" before your login URL will result in the correct API Server URL (i.e. apiacme.successfactors.com)


2 – SAP Username and Company ID

To find your SAP SuccessFactors username and company ID, you can look in your SAP SuccessFactors welcome email under "Company User Name" (see image below):

  1. You can also find your SAP SuccessFactors company ID as part of your login URL, which is also sent to you in your SAP SuccessFactors welcome email (under "Company Link" - see image below)

    1. For example, if your login URL is "https://successfactors.com/login?company=SFCPART00000", your company ID will be SFCPART000000.

  2. Alternatively, you can find your SAP SuccessFactors Company ID by logging into SAP SuccessFactors, hovering over your profile photo to expand the dropdown, clicking "Show version information," and locating Company ID in the modal that pops up:


3 – Client ID and Client Secret

  1. Log into your SAP instance.

  2. Search Manage OAuth2 Client Applications in the search bar

  3. Click Register Client Application

  4. Fill out Application Name (Grayscale) & Application URL (https://app.gograyscale.com) and click Generate X.509 Certificate

  5. Fill out Common Name (Grayscale) and hit Generate.

  6. Once the screen refreshes, click Download.

    1. This will download a file called Certificate.pem.

  7. Click Register.

    1. You will now see your application listed. Click View.

    2. You will now see an API key listed - this is your Client ID.

  8. Open up the "Certificate.pem" file that you downloaded previously in a text editor.

    1. Rename the Certificate.pem to Certificate.txt and double click to open

    2. Copy the string between ——BEGIN ENCRYPTED PRIVATE KEY——- and —-END ENCRYPTED PRIVATE KEY——- this is your Client Secret


4 – SMS Consent Question IDs

In order to turn on SMS consent management, we’ll need the following values:

  1. Field ID

    • I.e. Grayscale_sms_consent

  2. Option ID of picklist value “Yes”

    • I.e. 1234

  3. Option ID of picklist value “No”

    • I.e. 1235

To locate the Picklist Option IDs:

  1. Search and select Picklist Center

  2. Type the value of the Pickist id into the search bar and select the corresponding Yes/No picklist

  3. Select the Active row

  4. Select the value that represents the negative action, i.e. “No”

  5. Collect the Option ID value

  6. Repeat steps 4 & 5 by selecting the affirmative action, i.e. “Yes”


SMS Consent Enforcement Options

There are 3 levels of consent enforcement available in Grayscale:

  1. No enforcement. Users will manage on their own – manually identifying and respecting each candidate's response prior to sending a text message. They can text any candidate, unless they have opted-out via SMS directly (i.e. responded with “STOP” or “UNSUBSCRIBE”). It is still the responsibility of the customer to collect consent.

  2. Permissive enforcement. Users will not be able to text candidates who have responded NO to the consent question.

    • Candidates who submitted an application prior to the collection of SMS consent can continue to be communicated with.

    • Candidates who responded with YES to the SMS consent question can be communicated with.

  3. Strict or full enforcement. Users will only be able to communicate with candidates who have responded YES to the SMS consent question.

    • Users will not be able to begin or continue communicating with candidates who have answered NO to the SMS consent question.

    • Users will not be able to begin or continue communicating with candidates who have not made a selection on the SMS consent question.

      • This would typically apply to candidates who submitted their application(s) prior to the addition of the SMS questionnaire.

Did this answer your question?