SAP SuccessFactors – Gotchas

Custom fields are extracted from both personalInfoNav and employmentNav.jobInfoNav on each employee record. Custom fields stored on other navs are not surfaced in custom_fields — use pass_through to access them.

Address fields line1–line5 are passed through verbatim from SAP's positional fields address1–address5 with no per-country recomposition. SAP SuccessFactors interprets these positions differently per country, and the meaning of each position also varies per tenant — two SAP customers in the same country can configure address1–addressN semantics differently via Manage Business Configuration. Belgium and the Netherlands are confirmed examples of per-tenant variation. The country code is exposed in addresses[].country as ISO-2 (e.g. "BE", "NL") — consumers must use it together with knowledge of the specific tenant's configuration to interpret the semantic meaning of each line.

Fields address6 through address20 are not surfaced in the unified response — the JSON mapping declares line1–line5 only. Consumers that need higher-numbered positional fields must use pass_through.

The street_number field is not populated for SAP SuccessFactors employees.

This limitation is by SAP design: their OData v2 API exposes a single merged PerAddressDEFLT entity for all countries and does not surface per-country field semantics. See SAP KBA 2902948.

Email type is resolved from the externalCode of the email-category picklist option (ecEmailType), which is locale-independent, so the resolved type does not depend on the tenant's configured language. The externalCode to unified type mapping is: B maps to work, P to personal, PI to primary, S to secondary, BI to billing, and O to other. B, P and O are SAP-seeded defaults present in every tenant; PI, S and BI must be configured as picklist options by the tenant to take effect. Any email whose ecEmailType option uses an externalCode outside this set, or has no externalCode, resolves to other.

preferred_language is derived from the externalCode of the employee's nativePreferredLang picklist option, which is locale-independent. The value is the BCP-47 language subtag, uppercased (e.g. ru_RU resolves to RU, en to EN). It is null when the externalCode is absent, system-generated, or not a parseable ISO-639-1 two-letter code.

Custom fields are extracted from both personalInfoNav and employmentNav.jobInfoNav on each employee record. Custom fields stored on other navs are not surfaced in custom_fields — use pass_through to access them.

Address fields line1–line5 are passed through verbatim from SAP's positional fields address1–address5 with no per-country recomposition. SAP SuccessFactors interprets these positions differently per country, and the meaning of each position also varies per tenant — two SAP customers in the same country can configure address1–addressN semantics differently via Manage Business Configuration. Belgium and the Netherlands are confirmed examples of per-tenant variation. The country code is exposed in addresses[].country as ISO-2 (e.g. "BE", "NL") — consumers must use it together with knowledge of the specific tenant's configuration to interpret the semantic meaning of each line.

Fields address6 through address20 are not surfaced in the unified response — the JSON mapping declares line1–line5 only. Consumers that need higher-numbered positional fields must use pass_through.

The street_number field is not populated for SAP SuccessFactors employees.

This limitation is by SAP design: their OData v2 API exposes a single merged PerAddressDEFLT entity for all countries and does not surface per-country field semantics. See SAP KBA 2902948.

Email type is resolved from the externalCode of the email-category picklist option (ecEmailType), which is locale-independent, so the resolved type does not depend on the tenant's configured language. The externalCode to unified type mapping is: B maps to work, P to personal, PI to primary, S to secondary, BI to billing, and O to other. B, P and O are SAP-seeded defaults present in every tenant; PI, S and BI must be configured as picklist options by the tenant to take effect. Any email whose ecEmailType option uses an externalCode outside this set, or has no externalCode, resolves to other.

preferred_language is derived from the externalCode of the employee's nativePreferredLang picklist option, which is locale-independent. The value is the BCP-47 language subtag, uppercased (e.g. ru_RU resolves to RU, en to EN). It is null when the externalCode is absent, system-generated, or not a parseable ISO-639-1 two-letter code.