# 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.

<figure><img src="/files/NpBDwK41lkOqRdrt3kgv" alt=""><figcaption><p>Architectural diagram – how it could work with a Runbook using Azure Automation</p></figcaption></figure>

### 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)**

```json
{
  "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.

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

#### 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

```bash
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

```bash
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

```bash
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.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://servicechanger.gitbook.io/servicechanger.com/general/api-documentation.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.