Working with external Ids

This document describes how data stored in Bipsync can be managed through the API using Ids from external systems, for example data that is stored in Bipsync that has been imported from a clients own internal systems.

External Id format

The external Id property can be applied to most domain objects in Bipsync, this property is an array containing multiple external Id objects. Each object should contain two properties, a source property and a value property and both these values should be strings. The source value would normally map to a resource within the external system and the value to an Id for that resource.

While there are no limitations on what can be set, it is recommended that the source/value pair is uniquely identifiable, particularly in instances where the external Id will be used to manage a document.

Some example of external ids that can be applied to documents:

{
	"externalIds": [{
		"source": "external-table",
		"value": "external-entry-id"
	}]
}

{
	"externalIds": [{
		"source": "sectors",
		"value": "4fc7140c-0c58-4f21-b46e-328b3d53b044"
	}]
}

Ingest Endpoint

The ingest endpoint allows upserting (updating or creating), categories, contacts and projects using an external Id source and value. The endpoint will attempt to resolve a document to update or create using the external Id source and value provided, if more than one entry is returned then the request will fail. In order for the ingest endpoint to create a new record when a record is not found the document type parameter (documentType) is required, this will allow us to determine what type of record will be created. If no current record is found and no document type is provided then the request will fail.

Using the example external Ids from above a request path would look like the following:

POST v3/ingest/external-table/external-entry-id
POST v3/ingest/sectors/4fc7140c-0c58-4f21-b46e-328b3d53b044

An example request body to create a new category record would look like the following

 {
    "sectors": "4fc7140c-0c58-4f21-b46e-328b3d53b044",
    "name": "Information Technology",
    "classification": "66f3ff460aceb45e6101b47d",
    "user": "66f402092ed85b487f01a842",
    "documentType": "category"
}

Lookup Fields

External Ids can be used to update lookup fields by referencing the properties on the lookup document.

To achieve this we use an object in the request body that contains a property and value.
The property references the lookup document's property and the value would contain the externalId object we wish to resolve.

For fields that allow multiple entries you can pass an array of external Id objects.

POST v2/category/5e68f431650bec04c1454fec
BODY
{
	"fields": {
		"assigned-analyst": {
			"property": "externalIds",
			"value": {
				"source": "externalSystemUser",
				"value": "c61ff840-7bb3-4054-9c39-29d31016d00f"
			}
		},
		"associated-companies": {
			"property": "externalIds",
			"value": [{
				"source": "externalSystemCompany",
				"value": "61efce33-1025-4ecb-a4e1-a270d724ec7e"
			}, {
				"source": "externalSystemCompany",
				"value": "fa0c3487-dac1-4303-8ef1-1022be70a1f6"
			}]
		}
	}
}

Modify Related Categories

Related categories can be managed using external Ids by posting relatedCategories with an array of external Ids.

POST v2/category/5e68f431650bec04c1454fec
BODY
{
	"relatedCategories": {"externalIds": [ { "source": "SubSector", "value": "333" } ]}
}

Document Properties

It is also possible to update document properties that reference other Bipsync Internal Ids. For example parentId:

POST v2/category/5e68f431650bec04c1454fec
BODY
{
	"parentId": {
		"property": "externalIds",
		"value": {
			"source": "salesforce",
			"value": "123"
		}
	}
}

Accessing records via external ID

Research items are directly accessible in the web app by specifying the externalId source and value in the URL.

https://clientname.bipsync.com/#home/external/externalIdSource/externalIdValue

For example:

https://demoenvironment.bipsync.com/#home/external/dataWarehouseId/55663311