API Documentation

Directory Changes API Documentation

Overview

The Directory Changes API allows developers to retrieve changes (delta changes) for different types of resources in a directory service. This API is useful for keeping track of user, group, and membership changes in a system, especially in scenarios where on-premises synchronization is involved.

Architectural diagram – how it could work with a Runbook using Azure Automation

Base URL

The base endpoint for this API is:

https://api.servicechanger.com/public/directory-changes

Authentication

All API requests require authentication using an API key that should be included in the request headers.

x-api-key: YOUR_API_KEY

Endpoints

Get Delta Changes for Resources

Retrieves changes (created, updated, deleted) for specified resource types since a given timestamp.

GET /public/directory-changes

Query Parameters

Parameter	Type	Required	Description
onPremisesSyncEnabled	boolean	Yes	Filter for resources that have on-premises sync enabled or disabled
lastSyncDate	string	No	ISO timestamp to retrieve changes that occurred after this date
resourceType	string (enum)	Yes	Type of resource to get changes for. Possible values: user, group, membership

Request Headers

Header	Type	Required	Description
x-api-key	string	Yes	API key for authentication

Response

Status Code: 200 (Success)

{
  "data": [
    {
      "resourceType": "user",
      "resource": {
        // User properties (see Resource Models below)
      },
      "changeType": "created",
      "timestamp": "2023-05-15T14:30:00Z",
      "onPremisesSyncEnabled": true
    },
    // Additional change records...
  ],
  "message": "Delta changes fetched successfully",
  "statusCode": 200
}

Status Code: 400 (Bad Request)

Returned when the request is invalid or missing required parameters.

Resource Models

The API deals with three main resource types:

User Resource

Represents user entities in the system.

Property	Type	Description
id	string (UUID)	Unique identifier for the user
displayName	string	The display name of the user
department	string	Department the user belongs to
jobTitle	string	User's job title
businessPhones	string[]	List of business phone numbers
surname	string	Last name of the user
givenName	string	First name of the user
accountEnabled	boolean	Whether the user account is enabled
userPrincipalName	string	Principal name used for authentication
onPremisesDomainName	string	Domain name for on-premises AD (if applicable)
onPremisesSamAccountName	string	SAM account name for on-premises AD
onPremisesSecurityIdentifier	string	Security identifier for on-premises AD
onPremisesLastSyncDateTime	string	Timestamp of last sync with on-premises AD
onPremisesUserPrincipalName	string	UPN for on-premises AD

Group Resource

Represents group entities in the system.

Property	Type	Description
id	string (UUID)	Unique identifier for the group
displayName	string	The display name of the group
created	string	Timestamp when the group was created
description	string	Description of the group
mailNickname	string	Mail nickname for the group (if applicable)
mailEnabled	boolean	Whether mail is enabled for this group
onPremisesSyncEnabled	boolean	Whether this group syncs with on-premises AD
onPremisesSamAccountName	string	SAM account name for on-premises AD
onPremisesNetBiosName	string	NetBIOS name for on-premises AD
onPremisesDomainName	string	Domain name for on-premises AD
onPremisesSecurityIdentifier	string	Security identifier for on-premises AD
onPremisesLastSyncDateTime	string	Timestamp of last sync with on-premises AD

Membership Resource

Represents membership relationships between users and groups.

Property	Type	Description
userId	string (UUID)	ID of the user in the membership
groupId	string (UUID)	ID of the group in the membership

Change Types

The API tracks three types of changes:

Change Type	Description
created	A new resource was created
updated	An existing resource was modified
deleted	A resource was removed

Example Requests

Get All User Changes Since Last Sync

curl -X GET \
  'https://api.servicechanger.com/public/directory-changes?onPremisesSyncEnabled=true&resourceType=user&lastSyncDate=2023-05-01T00:00:00Z' \
  -H 'x-api-key: your-api-key'

Get All Group Changes

curl -X GET \
  'https://api.servicechanger.com/public/directory-changes?onPremisesSyncEnabled=false&resourceType=group' \
  -H 'x-api-key: your-api-key'

Get All Membership Changes

curl -X GET \
  'https://api.servicechanger.com/public/directory-changes?onPremisesSyncEnabled=true&resourceType=membership&lastSyncDate=2023-06-01T00:00:00Z' \
  -H 'x-api-key: your-api-key'

Error Handling

The API returns standard HTTP status codes to indicate the success or failure of a request:

Status Code	Description
200	OK - The request was successful
400	Bad Request - The request was invalid or cannot be served
401	Unauthorized - API key is missing or invalid

Best Practices

1. Efficient Syncing: Use the lastSyncDate parameter to only retrieve changes since your last synchronization.

2. Rate Limiting: Implement appropriate rate limiting in your client applications to prevent API throttling and ensure consistent service availability.

3. Error Handling: Implement robust error handling to manage API failures gracefully.

4. Authentication: Please keep your API key secure and store it in any key-value solutions such as vault.