REST API
It is recommended that these new APIs be used in favour of the legacy APIs.
Authentication / Security
The new APIs use the same authentication mechanism as the legacy APIs
Requests to the APIs need to include
- An X-ApiKey header
- This should have the same value as the Security Key that you entered when configuring the Custom Connector
- An X-Tenant header.
- Tenant identifier unique to your tenant
- An appid
- This can be found by going go the edit page for a Custom Connector and taking the id from the URL. E.g. if the url is
.../InteractV7/SearchApp/Edit/47
then theappid
would be47
- This can be found by going go the edit page for a Custom Connector and taking the id from the URL. E.g. if the url is
Document APIs
PUT /api/search/connector/{appid}/docs/beginsyncsession
Will set the all documents which have Session deletion mode, to be Session Deletion Candidates. If a document is synchronised through the Add Update endpoint during a synchronisation session, then it will no longer be classed as a Session Deletion Candidate - meaning that it will not be automatically deleted once the sync session is ended.
It is not neccesary 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
No additional parameters.
Response
Http Response: 200.
PUT /api/search/connector/{appid}/docs/addupdate
Used to push documents to Interact. Internally will either add a new document or update an existing document which shares the same GlobalUniqueId
Parameters
Within the request body/content you should provide a serialised collection of documents of the form:
[
{
"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",
"DebuggerDisplay": "string"
}
],
"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 Response: 200
The response content will return information about which GloballyUniqueIds have 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 |
PUT /api/search/connector/{appid}/docs/delete
Used to delete the specified documents from Interact
Parameters
Within the request body/content you should provide a serialised collection of document GloballyUniqueIds
[
"GloballyUniqueId_1",
"GloballyUniqueId_2",
"GloballyUniqueId_3"
]
Response
Http Response: 200
PUT /api/search/connector/{appid}/docs/endsyncsession
Used to end a synchronisation session which has been started using the beginsyncsession endpoint.
Deletes any documents which meet the following criteria:
- Already existed before the synchronisation session was started
- Have their Deletion Mode set to Session
- Have not been updated in the current synchronisation session (via the addupdate endpoint)
Parameters
No additional parameters.
Response
Http Response: 200
The response content will include information about how many documents were automatically deleted
{
"Deleted": 0
}
GET /api/search/connector/{appid}/docs/state?docId=X
Gets the state of a document with a supplied globally unique id.
Parameters
The GloballyUniqueId of the document state that you want to get should be included in the request querystring.
Response
Http Response: 200
The response content will include the document state
{
"DocExists": true,
"DateLastUpdated": "2024-04-24T21:17:32.538Z",
"SynchroniseState": "string"
}
The SynchroniseState is not used internally by the connector framework, and is something that can just be used by your custom connector implementation to record additional meta data or synchronisation state (e.g. a delta token) against a document. I.e. no need to store state in a separate system.
PUT /api/search/connector/{appid}/docs/resetstate?docId=X
Resets the state of a document with a supplied globally unique id.
For the supplied document and its children, this will set the
- DateLastUpdated = null
- DeletionMode = Session
- State = null
- SyncSessionDeletionCandidate = 1
Parameters
The GloballyUniqueId of the document that you want to reset the state for should be included in the request querystring. The state of any children will also be reset.
Response
Http Response: 200
User APIs (External Identities)
The synchronisation framework does not actually add/update/delete any users, and is used to only manage the the External Identities associated with a user.
PUT /api/search/connector/{appid}/users/beginsyncsession
Will set the any user external identities associated with this connector to have their Deletion Mode set to Session, to be Session Deletion Candidates. If a users external identities are updated through the Add Update endpoint, then it will no longer be a Session Deletion Candidate.
Any external identities which have their Deletion Mode set to Session and were not updated during a synchronisation session will automatically be removed when the session ends.
Parameters
No additional parameters.
Response
Http Response: 200
PUT /api/search/connector/{appid}/users/addupdate
Used to push external identities for a user.
Internally will perform a lookup for an Interact user with the matching Email address or Username. If one and only one match is found, then the external identities and other synchronisation state properties (in the context of this connector) are updated.
Parameters
Within the request body/content you should 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 Response: 200
The response content will return information about which GloballyUniqueIds have been 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"
]
}
Error Codes:
Error Code | Description |
---|---|
1 | loballyUniqueId must have a value |
2 | Either Username or Email must have a value to perform an intranet person lookup |
PUT /api/search/connector/{appid}/users/delete
Used to delete a user synchronisation record, including any External Identities (in the context of this connector).
Parameters
Within the request body/content you should provide a serialised collection of document GloballyUniqueIds
[
"GloballyUniqueId_1",
"GloballyUniqueId_2",
"GloballyUniqueId_3"
]
Response
Http Response: 200
PUT /api/search/connector/{appid}/users/endsyncsession
Used to end a synchronisation session which has been started using the beginsyncsession endpoint.
Deletes any user synchronisation records and associated External Identities which meet the following criteria:
- Already existed before the synchronisation session was started
- Have their Deletion Mode set to Session
- Have not been updated in the current synchronisation session (via the addupdate endpoint)
Parameters
No additional parameters.
Response
Http Response: 200
The response content will include information about how many documents were automatically deleted
{
"Deleted": 0
}
Updated 3 days ago