Fourth Account SCIM API Guide

Introduction

The Fourth Account SCIM API returns details about a customer's Fourth user accounts. Its purpose is to support managing user identities with our partners and customers, particularly those with single sign-on (SSO) connections.

This API enables you to retrieve user data, but not to update or delete the data.

The data returned is restricted to core identity data such as first and last name, email address, job role, job division, language, and timezone. It does not include the more sensitive data Fourth holds about users that is otherwise available through our Workforce Management APIs. This is beneficial as it helps ensure that your business does not unnecessarily receive sensitive personal data about users, while still providing enough details for you to create your own user accounts.

Quick Facts

API type	HTTP REST with JSON
Authentication	OAuth with client credentials
Availability	All customers using our Workforce Management solutions
Testing	A test environment is available
More information	See the API Reference

Get access

To get started with this API, you will need:

• A set of OAuth credentials
• The root URL for requests to both test and live environments

Your mutual Fourth customer must request OAuth credentials on your behalf. Please ensure they do this as soon as possible. The Fourth Professional Services team member managing the integration can help you with any additional questions you may have.

Updates

You can find any updates on the Release Notes page for the Fourth Account SCIM API.

SCIM

This API uses System for Cross-domain Identity Management (SCIM) version 2, an open standard for synchronizing user data across platforms. As our API conforms to this standard, you can use existing third-party standard SCIM tools to test and implement your own integration.

Note that there are three RFCs that define SCIM:

• https://tools.ietf.org/html/rfc7642: An overview of SCIM

• https://tools.ietf.org/html/rfc7643: The schema

• https://tools.ietf.org/html/rfc7644: The protocol

However, this guide and the reference contain everything you need to know to integrate with Fourth.

Terminology

Service Provider

• An HTTP web application that provides identity information via the SCIM protocol. Fourth acts as the Service Provider in SCIM interactions.

Client

• A website or application that gets identity information from the Service Provider.

Users / employees

• The employees whose Fourth Account details are available through this API.

Fourth Accounts

• Fourth Accounts hold the details of Fourth users, such as their name, email address, Fourth Account ID. For information on Fourth accounts, see Identity & Access Management.

Resources

• There are two types of resources in SCIM: Users (which holds attributes about employees) and Groups (which holds the users that belong to a group). We support Users only.

Supported endpoints and schemas

We support a subset of the SCIM RFC endpoints and their methods. As well, we provide only necessary and relevant information for users, which means we do not return all the possible fields documented in the SCIM specification.

End endpoint has one or more SCIM schemas to further identify the contained data.

These endpoints provide Fourth Account details:

• GET User — returns the Fourth Accounts for employees. The schemas in use are:
  • urn:ietf:params:scim:api:messages:2.0:ListResponse
  • urn:ietf:params:scim:schemas:core:2.0:User
  • urn:ietf:params:scim:schemas:extension:enterprise:2.0:User
• GET Users/{identifier} — returns the Fourth Account for one employee. The schemas in use are:
  • urn:ietf:params:scim:schemas:core:2.0:User
  • urn:ietf:params:scim:schemas:extension:enterprise:2.0:User
• GET Me — returns the Fourth Account for the authenticated API user, using the same schema.

These endpoints provide metadata to make the API "discoverable":

• GET ServiceProviderConfig — returns general information about our SCIM service.
  • urn:ietf:params:scim:schemas:core:2.0:ServiceProviderConfig
• GET ResourceTypes — returns details of the resources we support.
  • urn:ietf:params:scim:schemas:core:2.0:ResourceType
• GET Schema — returns the attributes and their characteristics for the resources we support (currently User).
  • urn:ietf:params:scim:schemas:core:2.0:Schema

For each endpoint, error messages use the urn:ietf:params:scim:api:messages:2.0:Error schema.

See the API Reference for information on each endpoint.

Authentication

This API uses OAuth. When you first integrate, please ensure that you request OAuth credentials via your Fourth customer as soon as possible.

The credentials provided will enable you to access their Fourth Accounts only.

For information on integrating with our OAuth service, see Authenticating with OAuth.

Terminated employees

This API returns both current and previous employees. In the response to /User requests, the active field differentiates between existing employees (true) and previous employees (false):

    {
        "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User": {
            "organization": "Acme Industries"
        },
        "active": true,
        "displayName": "Thomas Hardy",
        "emails": [
            {
                "type": "work",
                "primary": true,
                "value": "thomas.hardy@example.com"
            }
        ],
        ...
    }

Paginating the response

You can use two query parameters to limit the number of users returned. They must be used together. They are:

• startIndex

• count

The startIndex begins at “1”, and represents the first user in the index. The count is the number of users you want returned. For example:

• startIndex=1&count=100

returns the first 100 users. To get the next 100 users, you must increase the startIndex to 101:

• startIndex=101&count=100

Pagination is not stateful so clients MUST be prepared to handle inconsistent results. For example, the same request repeated later may return different results.

Filtering for a specific employee

The filter query parameter lets you search for a specific user. The supported options are:

• filter=userName eq <value>

• filter=employeNumber eq <value>

• filter=id eq <value>

• filter=department eq <value>

Where eq means that the values must be identical (but are case-insensitive).

For example:

• [ROOT]/scim/users?filter=userName eq example@hotmail.com

• [ROOT]/scim/users?filter=employeeNumber eq 2AkvSni4X3

• [ROOT]/scim/users?filter=id eq 0058E000001hYirQAE

• [ROOT]/scim/users?filter=department eq 123456789

The operators, attributes names and attribute values are all case insensitive. For example:

• filter=userName Eq john@EXAMPLE.com

• filter=Username eq JOHN@example.com

will both return the same results.

Note that you can only use one filter at a time.

Attributes filtering

Please note that we do not support filtering by attribute (an optional feature in the SCIM RFC).

Troubleshooting

Questions

When should I retry requests?

Retry HTTP 500: Internal Server Error requests only. Any other error message will need you to update the request in some way - or for the authentication token to be renewed.

When retrying requests, ensure you use an exponential backoff strategy. Please make this strategy start are no more than one request per minute. If your service continues to receive these error messages, please contact your customer who can raise a ticket with Fourth.

I am using filter operators like sw and ew - why aren't they working?

We support the eq operator only.

I have included startIndex or count in my request, but the results are not filtered by these, what's wrong?

If you use only one of these two query parameters, then the parameter is ignored. You must use both query parameters together.

Error codes

Code	Error message	Description
400	Invalid request	The request contained an error such as the header being too long or special characters being used in the URL.
401	User is not authorized	The user account does not have permission to access the resources. Check that the user details are correct and retry the request. Please get in touch if you still cannot access the resource.
404	Resource not found	The resource doesn’t exist. Check that your endpoint is correct; e.g: That you are using users and not user If you are using the users/{identifier} endpoint, that the user identifier is valid.
404	Not found <url>	There is a mistake in the URL. Check the full URL matches the test or production URL provided by Fourth.
410	This policy has been deprecated from the Gateway	There is a mistake in the URL. Check the full URL matches the test or production URL provided by Fourth.
500	Soap body with: Service Not Found. The request may have been sent to an invalid URL, or intended for an unsupported operation.	There is a mistake in the URL. Check the full URL matches the test or production URL provided by Fourth.
500	Internal Server Error	An issue occurred at Fourth's server end. Please retry the request using an exponential backoff strategy, starting at no more than one request per minute.
500	Token has expired	The OAuth token has expired. You will need a new token before you can access resources.
501	Functionality not supported. This includes some filter attributes and operators. See our documentation for a list of supported options.	The functionality you tried is not support. For example, you will get this error if you try to use a filter that is not supported, such as: filter=givenname.