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 SAP picklist label of the email category (ecEmailType). Because SAP admins can configure their own email-category picklist, the label can be anything an organisation defines, so we resolve the unified type from the picklist label as follows: Business → work, Personal → personal, Primary → primary, Secondary → secondary, Other → other. Any unlabelled email, or a label with no en_US translation or that does not match the values above, resolves to other.

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.