Home›Workplace Search›Custom connector API

Custom connector API

Reference for the Workplace Search custom connector REST API for synchronising documents and user external identities.

Before you start

Note: Use these APIs in favour of the legacy APIs.

Authentication and security

The new APIs use the same authentication mechanism as the legacy APIs. Requests must include:

  • An X-ApiKey header — the same value as the secret key you entered when configuring the custom connector.
  • An X-Tenant header — the tenant identifier unique to your tenant.
  • An appid — found by going to the edit page for a custom connector and taking the ID from the URL. For example, if the URL is .../InteractV7/SearchApp/Edit/47, the appid is 47.

Warning: Never expose your secret key in any public website or client-side code.

Document APIs

Begin a document sync session

PUT /api/search/connector/{{appid}}/docs/beginsyncsession

Sets all documents that have Session deletion mode to be session deletion candidates. If a document is synchronised through the add/update endpoint during a synchronisation session, it is no longer classed as a session deletion candidate, so it is not automatically deleted when the session ends.

You do not need to use a synchronisation session if you intend to manage which documents have been pushed or deleted from Interact yourself, as part of your own external tool.

Parameters: none.

Response: HTTP 200.

Add or update documents

PUT /api/search/connector/{{appid}}/docs/addupdate

Pushes documents to Interact. Internally, this adds a new document or updates an existing document that shares the same GloballyUniqueId.

Parameters: in the request body, provide a serialised collection of documents:

[
  {
    "GloballyUniqueId": "string",
    "DocTypeName": "string",
    "Title": "string",
    "Url": "string",
    "Summary": "string",
    "AuthorId": "string",
    "AuthorName": "string",
    "AssetId": "string",
    "AvatarPath": "string",
    "CreatedDate": "2024-04-24T21:17:32.535Z",
    "ModifiedDate": "2024-04-24T21:17:32.535Z",
    "Taxonomy": [
      {
        "Name": "string",
        "Type": "Text",
        "TextValue": "string",
        "NumberValue": 0,
        "DateValue": "2024-04-24T21:17:32.535Z"
      }
    ],
    "CrumbLinks": [
      {
        "Key": "string",
        "Url": "string"
      }
    ],
    "FileContents": "string",
    "Keywords": "string",
    "Bestbets": [
      "string"
    ],
    "DeletionMode": "Session",
    "SynchroniseState": "string",
    "ShouldSaveSynchroniseState": false,
    "IsPublic": false,
    "ExternalIdentities": [
      "string"
    ],
    "MaterializedPath": "string",
    "IsParent": true
  }
]

Response: HTTP 200. The response content returns information about which GloballyUniqueId values succeeded (AddedUpdated) or failed (Errors), including any failure reasons.

{
  "HasErrors": true,
  "Errors": [
    {
      "HasError": true,
      "GloballyUniqueId": "string",
      "Errors": [
        {
          "ErrorCode": 0,
          "ErrorMessage": "string"
        }
      ]
    }
  ],
  "AddedUpdated": [
    "string"
  ]
}

Response error codes:

Error code Description
1 GloballyUniqueId must have a value
2 DocTypeName must have a value
3 Title must have a value
4 Url must have a value
5 Taxonomy value must have a name
6 Taxonomy number value must have a value
7 Taxonomy date value must have a value
8 CrumbLink Key must have a value

Delete documents

PUT /api/search/connector/{{appid}}/docs/delete

Deletes the specified documents from Interact.

Parameters: in the request body, provide a serialised collection of document GloballyUniqueId values:

[
  "GloballyUniqueId_1",
  "GloballyUniqueId_2",
  "GloballyUniqueId_3"
]

Response: HTTP 200.

End a document sync session

PUT /api/search/connector/{{appid}}/docs/endsyncsession

Ends a synchronisation session started with the begin sync session endpoint. Deletes any documents that:

  • Already existed before the session was started
  • Have their deletion mode set to Session
  • Have not been updated in the current session (via the add/update endpoint)

Parameters: none.

Response: HTTP 200. The response content includes how many documents were automatically deleted.

{
  "Deleted": 0
}

Get document state

GET /api/search/connector/{{appid}}/docs/state?docId=X

Gets the state of a document with the supplied globally unique ID.

Parameters: include the GloballyUniqueId of the document state you want in the request query string.

Response: HTTP 200. The response content includes the document state.

{
  "DocExists": true,
  "DateLastUpdated": "2024-04-24T21:17:32.538Z",
  "SynchroniseState": "string"
}

SynchroniseState is not used internally by the connector framework. Your custom connector implementation can use it to record additional metadata or synchronisation state (for example, a delta token) against a document, without storing state in a separate system.

Reset document state

PUT /api/search/connector/{{appid}}/docs/resetstate?docId=X

Resets the state of a document with the supplied globally unique ID. For the supplied document and its children, this sets:

  • DateLastUpdated = null
  • DeletionMode = Session
  • State = null
  • SyncSessionDeletionCandidate = 1

Parameters: include the GloballyUniqueId of the document to reset in the request query string. The state of any children is also reset.

Response: HTTP 200.

User APIs (external identities)

The synchronisation framework does not add, update, or delete any users. It is used only to manage the external identities associated with a user.

Begin a user sync session

PUT /api/search/connector/{{appid}}/users/beginsyncsession

Sets any user external identities associated with this connector that have their deletion mode set to Session to be session deletion candidates. If a user's external identities are updated through the add/update endpoint, they are no longer a session deletion candidate. Any external identities with deletion mode set to Session that were not updated during a session are automatically removed when the session ends.

Parameters: none.

Response: HTTP 200.

Add or update users

PUT /api/search/connector/{{appid}}/users/addupdate

Pushes external identities for a user. Internally, this looks up an Interact user with the matching email address or username. If one and only one match is found, the external identities and other synchronisation state properties (in the context of this connector) are updated.

Parameters: in the request body, provide a serialised collection of user synchronisation records:

[
  {
    "Email": "string",
    "Username": "string",
    "ModifiedDate": "2024-04-24T21:17:32.542Z",
    "GloballyUniqueId": "string",
    "DeletionMode": "Session",
    "SynchroniseState": "string",
    "ShouldSaveSynchroniseState": true,
    "ExternalIdentities": [
      "string"
    ]
  }
]

Response: HTTP 200. The response content returns information about which GloballyUniqueId values were Added, Updated, NotFound, or failed (Errors), including any failure reasons.

{
  "HasErrors": true,
  "Errors": [
    {
      "HasError": true,
      "GloballyUniqueId": "string",
      "Errors": [
        {
          "ErrorCode": 0,
          "ErrorMessage": "string"
        }
      ]
    }
  ],
  "Added": [
    "string"
  ],
  "Updated": [
    "string"
  ],
  "NotFound": [
    "string"
  ]
}

Response error codes:

Error code Description
1 GloballyUniqueId must have a value
2 Either Username or Email must have a value to perform an intranet person lookup

Delete users

PUT /api/search/connector/{{appid}}/users/delete

Deletes a user synchronisation record, including any external identities (in the context of this connector).

Parameters: in the request body, provide a serialised collection of document GloballyUniqueId values:

[
  "GloballyUniqueId_1",
  "GloballyUniqueId_2",
  "GloballyUniqueId_3"
]

Response: HTTP 200.

End a user sync session

PUT /api/search/connector/{{appid}}/users/endsyncsession

Ends a synchronisation session started with the begin sync session endpoint. Deletes any user synchronisation records and associated external identities that:

  • Already existed before the session was started
  • Have their deletion mode set to Session
  • Have not been updated in the current session (via the add/update endpoint)

Parameters: none.

Response: HTTP 200. The response content includes how many records were automatically deleted.

{
  "Deleted": 0
}
Section: Workplace Search