GuidesREST API ReferenceRelease Notes
Guides

API Examples

Some real-world examples of API usage.

This document illustrates how Bipsync's API can be used to extract the sort of data that is often useful to our clients.

1. Finding all notes tagged to a certain ticker.

When we associate companies (tickers) with research, the values are stored within each research document's fields property, keyed on the ID of the field which has been configured to store companies.

Fields that store categories like companies are referred to as entity fields.

The GET /v1/research endpoint allows us to filter by field value. So if we do the following:

  • Find the ID of the field that has been related to the note content type and is of type lookup and lookup type entity – let's call this fieldId
  • Find the ID of the category which matches our desired ticker – let's call this categoryId
  • Find all research which has a field value of the categoryId for the field fieldId

we'll have a list of all research tagged to a given ticker.

First, we fetch all the content types in the system. Within the response we can see the one that relates to notes (we've truncated the result so it's easier to see the relevant content):

GET /v1/contenttype

{
    "total": 13,
    "offset": 0,
    "limit": 10,
    "results": [
        {
            "id": "5aa7b4e50d3cb5792d8b4567",
            "name": "note",
            "displayName": "Note"
        }
    ]
}

We make a note of that id.

Next, we call GET /v1/field which lists all the fields that have been created. Amongst the response we see this field:

{
    "id": "5aa7b4e50d3cb5792d8b4574",
    "apiIdentifier": "entities",
    "name": "Entities",
    "fieldType": "lookup",
    "options": {
        "allowMultiple": true,
        "supportsAutopopulation": true,
        "lookup": "entity",
        "lookupFlags": "groupByClassification"
    },
    "contentType": "5aa7b4e50d3cb5792d8b4567",
    "order": 0,
    "disabled": false
}

We know this is the field we need because:

  • the contentType property matches our note content type ID
  • it has the fieldType value of lookup
  • it has an options.lookup value of entity.

We make a note of the apiIdentifier property of this field.

Next, we need the ID of the category we're trying to match. Let's say the ticker we want to match is AK.

We call GET /v2/category?classification=company&ticker=AK to find all company categories with that ticker. NB: if we had a ticker in the Bloomberg format (ticker exchange) then we'd use the bbgTicker parameter in place of the ticker parameter in the query string.

We get this response:

{
    "total": 2,
    "offset": 0,
    "limit": 10,
    "results": [
        {
            "id": "5aa7b4e70d3cb57f2d8b4612",
            "name": "Nienow, O'Connell and Stokes",
            "ticker": "AK",
            "exchange": "NASDAQ",
            "classification": "5aa7b4e50d3cb5762d8b4567",
            "created": "13/03/2018 11:24:23",
            "updated": "13/03/2018 11:24:23"
        },
        {
            "id": "5aa7b4e70d3cb57f2d8b45c4",
            "name": "Howe-Smith",
            "ticker": "AK",
            "exchange": "ASX",
            "classification": "5aa7b4e50d3cb5762d8b4567",
            "created": "13/03/2018 11:24:23",
            "updated": "13/03/2018 11:24:23"
        }
    ]
}

Let's say the first company, listed on the NASDAQ, is the one we want. We take that company's ID. Now we know which field value we're looking for, we can find our research.

We submit a request to GET /v1/research with a body that looks like this – matching the category ID to the field API identifier:

{
    "field": {
        "entities": "5aa7b4e70d3cb57f2d8b4612"
    }
}

That returns the following response (which we've truncated):

{
    "total": 22,
    "offset": 0,
    "limit": 10,
    "results": [
        {
            "id": "5aa7b4f50d3cb57f2d8b55ad",
            "labels": [
                "5aa7b4e80d3cb57f2d8b4728"
            ],
            "created": "09/12/2017 21:24:34",
            "updated": "13/03/2018 11:24:37",
            "title": "Voluptatem eos molestiae aut maxime saepe at accusamus.",
            "content": "Voluptatem et provident et eum alias...",
            "user": "5aa7b4e60d3cb57f2d8b4577",
            "fields": {
                "entities": [
                    "5aa7b4e70d3cb57f2d8b4612",
                    "5aa7b4e70d3cb57f2d8b45f0",
                    "5aa7b4e80d3cb57f2d8b4692",
                    "5aa7b4e80d3cb57f2d8b46d6"
                ],
                "contacts": [
                    "5aa7b4e60d3cb57f2d8b4598",
                    "5aa7b4e60d3cb57f2d8b459e"
                ],
                "note-type": [
                    "Management"
                ]
            },
            "sharedGroups": [
                "Fund"
            ],
            "complete": true,
            "textContent": "Voluptatem et provident et eum alias..."
        },
    ]
}

Each of the notes in this list have been tagged with the AK ticker we're interested in. This approach could be tweaked to find any other content document tagged with a certain category – projects, contacts, etc.

2. Finding all notes created by a certain user.

If we wanted to find all the notes that were authored by a given user, we first need to find the user ID of that user.

Say we have the email address of the user in question. By making a request to GET /v1/[email protected] we can find the object for that user:

{
    "total": 1,
    "offset": 0,
    "limit": 10,
    "results": [
        {
            "id": "5aa7b4e60d3cb57f2d8b4574",
            "name": "Candido Mohr",
            "email": "[email protected]",
            "company": "Lynch-Schroeder",
            "team": "5aa7b4e60d3cb57f2d8b4567",
            "created": "13/03/2018 11:24:22",
            "updated": "13/03/2018 11:24:22"
        }
    ]
}

With the ID we can now find all research authored by the user by making a request to GET /v1/research?user=5aa7b4e60d3cb57f2d8b4574

3. Finding all expert network meeting notes and deriving the associated security.

If we'd like to find the notes that were taken in meetings with expert networks, and subsequently the security that corresponds to each meeting, we start by determining the fields that are responsible for storing:

  1. The note type
  2. The entities (i.e. categories) that have been tagged to the note

Following the approach we shared in example 1 (finding notes by ticker), we start by finding the ID of the content type that is associated with notes, via GET /v1/contenttype.

Once we have the note content type's ID, we then find the fields for that note by making a request to GET /v1/field

{
    "total": 2,
    "offset": 0,
    "limit": 10,
    "results": [
        {
            "id": "5aa7b4e50d3cb5792d8b4576",
            "apiIdentifier": "note-type",
            "name": "Note Type",
            "fieldType": "list",
            "options": {
                "allowMultiple": false,
                "values": {
                    "544d506900726d6d488b4567": {
                        "name": "Meeting",
                        "order": 1,
                        "disabled": false,
                        "flags": "interaction",
                        "breadcrumb": "meeting"
                    },
                    "544d509d00726d73488b4567": {
                        "name": "Model",
                        "order": 8,
                        "disabled": false,
                        "breadcrumb": "model"
                    },
                    "544d50a100726d69488b4568": {
                        "name": "Memo",
                        "order": 9,
                        "disabled": false,
                        "breadcrumb": "memo"
                    }
                },
                "defaultValue": null
            },
            "contentType": "5aa7b4e50d3cb5792d8b4567",
            "order": 2,
            "disabled": false
        },
        {
            "id": "5aa7b4e50d3cb5792d8b4574",
            "apiIdentifier": "entities",
            "name": "Entities",
            "fieldType": "lookup",
            "options": {
                "allowMultiple": true,
                "supportsAutopopulation": true,
                "lookup": "entity",
                "lookupFlags": "groupByClassification"
            },
            "contentType": "5aa7b4e50d3cb5792d8b4567",
            "order": 0,
            "disabled": false
        }
    ]
}

These are the two fields we're interested in. The field with the API identifier note-type has a list of possible values that includes one called Meeting. That's the note type we wish to filter by.

The field with the identifier entity, which we also saw in example 1, will allow us to determine the company that was associated with each note, if any.

Now we submit a request to GET /v1/research with a body that looks like this – finding all notes with that meeting note type:

{
    "field": {
        "note-type": "Meeting"
    }
}

Note: we've taken advantage of a convenience here where with list fields, we can supply the name of the option we want to match against. This only works with list fields, and we could just as easily provided the ID of the option we were filtering by.

From the response that comes back, we can then inspect the fields property of each note and, if it has an entry for the entities field, use the value of that entry to look up the exact security by making requests to GET /v2/category/{id} with the appropriate ID placed on the end of the URL.

So taking this note as an example:

{
    "id": "5aa7b4f20d3cb57f2d8b5304",
    "labels": [
        "5aa7b4e80d3cb57f2d8b471c"
    ],
    "created": "09/12/2017 16:24:31",
    "updated": "13/03/2018 11:24:34",
    "title": "Quidem delectus libero aliquam id.",
    "content": "Ratione rerum dicta blanditiis.",
    "user": "5aa7b4e60d3cb57f2d8b4574",
    "fields": {
        "entities": [
             "5aa7b4e70d3cb57f2d8b45d0",
             "5aa7b4e70d3cb57f2d8b45fa"
        ],
        "note-type": [
             "Meeting"
         ]
     },
     "sharedGroups": [
         "Fund"
    ]
}

We make two calls:

GET /v2/category/5aa7b4e70d3cb57f2d8b45d0
GET /v2/category/5aa7b4e70d3cb57f2d8b45fa

to determine if these entities are companies. We can confirm this by matching the classification ID the category to a classification with the company type, which we illustrated retrieving in example 1.

4. Finding a list of companies

To access a list of companies / securities that are stored within Bipsync, you first need to determine the classification which represents companies in the system. Companies are stored as categories, each of which are related to a single classification.

Querying for classifications is done by making a request to GET /v1/classification, which returns a response like so:

{
    "total": 5,
    "offset": 0,
    "limit": 10,
    "results": [
        {
            "id": "5b9f6d2d650bec2ef5640f43",
            "name": "Geographies",
            "entity": "geography",
            "created": "17/09/2018 09:00:29",
            "updated": "17/09/2018 09:00:29"
        },
        {
            "id": "5b9f6d2d650bec2ef5640f42",
            "name": "Industries",
            "entity": "industry",
            "created": "17/09/2018 09:00:29",
            "updated": "17/09/2018 09:00:29"
        },
        {
            "id": "5b9f6d2d650bec2ef5640f41",
            "name": "Companies",
            "entity": "company",
            "created": "17/09/2018 09:00:29",
            "updated": "17/09/2018 09:00:29"
        }
    ]
}

We can see that the Companies classification has an ID of 5b9f6d2d650bec2ef5640f41. We make a note of this, then provide it to a second call to the category endpoint to retrieve a list of categories for that classification:

GET /v2/category?classification=5b9f6d2d650bec2ef5640f41

{
    "total": 51,
    "offset": 0,
    "limit": 10,
    "results": [
        {
            "id": "5b9f6d2f650bec2f02399dee",
            "name": "Ebert and Sons",
            "ticker": "ME",
            "exchange": "NASDAQ",
            "classification": "5b9f6d2d650bec2ef5640f41",
            "created": "17/09/2018 09:00:32",
            "updated": "17/09/2018 09:00:32"
        },
        {
            "id": "5b9f6d2f650bec2f02399dec",
            "name": "Gusikowski LLC",
            "ticker": "AK",
            "exchange": "NASDAQ",
            "classification": "5b9f6d2d650bec2ef5640f41",
            "created": "17/09/2018 09:00:32",
            "updated": "17/09/2018 09:00:32"
        },
        ...
    ]
}

Updated 3 months ago