API Documentation

API Endpoint

Actor profiles

For actor profiles to be created, updated and fetched, an actors API endpoint has been created. This API endpoint works on top of the DataScouts platform (i.e. https://client.datascouts.eu) and requires an API token. API tokens for this API endpoint can be created and revoked in the DataScouts platform.

Creating an actor profile

POST /api/external/actors
Requestsexample 1
Headers
Content-Type: application/json
Body
{
  "api_token": "1234",
  "name": "DataScouts",
  "category": "Company",
  "address": {
    "street": "Wiedauwkaai",
    "number": "23S",
    "zip": "9000",
    "city": "Gent",
    "country": "Belgium"
  }
}
Responses200400401422
Headers
Content-Type: application/json
Body
{
  "id": "AVeikZ3Plz-123"
}
Headers
Content-Type: application/json
Body
{
"message" : "Something went wrong while adding a new actor, make sure the request contains the correct fields and the parameters are passed propertly (check for correct JSON or key value parameters)",
}
Headers
Content-Type: application/json
Body
{
  "message": "Unauthorized"
}
Headers
Content-Type: application/json
Body
{
  "message": "A matching actor was found, no new actor was created, or one of the fields failed to pass validation. Invalid fields will be returned in the error message.",
  "id": "matching-actor-id"
}

Creating an actor profile
POST/api/external/actors

This request allows for a client to create an actor profile on the DataScouts platform. If the request is succesful, the response will contain the ID with which the actor can be identified in DataScouts. Using this ID the client will also be able to retrieve actor profile information, coming from DataScouts. An error will be returned if there was already an actor in the DataScouts platform that matches the given actor profile information. (HTTP 400)

URI Parameters
HideShow
api_token
string (required) 

The API token authorized for CRUD actions on the DataScouts platform

name
string (required) 

The name of the actor.

category
string (optional) 

The category of the actor. This must be a value that is defined in the Category taxonomy of the DataScouts ecosystem the client is making the request to.

url
string (optional) 

The URL (website) of the actor.

street
string (optional) 

The street of the actor.

number
string (optional) 

The street number of the actor.

zip
string (optional) 

The zip code of the actor.

city
string (optional) 

The name city of the actor.

country
string (optional) 

The country of the actor.

vat_number
string (optional) 

The VAT number of the actor (excluding the jurisdiction).

company_number
string (optional) 

The company number of the actor (excluding the jurisdiction). For french companies for example, the SIRET number should be passed with this property.

jurisdiction
string (optional) 

The jurisdiction of the VAT number, needs to be an ISO alpha-2 country code.

username
string (optional) 

The name of the user that needs to be attached to the profile, when this property is given, the useremail property is required.

useremail
string (optional) 

The email of the user that needs to be attached to the profile. If this property is passed, an email will be sent asking the user to finalise the registration on DataScouts if the user is new.

Updating an actor profile

PUT /api/external/actors/actor-id
Requestsexample 1
Headers
Content-Type: application/json
Body
{
  "api_token": "1234",
  "address": {
    "street": "Wiedauwkaai",
    "number": "23S",
    "zip": "9000",
    "city": "Gent",
    "country": "Belgium"
  }
}
Responses200400401404422
Headers
Content-Type: application/json
Body
{
"name" : "DataScouts",
"category" : "Company",
"address" : {
    "street" : "Wiedauwkaai",
    "number" : "23S",
    "zip" : "9000",
    "city" : "Gent",
    "country" : "Belgium"
},
"company_number" : null,
"jurisdiction" : null,
"logo" : null,
"url" : null,
"vat_number" : null,
}
Headers
Content-Type: application/json
Body
{
"message" : "Something went wrong while updating an actor, make sure the request contains the correct fields and the parameters are passed propertly (check for correct JSON or key value parameters)",
}
Headers
Content-Type: application/json
Body
{
  "message": "Unauthorized"
}
Headers
Content-Type: application/json
Body
{
"message" : "The specified actor was not found.",
}
Headers
Content-Type: application/json
Body
{
  "message": "The passed {field} was invalid."
}

Updating an actor profile
PUT/api/external/actors/actor-id

This request allows for an actor profile to be updated. The “actor-id” in the URI identifies which actor profile needs to be updated.

URI Parameters
HideShow
api_token
string (required) 

The API token authorized for CRUD actions on the DataScouts platform

name
string (optional) 

The name of the actor.

category
string (optional) 

The category of the actor. This must be a value that is defined in the Category taxonomy of the DataScouts ecosystem the client is making the request to.

url
string (optional) 

The URL (website) of the actor.

street
string (optional) 

The street of the actor.

number
string (optional) 

The street number of the actor.

zip
string (optional) 

The zip code of the actor.

city
string (optional) 

The name city of the actor.

country
string (optional) 

The country of the actor.

vat_number
string (optional) 

The VAT number of the actor (excluding the jurisdiction).

company_number
string (optional) 

The company number of the actor (excluding the jurisdiction). For french companies for example, the SIRET number should be passed with this property.

jurisdiction
string (optional) 

The jurisdiction of the VAT number, needs to be an ISO alpha-2 country code.

username
string (optional) 

The name of the user that needs to be attached to the profile, when this property is given, the useremail property is required. Note that if there was a user attached to the profile, that user will be replaced with the given user in the request…

useremail
string (optional) 

The email of the user that needs to be attached to the profile. If this property is passed, an email will be sent asking the user to finalise the registration on DataScouts if the user is new.

Get actor profile details

GET /api/external/actors/actor-id
Requestsexample 1
Headers
Content-Type: application/json
Body
{
  "api_token": "1234"
}
Responses200401404
Headers
Content-Type: application/json
Body
{
"name" : "DataScouts",
"category" : "Company",
"logo" : "https://datascouts.eu/ekol1094O2LFIKL.jpg",
 "address" : {
    "street" : "Wiedauwkaai",
    "number" : "23S",
    "zip" : "9000",
    "city" : "Gent",
    "country" : "Belgium"
},
"company_number" : null,
"jurisdiction" : null,
"url" : null,
"vat_number" : null,
}
Headers
Content-Type: application/json
Body
{
  "message": "Unauthorized"
}
Headers
Content-Type: application/json
Body
{
  "message": "The actor was not found."
}

Get actor profile details
GET/api/external/actors/actor-id

This request allows for actor profile information to be retrieved using the API. Replacing the actor-id in the URI will provide the client with information of the actor profile.

URI Parameters
HideShow
api_token
string (required) 

The API token authorized for CRUD actions on the DataScouts platform

User accounts

Users can be added to and removed from the ecosystem that the client has access to. API tokens for this API endpoint can be created and revoked in the DataScouts platform.

Adding a user

POST /api/external/users
Requestsexample 1
Headers
Content-Type: application/json
Body
{
  "api_token": "1234",
  "name": "John Doe",
  "email": "[email protected]"
}
Responses200401422
Headers
Content-Type: application/json
Body
{
  "id": 5192
}
Headers
Content-Type: application/json
Body
{
  "message": "Unauthorized"
}
Headers
Content-Type: application/json
Body
{
  "message": "Something went wrong while adding a user.",
  "error": "Error message"
}

Adding a user
POST/api/external/users

This request allows for a client to add a user as an ecosystem member, to the ecosystem they have access to. If the request is succesful, the response will contain the ID of the user. Using this ID, the client will be able to retrieve profile information, such as the actor profiles that the user has claimed.

After a succesful request, the user will get the an email notification that provides the necessary information in order to complete the onboarding. For users that were already a member of DataScouts, an email will be sent informing them they now have access to a new ecosystem. For completely new users an email will be sent explaining them what DataScouts is and how they can complete their registration. Note that if the user already existed in the ecosystem, the result of this request will be that the user remains unchanged.

URI Parameters
HideShow
api_token
string (required) 

The API token authorized for CRUD actions on the DataScouts platform

name
string (required) 

The name of the user

email
string (required) 

The email of the user

Get user profile details

GET /api/external/users/user-id
Requestsexample 1
Headers
Content-Type: application/json
Body
{
"api_token" : "1234",
}
Responses200401404
Headers
Content-Type: application/json
Body
{
"email": "[email protected]",
"name": "John Doe",
"role": "actor",
"claimed_profiles": [
    {
        "name" : "DataScouts",
        "actor_type": "LegalEntity",
        "category" : "Company",
        "description": "A description of the actor profile",
        "logo" : "https://datascouts.eu/ekol1094O2LFIKL.jpg",
        "email": "[email protected]",
        "address" : {
            "street" : "Wiedauwkaai",
            "number" : "23S",
            "zip" : "9000",
            "city" : "Gent",
            "country" : "Belgium"
        },
        "company_number" : null,
        "jurisdiction" : null,
        "url" : null,
        "vat_number" : null,
    },
    {
        "name" : "Ecosystem Intelligence Platform",
        "actor_type": "Community",
        "category" : "Platform",
        "logo" : "https://datascouts.eu/ekol1094O2LFIKL.jpg",
         "address" : {
            "street" : "Wiedauwkaai",
            "number" : "23S",
            "zip" : "9000",
            "city" : "Gent",
            "country" : "Belgium"
        },
        "company_number" : null,
        "jurisdiction" : null,
        "url" : null,
        "vat_number" : null,
    }
]
}
Headers
Content-Type: application/json
Body
{
  "message": "Unauthorized"
}
Headers
Content-Type: application/json
Body
{
  "message": "The user was not found."
}

Get user profile details
GET/api/external/users/user-id

This request returns actor profile information from actors that are claimed by the user, identified by the user-id passed in the route.

URI Parameters
HideShow
api_token
string (required) 

The API token authorized for CRUD actions on the DataScouts platform

Updating a user

PUT /api/external/users/user-id
Requestsexample 1
Headers
Content-Type: application/json
Body
{
"api_token" : "1234",
"name" : "Jean Doe",
}
Responses200401422
Headers
Content-Type: application/json
Body
{
  "message": "The name was succesfully updated."
}
Headers
Content-Type: application/json
Body
{
  "message": "Unauthorized"
}
Headers
Content-Type: application/json
Body
{
  "message": "Something went wrong while updating the user.",
  "error": "Specific error message."
}

Updating a user
PUT/api/external/users/user-id

This request allows to update a user’s name.

URI Parameters
HideShow
api_token
string (required) 

The API token authorized for CRUD actions on the DataScouts platform

name
string (required) 

The name of the user

Remove a user

DELETE /api/external/users/user-id
Requestsexample 1
Headers
Content-Type: application/json
Body
{
"api_token" : "1234",
}
Responses200401404
Headers
Content-Type: application/json
Body
{}
Headers
Content-Type: application/json
Body
{
  "message": "Unauthorized"
}
Headers
Content-Type: application/json
Body
{
"message" : "The specified user has not been found.",
}

Remove a user
DELETE/api/external/users/user-id

This request allows to remove a user from the ecosystem, specified by its ID in the route.

URI Parameters
HideShow
api_token
string (required) 

The API token authorized for CRUD actions on the DataScouts platform

Fetching Actors

Actor profiles can be fetched in list by providing a portfolio ID. An administrator can configure which portofolios can be accessed by the generated API token, 3rd party clients with that token can then fetch actors from that portfolio by providing the portfolio ID.

Get a list of actors

GET /api/external/portfolio-actors/portfolio-id
Requestsexample 1
Headers
Content-Type: application/json
Body
{
  "api_token": "1234",
  "admin1_name": "Gelderland",
  "report_field_{number}": "Technology",
  "limit": 50,
  "offset": 0
}
Responses200401403
Headers
Content-Type: application/json
Body
[
{
    "id": "j3w7_IEBJZI3AjYH6UtQ",
    "name": "EMLaw",
    "description": "<p>EMLaw staat voor advocatuur rondom innovatie, distributie en concurrentie, gespecialiseerd en met een brede focus. edited</p>",
    "logo": "https://local.datascouts.test/images/uploads/KF10QHRGEOetsQ1n_1712221649.png",
    "url": "http://emlaw.nl",
    "vat_number": "853333336B01",
    "company_number": "59135719",
    "email": "[email protected]",
    "address": {
        "city": "Oosterbeek",
        "zip": "6861EJ",
        "number": "44",
        "street": "Stationsweg",
        "locality": "Oosterbeek",
        "country": "Netherlands",
        "country_code": "NL",
        "geoid": 2749503,
        "admin1_name": "Gelderland",
        "admin2_name": "Gemeente Renkum"
    },
    "location": {
        "lat": 51.99293,
        "lon": 5.84026
    },
    "report_fields": [
        {
            "actor_id": 43,
            "field_id": 5,
            "label": "Competitive sector",
            "value": [
                "Health"
            ]
        },
        {
            "actor_id": 43,
            "field_id": 4,
            "label": "Competitive edge",
            "value": "None"
        }
    ],
    "category": "Association",
    "technology": [
        "Advanced Materials",
        "Battery Technology",
        "BioTechnology",
        "Genetics",
        "Biometrics"
    ],
    "industries": [
        "Aerospace & Defense",
        "Automotive",
        "Food & Agriculture"
    ],
    "subIndustries": [
        "Cars",
        "Bicycles"
    ],
    "phone": "+31 26 333 33 33",
}
]
Headers
Content-Type: application/json
Body
{
  "message": "Unauthorized"
}
Headers
Content-Type: application/json
Body
{
  "message": "Unauthorized"
}

Get a list of actors
GET/api/external/portfolio-actors/portfolio-id

Fetch a list of actors based on the portfolio-id. Paging will be provided via the Link HTTP header, limit and offset can be passed to paginate results, with a limit of maximum 100.

URI Parameters
HideShow
api_token
string (required) 

The API token authorized for CRUD actions on the DataScouts platform

admin1_name
string (optional) 

An optional string parameter used to filter by provinces. Can be multiple comma seperated

report_field_1
string (optional) 

An optional string parameter representing the report field of the actor. Can be multiple comma seperated. Note: Replace the number 1 with the id of the report field.

Managing Content

For monitoring ecosystems, content can be retrieved via API. The content that is available via the API, can only come from searches that are marked as “published”.

Get the list of published searches

GET /api/external/searches
Requestsexample 1
Headers
Content-Type: application/json
Body
{
"api_token" : "1234",
}
Responses200401
Headers
Content-Type: application/json
Body
[
  {
    "id": "v8IzLO1",
    "title": "The title of the article",
    "preview": "The first couple of lines of the article",
    "date": 1591909260,
    "url": "https://link.to/original_article",
    "score": 0.89,
    "tags": [
      {
        "id": 1,
        "label": "tag1",
        "type": "wiki"
      }
    ],
    "mentioned_actors": [
      {
        "name": "Datascouts"
      }
    ],
    "mentioned_datascouts_actors": [
      {
        "name": "DataScouts",
        "id": "AVeikZ3Plz-123"
      }
    ]
  }
]
Headers
Content-Type: application/json
Body
{
  "message": "Unauthorized"
}

Get the list of published searches
GET/api/external/searches

Fetch a list of published searches

URI Parameters
HideShow
api_token
string (required) 

The API token

Get the content of a search

GET /api/external/searches/search-id
Requestsexample 1
Headers
Content-Type: application/json
Body
{
"api_token" : "1234",
}
Responses200401
Headers
Content-Type: application/json
Body
[
  {
    "id": "v8IzLO1",
    "title": "The title of the article",
    "preview": "The first couple of lines of the article",
    "date": 1591909260,
    "url": "https://link.to/original_article",
    "score": 0.89,
    "tags": [
      {
        "id": 1,
        "label": "tag1",
        "type": "wiki"
      }
    ],
    "mentioned_actors": [
      {
        "name": "Datascouts"
      }
    ],
    "mentioned_datascouts_actors": [
      {
        "name": "DataScouts",
        "id": "AVeikZ3Plz-123"
      }
    ]
  }
]
Headers
Content-Type: application/json
Body
{
  "message": "Unauthorized"
}

Get the content of a search
GET/api/external/searches/search-id

Get the most relevant content for the search.

URI Parameters
HideShow
api_token
string (required) 

The API token

curated
string (required) 

Return curated only results. By default this parameter is false.

timeframe
string (required) 

Optional: day(default), week, month

limit
string (required) 

The amount of results to return in 1 page

offset
string (required) 

The offset to start returning results from

Update the likes for a piece of content

POST /api/external/content/content-id/likes
Requestsexample 1
Headers
Content-Type: application/json
Body
{
"likes" : 6,
}
Responses200401422
Headers
Content-Type: application/json
Body
{
  "message": "success"
}
Headers
Content-Type: application/json
Body
{
  "message": "Unauthorized"
}
Headers
Content-Type: application/json
Body
{
  "message": "Pass the likes in your request body as a positive integer."
}

Update the likes for a piece of content
POST/api/external/content/content-id/likes

Update the likes count for a piece of content. The content-id parameter is the ID value of a result returned by one of the endpoints that returns content. For example “v8IzLO1” going by the example in the previous section of the content documentation.

URI Parameters
HideShow
api_token
string (required) 

The API token

Get the list of news monitored portfolios

GET /api/external/monitor
Requestsexample 1
Headers
Content-Type: application/json
Body
{
"api_token" : "1234",
}
Responses200401
Headers
Content-Type: application/json
Body
[
  {
    "id": "JeMz01",
    "name": "Monitored portfolio"
  }
]
Headers
Content-Type: application/json
Body
{
  "message": "Unauthorized"
}

Get the list of news monitored portfolios
GET/api/external/monitor

Fetch the list of portfolios that are being monitored for news

URI Parameters
HideShow
api_token
string (required) 

The API token

Get the list of actors that are part of a news monitored portfolio

GET /api/external/monitor/portfolio-id
Requestsexample 1
Headers
Content-Type: application/json
Body
{
  "api_token": "1234",
  "admin1_name": "Gelderland",
  "report_field_{number}": "Technology"
}
Responses200401
Headers
Content-Type: application/json
Body
[{
"count": 1,
"actors": [
    {
        "id": "j3w7_IEBJZI3AjYH6UtQ",
        "name": "EMLaw",
        "description_stripped_tags": "EMLaw staat voor advocatuur rondom innovatie, distributie en concurrentie, gespecialiseerd en met een brede focus. edited",
        "logo": "https://public.datascouts.eu/emlawnlgE3v3GTMvU.png",
        "url": "http://emlaw.nl",
        "address": {
            "city": "Oosterbeek",
            "zip": "6861EJ",
            "number": "44",
            "street": "Stationsweg",
            "locality": "Oosterbeek",
            "country": "Netherlands",
            "country_code": "NL",
            "geoid": 2749503,
            "admin1_name": "Gelderland",
            "admin2_name": "Gemeente Renkum"
        },
        "location": {
            "lat": 51.99293,
            "lon": 5.84026
        },
        "report_fields": [
            {
                "actor_id": 43,
                "field_id": 4,
                "label": "Support availability",
                "value": "Development support is always included"
            },
            {
                "actor_id": 43,
                "field_id": 5,
                "label": "Unacceptable allergens",
                "value": [
                    "Celery",
                    "Gluten",
                    "Eggs"
                ]
            }
        ]
    },
]
}]
Headers
Content-Type: application/json
Body
{
  "message": "Unauthorized"
}

Get the list of actors that are part of a news monitored portfolio
GET/api/external/monitor/portfolio-id

Fetch the list of actors that are part of the passed portfolio, based on the portfolio-id parameter. Responses are returned in batches of 1000 actor objects.

URI Parameters
HideShow
api_token
string (required) 

The API token

admin1_name
string (optional) 

An optional string parameter used to filter by provinces. Can be multiple comma seperated

report_field_1
string (optional) 

An optional string parameter representing the report field of the actor. Can be multiple comma seperated. Note: Replace the number 1 with the id of the report field.

Get the content of an actor

GET /api/external/monitor/portfolio-id/actor-id
Requestsexample 1
Headers
Content-Type: application/json
Body
{
"api_token" : "1234",
}
Responses200401
Headers
Content-Type: application/json
Body
{
  "articles": [
    {
      "title": "The title of the article",
      "preview": "The first couple of lines of the article",
      "date": 1591909260,
      "url": "https://link.to/original_article",
      "tags": [
        {
          "id": 1,
          "label": "tag1",
          "type": "wiki"
        }
      ],
      "mentioned_actors": [
        {
          "name": "Datascouts"
        }
      ],
      "mentioned_datascouts_actors": [
        {
          "name": "DataScouts",
          "id": "AVeikZ3Plz-123"
        }
      ]
    }
  ]
}
Headers
Content-Type: application/json
Body
{
  "message": "Unauthorized"
}

Get the content of an actor
GET/api/external/monitor/portfolio-id/actor-id

Get the latest 300 items of news for a monitored actor.

URI Parameters
HideShow
api_token
string (required) 

The API token

Login ecosystem members via token

Clients that have DataScouts API access and have the settings enabled to allow ecosystem members to be logged in via a temporary token can use this API endpoint to fetch a token for a specific user that has the role “ecosystem member”. This token can be used to build a login URI that a client application can use to log the user in: https://example.datascouts.eu/[email protected]&token=IkdiMPAKDOIIFNeikz390eNDIKZLA23K

The generated token will remain valid for 30 seconds, if the user consumes this token after 30 seconds, the user will get a 403 page.

Creating a token for a user

POST /api/login-tokens
Requestsexample 1
Headers
Content-Type: application/json
Body
{
  "email": "[email protected]"
}
Responses200400401404422500
Headers
Content-Type: application/json
Body
{
  "token": "token"
}
Headers
Content-Type: application/json
Body
{
"message" : "The user with email [email protected] is not an ecosystem member, login via a token only works for users that have the ecosystem member role.",
}
Headers
Content-Type: application/json
Body
{
  "message": "The option to allow ecosystem members to login with a token is not enabled for this ecosystem. Please contact DataScouts if you want this option to be enabled."
}
Headers
Content-Type: application/json
Body
{
  "message": "No user was found for the email [email protected]."
}
Headers
Content-Type: application/json
Body
{
  "message": "The email is not valid."
}
Headers
Content-Type: application/json
Body
{
  "message": "Something went wrong while making a token for the user."
}

Creating a token for a user
POST/api/login-tokens

This POST request will generate and return a token for a user matching the given email address. If the user is not found or does not have the role “ecosystem member” an appropriate error response will be returned.

URI Parameters
HideShow
email
string (required) 

The email of the user to generate a token for

OAuth

Customers that have specifically received a OAuth client credentials can ask users to login with their DataScouts accounts. DataScouts acts as a standard OAuth 2.0 server with the authorization, token and resource endpoints being the following:

  • /oauth/authorize

  • /oauth/token

  • /oauth/resource

Authorize

GET /oauth/authorize

Authorize
GET/oauth/authorize

Send a user to the DataScouts authorization page where the user can choose to accept or deny the client receiving its information. If the user accepts, DataScouts will redirect the user together with the authorization code (parameter: authorization_code) to the OAuth client. This authorization code can then be used by the OAuth client to get an access token.

URI Parameters
HideShow
client_id
string (required) 

The OAuth client ID

redirect_uri
string (required) 

The client redirect URI

response_type
string (required) 

“code”

Access token

POST /oauth/token
Requestsexample 1
Headers
Content-Type: application/json
Body
{
  "grant_type": "authorization_code",
  "client_id": "your client id",
  "client_secret": "your client secret",
  "redirect_uri": "your redirect uri",
  "code": "The received Authorization Code from the previous /oauth/authorize call"
}
Responses200
Headers
Content-Type: application/json
Body
{
  "token_type": "Bearer",
  "expires_in": 3155673600,
  "access_token": "eyJ0eXAiOiJKV1QiL....",
  "refresh_token": "..."
}

Access token
POST/oauth/token

Retrieve an access token, which grants access to the users’ resource.

Refreshing an access token

POST /oauth/token/refresh
Requestsexample 1
Headers
Content-Type: application/json
Body
{
"grant_type": "refresh_token",
"client_id": "your client ID"
"client_secret": "your client secret",
"refresh_token": "your refresh token"
"scope": ""
}
Responses

Refreshing an access token
POST/oauth/token/refresh

Fetching the user resource

GET /oauth/resource
Responses200
Headers
Content-Type: application/json
Body
{
"name": "John Doe",
"email": "[email protected]",
"id": 1,
"company": {
    "id": "...",
    "name": "ACME",
    "vat": "BE0...",
    "address": {
        "number": "",
        "street": "",
        "city": "",
        "zip": "",
        "country": "",
    },
    "phone": "",
    "description": "",
    "founding_date": "",
    "url": "",
    "email":""
}
}

Fetching the user resource
GET/oauth/resource

Make a GET request to this endpoint with the HTTP Authorization header filled in as follows: ‘Authorization’ => 'Bearer '.${accessToken},

Generated by aglio on 05 Apr 2024